agent-engineering

Agent 工程原则

为 AI 编码 Agent 打造可靠、高质量成果的实战原则。

何时使用此技能

• 为项目编写或审查 AGENTS.md / CLAUDE.md / CURSOR.md 文件
• 配置新的 AI 编码 Agent 或子 Agent
• 诊断 Agent 为何反复犯同样的错误
• 审查 Agent 输出质量并找出系统性问题
• 帮助 Agent 熟悉复杂代码库

1. 默认使用计划模式

• 对任何非简单任务（3 个或更多步骤，或涉及架构决策）进入计划模式
• 如果事情进展不顺，立即停止并重新规划——不要继续硬做
• 验证步骤也使用计划模式，而不只是构建时使用
• 事先编写详细规格，减少歧义

何时跳过： 解决方案显而易见的简单单文件编辑。

计划格式示例（tasks/todo.md）：

## Task: Migrate auth to JWT

### Plan
- [ ] Audit current session-based auth flow
- [ ] Design JWT payload schema (user_id, roles, expiry)
- [ ] Implement token generation in auth service
- [ ] Update middleware to validate JWT
- [ ] Write tests for edge cases (expired, invalid, revoked)
- [ ] Update docs

### Done
- [x] Audit complete — 4 routes need updating

2. 子 Agent 策略

• 多使用子 Agent，保持主上下文窗口整洁
• 将研究、探索和并行分析工作交给子 Agent
• 对于复杂问题，通过子 Agent 增加计算资源
• 每个子 Agent 只负责一项任务，以便专注执行

关键要点： 上下文窗口污染是导致 Agent 质量下降的头号原因。子 Agent 成本低廉，尽管使用。

何时启动子 Agent，何时直接处理：

使用子 Agent	直接处理
研究任务（超过 10 个文件）	简单的单文件编辑
可独立并行的工作	快速配置更改
长时间运行的编译或测试	输出明确的单条命令
独立实验（高风险更改）	简单重构

3. 自我改进循环

用户每次提出任何更正后：

1. 在 tasks/lessons.md（或同类文件）中记录这一模式
2. 为自己编写规则，避免重犯同样的错误
3. 持续严格迭代这些经验，直到错误率降低
4. 在会话开始时查看与当前项目相关的经验

经验格式

## Lesson: [Short title]
- **Trigger:** What went wrong
- **Rule:** What to do instead
- **Added:** [date]

经验示例：

## Lesson: Don't mutate shared config objects
- **Trigger:** Modified `config.defaults` directly, breaking other callers
- **Rule:** Always deep-clone config before modifying; treat config objects as read-only
- **Added:** 2026-03-15

这是最少被使用的 Agent 模式。 大多数 Agent 会反复犯同样的错误，因为它们没有反馈机制。经验文件可以形成闭环。

4. 完成前验证

• 未证明任务有效之前，绝不要标记为已完成
• 在适用时，对比主分支与更改后的行为
• 问问自己：“资深工程师会认可这项工作吗？”
• 运行测试、检查日志并证明正确性

反模式： 只说“我已经做了更改”，却没有证明更改有效。

标记完成前的验证清单：

• 测试通过（npm test / pytest / go test ./...）
• 没有新增 lint 错误
• 对更改的代码路径进行手动冒烟测试
• 审查 diff，确认没有意外更改
• 考虑边缘情况（空输入、错误路径、并发访问）

5. 追求优雅（保持平衡）

• 对于非简单更改，暂停并思考：“有没有更优雅的办法？”
• 如果修复看起来像权宜之计，就问：“基于现在掌握的所有信息，如何实现优雅的解决方案？”
• 简单、显而易见的修复无需如此——不要过度设计
• 在展示成果前先审视自己的工作

平衡之道： 对需要长期维护的代码而言，优雅很重要。对于一次性脚本，完成即可。

优雅的迹象： 代码读起来像行文。新工程师无需解释就能理解。抽象边界清晰。没有多余内容，也没有遗漏。

过度设计的迹象： 为 20 行的问题设置 3 层抽象。为一次性用途构建通用框架。基于“以后可能会用到”的理由进行设计。

6. 自主修复 Bug

• 收到 Bug 报告时：直接修复，不要要求用户手把手指导
• 指出日志、错误和失败的测试，然后解决问题
• 无需用户频繁切换上下文
• 无需用户告知如何操作，主动修复失败的 CI 测试

经验法则： 如果能看到错误并理解代码库，就直接修复。只有确实受阻时才提问。

受阻是指：

• 修复需要产品或 UX 决策（而非技术决策）
• 需要你无法获取的访问权限或凭据
• 存在两种合理的修复方案，且它们的权衡差异显著，应由负责人选择

7. 任务管理周期

对于任何非琐碎任务，请遵循以下 6 步周期：

1. 先制定计划： 在 tasks/todo.md 中编写包含可勾选事项的计划
2. 确认计划： 开始实现前先确认
3. 跟踪进度： 完成事项后及时标记
4. 说明变更： 在每个步骤提供高层级摘要
5. 记录结果： 在 tasks/todo.md 中添加评审部分
6. 总结经验： 更正后更新 tasks/lessons.md

核心原则

• 简单优先： 让每项变更尽可能简单，尽量减少代码改动
• 不偷懒： 找出根本原因，不要临时修补。遵循资深开发者的标准
• 证明有效： 提供测试、日志和证据，不要只说“应该能用”
• 从错误中学习： 每次更正都应成为一条永久规则
• 尊重上下文： 保持主要上下文整洁，果断委派
• 交付而非空谈： 倾向于采取行动，直接修复，不要争论

常见失败模式（反模式）

无休止的循环

Agent 不断尝试相同的失败方法，只做细微改动。解决方法： 停下来，重新阅读错误，查阅经验总结文件，然后尝试从根本上不同的方法。

上下文偏移

调用工具 20 次以上后，Agent 忘记了原始目标，开始解决相邻问题。解决方法： 在每个重要节点重新阅读原始任务。

过早自信

Agent 仅凭“代码看起来没问题”就标记任务完成，却没有实际运行。解决方法： 始终运行测试或命令，切勿想当然。

范围蔓延

修复 Bug 时，Agent 还顺手重构无关代码。解决方法： 一项变更，一个提交。重构应放在单独的 PR 中。

静默失败

命令以 0 退出，但实际上没有任何变化（例如仍处于试运行模式）。解决方法： 验证变更是否生效（检查日志、差异、重新加载配置）。

应用这些原则

对于 AGENTS.md / CLAUDE.md 文件

将相关原则直接添加到项目的 Agent 配置中：

## Engineering Standards

### Before Starting
- [ ] Read tasks/lessons.md for this project
- [ ] Plan non-trivial work in tasks/todo.md
- [ ] Verify plan before implementing

### While Working
- [ ] One task per subagent
- [ ] Verify each step works before moving on
- [ ] Track progress in todo.md

### Before Marking Done
- [ ] Run tests / check logs
- [ ] "Would a staff engineer approve this?"
- [ ] Update lessons.md if any corrections were made

对于 CI/评审集成

这些原则适用于 PR 评审自动化：

• 验证（#4） → 要求在 PR 描述中提供测试证据
• 优雅（#5） → 加入代码评审检查清单
• 经验总结（#3） → 记录合并后的回顾笔记

新项目启动

对于没有 tasks/ 目录的新代码库：

mkdir tasks
echo "# Todo\n\n(empty)" > tasks/todo.md
echo "# Lessons\n\n(empty)" > tasks/lessons.md

然后，如果这两个文件仅供 Agent 使用，就将它们都添加到 .gitignore；如果团队共享，则对它们进行版本跟踪。

参考资料

灵感来自社区分享的 Agent 工程实践模式（2026 年 3 月）。