7 个常见陷阱
基于 OpenAI、HumanLayer、LangChain 等多方实践经验总结
陷阱 1：把 AGENTS.md 写成百科全书
症状：AGENTS.md 超过 300 行，包含完整的编码规范、所有 API 文档、历史背景……
为什么有害：
- 耗尽上下文预算，Agent 处理任务的空间不足
- Agent 更容易遗漏关键信息（信噪比下降）
- 维护成本极高，文档很快过期
正确做法：
AGENTS.md（≤100 行，只做目录）
├── 仓库目的（3 句话）
├── 目录结构（文件树 + 一句话描述）
├── 核心术语（3-5 个）
├── 常用命令（5 行）
└── 关键约束入口（指向 docs/ 中的详细文档）
陷阱 2：连接过多 MCP 服务器
症状：给 Agent 接了 20 个 MCP 服务器，覆盖"所有可能需要的工具"。
为什么有害：
- 工具列表本身占用大量上下文
- 工具过多会让 Agent 陷入"选择困难"
- HumanLayer 研究：工具超过一定数量后，Agent 进入"愚蠢区"
正确做法：从最少的工具集开始，只在 Agent 反复因为缺少某工具而失败时，才添加新工具。
陷阱 3：为假想问题预防性地堆砌规则
症状：Agent 还没开始工作，就写了 50 条"可能需要的"规范。
正确做法：
观察真实的 Agent 失败
↓
找到根本原因（缺少什么工具/文档/约束？）
↓
精准添加一个修复
↓
观察是否解决了这类问题
↓
循环迭代
驭化层是通过反馈循环生长的，不是预先设计完整的。
陷阱 4：忽视"技术债积累速度 = AI 生成速度"
症状：AI 疯狂合并代码，几个月后代码库变成了无法维护的混乱状态。
正确做法：
- 从第一天起就配置 Drift Scanner
- 将"发现反复出现的坏模式 → 写成 lint 规则"作为团队习惯
- 定期（每月）进行架构健康审查
陷阱 5：上下文设置一次永久有效
症状：AGENTS.md 六个月没更新，docs/architecture.md 描述的是旧的系统架构。
建立更新触发器：
| 变更类型 | 需要更新的文档 |
|---|---|
| 添加新目录/模块 | AGENTS.md |
| 重要架构决策 | docs/decisions/ 新增 ADR |
| 重构分层结构 | docs/architecture/ARCHITECTURE.md |
陷阱 6：把所有 Lint 错误设为必须修复
症状：Agent 卡在 lint 循环中：修复了错误 A，产生了错误 B……
正确做法：
按严重级别分类：
- Error（阻断 CI）：只留真正关键的规则（<10 条）
- Warning（提示但不阻断）：建议遵守的规范
- Info（信息提示）：可以忽略的风格建议
陷阱 7：Agent 只写代码，不更新文档
症状：代码功能增加，但 AGENTS.md、API 文档、ADR 从未更新。
正确做法：在 Skill 文档（工作流）中明确要求 Agent 更新文档作为任务的一部分。
快速自检
- [ ] AGENTS.md 超过 100 行了吗？
- [ ] 你给 Agent 连接了超过 10 个工具吗？
- [ ] 你在 Agent 第一次运行前就写了大量规则吗？
- [ ] 你有自动化的代码库健康扫描机制吗？
- [ ] 你的架构文档是什么时候更新的？
- [ ] 你的 lint 规则有分优先级吗？
- [ ] 你的 Skill 文档包含"更新文档"步骤吗？
全部勾选 = 驭化层健康 🟢