agentic-development-principles
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAgentic development principles (Agentic Development Principles)
Agentic开发原则（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.
"AI是副驾驶，你才是主驾驶" AI Agent可以拓展开发者的思考边界、接管重复性工作，但最终决策权和责任始终由开发者承担。
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
- 开启与AI Agent的协作会话时
- 启动复杂任务前确定实现方案时
- 制定上下文管理策略时
- 复盘工作流以提升生产力时
- 向团队成员培训如何与AI协作时
- 采用新AI工具时落地基线原则时
Principle 1: Divide and conquer (Divide and Conquer)
原则1：分治（Divide and Conquer）
Core concept
核心理念
AI performs much better with small, clear instructions than with large, ambiguous tasks.
AI处理小型、清晰的指令的效果远优于处理大型、模糊的任务。
How to apply
如何应用
| Wrong example | Right example |
|---|---|
| "Build me a login page" | 1. "Create the login form UI component" |
| 2. "Implement the login API endpoint" | |
| 3. "Wire up the authentication logic" | |
| 4. "Write test code" | |
| "Optimize the app" | 1. "Analyze performance bottlenecks" |
| 2. "Optimize database queries" | |
| 3. "Reduce frontend bundle size" |
| 错误示例 | 正确示例 |
|---|---|
| "给我做一个登录页" | 1. "创建登录表单UI组件" |
| 2. "实现登录API接口" | |
| 3. "对接认证逻辑" | |
| 4. "编写测试代码" | |
| "优化这个应用" | 1. "分析性能瓶颈" |
| 2. "优化数据库查询" | |
| 3. "减小前端包体积" |
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步骤1：设计并验证模型/ schema
步骤2：实现核心逻辑（最小可用功能）
步骤3：对接API/接口
步骤4：编写并运行测试
步骤5：集成与重构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?
- 每个步骤是否可以独立验证？
- 如果执行失败，是否可以仅修复该步骤？
- 范围是否足够清晰，AI能够理解？
Principle 2: Context is like milk (Context is like Milk)
原则2：上下文就像牛奶（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)
上下文（AI的工作内存）应当始终保持新鲜且精简。
- 陈旧、无关的信息会降低AI的表现
- 上下文漂移：混合多个主题会让AI表现最高下降39%（研究数据）
Context management strategies
上下文管理策略
Strategy 1: Single-purpose conversation
策略1：单用途会话
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
会话1：开发认证系统
会话2：开发UI组件
会话3：编写测试代码
会话4：DevOps/部署相关工作- 不要在单个会话中混合多个主题
- 新主题开启新会话
Strategy 2: HANDOFF.md technique
策略2：HANDOFF.md技巧
When the conversation gets long, summarize only the essentials and hand them to a new session:
markdown
undefined当会话变得过长时，仅总结核心信息，传递到新会话中：
markdown
undefinedHANDOFF.md
HANDOFF.md
Completed work
已完成工作
- ✅ Implemented user authentication API
- ✅ Implemented JWT token issuance logic
- ✅ 已实现用户认证API
- ✅ 已实现JWT token签发逻辑
Current status
当前状态
- Working on token refresh logic
- 正在开发token刷新逻辑
Next tasks
后续任务
- Implement refresh tokens
- Add logout endpoint
- 实现刷新token功能
- 新增登出接口
Tried but failed
尝试过但失败的方案
- Failed to integrate Redis session store (network issue)
- 集成Redis会话存储失败（网络问题）
Cautions
注意事项
- Watch for conflicts with existing session management code
undefined- 注意和现有会话管理代码的冲突
undefinedStrategy 3: Monitor context state
策略3：监控上下文状态
- When the conversation gets long, ask the AI to summarize the current state
- If needed, reset the conversation and restart using HANDOFF.md
- 当会话过长时，要求AI总结当前状态
- 必要时重置会话，使用HANDOFF.md重新启动
Strategy 4: Optimization metrics
策略4：优化指标
| Metric | Recommended value | Action |
|---|---|---|
| Conversation length | Keep to a reasonable level | Create HANDOFF.md if it gets long |
| Topic count | 1 (single purpose) | Use a new session for new topics |
| Active files | Only what's needed | Remove unnecessary context |
| 指标 | 推荐值 | 操作 |
|---|---|---|
| 会话长度 | 保持在合理范围 | 过长时创建HANDOFF.md |
| 主题数量 | 1个（单用途） | 新主题使用新会话 |
| 活跃文件 | 仅保留需要的文件 | 移除不必要的上下文 |
Principle 3: Choose the right abstraction level
原则3：选择合适的抽象层级
Core concept
核心理念
Choose an appropriate abstraction level depending on the situation.
| Mode | Description | When to use |
|---|---|---|
| Vibe Coding | High level (see only overall structure) | Rapid prototyping, idea validation, one-off projects |
| Deep Dive | Low level (go line-by-line) | Bug fixes, security review, performance optimization, production code |
根据场景选择合适的抽象层级。
| 模式 | 描述 | 适用场景 |
|---|---|---|
| Vibe Coding | 高层级（仅关注整体结构） | 快速原型、想法验证、一次性项目 |
| Deep Dive | 低层级（逐行梳理） | Bug修复、安全评审、性能优化、生产环境代码 |
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新增功能时：
1. 高抽象："创建用户个人资料页" → 了解整体结构
2. 中抽象："展示资料编辑表单的校验逻辑" → 评审特定功能
3. 低抽象："解释为什么这个正则无法通过邮箱校验" → 细节调试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%
- 原型/概念验证: 80% Vibe Coding，20% Deep Dive
- 生产环境代码: 30% Vibe Coding，70% Deep Dive
- Bug修复: 100% Deep Dive
Principle 4: Automation of automation (Automation of Automation)
原则4：自动化的自动化（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如果你已经重复做同一项任务3次以上 → 找到方法自动化它
而自动化的过程本身 → 也要实现自动化Automation level evolution
自动化层级演进
| Level | Approach | Example |
|---|---|---|
| 1 | Manual copy/paste | AI output → copy into terminal |
| 2 | Terminal integration | Use AI tools directly |
| 3 | Voice input | Voice transcription system |
| 4 | Automate repeated instructions | Use project config files |
| 5 | Workflow automation | Custom commands/scripts |
| 6 | Automate decisions | Use Skills |
| 7 | Enforce rules automatically | Use hooks/guardrails |
| 层级 | 方案 | 示例 |
|---|---|---|
| 1 | 手动复制粘贴 | AI输出内容 → 复制到终端 |
| 2 | 终端集成 | 直接使用AI工具 |
| 3 | 语音输入 | 语音转文字系统 |
| 4 | 重复指令自动化 | 使用项目配置文件 |
| 5 | 工作流自动化 | 自定义命令/脚本 |
| 6 | 决策自动化 | 使用Skills |
| 7 | 规则自动执行 | 使用hooks/防护机制 |
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?
- 你是否会重复运行同一个命令3次以上？
- 你是否会重复给出相同的解释？
- 你是否经常编写相同的代码模式？
- 你是否会重复执行相同的校验流程？
Automation priority
自动化优先级
- High: tasks repeated daily
- Medium: tasks repeated weekly (or more)
- Low: tasks repeated about once a month
- 高优先级: 每日重复的任务
- 中优先级: 每周（或更频繁）重复的任务
- 低优先级: 大约每月重复一次的任务
Principle 5: Balance caution and speed (Plan vs Execute)
原则5：平衡谨慎与速度（Plan vs Execute）
Plan mode (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)
执行模式（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
AI直接编辑代码、运行命令
适用场景:
- 简单、清晰的任务
- 使用经过充分验证的模式的工作
- 沙箱/容器环境
- 容易回滚的工作
Recommended ratio
推荐占比
- Plan mode: 70-90% (use as the default)
- Execute mode: 10-30% (only in safe environments)
- 规划模式: 70-90%（作为默认选项）
- 执行模式: 10-30%（仅在安全环境下使用）
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)
原则6：验证与反思（Verify and Reflect）
How to verify output
如何验证输出
-
Write test code
"Write tests for this function. Include edge cases too." -
Visual review
- Review changed files via diff
- Revert unintended changes
-
Draft PR / code review
"Create a draft PR for these changes" -
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."
-
编写测试代码
"为这个函数编写测试，也包含边界用例。" -
可视化评审
- 通过diff评审变更的文件
- 回滚非预期的变更
-
草稿PR / 代码评审
"为这些变更创建一个草稿PR" -
要求自校验
"再评审一遍你刚生成的代码。校验每一处声明，最后用表格总结校验结果。"
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
六大原则总结
| Principle | Core | Practice |
|---|---|---|
| 1. Divide and conquer | Small, clear units | Split into independently verifiable steps |
| 2. Context management | Keep it fresh | Single-purpose conversations, HANDOFF.md |
| 3. Abstraction choice | Depth per situation | Adjust Vibe ↔ Deep Dive |
| 4. Automation² | Remove repetition | Automate after 3 repetitions |
| 5. Plan/execute balance | Caution first | Plan 70-90%, execute 10-30% |
| 6. Verification/reflection | Check outputs | Tests, reviews, self-verification |
| 原则 | 核心 | 实践 |
|---|---|---|
| 1. 分治 | 小型、清晰的单元 | 拆分为可独立验证的步骤 |
| 2. 上下文管理 | 保持新鲜 | 单用途会话、HANDOFF.md |
| 3. 抽象层级选择 | 按需调整深度 | 在Vibe ↔ Deep Dive间切换 |
| 4. 二次自动化 | 消除重复 | 重复3次后自动化 |
| 5. 规划/执行平衡 | 谨慎优先 | 70-90%时间规划，10-30%时间执行 |
| 6. 验证/反思 | 检查输出 | 测试、评审、自校验 |
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.
"要真正掌握AI工具，你需要足够多的使用量"
边用边学是关键——仅靠理论不够，你需要在实际项目中经历不同的场景。
Golden rule
黄金法则
When instructing an AI:
1. Clearly (Specific)
2. Step-by-step (Step-by-step)
3. Verifiable (Verifiable)给AI下达指令时：
1. 清晰明确（Specific）
2. 分步说明（Step-by-step）
3. 可验证（Verifiable）Best Practices
最佳实践
DO (recommended)
推荐做法（DO）
- Focus on one clear goal per conversation
- Regularly clean up context
- Plan before complex work
- Always verify outputs
- Automate repetitive work
- 每个会话专注于一个明确的目标
- 定期清理上下文
- 复杂工作前先规划
- 始终验证输出
- 自动化重复性工作
DON'T (prohibited)
禁止做法（DON'T）
- 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
- 在一个会话中处理多个不相关的任务
- 持续使用臃肿的上下文工作
- 随意自动运行危险命令
- 不加验证直接使用AI输出
- 重复做相同工作却不自动化