首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >让 Codex 读懂你的老项目:AGENTS.md 应该写哪五样东西

让 Codex 读懂你的老项目:AGENTS.md 应该写哪五样东西

原创
作者头像
云思思
发布于 2026-11-05 20:24:50
发布于 2026-11-05 20:24:50
1480
举报

用 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
  • 新增文件命名用 kebab-case,老文件保持原样不批量改名

约定写进去之后,review 时明显能感觉到它的产出「像项目里的人写的」。

四、禁区:哪些地方不许碰

这一节最容易被忽略,但价值最高:

  • migrations/ 里已执行过的迁移文件只许新增、不许修改
  • 支付相关代码改动必须先出方案、经人工确认才许动手
  • 不要为了「统一风格」去格式化无关文件

禁区写明,它顺手扩大改动范围的毛病会收敛很多。

五、交付格式:汇报必须带什么

最后一条是流程约定:每次改完,汇报必须包含改了哪些文件、每处改了什么、跑了什么验证、结果如何。再加上一条:涉及报错修复的,把根因追加到文件末尾的「踩坑记录」一节。

坚持几个月,这份文件的踩坑记录会长成项目自己的故障手册,比任何人的记忆都可靠。

小结

AGENTS.md 的写法原则就一句:只写「这个项目特有的、代码里看不出来的」东西。通用知识不用教,项目规矩必须明说。写一次,之后每次开工都省一遍口头交代。

(作者:云思思,平时主要折腾 ChatGPT 和 Codex 的实际用法。)

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 一、项目地图:目录都是干什么的
  • 二、技术栈与版本:把环境说死
  • 三、编码约定:只写和通用习惯不一样的
  • 四、禁区:哪些地方不许碰
  • 五、交付格式:汇报必须带什么
  • 小结
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档