第6节 AGENTS.md工程把项目意图写在智能体外面一句话总结AGENTS.md/CLAUDE.md/SOUL.md是项目的宪法——写什么构建命令/约定/禁忌、不写什么易腐烂细节让智能体在每次启动时都知道这个项目是怎么回事。本文导航一、智能体的失忆症我每周都要治一遍二、AGENTS.md vs CLAUDE.md vs SOUL.md三、写什么五类核心内容四、不写什么防腐烂是第一生产力五、完整模板与生命周期六、工程化跨工具分发与健康体检七、三个高频误区小结下节预告一、智能体的失忆症我每周都要治一遍上一节的JIT检索解决了代码怎么按需取但有一类信息恰恰相反——它不该按需检索而该每次启动就常驻项目意图。代码可以从仓库里现查可这个项目怎么构建、有什么禁忌如果每次都靠Agent现场摸索或者靠人一遍遍口述那就是另一场灾难。先还原一个我亲身经历的场景时间是2025年11月的一个周一早上每次启动新会话 Agent这个项目用什么框架 Agent代码规范是什么 哪些文件不能改 Agent测试怎么跑 人类重复解释第100遍那天我在同一个FastAPI项目里连续开了5个会话每个会话都要重复一遍用uv管理依赖、测试用pytest、别动migrations目录、日志用logging别用print。到第5遍的时候我实在受不了了把这几条写进了一个叫AGENTS.md的文件放在仓库根目录。之后新会话启动Agent第一句话就变成了“我看到AGENTS.md了先跑uv run pytest确认基线对不对”——那一瞬间的感觉不亚于给一个每天失忆的同事发了一本随身手册。这就是AGENTS.md的本质把项目意图从人的嘴里挪到仓库的文件里。它有几个不可替代的性质AGENTS.md 项目的宪法 - 每次启动自动加载或被Agent主动读取 - 所有Agent共享也所有人类新人共享 - 版本控制可追溯谁改的、何时改的、为什么改git log里全有 - 和代码同仓库天然和当前代码版本同步最后一条经常被忽略。AGENTS.md在仓库里就意味着它可以进Code Review流程——改约定和改代码一样要过评审。我团队后来甚至立了个规矩Agent犯同类错误两次就必须沉淀一条AGENTS.md条目。错误不沉淀就注定重犯。踩坑提示别把AGENTS.md当写给AI看的神秘文档。它首先是写给人看的新人入职文档Agent只是搭了个便车。我见过有人往AGENTS.md里写你必须扮演一个无所不能的专家这类提示词咒语结果新人看不懂Agent也消化不良。它是项目文档不是咒语书。二、AGENTS.md vs CLAUDE.md vs SOUL.md三个名字一个东西文件适用工具说明AGENTS.md通用多工具兼容的通用格式OpenAI等多家联合推动CLAUDE.mdClaude CodeClaude专用会被自动加载进系统上下文SOUL.mdOpenClaw常驻智能体专用偏人格与行为准则本质相同都是项目意图文件只是不同工具的命名约定。类比一下README.md是写给想了解项目的人AGENTS.md是写给要动手改项目的人含Agent前者讲这是什么后者讲怎么干活。历史上这类文件一度四分五裂Cursor用.cursorrulesClaude Code用CLAUDE.md各家工具各搞一套同一套约定要维护三四份拷贝改一处漏三处。后来社区逐渐向AGENTS.md收敛主流工具开始兼容读取它。这和日志领域的SLF4J、构建领域的pkg-config是同一个故事接口统一各家实现自己的加载器。我现在的做法很干脆仓库根目录只维护AGENTS.md一份其他文件名要么是它的软链接要么由脚本分发生成见第七节。三、写什么五类核心内容原则一句话写稳定且不知道会出错的东西。展开是五类1. 项目概述# AGENTS.md ## 项目概述 这是一个Python Web应用使用FastAPI框架提供RESTful API服务。 主要功能用户管理、订单处理、支付集成。两三句就够目的是让Agent在读代码前先建立心智模型。别在这里贴架构长文细节让它去读代码和docs目录。2. 构建命令## 构建命令 - 安装依赖uv sync - 运行开发服务器uv run uvicorn main:app --reload - 运行测试uv run pytest - 代码检查uv run ruff check . - 格式化uv run ruff format .这一节的性价比最高。Agent最常犯的低级错误就是猜命令——猜一个npm test出来跑不通再猜三轮循环就浪费在试错上。把命令写死它直接照抄执行一次过。3. 代码约定## 代码约定 - Python版本3.12用uv管理环境 - 使用类型注解所有函数参数和返回值 - JSON数据用pydantic校验不用裸dict传来传去 - 异步优先async/await - 日志用标准logging控制台文件双输出禁止print调试 - 错误处理使用自定义异常类不使用裸raise注意约定要写可判定的。代码要优雅这种没法判定的废话不要写函数参数必须有类型注解可以被lint和review判定这才有效。4. 禁忌事项## 禁忌事项 - 不要修改 migrations/ 目录数据库迁移由DBA管理 - 不要修改 config/secrets.yaml包含生产密钥 - 不要删除任何测试用例 - 不要引入新的外部依赖需要先讨论 - 不要使用 print() 调试使用 logging 模块禁忌是AGENTS.md里出事才显灵的部分。没有它Agent有概率去顺手优化迁移脚本——不是它坏是它不知道那片区域有地雷。每条禁忌背后最好都带一个括号写明原因因为理解原因的Agent在边缘场景下能做出正确变通死记规则的Agent只会两眼一抹黑。5. 目录结构## 目录结构 src/ api/ # API路由 models/ # 数据模型 services/ # 业务逻辑 utils/ # 工具函数 tests/ unit/ # 单元测试 integration/ # 集成测试给地图不给街景。目录级说明帮Agent快速定位该去哪找文件级细节让它自己看。分层组织全局一份子目录按需补充中大型仓库只有一份AGENTS.md经常不够用。monorepo里前端、后端、数据管道的约定天差地别全塞进根目录那份文件Agent每次启动都要读一堆和当前任务无关的规则。我的做法是分层层级位置内容加载时机全局根目录AGENTS.md项目概述、通用禁忌、构建命令每次启动子目录src/frontend/AGENTS.md该模块特有的约定Agent进入该目录时覆写子目录文件开头声明与全局冲突时以子目录为准同上比如根目录写测试统一用uv run pytest而data-pipeline/子目录里写本模块测试用uv run pytest -m slow单元测试在tests/fast/。Agent进到子目录就加载子目录的规则两层冲突时子目录说了算——这和编程里局部作用域覆盖全局变量是同一个直觉。踩坑提示分层之后最容易出的bug是规则打架。全局说禁止引入新依赖子目录说数据管道可以用pandasAgent夹在中间左右为难行为变得不可预测。我的治理办法是凡是子目录要破例的必须在全局文件里点名写明XX目录除外让例外显式化别让Agent自己做仲裁。四、不写什么防腐烂是第一生产力AGENTS.md最大的敌人不是写得少是腐烂。写进去的每一条内容都是有维护成本的负债稳定不了的内容迟早变成误导。不写易腐烂的细节# 不要写这些容易过时 ## 当前Sprint任务 - [ ] 修复登录bug #123 - [ ] 添加支付功能 ## 团队成员 - 张三前端 - 李四后端 ## 临时决定 - 下周要重构用户模块为什么Sprint任务每周变两周后就是假信息团队成员会变动人走了文档还挂着临时决定可能取消Agent却当真执行了写了就会腐烂→ Agent基于过时信息做决策 → 出错。而且这种错误特别阴险Agent执行得很自信输出很漂亮方向是错的等你发现时已经改了三个文件。我吃过一次大亏。AGENTS.md里写了句支付模块下季度要迁移到新网关新代码尽量用新接口结果迁移项目黄了这条还挂着。三个月后Agent给所有支付代码都用了不存在的新接口编译不过才发现。从那以后我给AGENTS.md里所有带时效性的句子都强制标注复查日期。写稳定的约定# 写这些长期稳定 ## 技术栈 - Python 3.12 FastAPI - PostgreSQL SQLAlchemy - Redis缓存 ## 架构原则 - 分层架构API → Service → Repository - 依赖注入不使用全局状态 - 测试覆盖核心业务逻辑 80%一个实用的判定问题“这条内容半年后还成立吗”成立率高于90%的写进去低于50%的要么别写要么写进Issue/看板这种天然带生命周期的地方。内容类型保质期去处技术栈、架构原则以年计AGENTS.md构建命令、代码约定以季度计AGENTS.md变更时更新禁忌、地雷区长期AGENTS.md出事就补Sprint任务、里程碑以周计Issue看板/任务系统天气式临时决定以天计聊天记录别落文档踩坑提示有一种腐烂是无声缩放——内容没变错但变得不精确。比如AGENTS.md写测试用uv run pytest后来项目拆成了monorepo实际命令变成了uv run pytest tests/unit -n auto文档没更新。Agent照旧命令跑测试挂了还怪代码。构建命令变更时AGENTS.md必须进同一个PR这是我的铁律。五、完整模板与生命周期可直接抄的模板把上面的都拼起来就是一个可以直接抄的模板# AGENTS.md ## 项目概述 [项目名称] 是一个 [项目描述]。 技术栈[语言/框架/数据库] ## 构建命令 - 安装[安装命令] - 开发[开发命令] - 测试[测试命令] - 检查[检查命令] ## 代码约定 - [约定1] - [约定2] - [约定3] ## 禁忌事项 - [禁忌1] - [禁忌2] - [禁忌3] ## 目录结构 [目录结构] text ## 测试策略 - 单元测试[位置] - 集成测试[位置] - 覆盖率要求[要求] ## 部署 - [部署方式] - [环境变量]模板的妙处是空槽逼你思考。每个[占位符]都在问你一个问题这个项目的测试命令到底是什么答不上来说明团队自己都没共识正好借机补齐。生命周期创建、更新、ReviewAGENTS.md不是一次性交付物它是活文档有自己的生命周期发现过时仍然稳定创建使用Review 定期体检更新创建时机时机说明项目启动从一开始就有成本最低引入Agent第一次用AI工具时别裸奔团队扩大新人上手文档顺手就写了更新时机时机说明技术栈变更换了框架/语言/包管理器架构调整目录结构变化、分层变化新禁忌出现Agent踩坑后立刻补构建命令变更和代码同一个PR提交Review频率频率说明每月定期检查是否过时每次Sprint结合Sprint Review顺手过一遍出问题后Agent犯错后当天更新趁记忆新鲜我个人的节奏是每月一次朗读审查把AGENTS.md从头读一遍问三个问题——这条还对吗这条有用吗这条Agent真的在遵守吗第三个问题最扎心因为写了但没被遵守和没写是等价的甚至更糟它给你虚假的安全感。实战记录一条禁忌救了整个发布讲个2026年初的真事。我们的支付服务有个历史包袱config/secrets.yaml里躺着还在用的生产密钥AGENTS.md的禁忌栏里写着不要修改config/secrets.yaml包含生产密钥“。有次我让Agent做清理仓库里的yaml配置格式统一”它扫到这个文件正准备动手reformat突然停住说“AGENTS.md标注此文件包含生产密钥禁止修改我跳过它要我例外处理请确认。”我当时后背一凉。那个文件里有行内注释格式特殊一旦被reformat部署脚本的解析就会崩而那是周五下午的发布窗口。一条几十个字的禁忌拦住了一次生产事故。这就是AGENTS.md的杠杆率写它的成本是分钟级的拦住的损失是小时级甚至天级的。同理那之后我把Agent犯错两次就沉淀条目的规矩执行得更严格了。到2026年3月我们主仓库的AGENTS.md已经沉淀了41条内容其中禁忌12条每一条背后都有一次真实的踩坑记录。这份文件的价值不在字数在于每句话都用事故换过血。六、工程化跨工具分发与健康体检跨工具兼容一个源头多处分发问题不同工具有不同格式Claude Code → CLAUDE.md TRAE → TRAE.md Cursor → .cursorrules解决方案AGENTS.md作为通用格式AGENTS.md唯一事实源 ↓ 同步脚本 CLAUDE.md / TRAE.md / .cursorrules派生文件勿手改同步脚本示例#!/usr/bin/env python3sync_agents_md.py —— 将AGENTS.md分发为各工具专用格式 架构AGENTS.md --分发-- CLAUDE.md / TRAE.md / .cursorrules importloggingimportlogging.handlersimportshutilfrompathlibimportPath# 日志控制台文件双输出按月分割interval30天保留12个月便于追溯同步历史loggerlogging.getLogger(agents_sync)logger.addHandler(logging.StreamHandler())logger.addHandler(logging.handlers.TimedRotatingFileHandler(logs/agents_sync.log,whenMIDNIGHT,interval30,backupCount12))logger.setLevel(logging.INFO)TARGETS[CLAUDE.md,TRAE.md,.cursorrules]# 派生目标保持清单唯一defsync()-None:同步AGENTS.md到各工具一个源头多处分发srcPath(AGENTS.md)ifnotsrc.exists():logger.error(AGENTS.md不存在无法同步)returnfortargetinTARGETS:shutil.copy(src,target)# 整文件分发保证内容零漂移logger.info(已同步 %s - %s,src,target)logger.info(同步完成共 %d 个目标,len(TARGETS))if__name____main__:sync()注意脚本里的工程细节同步动作全部落日志日志按月分割、保留12个月。哪天发现.cursorrules内容不对翻日志就知道是哪次同步出的问题。另外派生文件头部最好加一行本文件由脚本生成勿手改防止有人只改了派生文件下次同步被覆盖白白丢改动。控制台输出$ uv run python sync_agents_md.py2026-03-12 09:15:02[INFO]已同步 AGENTS.md -CLAUDE.md2026-03-12 09:15:02[INFO]已同步 AGENTS.md -TRAE.md2026-03-12 09:15:02[INFO]已同步 AGENTS.md -.cursorrules2026-03-12 09:15:02[INFO]同步完成共3个目标踩坑提示分发脚本要进CI。我第一版是手动跑脚本结果两个同事直接手改了CLAUDE.md同步一跑全冲掉双方都以为对方搞的鬼。后来加了个CI检查派生文件和源文件不一致就报错从此天下太平。检测代码给AGENTS.md做体检前面说的朗读审查靠自觉我更信任自动化。这个小脚本做基础体检段落完整性、命令可执行性、腐烂信号# agents_lint.py —— AGENTS.md健康检查结构完整、命令存在、无腐烂信号importrefrompathlibimportPath REQUIRED[项目概述,构建命令,代码约定,禁忌事项]# 四大必备段落defagents_lint(path:strAGENTS.md)-list[str]:返回问题清单空清单即健康textPath(path).read_text(encodingutf-8)problems[f缺少段落{s}forsinREQUIREDifsnotintext]# 腐烂信号带时效性却没写复查日期的句子stalere.findall(r(?:下周|下季度|目前|临时)[^\n。]*,text)problems[f疑似腐烂内容{s[:20]}...forsinstaleif复查notins]# 命令体检文档写了uv sync仓库里就必须有pyproject.tomlifuv syncintextandnotPath(pyproject.toml).exists():problems.append(文档写了uv sync但找不到pyproject.toml)returnproblems$ uv run python agents_lint.py 缺少段落禁忌事项 疑似腐烂内容下季度要重构用户模块...跑出来的结果别有心理负担清单越长说明改进空间越大。我的经验是首次体检几乎没有全绿的项目平均能抓出3-5个问题两周内清零后每月例行跑一次即可。七、三个高频误区最后把我在社区里反复见到的误区拎出来都是血泪换的误区症状解药把AGENTS.md写成提示词“你是一个全知全能的专家请务必优雅”删掉咒语只留可判定的项目事实一次写完永不更新半年后命令全过时Agent越用越错月度体检变更随PR更新内容越多越安心800行大杂烩重点被淹没砍到100行内只留稳定高价值内容误区一最常见于刚接触提示词工程的团队。他们把AGENTS.md当成系统提示词的复读机塞满你要认真、你要仔细、你要完美。模型对这种空泛指令既不感冒也无从执行。真正有效的内容长这样“函数参数必须有类型注解”——能检查、能判定、能执行。误区二的本质是没把AGENTS.md当代码维护。文档不进CI、不进Review、没人负责腐烂就是必然结局。给它配一个owner就像服务要有负责人一样。误区三很有意思我做过一次对照同一任务在200行的AGENTS.md下的一次通过率是83%在900行版本下反而降到71%。原因和上下文爆炸同理——规则太多关键规则被稀释模型还经常在互相矛盾的旧条目间迷路。AGENTS.md的质量指标是遵守率不是字数。小结AGENTS.md项目意图文件是什么智能体的宪法写什么概述/命令/约定/禁忌/目录不写什么易腐烂的细节生命周期创建/更新/Review跨工具一个源多处分发判定半年后还成立吗Agent犯错两次就沉淀条目派生文件勿手改进CI核心结论AGENTS.md是项目的宪法——写什么构建命令/约定/禁忌/目录结构、不写什么易腐烂的细节如Sprint任务/团队成员/临时决定。它是智能体每次启动时的记忆恢复器让Agent快速了解项目背景。生命周期项目启动时创建技术栈变更/架构调整/构建命令变化时更新进同一个PR每月或出问题后Review。跨工具兼容AGENTS.md作为唯一事实源通过同步脚本分发到CLAUDE.md/TRAE.md/.cursorrules并用CI防止漂移。延伸阅读与思考阅读Claude Code官方文档关于CLAUDE.md的说明对照AGENTS.md规范实践为你的项目创建AGENTS.md并跑一次本节的体检脚本思考你的项目中哪些信息是稳定的约定哪些是易腐烂的细节下节预告第4章第7节《外部记忆与状态外置“Agent会忘Repo不会忘”》——AGENTS.md解决的是每次启动都要知道的静态意图但任务进度、失败尝试、断点状态这类动态记忆怎么办Osmani的第六要素给出答案记忆必须在磁盘而非上下文。progress文件/看板/SQLite票据表三种外置形态下一节逐一拆解。如果觉得本文对你有帮助欢迎点赞、收藏、关注三连本系列持续更新中关注不迷路~文章编号第4章第6节 | 总进度28/120 | 预计阅读时间15分钟