8.4 常见坑和坏写法¶

有些做法短期看起来省事，长期会让 Agent 改错文件、漏跑测试，或提交只有表面可运行的代码。这里直接列出常见坏写法，以及对应的修法。

坑 1：一句话开工¶

帮我优化一下。

这句话对人类同事都不够用，对 AI 则只能依赖猜测。它不知道你要优化速度、结构、文案，还是视觉；也不知道哪些位置不能修改。

开工前把四件事写清楚：

写 Goal / Context / Constraints / Done When。

把文件一段段复制给网页模型，让它生成补丁。

这样做容易制造表面正确但无法应用的补丁。网页模型看不到完整本地仓库，也跑不了测试；如果你复制遗漏一段，它会自行补全缺失上下文。

建议分工是：

网页端负责澄清，本地 Agent 负责执行。

规范文件不是宣言。写太长、太虚，Agent 难以提取可执行约束。尤其是“写可验证、可维护的代码”“注意安全”这种话，看着正确，但没有可执行约束。

把规则改成短、明确、可验证：

短、硬、具体。
每条规则问：删掉它，Agent 会犯错吗？

MCP 不是越多越强。工具过多时，权限边界会变乱，调用噪声会变大，Agent 也更容易在多个相似工具里选错。

起步时只接最小集合：

先只读、少量、明确场景。

别人写的 skill 可以参考，但不能替你理解自己的流程。下载太多以后，常见结果是触发条件互相冲突，输出格式也和你的项目流程不匹配。

先从自己的高频流程提炼：

优先把自己的高频流程写成 skill。

聊天总结可能遗漏事实，diff 记录实际改动。最终发生了什么，只能看文件改动。AI 可能附带修改无关文件，也可能绕过已有抽象，风险也可能出现在一行看似无害的改动里。

不要跳过最后这一步：

最终事实是 diff，不是聊天总结。

“AI 说完成”只是一个声明，不是证据。

AI 说完成 != 项目已经完成。

让它交代验证命令和结果；跑不了，也要说清楚为什么跑不了。

完成前必须运行或说明验证命令。

同时装很多 MCP、skills、hooks 和多 Agent 框架，看起来像系统，实际可能只是更难解释的混乱。

先问缺口：

当前失败来自任务不清、上下文不足、执行不稳、权限太大，还是验证缺失？

每次只补一层。补完后用一次真实任务验证它是否减少返工。

长任务做到一半只靠聊天历史续命，很容易在上下文压缩、换工具或换人时断掉。

每次阶段结束都写四行：

已完成：
未完成：
验证结果：
下一步：

这些内容应该进入任务目录或项目文档，而不是只留在对话里。