AI 编程 Agent 协作实践:从计划、审查到代码瘦身

AI 编程 Agent 的能力越来越强,但“能写代码”不等于“能稳定维护项目”。真正影响效率的,往往不是模型会不会生成某段代码,而是有没有一套可靠的协作流程。

这篇文章记录使用 Codex、Claude Code 等 AI 编程工具时总结出的几条经验。它们不依赖某个特定模型,换成其他支持文件读写、命令执行和 Git 操作的 Agent,同样适用。

一、不要把 Agent 当成一次性代码生成器

很多人使用 AI 编程工具时,习惯直接描述需求:

帮我实现这个功能。

这种方式在小 demo 中通常没问题,但真实项目还涉及目录结构、依赖版本、兼容性、测试方式和部署流程。如果没有明确的协作边界,Agent 很容易误改文件、引入不必要的封装,或者只验证自己熟悉的成功路径。

更稳妥的方式,是把 Agent 当成一名需要协作流程约束的开发者:先确认方案,再实施改动;写完代码后换一个视角审查;能够交给工具自动检查的规则,不要只写在提示词里。

二、动手前先看 Plan

为什么计划阶段重要?

“增加一个按钮”可能同时涉及页面组件、样式、状态管理、路由权限、测试和文档。如果一开始就让 Agent 直接修改,发现方向不对时通常已经产生了一批关联改动,回退成本会明显增加。

可以先要求 Agent 只读项目文件,并回答:

  1. 当前实现的入口在哪里;
  2. 最小改动方案是什么;
  3. 准备修改、新增和明确不修改哪些文件;
  4. 可能影响的功能和兼容性风险;
  5. 完成后如何验证;
  6. 当前有哪些假设或疑问。

例如:

1
2
3
4
5
6
7
8
先进入计划阶段,不要修改文件。
请阅读与需求相关的代码,并说明:
1. 当前实现入口;
2. 最小改动方案;
3. 准备修改的文件;
4. 明确不会修改的文件;
5. 验证命令;
6. 你的假设。

计划不必每次都很长。拼写修正、修改一个已定位的配置值等低风险操作可以直接处理,关键是让改动范围和假设在实施前变得可见。

三、交叉审查:不要让同一个视角包办开发和验收

Agent 在实现功能时已经形成了自己的理解。随后让它根据同一套理解编写测试,往往只会验证“它认为应该成立的情况”,而不会主动寻找遗漏。

常见盲区包括:

  • 空值、异常值和边界输入;
  • 并发或重复调用;
  • 权限校验遗漏;
  • 旧数据兼容问题;
  • 错误处理路径没有真正执行;
  • 改动破坏了其他模块,但当前测试没有覆盖。

可以把开发和审查拆成两个角色:

1
2
3
4
5
角色 A:理解需求、修改代码、补充测试。

角色 B:只负责审查,不预设实现正确。
请检查需求覆盖、逻辑漏洞、不必要改动、兼容性、
失败路径、边界条件,以及文档和代码是否一致。

如果只有一个 Agent,也可以在不同阶段清空上下文,只提供变更说明、差异内容和测试结果,让它以审查者身份重新阅读。审查结果最好分为阻塞问题、一般问题和建议项,先处理真正会导致功能错误或安全风险的问题。

四、规范拆进 SKILL.md,按需加载

很多项目会不断向 AGENTS.md、项目说明或系统提示词追加规则。短期看起来很完整,长期却容易导致上下文变长、无关规则干扰判断,甚至出现相互冲突的约定。

更合理的做法是分成两层。

常驻规则只保留项目级基础信息:目录结构、常用命令、不可修改的目录、提交前检查和整体编码风格。

具体流程拆成独立的 SKILL.md 或专项说明,例如:

1
2
3
4
5
skills/
├── database-migration/SKILL.md
├── release-process/SKILL.md
├── frontend-component/SKILL.md
└── api-testing/SKILL.md

任务涉及数据库迁移时加载数据库规范,需要发版时加载发版流程。每份专项技能说明应该写清楚:使用时机、前置文件、实施步骤、禁止操作、验证命令、常见失败原因和完成清单。

不要把 SKILL.md 写成百科全书。它的目标是帮助 Agent 在特定任务中稳定执行,而不是覆盖项目所有知识。

五、边界交给 Hooks 和 Linter

在提示词里反复强调“不要破坏格式”“记得执行测试”“不要修改这个目录”确实有帮助,但不能替代自动化约束。长任务经过多轮修改后,早期约束很容易被忽略。

适合交给工具的规则包括:

  • 提交前格式化;
  • 类型检查和单元测试;
  • 检查 Markdown、YAML、JSON 是否可解析;
  • 扫描敏感信息;
  • 阻止修改生成目录或锁定文件;
  • 检查变更文件范围。

例如在 Git Hooks、CI 或项目脚本中配置:

1
2
3
4
# 根据项目实际命令替换
npm run lint
npm run typecheck
npm test

这样规则就从“提醒”变成了“门禁”:检查失败就不能进入下一步。检查也不必越多越好,优先选择与项目风险最相关、失败信息清晰且不会频繁误报的检查。

六、并行任务使用 git worktree

多个终端或 Agent 共用同一个目录时,一个 Agent 可能覆盖另一个 Agent 尚未提交的修改,测试结果也可能与当前代码对不上。暂存区、分支状态和临时文件还会互相污染。

推荐一个任务对应一个独立工作树:

1
2
3
4
5
6
7
8
# 在仓库同级目录创建独立工作树和分支
git worktree add ..\blog-feature -b codex/blog-feature

# 查看当前仓库的所有工作树
git worktree list

# 合并完成后清理工作树
git worktree remove ..\blog-feature

推荐流程是:主目录负责整合和发布;每个任务创建独立分支和工作树;Agent 只在自己的工作树内修改和测试;审查通过后再合并。

适合并行的任务通常耦合度较低,例如一个 Agent 整理文档,另一个修复测试;一个开发前端页面,另一个补充后端接口。如果两个任务会频繁修改同一个文件,强行并行反而会增加合并成本。

七、定期代码瘦身

Agent 擅长解决当前问题,但不一定会主动删除历史遗留内容。几轮需求迭代后,项目很容易出现未使用的封装、重复工具函数、过期兼容逻辑、失效文档和临时补丁。

可以定期单开一个只做维护的任务:

1
2
3
4
5
6
7
8
9
10
11
请对当前项目进行一次维护性审查,不新增业务功能。

重点检查:
1. 未使用的文件、函数、依赖和配置;
2. 重复实现和可以合并的封装;
3. 过期注释与实际代码不一致的地方;
4. 文档、示例和命令是否仍然可用;
5. 可以安全删除的死代码。

请先输出问题清单和删除依据,确认后再修改;
每一项修改完成后运行相关测试。

清理任务尤其要强调“先列清单、再修改”。删除代码的风险通常高于新增代码,不能仅凭“看起来没有使用”就直接删除。

八、把 6 条经验串成一套工作流

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
需求进入
↓
读取项目规则与相关文件
↓
只读 Plan:确认范围、假设和验证方式
↓
拆分任务:必要时创建独立 worktree
↓
Agent 实施代码和测试
↓
自动执行格式化、Lint、类型检查和测试
↓
另一个 Agent 或独立上下文进行交叉审查
↓
修复问题并重新验证
↓
合并、记录变更、清理工作树
↓
定期执行代码瘦身和文档对齐

这套流程的重点不是增加流程数量,而是把问题放到最适合发现它们的环节:方向问题在 Plan 阶段发现,逻辑问题在交叉审查阶段发现,格式和类型问题交给自动化工具发现,并发冲突通过工作树隔离,长期维护问题通过定期瘦身发现。

九、实战检查清单

  • 是否先读取了项目规则和相关代码?
  • 是否明确了本次改动的文件范围?
  • 是否说明了不应该修改的文件或目录?
  • 是否列出了失败路径、边界条件和兼容性风险?
  • 是否执行了格式化、Lint、类型检查或测试?
  • 是否有独立视角进行代码审查?
  • 并行任务是否使用了独立分支或 git worktree?
  • 是否更新了受影响的文档和示例?
  • 是否定期清理了不再使用的代码和配置?

结语

比较可靠的协作方式是:让 Agent 负责探索和实施,让 Plan 帮我们确认方向,让审查者寻找盲区,让 Hooks 和 Linter 守住底线,再通过 git worktree 和定期代码瘦身控制长期复杂度。

当这些环节形成习惯后,Agent 才真正从“会写代码的聊天机器人”,变成可以参与项目协作的工程助手。


AI 编程 Agent 协作实践:从计划、审查到代码瘦身
https://miku2024.top/posts/AI编程Agent协作实践/
作者
KB
发布于
2026年11月19日
许可协议