AGENTS.md 文档规范

文章目录AGENTS.md 文档规范一、概述二、核心架构2.1 两层设计2.2 深层扩展三、设计原理为什么不把所有文档都放在 AGENTS.md 中四、如何让 AI 及时检查并更新 AGENTS.md利用 AI 的 hook 能力触发特定逻辑利用 PostToolUse 和 Stop hook 让 AI 在特定时机触发脚本SKILL.md 的内容AGENTS.md 文档规范本规范用于约定项目中基础知识文档的内容与结构辅助 AI 获取项目知识。本规范与具体 AI 工具无关应尽量脱离具体工具例如 Cursor、Claude Code 等。关于 Agent 文档AGENTS.md 简介一、概述AGENTS.md 是一个开放标准为 AI Coding Agent 提供项目级指引已被 60,000 开源项目采用兼容 GitHub Copilot、Cursor、Windsurf、OpenAI Codex、Gemini CLI 等主流工具。本规范定义了 AGENTS.md docs 两层文档架构的编写和维护规则目标是让 AI Agent 在每次对话中都遵守项目约定硬性约束始终加载让 AI Agent 按需获取详细参考不浪费上下文窗口让文档随代码同步演进不会过时二、核心架构2.1 两层设计项目根目录下存放一个 AGENTS.md 文件主要包含硬性约束、项目架构等信息同级根目录下有一个 docs 文件夹AGENTS.md 中的 docs 索引应简要说明每篇文档的用途和适用场景方便 AI 判断什么时候需要读取AGENTS.md (始终加载≤300 行) ├── 硬性约束 ← 每次对话都必须遵守的规则 ├── 关键约定摘要 ← 技术栈、目录结构、命名等速查 ├── 文档维护规则 ← AI 必须遵守的文档更新要求 └── docs/ 索引列表 ← AI 知道有哪些文档可按需加载以及何时加载 ├── ./docs/guides/xxx.md ├── ./docs/components/xxx.md └── ./docs/api/xxx.md2.2 深层扩展项目中的组件、模块也需要独立的文档来进行说明如下所示project-root/ ├── AGENTS.md ← 全局入口始终加载≤300 行 │ └── docs/ 索引列表 ← 项目级文档AI 按需加载 │ ├── ./docs/guides/xxx.md │ ├── ./docs/components/xxx.md │ ├── ./docs/api/xxx.md │ ├── ./docs/conventions/ │ └── ./docs/troubleshooting/ ├── docs/ ← 项目级文档目录 │ ├── xxxxx └── src/ └── components/ ├── ui-dialog │ ├── 组件内文件如 xxx.ts、xxx.vue 等 │ ├── AGENTS.md ← 组件的整体介绍 │ ├── docs ← 按需如果组件比较复杂可以增加此文件夹需要在 AGENTS.md 建立文档索引 │ ├── xxx.md └── 组件2/ ← 业务组件内部模块也可按需生成 AGENTS.md。可以在同级别创建 docs 文件夹其中的文件需要被同级别的 AGENTS.md 引用。该模块下的 AGENTS.md 最好在外层的 AGENTS.md 中引用这样可以形成一棵 AGENTS.md 文档树。AGENTS.md 层级不要太深最好不要超过 4 层否则文件过多会占用上下文。每个文件都要尽量控制大小建议控制在 200 行以内不要超过 500 行。根目录 AGENTS.md 应优先写清高频命令例如安装、启动、测试、构建、类型检查和代码检查命令。当目录结构、公共约定、常用命令、关键业务流程发生变化时应同步检查对应 AGENTS.md 和 docs 索引。三、设计原理为什么不把所有文档都放在 AGENTS.md 中问题全量加载两层架构上下文消耗全部内容占满窗口挤压实际任务空间仅根目录 AGENTS.md 始终加载其余按需规则遗忘长对话中关键约束被冗长内容稀释硬性约束始终在最前面灵活性无法控制加载哪些上下文AI 根据任务自主选择加载维护成本单文件膨胀难以维护每个文件独立维护减少冲突通过这种方式最终能够得到一棵由 AGENTS.md 连接的文档树示例如下project-root/ ├── AGENTS.md ← 全局入口始终加载≤300 行 │ └── 包含 docs/ 索引 模块 AGENTS.md 索引 ├── docs/ ← 项目级文档目录 │ ├── guides/ ← 开发指南 │ │ ├── getting-started.md │ │ └── deployment.md │ ├── components/ ← 组件通用文档 │ │ └── design-system.md │ ├── api/ ← API 文档 │ │ └── rest-api.md │ ├── conventions/ ← 编码规范 │ │ ├── naming.md │ │ └── git-workflow.md │ └── troubleshooting/ ← 常见问题 │ └── faq.md └── src/ └── components/ ├── ui-dialog/ ← 组件1 │ ├── index.ts │ ├── Dialog.vue │ ├── AGENTS.md ← 组件级入口 │ └── docs/ ← 组件级详细文档按需 │ ├── props-api.md │ └── usage-examples.md └──>四、如何让 AI 及时检查并更新 AGENTS.mdCursor 自动兼容 Claude Code 的 hook 配置。Codex 官方目前没有 hook 相关的概念。利用 AI 的 hook 能力触发特定逻辑修改.claude/settings.json中的内容兼容 Cursor{$schema:https://json.schemastore.org/claude-code-settings.json,hooks:{PostToolUse:[{matcher:Edit|Write,hooks:[{type:command,command:node .claude/hooks/agents-md-reminder.cjs}]}],Stop:[{matcher:,hooks:[{type:command,command:node .claude/hooks/agents-md-reminder.cjs}]}]}}利用 PostToolUse 和 Stop hook 让 AI 在特定时机触发脚本脚本内容#!/usr/bin/env node/** - agents-md-reminder.cjs - - 提醒 AI 在修改代码后检查并更新就近的 AGENTS.md - - 两阶段协作 - PostToolUse (Edit/Write) → 代码文件被修改时设置标记文件 - Stop → 标记存在则 block让 AI 自行判断是否需要更新 AGENTS.md - - AI 拥有完整上下文知道自己改了什么不需要 hook 告诉它具体文件列表。 - hook 只负责提醒AI 负责判断。 */constfsrequire(fs)constpathrequire(path)constSKIP()process.stdout.write({})constFLAG_FILEpath.join(__dirname,.code-modified)constchunks[]process.stdin.on(data,(chunk)chunks.push(chunk))process.stdin.on(end,(){try{constinputJSON.parse(Buffer.concat(chunks).toString())// PostToolUse: 代码文件被修改时设置标记 if(input.hook_event_namePostToolUse){if(input.tool_name!Writeinput.tool_name!Edit)returnSKIP()constfilePathinput.tool_input?.file_path||if(!filePath.includes(/src/))returnSKIP()if(!/\.(ts|tsx|js|jsx|less|css|scss|vue)$/.test(filePath))returnSKIP()fs.writeFileSync(FLAG_FILE,)returnSKIP()}// Stop: 标记存在则提醒 AI 检查 AGENTS.md if(input.hook_event_nameStop){if(input.stop_hook_active)returnSKIP()if(!fs.existsSync(FLAG_FILE))returnSKIP()fs.unlinkSync(FLAG_FILE)process.stdout.write(JSON.stringify({decision:block,reason:[If you have modified the code logic in /src/ directory, you MUST use the agents-md skill (invoke via Skill tool) to check and update the nearest AGENTS.md.,Reference: docs/agents-md/guide.md].join(\n)}))}}catch{SKIP()}})核心在process.stdout.write( JSON.stringify({ decision: block, reason: [ If you have modified the code logic in /src/ directory, you MUST use the agents-md skill (invoke via Skill tool) to check and update the nearest AGENTS.md., Reference: docs/agents-md/guide.md ].join(\n) }) )提示大模型在触发逻辑修改后必须调用 agents-md 这个 skill。SKILL.md 的内容agents-md/SKILL.md的内容--- ## name: agents-md description: 代码生成、整体任务完成之后创建或更新 AGENTS.md。当你完成了代码编写新增组件、修改逻辑、重构文件或者用户提到更新文档、更新 AGENTS、创建 AGENTS时使用此 skill。即使用户没有明确提到 AGENTS.md只要你刚修改了代码文件就应该检查是否需要同步更新文档。 allowed-tools: ## 决策流程 代码修改完成 ↓ 从修改文件所在目录开始(包含当前目录)向上查找 AGENTS.md最多3层注意**当前目录也要查找** ↓ 找到了吗 ├→ 是 → 读取该 AGENTS.md判断修改内容是否影响文档中已记录的部分 │ ├→ 有影响 → 同步更新结构、数据流、注意事项等 │ └→ 无影响 → 跳过 │ └→ 否 → 提示用户「是否在 xxx 目录下创建 AGENTS.md」 ├→ 用户同意 → 判断层级阅读对应指南文档生成 └→ 用户拒绝 → 跳过 ↓ 创建/更新完成后 → 检查上层文档是否已引用未引用则添加 ## 核心规则 - **嵌套不超过 4 层**从项目根到最深的 AGENTS.md 最多 4 级引用链 - **只更新与修改相关的部分**不要重写整个文档 - **注意事项是最有价值的部分** — 踩坑或发现约束时一定要记录 - 创建 AGENTS.md 后同目录下应有 CLAUDE.md 引用 AGENTS.md ## 指南文档 **先阅读对应的指南文档再动手写**用 Read 工具读取不要凭记忆生成 - **完整指引必读**docs/agents-md/guide.md — Checklist、创建流程、模板选择、更新策略、引用格式 - **项目根目录模板**docs/agents-md/root-agent.md - **子模块目录模板**docs/agents-md/sub-agent.md - **子模块引用格式**docs/agents-md/reference-sub.md这个文档中定义了大模型应该如何更新 AGENTS.md 文档。