最近在 Hacker News 上看到一个很有意思的提问有人试过用一份“极简起步、随仓库一起生长”的 AGENTS.md 吗这个问题看起来很简单但真正维护过仓库的人都知道AGENTS.md 写少了AI 编程助手经常答非所问写多了文件变成一本没人愿意看的手册最后连你自己都不确定里面哪条规则已经过期。这篇文章就围绕这个场景展开AGENTS.md 应该怎么起步怎么在仓库演进过程中不断补充又不让它变成一堆僵尸文本。AGENTS.md 本质上是给 AI 编程助手看的仓库说明书。现在不少 AI 编码工具已经会在仓库里自动查找这份文件用它了解项目结构、命令规范、架构约定和常见坑。它的重要性在于AI 助手每次对话的上下文窗口有限它不会把一个几千行的 README 全部读进去但一份结构清晰的 AGENTS.md往往会在会话开始时就被加载直接影响助手后面所有代码建议的质量。换句话说这份文件写得怎么样基本决定了 AI 是“了解项目的老同事”还是“第一次打开代码库的外包新人”。这个问题的价值点在于它提出了一个与直觉相反的做法不追求第一步就写出完美文档而是从极简版本开始让文件跟随项目迭代自然生长。这种思路很适合正在快速演进的中小型仓库也适合团队里还没有形成文档文化的场景。我会在这篇文章里给出完整的落地路径初始 AGENTS.md 的最小结构、长大后的目录级维护策略、命令沉淀方式、过期内容清理方法以及一套可以直接套用的排查清单。1. AGENTS.md 核心能力速览能力项说明文件定位给 AI 编程助手读取的仓库级上下文说明与 README 面向人类读者形成互补主要作用让 AI 助手理解项目结构、技术栈、命令约定、架构约束和常见注意事项起步方式极简文件起步随仓库演进持续增补避免一次性写大而全维护粒度仓库根目录一份复杂模块或子目录可以单独放局部 AGENTS.md适用场景个人项目规范化、团队协作时提升 AI 辅助编程一致性、跨工具统一上下文常见误区一上来写几百行、规则不互相协作、命令过期后无人更新、与 README 内容冲突需要配套清晰的目录结构、可执行命令、README、变更记录不解决什么不能替代代码注释不能替代架构文档不能替代人类 Code Review从这张表能看出AGENTS.md 不是一个“写一次就完事”的交付物而是一个需要持续维护的工程文件。它的价值不是文本量而是稳定性和可执行性。真正有用的 AGENTS.md往往不是第一次提交时写出来的而是在十几次修 bug、补功能、改目录之后逐渐沉淀出来的。2. 为什么是“极简起步”而不是“一次写满”很多人第一次看到 AGENTS.md 时会下意识地想把所有东西都写进去项目背景、目录结构、每一个模块的设计、所有的命令、全部的编码规范。这个冲动可以理解但实际效果通常不好。第一你在项目早期对仓库的核心约束还没有清晰认知。架构还没稳定依赖可能要换目录可能重构命令可能改名。你现在花三小时写出来的规范可能在两周后就过时了。过时的规则比没有规则更可怕因为 AI 助手会基于这些规则给出与现状不符的建议你需要额外花精力去识别和纠正。第二大段没有边界的文本会稀释注意力。AI 编程助手加载上下文文件后需要从中提取与当前任务相关的信息。如果一个 300 行的 AGENTS.md 里有 80% 是与当前模块无关的内容助手可能会漏掉真正重要的那几条约束。极简文件的最大优势是信噪比高每条规则都有明确作用。第三从维护心态看极简文件更容易坚持更新。今天加一条命令明天补一个模块说明这种增量更新几乎没有心理负担。反过来维护一份 300 行的文档大多数人的做法是“等有空再大改”然后就没有然后了。所以“极简起步随仓库生长”的核心逻辑是把 AGENTS.md 当作代码库的一部分来维护而不是当作一次性交付的文档。它应该有生命周期有变更记录有删除机制。开始的时候只写那些“不写就一定会出问题”的内容剩下的等它真正成为阻碍时再补。3. 从零开始最小 AGENTS.md 应该写什么一份极简 AGENTS.md不需要面面俱到但必须包含四类基本内容项目是什么、怎么跑起来、目录怎么组织、有哪些绝对不能违反的约定。下面是适合大多数中小型仓库的最小模板可以直接复制到仓库根目录再按实际情况修改。# AGENTS.md ## 项目简介 - 项目名称这里写项目名 - 一句话定位这个项目解决什么问题 - 技术栈主要语言、框架、依赖管理工具 ## 常用命令 - 启动开发环境make dev 或 npm run dev - 运行测试make test 或 npm test - 构建产物make build 或 npm run build - 代码检查npm run lint ## 目录结构 - src/源代码 - tests/测试文件 - docs/文档 - scripts/辅助脚本 ## 核心约定 - 不要直接修改 dist/ 目录下的文件它是构建产物 - 新增依赖前先和项目维护者确认 - 数据库迁移文件只追加不修改已合并的历史迁移这个文件控制在 20 到 30 行之间每一条信息都是 AI 助手在第一次接触仓库时最需要知道的。你看它写得很简单但实际覆盖了几个关键判断维度助手能知道这个项目用什么技术栈能知道跑测试和构建的命令能知道哪些目录是生成物不能手改。接下来是一个很关键的动作把它提交到仓库然后在真实开发场景中使用 AI 编程助手观察它是否还会犯和上下文相关的低级错误。如果不再犯说明这份文件已经覆盖了基本问题暂时不需要扩展。我还建议在第一版就加入一个“变更说明”区域哪怕初始只有一行“创建初始版本”它会给后续的版本管理提供锚点。以后每次增补规则时在这里追加一行记录这份文件的演进历史就会非常清晰。4. 随仓库成长的三种补充机制当你已经带着极简版 AGENTS.md 跑了一段时间开始频繁遇到同一类问题时就该考虑让文件生长了。下面这些信号值得关注AI 助手反复猜测项目命令导致执行错误。AI 助手多次修改了不该修改的生成文件。新加入的模块总被助手忽略因为根目录描述里没有提到它。同样的错误提示反复出现说明规则没有沉淀下来。三个信号出现任意一个就说明当前 AGENTS.md 的信息量已经不够了。下面是三种常用的补充机制。4.1 目录级维护模块太大就拆局部文件仓库变大之后所有规则都堆在根目录的 AGENTS.md 里会随着体积增长而逐渐失效。更稳妥的做法是根目录文件只保留全仓库通用的规则复杂模块或子目录单独维护一份局部 AGENTS.md。# src/backend/AGENTS.md ## 模块边界 - 本模块只处理业务逻辑不直接访问数据库 - 对外提供 REST API接口定义见 api.md - 新增接口必须包含输入校验和错误码 ## 本地开发 - 本地启动docker compose up backend - 单元测试go test ./... - 数据库重置make db-reset仅在开发环境使用 ## 特别注意 - 所有时间字段统一使用 UTC 存储 - 不要在业务代码中执行 SELECT *必须显式指定字段放在模块目录下的局部说明加载距离更短AI 助手在处理对应目录的文件时更容易命中。而且局部文件的维护边界清晰谁负责这个模块谁就负责它的 AGENTS.md不需要等根目录负责人统一更新。4.2 命令沉淀把“反复解释过的事”固化成脚本AI 助手在对话中经常会出现“执行什么命令来测试”这样的疑问。如果同一个问题被问了三次以上就应该把它写进命令列表甚至写成一个脚本。命令沉淀有几个原则优先提供标准命令入口Makefile、npm scripts、taskfile而不是散落的命令行参数。如果项目里有“开发环境重置”“快速跑通全部测试”这类高频操作必须写进 AGENTS.md。命令带副作用时要明确标注例如“会删除本地数据库”“需要外部服务依赖”。# Makefile 片段AI 助手可以依据 AGENTS.md 中的说明直接调用 .PHONY: dev test lint build reset dev: npm run dev test: npm test lint: npm run lint build: npm run build reset: echo 重置本地数据库仅限开发环境 docker compose down -v docker compose up -d db当 AGENTS.md 里写着“开发环境重置用make reset”时AI 助手就不会再自己发明一套命令行参数。这样既减少了沟通成本也避免了误操作。4.3 变更记录与过期标记让旧规则能被清理任何长期维护的文档都会积累过期内容。AGENTS.md 最大的风险不是写得太少而是写着写着没人敢删。为了解决这个问题可以在文件里给每条规则打上“生效日期”或“最后一次验证日期”并保留一个“待观察区”来放置不确定的规则。## 核心约定 - [2025-01-05 新增] 后端返回的时间统一使用 ISO 8601 字符串不再使用时间戳 - [2025-02-18 更新] 测试命令由 npm test 改为 make test旧命令已废弃 - [待验证] 当前部署使用 PM2后续如果迁移到 Docker需要同步更新本文件 - [2024-11-01 已过期] ~~移动端支持 QQ 登录~~2025-01 已下线等待清理这种做法不复杂但非常有价值。AI 助手读到“过期标记”后会倾向于不采纳这些旧规则。而人工维护者看到“待验证”和“已过期”就能快速判断哪些规则该删、哪些该重写。这份文件会从“静态文档”变成“活文档”。5. 实战示例从 20 行到 200 行的演进光说方法论不够下面用一个模拟案例来展示 AGENTS.md 的完整成长路径。假设你有一个 Web 应用仓库最初只有前端代码两行说明就能表达。随后加入后端、数据库迁移、部署脚本文件内容随之增加。初始阶段项目只有一个 React 前端。# AGENTS.md ## 项目简介 - 前端单页应用技术栈 React TypeScript - 包管理使用 pnpm ## 常用命令 - 安装依赖pnpm install - 本地启动pnpm dev - 构建pnpm build - 测试pnpm test ## 目录结构 - src/源码 - src/components/通用组件 - src/pages/页面 ## 核心约定 - 修改样式优先使用 Tailwind 工具类 - 不允许在组件内部直接写内联样式跑了一个月之后团队发现几个反复出现的问题AI 助手总是不理解后端接口在哪儿、总是改到构建产物、总是对数据库迁移文件做错误操作。于是文件开始增长。# AGENTS.md ## 项目简介 - Web 应用仓库React 前端 Node.js 后端 - 前端技术栈React TypeScript Tailwind - 后端技术栈Node.js Express Prisma - 包管理使用 pnpm后端 API 文档见 docs/api.md ## 常用命令 - 安装依赖pnpm install - 启动前端pnpm dev:web - 启动后端pnpm dev:server需要本地 PostgreSQL - 运行全部测试pnpm test - 数据库迁移pnpm prisma:migrate - 数据库重置pnpm prisma:reset仅限开发环境会清空本地数据 ## 目录结构 - web/React 前端源码 - web/src/components/通用组件 - web/src/pages/页面 - server/Node.js 后端源码 - server/src/routes/路由定义 - server/src/services/业务逻辑 - server/prisma/数据库 schema 与迁移文件 - dist/构建产物禁止直接修改 ## 核心约定 - 禁止修改 dist/ 下任何文件它们是构建生成物 - 数据库迁移文件只追加不修改已合并的历史文件 - 新增后端接口时必须同步更新 docs/api.md - 修改数据库 schema 后必须生成迁移文件 - 前端请求后端接口时统一通过 server/src/routes 层转发禁止在组件里直接拼接数据库模型字段 - 时间字段统一使用 UTC 存储前端展示时再转本地时区 ## 变更记录 - [2025-01-05] 初始版本 - [2025-01-20] 加入后端目录结构和数据库约定 - [2025-02-10] 加入 API 文档同步要求可以看到文件从 20 行左右增长到了约 60 行但增长的部分都是“实际遇到问题才补的规则”没有一条是拍脑袋写出来的。这种生长方式的好处是每一条内容都有出处都有真实场景支撑。AI 助手按照这套规则工作后很大概率不会再犯前面提到的几类错误。如果项目继续扩大比如新增了客户端、后台管理端、Python 数据处理模块那么根目录文件就不需要再继续膨胀而是应该把对应模块的规则拆到局部 AGENTS.md 中根目录只保留跨模块的公共约定。6. 如何防止 AGENTS.md “长死”文档写到后面容易失控AGENTS.md 也一样。一个文件如果变得太长、太碎、太抽象AI 助手加载效果会下降。这里提供几个实用的控制手段。第一为文件设置边界。超过 200 行是一个危险信号根目录 AGENTS.md 尽量控制在 100 行左右更细的内容拆分到局部文件或引用到单独文档中。你可以把行数限制本身写进维护说明提醒自己和团队不要无限膨胀。第二建立定期审查机制。并不需要很复杂可以在每次发版前扫一眼 AGENTS.md确认命令是否还有效、目录引用是否还对。也可以用脚本做基础检查比如验证文件里出现的命令是否真的存在于 Makefile 或 package.json 中。#!/usr/bin/env python3 检查 AGENTS.md 中出现的 make 目标是否真实存在。 import re from pathlib import Path content Path(AGENTS.md).read_text(encodingutf-8) makefile Path(Makefile).read_text(encodingutf-8) # 提取 AGENTS.md 中反引号包裹的 make 命令 commands re.findall(rmake (\w), content) # 提取 Makefile 中的 target targets set( re.findall(r^([a-zA-Z0-9_-]):, makefile, flagsre.MULTILINE) ) missing [cmd for cmd in commands if cmd not in targets] if missing: raise SystemExit(fAGENTS.md 中引用了不存在的 make 目标: {missing}) print(AGENTS.md 命令检查通过。)第三给规则排序。越靠前的规则权重越高。文件的顶部区域专门放“绝对不能违反的硬性约束”中间放“常用命令和结构说明”底部放“变更记录和待办事项”。AI 助手读取上下文时通常会更关注文件开头部分这个顺序能保证关键规则被优先处理。第四接受删除。不要因为“这条规则当时花了很多心思写”就不敢改。AGENTS.md 的生命力来自持续修订。任何无法在今天帮助 AI 更好工作的内容都应该移到待清理区或直接删除。7. 常见问题与排查方法实际使用 AGENTS.md 时会遇到一些典型问题。下面这张表格可以作为排查清单。问题现象可能原因排查方式解决方案AI 助手不读 AGENTS.md文件名拼写错误或位置不对检查仓库根目录是否存在且文件名完全匹配重命名为根目录下的 AGENTS.md助手读取了但效果不明显上下文被其他说明覆盖或文件中的指令不够具体在对话中直接询问助手“请总结 AGENTS.md 内容”压缩描述把关键规则前置去除模糊表述命令反复说错AGENTS.md 中的命令与项目实际命令不一致对比脚本命令与 package.json/Makefile更新为当前可执行命令修改生成文件没有明确标注哪些目录是构建产物检查 AGENTS.md 是否写明禁止修改的目录加入“禁止直接修改 dist/ 等生成目录”的硬性约束局部模块被助手忽略根目录文件没有模块索引或局部文件加载不到检查模块目录是否存在 AGENTS.md补充根目录索引或增加模块级说明文件太乱找不到关键信息内容堆积没有优先级和分区打开文件查看标题结构按“硬性约定—常用命令—目录说明—变更记录”重新组织规则过时之后仍在生效过期内容没有标记AI 无法区分新旧检查文件内是否有日期或状态标记为规则补充新增/更新日期过期的移入待清理区多工具读取行为不一致不同 AI 工具对 AGENTS.md 的支持程度不同查阅工具的官方文档确认支持情况统一约定部分场景用 CLAUDE.md 或 cursor 规则作为补充排查思路可以很直接先确认文件存在且拼写正确再确认内容是否更新到当前仓库状态最后确认关键规则是否放在高优先级位置。绝大多数问题都出在这三个环节。8. 最佳实践AGENTS.md 与项目文档体系协同AGENTS.md 不应该取代 README、架构文档和 API 文档它更像是这些文档的导航入口和“执行摘要”。一份合理的文档体系应该让 AI 助手先读 AGENTS.md再按需深入到具体文档。一个比较推荐的分工是README 告诉人类开发者这个项目是什么怎么跑起来。AGENTS.md 告诉 AI 助手这个项目的关键约束、命令入口、目录边界是什么。架构文档描述模块关系和设计决策。API 文档提供接口定义和调用约定。变更记录记录线上行为和重要决策。如果 AGENTS.md 里出现了需要长篇幅展开的内容不要直接把它全抄进去而是写一个链接引用让 AI 助手知道“需要时去读某个文件”。比如## 核心约定 - 新增 API 接口前阅读 docs/api-design.md并遵守其中的接口版本规范 - 数据库变更必须基于 prisma/schema.prisma 生成迁移文件迁移规范见 docs/migration-guide.md这种做法的好处是AGENTS.md 保持精简AI 助手在遇到具体任务时能知道去查哪个文件而不是在同一个长文件里大海捞针。另一个工程化建议是把 AGENTS.md 的更新纳入常规开发流程。比如当 PR 中涉及命令变更、目录结构变更或新模块引入时要求同步检查 AGENTS.md 是否需要更新。这不是额外负担而是文档与代码的一致性保障。如果你用的是 GitHub 或类似平台的 PR 模板可以在模板里加一个 issue 勾选项例如“是否同步更新了 AGENTS.md”。使用 AGENTS.md 时还有一个容易忽略的点版权和隐私。如果你在仓库中使用了 AGENTS.md 来约束 AI 编程助手注意不要在其中写入敏感信息例如数据库密码、密钥、内部服务地址。它不是加密文件推送仓库后等同于公开。任何涉及权限的内容都应该使用环境变量或密钥管理系统而不是文档。此外AI 编程助手生成的代码依旧需要人工审查。AGENTS.md 可以帮助助手降低重复性错误但不能代替你对架构设计、安全性、兼容性的判断。实际落地时可以把“AI 助手必须通过 AGENTS.md 了解约定但最终代码质量由开发者把关”作为团队共识。9. 总结与下一步如果你现在还没有 AGENTS.md不用急着写一份大而全的规范。按这篇文章的方式先写 20 行最核心的上下文文件提交到仓库在日常 AI 编程中观察哪里反复出错再针对性地补规则。每一轮补充都记录日期和变更原因。等仓库足够复杂时再把根目录文件拆分到局部目录让 AGENTS.md 永远保持“够用、可读、可删”。如果已经有了一份 AGENTS.md可以试着做一次清理把硬性约束放在最前面补上变更记录给过期内容打上标记删除所有你不敢确认还有效的规则。这个过程不会超过半小时但对 AI 编程助手后续的使用体验改善非常明显。下一步可以再引入一个简单的检查脚本把 AGENTS.md 中的命令与 Makefile、package.json 绑定起来防止仓库演进后文档悄悄失真。这是我维护多个仓库下来觉得最值得长期坚持的一条习惯把文档当作代码把维护文档当作日常开发的一部分。