agentic-development-principles（主体发展原则）

Agentic development principles (Agentic Development Principles)

"AI is the copilot; you are the pilot" AI agents amplify the developer's thinking and take over repetitive work, but final decision-making authority and responsibility always remain with the developer.

When to use this skill

• When starting a collaboration session with an AI agent
• When deciding an approach before starting a complex task
• When establishing a context management strategy
• When reviewing workflows to improve productivity
• When onboarding teammates on how to collaborate with AI
• When applying baseline principles while adopting a new AI tool

Principle 1: Divide and conquer (Divide and Conquer)

Core concept

AI performs much better with small, clear instructions than with large, ambiguous tasks.

How to apply

Practical pattern: staged implementation

Step 1: Design and validate the model/schema
Step 2: Implement core logic (minimum viable functionality)
Step 3: Connect APIs/interfaces
Step 4: Write and run tests
Step 5: Integrate and refactor

Validation points

• Can each step be validated independently?
• If it fails, can you fix only that step?
• Is the scope clear enough for the AI to understand?

Principle 2: Context is like milk (Context is like Milk)

Core concept

Context (the AI's working memory) should always be kept fresh and compact.

• Old and irrelevant information reduces AI performance
• Context drift: mixing multiple topics can reduce performance by up to 39% (research)

Context management strategies

Strategy 1: Single-purpose conversation

Session 1: Work on the authentication system
Session 2: Work on UI components
Session 3: Write test code
Session 4: DevOps/deployment work

• Do not mix multiple topics in a single conversation
• Start a new session for a new topic

Strategy 2: HANDOFF.md technique

When the conversation gets long, summarize only the essentials and hand them to a new session:

# HANDOFF.md

## Completed work
- ✅ Implemented user authentication API
- ✅ Implemented JWT token issuance logic

## Current status
- Working on token refresh logic

## Next tasks
- Implement refresh tokens
- Add logout endpoint

## Tried but failed
- Failed to integrate Redis session store (network issue)

## Cautions
- Watch for conflicts with existing session management code

Strategy 3: Monitor context state

• When the conversation gets long, ask the AI to summarize the current state
• If needed, reset the conversation and restart using HANDOFF.md

Strategy 4: Optimization metrics

Principle 3: Choose the right abstraction level

Core concept

Choose an appropriate abstraction level depending on the situation.

In practice

When adding a new feature:
1. High abstraction: "Create a user profile page" → understand overall structure
2. Medium abstraction: "Show the validation logic for the profile edit form" → review a specific feature
3. Low abstraction: "Explain why this regex fails email validation" → detailed debugging

Abstraction level selection guide

• Prototype/PoC: Vibe Coding 80%, Deep Dive 20%
• Production code: Vibe Coding 30%, Deep Dive 70%
• Bug fixes: Deep Dive 100%

Principle 4: Automation of automation (Automation of Automation)

Core concept

If you've repeated the same task 3+ times → find a way to automate it
And the automation process itself → automate that too

Automation level evolution

Checklist: identify automation targets

• Do you run the same command 3+ times?
• Do you repeat the same explanations?
• Do you often write the same code patterns?
• Do you repeat the same validation procedures?

Automation priority

1. High: tasks repeated daily
2. Medium: tasks repeated weekly (or more)
3. Low: tasks repeated about once a month

Principle 5: Balance caution and speed (Plan vs Execute)

Plan mode (Plan Mode)

Analyze without executing; execute only after review/approval

When to use:

• A complex task you're doing for the first time
• A large refactor spanning multiple files
• Architecture changes
• Database migrations
• Hard-to-roll-back work

Execute mode (Execute Mode)

AI directly edits code and runs commands

When to use:

• Simple, clear tasks
• Work with well-validated patterns
• Sandbox/container environments
• Easy-to-revert work

Recommended ratio

• Plan mode: 70-90% (use as the default)
• Execute mode: 10-30% (only in safe environments)

Safety principles

• ⚠️ Auto-running dangerous commands only in isolated environments
• Always back up before changing important data
• Always use plan mode for irreversible work

Principle 6: Verify and reflect (Verify and Reflect)

How to verify output

1. Write test code "Write tests for this function. Include edge cases too."
2. Visual review

- Review changed files via diff - Revert unintended changes

1. Draft PR / code review "Create a draft PR for these changes"
2. Ask for self-verification "Review the code you just generated again. Validate every claim, and summarize the verification results in a table at the end."

Verification checklist

• Does the code work as intended?
• Are edge cases handled?
• Are there any security vulnerabilities?
• Are tests sufficient?
• Are there any performance issues?

Reflection questions

• What did you learn in this session?
• What could you do better next time?
• Were there repetitive tasks you could automate?

Quick Reference

Six principles summary

Mastery rule

"To truly master AI tools, you need to use them enough"

Learning by using is key - theory alone is not enough; you need to experience different situations in real projects.

Golden rule

When instructing an AI:
1. Clearly (Specific)
2. Step-by-step (Step-by-step)
3. Verifiable (Verifiable)

Best Practices

DO (recommended)

• Focus on one clear goal per conversation
• Regularly clean up context
• Plan before complex work
• Always verify outputs
• Automate repetitive work

DON'T (prohibited)

• Handle multiple unrelated tasks in one conversation
• Keep working with a bloated context
• Auto-run dangerous commands carelessly
• Use AI output as-is without verification
• Repeat the same work without automating it

References

• Anthropic Claude Best Practices
• ykdojo claude-code-tips
• Ado's Advent of Claude
• OpenAI Best Practices