如何写好AGENTS.md和CLAUDE.md:WuMing's Claude Skills的AI Agent指令文件最佳实践
如何写好AGENTS.md和CLAUDE.md:WuMing's Claude Skills的AI Agent指令文件最佳实践
AGENTS.md 与 CLAUDE.md 是写给 AI 编程助手看的"项目说明书",WuMing's Claude Skills 开源仓库把多年实战沉淀成了可直接套用的模板、审查量表和诊断方法。本文面向新手和普通用户,不贴大段代码,用最少的话讲清楚:这两份文件该怎么选、写多长、写什么、不写什么,以及如何让 AI Agent 干活更靠谱。
AGENTS.md 和 CLAUDE.md 是什么?为什么重要 📝
每次开启新对话,AI Agent 都是"失忆"状态——它不知道你的项目用什么技术栈、测试命令是什么、哪些目录绝对不能动。AGENTS.md / CLAUDE.md 就是解决这个问题的指令文件:它们会在每次会话时自动注入上下文,相当于给 AI 队友做一份"入职简报"。
一句话定位(来自 best-practices.md 的核心心智模型):
- 它们不是 README 的替代品,不是 API 手册,更不是"要像资深工程师一样思考"的人设口号墙
- 它们应该读起来像给资深工程师的技术交接简报:短、准、可执行
- 每一行都要能回答:"删掉这行,Agent 是不是更容易犯错?"答"否"就删
AGENTS.md vs CLAUDE.md:一份就够,还是两份都要?
很多人纠结到底建哪个文件。判断标准其实很简单:
| 你的场景 | 推荐文件 |
|---|---|
| 同时用 Codex、Copilot、Cursor 等多种工具 | 以 AGENTS.md 为准(工具中立,纯 Markdown) |
| 主要使用 Claude Code | CLAUDE.md(Claude 项目记忆) |
| 多工具都要 + 团队共享 | AGENTS.md 作为单一事实来源,CLAUDE.md 只写差异或引用 |
| 个人本地偏好(不想提交给团队) | CLAUDE.local.md 或用户级 memory |
三层记忆要分清:
- Global(全局):每个项目都重复的偏好,放用户级配置
- Project(项目):本仓库的命令、架构、约束、安全边界,放提交到 Git 的共享文件
- Local(本地):个人习惯、机器路径,绝不提交
⚠️ 常见错误:把个人偏好写进团队共享的
CLAUDE.md,或者同时维护两份内容分叉的文件。宁缺毋滥,不要维护两份会互相"跑偏"的副本。
写多长才合适?记住 150 行红线
指令文件会整段塞进上下文窗口,越长越稀释指令遵循效果。WuMing's Claude Skills 给出的量化建议:
| 阶段 | 目标行数 |
|---|---|
| 起步文件 | 20–30 行 |
AGENTS.md |
控制在 150 行以内 |
CLAUDE.md |
优先压到 80–120 行,200 行是软上限 |
| 超过 300 行 | 强烈考虑拆分成引用文档、嵌套文件或 skills |
判断标准很朴素:短而具体,胜过长而空泛。
该写什么?不该写什么?🧩
✅ 值得写的高价值内容
- 一两句话的项目背景:是什么、给谁用、最重要的目标
- 可复制粘贴的真实命令:安装、开发、测试、构建、Lint
- 目录地图 + "新代码放哪里"的放置规则
- Agent 猜不到的非默认约定(禁用的库、反直觉的行为)
- 测试要求与"完成标准"(done criteria)
- 安全边界:哪些操作必须先确认
- 反复踩过的坑(gotchas)
- 指向深层文档的链接 + "什么时候读(Read when)"触发条件
❌ 坚决不写的内容
- 项目历史、营销文案、大段背景故事
- "保持代码整洁""遵循最佳实践"这类模型早就会的空话
- linter / formatter 能自动执行的机械规则
- 完整 API 文档、数据库结构、整仓库逐文件描述
- 任何真实密钥、token、生产连接串、客户数据——只写"密钥在哪里、怎么访问"
推荐结构:按这个顺序写
best-practices.md 给出的推荐章节顺序(可按项目裁剪):
- 项目概览 — 是什么、给谁用、最优先优化什么
- 技术栈 — 框架、包管理器、运行时版本、禁用的替代品
- 命令 — 先列文件级快速检查,再列全量检查
- 项目结构 — 关键目录职责与放置规则
- 关键规则 — 防重复犯错的最短约束清单
- 约定 — 只写非默认模式
- 测试与质量 — 测什么、怎么验证、完成的定义
- 安全与权限 — 允许做什么、什么需要批准
- 参考文档 — 带"Read when"触发器的链接
- 好模式 / 反模式 — 用真实文件路径举例
完整可复制的模板(最小版 AGENTS.md、完整版 AGENTS.md、CLAUDE.md 模板、Monorepo 拆分方案)都在 templates.md。
命令怎么写才"可执行"
模糊的命令是 Agent 跑偏的最大来源。对比感受一下:
| ❌ 模糊 | ✅ 精确 |
|---|---|
| "运行测试" | pnpm vitest run src/foo.test.ts |
| "正常构建" | pnpm build |
| "检查质量" | pnpm tsc --noEmit |
小技巧:把文件级检查(只测改动的那个文件,反馈快)放在全量检查前面,Agent 迭代会快很多。命令必须来自 package.json、pyproject.toml、Makefile、CI 配置这些可验证来源,不要凭空发明。
长内容怎么办?用"渐进披露"拆出去
根文件只做两件事:路由 + 关键约束。长内容一律外链出去:
- 长 SOP、API 说明 →
docs/*.md,并写明"Read when 什么场景再读" - 子项目专属规则 → 子目录嵌套
AGENTS.md/CLAUDE.md(Monorepo 按域拆分) - 专项工作流 → skills;重复提示 → commands;确定性校验 → hooks/脚本
引用示例写法:
docs/testing.md- Read when 加测试或调试 CI 失败。覆盖 fixtures、mocks 和命令。
优先链接,拒绝复制粘贴——粘贴进去的长文一定会腐烂。
关键规则怎么写?MUST 要惜字如金
MUST / MUST NOT 只留给少数能阻止具体错误的高影响约束,总量控制在 15 条以内:
- ✅ 好:
MUST NOT commit .env files or generated secrets. - ✅ 好:
MUST run pnpm vitest run <file> before finishing changes to tested TypeScript modules. - ❌ 弱:
MUST write clean, high-quality code.(删掉也不会少犯一次错)
安全边界:把指令文件当"公开文件"写
指令文件通常提交在仓库里,可能被广泛看到。best-practices.md 建议永远包含这几条:
- 永不提交
.env或凭据文件,不硬编码密钥,不打印 secret 值 - 用团队密钥管理器或
.env.example模式,文档里只描述密钥位置 - 破坏性操作(装依赖、删文件、git push、基础设施变更)必须先询问
仓库根目录的 AGENTS.md 就是这么做的——Safety 一节只有 4 条,却条条可执行。
实战案例:看看这个仓库自己的 AGENTS.md
WuMing's Claude Skills 仓库的 AGENTS.md 本身就是一份教科书级样本,值得逐节对照:
- Project:一句话说清仓库定位——"可复用 Agent Skills 的公开集合"
- Commands:5 条真实可复制命令,从列出所有 Skill 到跑单测,全部验证过
- Repository Map:
skills/<name>/SKILL.md是入口、references/存细节、config/skills.json是注册表,一眼看懂 - New Skill Checklist:创建新 Skill 的三步检查清单,防止流程跳步
- Verification And Done Criteria:明确定义"什么才算完成"——校验通过、测试通过、提交在 main 上
- Safety:不提交密钥、不动无关文件、高风险操作先问
这就是"短、准、可执行"八个字的落地。想看诊断已有文件的方法,可以读 review-rubric.md:它提供 9 个维度的 0–3 分打分表(总分 27 分)和 L0–L6 成熟度分级;想直接让 AI 帮你审查或生成,则可以用仓库里现成的 agent-md-advisor 和 claude-config-advisor 两个 skill。
怎么维护?像维护代码一样维护它 🔄
指令文件不是写完就忘的文档:
- 命令或架构变了 → 立刻更新
- Agent 反复犯同一种错误 → 这时再补规则(别一上来就写巨型规则书)
- 定期审计:删过期规则、查密钥泄露、核对与 README/CI 是否一致
- 成熟度自评:L0 没有 → L1 有文件 → L2 有项目专属约束 → L3 有结构化引用 → L4 有嵌套/路径作用域 → L5 持续维护 → L6 有 skills/hooks/动态上下文。多数小项目做到 L2–L3 就够了,小仓库堆复杂 hooks 系统属于过度设计
常见坑速查表
| 症状 | 快速修法 |
|---|---|
| 超过 300 行、贴满长文档 | 根文件只留全局约束,长内容改"Read when"外链 |
| 只有"运行测试""注意质量" | 换成精确命令,补充文件级检查 |
| "扮演资深工程师"人设墙 | 删掉,换成命令、目录地图和硬约束 |
| 十几条 MUST 堆在一起 | 砍到 15 条以内,普通约定降级或交给工具 |
| README / API 文档整段复制 | 一两行摘要 + 链接权威文档 |
| 没有安全边界和审批规则 | 补上"允许做 / 需批准 / 密钥位置"三块 |
| 个人偏好进了团队共享文件 | 拆到 CLAUDE.local.md 或本地配置 |
快速上手清单:今天就建一个最小版
- 复制 templates.md 里的"Minimal AGENTS.md"
- 填项目一句话、5 条真实命令、目录地图、安全三条
- 用 Agent 跑一个常见任务,观察它在哪里犯错
- 每犯一次具体错误,补一条对应规则,同时删一行废话
- 文件超过 150 行时,开始拆 references 和嵌套文件
写 AGENTS.md / CLAUDE.md 的心法其实就一句:像给一位聪明但刚入职的工程师写交接简报——短、真、能照着动手。 掌握这一点,AI Agent 的项目协作水平会有一个肉眼可见的跃升。🚀

