[{"data":1,"prerenderedAt":535},["ShallowReactive",2],{"header-counts":3,"footer-counts":6,"wiki-agents-md":9},{"tools":4,"reviews":5},70,12,{"tools":4,"reviews":5,"playbooks":7,"news":8},15,13,{"id":10,"title":11,"body":12,"category":513,"description":86,"extension":514,"meta":515,"navigation":103,"path":516,"published":517,"relatedModels":518,"relatedTools":521,"seo":525,"slug":526,"stem":527,"summary":528,"tags":529,"updated":517,"__hash__":534},"wiki\u002Fwiki\u002Fagents-md.md","AGENTS.md",{"type":13,"value":14,"toc":502},"minimark",[15,20,24,38,41,44,64,71,74,80,271,276,290,293,313,325,328,383,386,456,459,462,498],[16,17,19],"h2",{"id":18},"什么是-agentsmd","什么是 AGENTS.md",[21,22,23],"p",{},"AGENTS.md 是一个放在仓库根目录的 Markdown 文件，给 AI 编码 agent 提供项目专属的操作指引——怎么装依赖、怎么跑测试、代码规范是什么、有哪些坑别踩。可以理解为「给 agent 看的 README」：README 是给人看的，AGENTS.md 是给 agent 看的。",[21,25,26,27,32,33,37],{},"它由 OpenAI 发起，2025 年 12 月连同 ",[28,29,31],"a",{"href":30},"\u002Fwiki\u002Fmcp.html","MCP"," 一起捐给 Linux 基金会的 Agentic AI Foundation（AAIF）。截至捐赠时已被 ",[34,35,36],"strong",{},"6 万+ 开源项目","采用，Devin、GitHub Copilot、Cursor、Codex 等主流工具原生读取，是当前跨工具的事实标准。",[16,39,40],{"id":40},"解决什么问题",[21,42,43],{},"在 AGENTS.md 之前，每家 agent 工具有自己的配置文件：",[45,46,47,55,61],"ul",{},[48,49,50,51],"li",{},"Cursor 用 ",[52,53,54],"code",{},".cursorrules",[48,56,57,58],{},"Claude Code 用 ",[52,59,60],{},"CLAUDE.md",[48,62,63],{},"其它工具各有各的约定",[21,65,66,67,70],{},"结果是：换个工具就得重写一份项目说明，团队里用不同工具的人各维护各的。AGENTS.md 想做的是「一次编写，所有 agent 都读」——类似 ",[52,68,69],{},".editorconfig"," 统一了编辑器配置那样，统一 agent 的项目上下文。",[16,72,73],{"id":73},"怎么写",[21,75,76,77,79],{},"放在仓库根目录，文件名就叫 ",[52,78,11],{},"。没有强制 schema，但社区约定俗成会包含这些部分：",[81,82,87],"pre",{"className":83,"code":84,"language":85,"meta":86,"style":86},"language-markdown shiki shiki-themes github-light github-dark","# AGENTS.md\n\n## 项目结构\n- `src\u002F` 业务代码\n- `tests\u002F` 测试，用 pytest\n- `scripts\u002F` 运维脚本\n\n## 构建与测试\n- 安装依赖：`pnpm install`\n- 跑测试：`pnpm test`\n- 单测单文件：`pnpm test path\u002Fto\u002Ffile.test.ts`\n- 类型检查：`pnpm typecheck`\n\n## 代码规范\n- 用 TypeScript strict 模式\n- 不要引入新的运行时依赖，先问\n- 提交前必须过 lint：`pnpm lint`\n\n## 注意事项\n- 不要改 `legacy\u002F` 目录，那是冻结代码\n- 数据库迁移必须可回滚\n","markdown","",[52,88,89,98,105,111,126,137,148,153,159,170,181,192,202,206,212,219,227,238,243,249,263],{"__ignoreMap":86},[90,91,94],"span",{"class":92,"line":93},"line",1,[90,95,97],{"class":96},"sq-ep","# AGENTS.md\n",[90,99,101],{"class":92,"line":100},2,[90,102,104],{"emptyLinePlaceholder":103},true,"\n",[90,106,108],{"class":92,"line":107},3,[90,109,110],{"class":96},"## 项目结构\n",[90,112,114,118,122],{"class":92,"line":113},4,[90,115,117],{"class":116},"s4XuR","-",[90,119,121],{"class":120},"sj4cs"," `src\u002F`",[90,123,125],{"class":124},"sVt8B"," 业务代码\n",[90,127,129,131,134],{"class":92,"line":128},5,[90,130,117],{"class":116},[90,132,133],{"class":120}," `tests\u002F`",[90,135,136],{"class":124}," 测试，用 pytest\n",[90,138,140,142,145],{"class":92,"line":139},6,[90,141,117],{"class":116},[90,143,144],{"class":120}," `scripts\u002F`",[90,146,147],{"class":124}," 运维脚本\n",[90,149,151],{"class":92,"line":150},7,[90,152,104],{"emptyLinePlaceholder":103},[90,154,156],{"class":92,"line":155},8,[90,157,158],{"class":96},"## 构建与测试\n",[90,160,162,164,167],{"class":92,"line":161},9,[90,163,117],{"class":116},[90,165,166],{"class":124}," 安装依赖：",[90,168,169],{"class":120},"`pnpm install`\n",[90,171,173,175,178],{"class":92,"line":172},10,[90,174,117],{"class":116},[90,176,177],{"class":124}," 跑测试：",[90,179,180],{"class":120},"`pnpm test`\n",[90,182,184,186,189],{"class":92,"line":183},11,[90,185,117],{"class":116},[90,187,188],{"class":124}," 单测单文件：",[90,190,191],{"class":120},"`pnpm test path\u002Fto\u002Ffile.test.ts`\n",[90,193,194,196,199],{"class":92,"line":5},[90,195,117],{"class":116},[90,197,198],{"class":124}," 类型检查：",[90,200,201],{"class":120},"`pnpm typecheck`\n",[90,203,204],{"class":92,"line":8},[90,205,104],{"emptyLinePlaceholder":103},[90,207,209],{"class":92,"line":208},14,[90,210,211],{"class":96},"## 代码规范\n",[90,213,214,216],{"class":92,"line":7},[90,215,117],{"class":116},[90,217,218],{"class":124}," 用 TypeScript strict 模式\n",[90,220,222,224],{"class":92,"line":221},16,[90,223,117],{"class":116},[90,225,226],{"class":124}," 不要引入新的运行时依赖，先问\n",[90,228,230,232,235],{"class":92,"line":229},17,[90,231,117],{"class":116},[90,233,234],{"class":124}," 提交前必须过 lint：",[90,236,237],{"class":120},"`pnpm lint`\n",[90,239,241],{"class":92,"line":240},18,[90,242,104],{"emptyLinePlaceholder":103},[90,244,246],{"class":92,"line":245},19,[90,247,248],{"class":96},"## 注意事项\n",[90,250,252,254,257,260],{"class":92,"line":251},20,[90,253,117],{"class":116},[90,255,256],{"class":124}," 不要改 ",[90,258,259],{"class":120},"`legacy\u002F`",[90,261,262],{"class":124}," 目录，那是冻结代码\n",[90,264,266,268],{"class":92,"line":265},21,[90,267,117],{"class":116},[90,269,270],{"class":124}," 数据库迁移必须可回滚\n",[272,273,275],"h3",{"id":274},"monorepo-的层级作用域","Monorepo 的层级作用域",[21,277,278,279,281,282,285,286,289],{},"AGENTS.md 支持目录层级：根目录放全局约定，子包目录可以放自己的 ",[52,280,11],{}," 覆盖\u002F补充。agent 会就近读取——改 ",[52,283,284],{},"packages\u002Fapi\u002F"," 下的代码时，优先读 ",[52,287,288],{},"packages\u002Fapi\u002FAGENTS.md","。",[16,291,292],{"id":292},"为什么重要",[45,294,295,301,307],{},[48,296,297,300],{},[34,298,299],{},"跨工具复用","：写一次，Claude Code \u002F Cursor \u002F Codex \u002F Devin 都能读，团队成员用什么工具都行",[48,302,303,306],{},[34,304,305],{},"降低 agent 出错率","：明确告诉 agent 测试怎么跑、哪些目录别碰，比让它瞎猜强得多",[48,308,309,312],{},[34,310,311],{},"进入中立治理","：捐给 Linux 基金会后不再被单一厂商控制，长期稳定性有保障",[21,314,315,316,320,321,289],{},"关于「为什么给 agent 喂对上下文这么关键」，见 ",[28,317,319],{"href":318},"\u002Fwiki\u002Fcontext-engineering.html","Context Engineering"," 和 ",[28,322,324],{"href":323},"\u002Fwiki\u002Fcontext-rot.html","Context Rot",[16,326,327],{"id":327},"常见踩坑",[45,329,330,344,358,368,377],{},[48,331,332,335,336,339,340,343],{},[34,333,334],{},"写成第二份 README","：AGENTS.md 是给 agent 的操作手册，重点是",[34,337,338],{},"可执行的命令","和",[34,341,342],{},"硬性约束","，不是项目介绍。别把 README 复制过来。",[48,345,346,349,350,353,354,357],{},[34,347,348],{},"命令写得不精确","：写 ",[52,351,352],{},"跑测试"," 没用，要写确切命令 ",[52,355,356],{},"pnpm test","。agent 会照着敲，含糊的指令等于没写。",[48,359,360,363,364,367],{},[34,361,362],{},"约束写成建议","：想让 agent 别动某目录，要写「不要修改 ",[52,365,366],{},"legacy\u002F","」，而不是「尽量避免」。agent 对强约束更敏感。",[48,369,370,373,374,376],{},[34,371,372],{},"过长","：塞进几千行规范反而稀释重点（这本身就是一种 ",[28,375,324],{"href":323},"）。挑最高频、最容易出错的点写，控制在一两屏内。",[48,378,379,382],{},[34,380,381],{},"不更新","：构建命令变了但 AGENTS.md 没改，agent 照着老命令跑就报错。把它当代码维护，跟着项目变更走。",[16,384,385],{"id":385},"与其它标准的关系",[387,388,389,405],"table",{},[390,391,392],"thead",{},[393,394,395,399,402],"tr",{},[396,397,398],"th",{},"文件",[396,400,401],{},"给谁看",[396,403,404],{},"作用",[406,407,408,420,430,442],"tbody",{},[393,409,410,414,417],{},[411,412,413],"td",{},"README.md",[411,415,416],{},"人",[411,418,419],{},"项目介绍、快速上手",[393,421,422,424,427],{},[411,423,11],{},[411,425,426],{},"AI agent",[411,428,429],{},"操作指引、构建\u002F测试\u002F约束",[393,431,432,436,439],{},[411,433,434],{},[28,435,31],{"href":30},[411,437,438],{},"agent ↔ 工具",[411,440,441],{},"连接外部工具和数据",[393,443,444,450,453],{},[411,445,446],{},[28,447,449],{"href":448},"\u002Fwiki\u002Fa2a.html","A2A",[411,451,452],{},"agent ↔ agent",[411,454,455],{},"agent 之间协作",[21,457,458],{},"AGENTS.md 解决「agent ↔ 项目」的约定，MCP 解决「agent ↔ 工具」的连接，二者互补——一个告诉 agent 项目怎么跑，一个让 agent 能调用外部能力。",[16,460,461],{"id":461},"延伸阅读",[45,463,464,476,483],{},[48,465,466,467,469,470,469,472],{},"概念：",[28,468,31],{"href":30}," \u002F ",[28,471,449],{"href":448},[28,473,475],{"href":474},"\u002Fwiki\u002Fai-agent.html","AI Agent",[48,477,478,479,469,481],{},"上下文：",[28,480,319],{"href":318},[28,482,324],{"href":323},[48,484,485,486,469,490,469,494],{},"工具：",[28,487,489],{"href":488},"\u002Fcoding\u002Fcli\u002Fclaude-code.html","Claude Code",[28,491,493],{"href":492},"\u002Fcoding\u002Fide\u002Fcursor.html","Cursor",[28,495,497],{"href":496},"\u002Fcoding\u002Fcli\u002Fcodex.html","Codex",[499,500,501],"style",{},"html pre.shiki code .sq-ep, html code.shiki .sq-ep{--shiki-default:#005CC5;--shiki-default-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold}html pre.shiki code .s4XuR, html code.shiki .s4XuR{--shiki-default:#E36209;--shiki-dark:#FFAB70}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":86,"searchDepth":107,"depth":107,"links":503},[504,505,506,509,510,511,512],{"id":18,"depth":100,"text":19},{"id":40,"depth":100,"text":40},{"id":73,"depth":100,"text":73,"children":507},[508],{"id":274,"depth":107,"text":275},{"id":292,"depth":100,"text":292},{"id":327,"depth":100,"text":327},{"id":385,"depth":100,"text":385},{"id":461,"depth":100,"text":461},"protocol","md",{},"\u002Fwiki\u002Fagents-md","2026-06-28",[519,520],"claude-opus-4-5","gpt-5-1-codex-max",[522,523,524],"coding\u002Fcli\u002Fclaude-code","coding\u002Fide\u002Fcursor","coding\u002Fcli\u002Fcodex",{"title":11,"description":86},"agents-md","wiki\u002Fagents-md","给 AI 编码 agent 看的项目说明文件：用一个放在仓库根目录的 Markdown 文件，告诉 agent 怎么装依赖、怎么跑测试、有哪些约定。被 6 万+ 项目采用，已成跨工具事实标准。",[11,530,531,532,533],"协议","标准","Agent","OpenAI","FCPr2JMZKTwu3v29KLQg2IBJB7d_QoCX_7oU-NGFnOs",1782663749253]