用 Codex 维护老项目的人多半有这个体会:它的通用能力没问题,但总在项目特有的地方犯错——不用现成的封装、命名跟项目对不上、改完不跑该跑的测试。
这些错误有个共同点:不是它不会,是它不知道。而「让它知道」的办法,就是在项目根目录放一份 AGENTS.md,把项目特有的规矩写下来。Codex 每次开工都会读它,等于一份常驻的交接文档。
我自己的 AGENTS.md 主要写五样东西,供参考。
不要把目录树原样贴进去,要写「职责」:
src/api/ 是全部接口的统一出口,业务代码不许直接发请求src/legacy/ 是历史代码,只修 bug,不做重构config/ 读,禁止在代码里写死环境地址它据此判断改动应该落在哪一层,少走很多弯路。
Node 版本、框架大版本、包管理器、构建命令、测试命令,逐条写明。尤其是「这个项目用 npm 不用 pnpm」「测试跑 npm run test:unit 不是 npm test」这种细节——它猜错一次,你就要多等一轮。
通用规范它本来就懂,不用重复。只写项目特有的:
Result<T> 包装,不要裸返回数据db/ 下的封装,不许在业务层拼 SQL约定写进去之后,review 时明显能感觉到它的产出「像项目里的人写的」。
这一节最容易被忽略,但价值最高:
migrations/ 里已执行过的迁移文件只许新增、不许修改禁区写明,它顺手扩大改动范围的毛病会收敛很多。
最后一条是流程约定:每次改完,汇报必须包含改了哪些文件、每处改了什么、跑了什么验证、结果如何。再加上一条:涉及报错修复的,把根因追加到文件末尾的「踩坑记录」一节。
坚持几个月,这份文件的踩坑记录会长成项目自己的故障手册,比任何人的记忆都可靠。
AGENTS.md 的写法原则就一句:只写「这个项目特有的、代码里看不出来的」东西。通用知识不用教,项目规矩必须明说。写一次,之后每次开工都省一遍口头交代。
(作者:云思思,平时主要折腾 ChatGPT 和 Codex 的实际用法。)
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。