AI 编程 Agent 协作实践:从计划、审查到代码瘦身
AI 编程 Agent 的能力越来越强,但“能写代码”不等于“能稳定维护项目”。真正影响效率的,往往不是模型会不会生成某段代码,而是有没有一套可靠的协作流程。
这篇文章记录使用 Codex、Claude Code 等 AI 编程工具时总结出的几条经验。它们不依赖某个特定模型,换成其他支持文件读写、命令执行和 Git 操作的 Agent,同样适用。
一、不要把 Agent 当成一次性代码生成器
很多人使用 AI 编程工具时,习惯直接描述需求:
帮我实现这个功能。
这种方式在小 demo 中通常没问题,但真实项目还涉及目录结构、依赖版本、兼容性、测试方式和部署流程。如果没有明确的协作边界,Agent 很容易误改文件、引入不必要的封装,或者只验证自己熟悉的成功路径。
更稳妥的方式,是把 Agent 当成一名需要协作流程约束的开发者:先确认方案,再实施改动;写完代码后换一个视角审查;能够交给工具自动检查的规则,不要只写在提示词里。
二、动手前先看 Plan
为什么计划阶段重要?
“增加一个按钮”可能同时涉及页面组件、样式、状态管理、路由权限、测试和文档。如果一开始就让 Agent 直接修改,发现方向不对时通常已经产生了一批关联改动,回退成本会明显增加。
可以先要求 Agent 只读项目文件,并回答:
- 当前实现的入口在哪里;
- 最小改动方案是什么;
- 准备修改、新增和明确不修改哪些文件;
- 可能影响的功能和兼容性风险;
- 完成后如何验证;
- 当前有哪些假设或疑问。
例如:
1 | |
计划不必每次都很长。拼写修正、修改一个已定位的配置值等低风险操作可以直接处理,关键是让改动范围和假设在实施前变得可见。
三、交叉审查:不要让同一个视角包办开发和验收
Agent 在实现功能时已经形成了自己的理解。随后让它根据同一套理解编写测试,往往只会验证“它认为应该成立的情况”,而不会主动寻找遗漏。
常见盲区包括:
- 空值、异常值和边界输入;
- 并发或重复调用;
- 权限校验遗漏;
- 旧数据兼容问题;
- 错误处理路径没有真正执行;
- 改动破坏了其他模块,但当前测试没有覆盖。
可以把开发和审查拆成两个角色:
1 | |
如果只有一个 Agent,也可以在不同阶段清空上下文,只提供变更说明、差异内容和测试结果,让它以审查者身份重新阅读。审查结果最好分为阻塞问题、一般问题和建议项,先处理真正会导致功能错误或安全风险的问题。
四、规范拆进 SKILL.md,按需加载
很多项目会不断向 AGENTS.md、项目说明或系统提示词追加规则。短期看起来很完整,长期却容易导致上下文变长、无关规则干扰判断,甚至出现相互冲突的约定。
更合理的做法是分成两层。
常驻规则只保留项目级基础信息:目录结构、常用命令、不可修改的目录、提交前检查和整体编码风格。
具体流程拆成独立的 SKILL.md 或专项说明,例如:
1 | |
任务涉及数据库迁移时加载数据库规范,需要发版时加载发版流程。每份专项技能说明应该写清楚:使用时机、前置文件、实施步骤、禁止操作、验证命令、常见失败原因和完成清单。
不要把 SKILL.md 写成百科全书。它的目标是帮助 Agent 在特定任务中稳定执行,而不是覆盖项目所有知识。
五、边界交给 Hooks 和 Linter
在提示词里反复强调“不要破坏格式”“记得执行测试”“不要修改这个目录”确实有帮助,但不能替代自动化约束。长任务经过多轮修改后,早期约束很容易被忽略。
适合交给工具的规则包括:
- 提交前格式化;
- 类型检查和单元测试;
- 检查 Markdown、YAML、JSON 是否可解析;
- 扫描敏感信息;
- 阻止修改生成目录或锁定文件;
- 检查变更文件范围。
例如在 Git Hooks、CI 或项目脚本中配置:
1 | |
这样规则就从“提醒”变成了“门禁”:检查失败就不能进入下一步。检查也不必越多越好,优先选择与项目风险最相关、失败信息清晰且不会频繁误报的检查。
六、并行任务使用 git worktree
多个终端或 Agent 共用同一个目录时,一个 Agent 可能覆盖另一个 Agent 尚未提交的修改,测试结果也可能与当前代码对不上。暂存区、分支状态和临时文件还会互相污染。
推荐一个任务对应一个独立工作树:
1 | |
推荐流程是:主目录负责整合和发布;每个任务创建独立分支和工作树;Agent 只在自己的工作树内修改和测试;审查通过后再合并。
适合并行的任务通常耦合度较低,例如一个 Agent 整理文档,另一个修复测试;一个开发前端页面,另一个补充后端接口。如果两个任务会频繁修改同一个文件,强行并行反而会增加合并成本。
七、定期代码瘦身
Agent 擅长解决当前问题,但不一定会主动删除历史遗留内容。几轮需求迭代后,项目很容易出现未使用的封装、重复工具函数、过期兼容逻辑、失效文档和临时补丁。
可以定期单开一个只做维护的任务:
1 | |
清理任务尤其要强调“先列清单、再修改”。删除代码的风险通常高于新增代码,不能仅凭“看起来没有使用”就直接删除。
八、把 6 条经验串成一套工作流
1 | |
这套流程的重点不是增加流程数量,而是把问题放到最适合发现它们的环节:方向问题在 Plan 阶段发现,逻辑问题在交叉审查阶段发现,格式和类型问题交给自动化工具发现,并发冲突通过工作树隔离,长期维护问题通过定期瘦身发现。
九、实战检查清单
- 是否先读取了项目规则和相关代码?
- 是否明确了本次改动的文件范围?
- 是否说明了不应该修改的文件或目录?
- 是否列出了失败路径、边界条件和兼容性风险?
- 是否执行了格式化、Lint、类型检查或测试?
- 是否有独立视角进行代码审查?
- 并行任务是否使用了独立分支或
git worktree? - 是否更新了受影响的文档和示例?
- 是否定期清理了不再使用的代码和配置?
结语
比较可靠的协作方式是:让 Agent 负责探索和实施,让 Plan 帮我们确认方向,让审查者寻找盲区,让 Hooks 和 Linter 守住底线,再通过 git worktree 和定期代码瘦身控制长期复杂度。
当这些环节形成习惯后,Agent 才真正从“会写代码的聊天机器人”,变成可以参与项目协作的工程助手。