如何写好AGENTS.md和CLAUDE.md:WuMing's Claude Skills的AI Agent指令文件最佳实践

原创2026-10-30 09:36:082,275 阅读

如何写好AGENTS.md和CLAUDE.md:WuMing's Claude Skills的AI Agent指令文件最佳实践

AGENTS.md 与 CLAUDE.md 是写给 AI 编程助手看的"项目说明书",WuMing's Claude Skills 开源仓库把多年实战沉淀成了可直接套用的模板、审查量表和诊断方法。本文面向新手和普通用户,不贴大段代码,用最少的话讲清楚:这两份文件该怎么选、写多长、写什么、不写什么,以及如何让 AI Agent 干活更靠谱。

Claude Code 界面示例:AI Agent 指令文件的实际使用场景

AGENTS.md 和 CLAUDE.md 是什么?为什么重要 📝

每次开启新对话,AI Agent 都是"失忆"状态——它不知道你的项目用什么技术栈、测试命令是什么、哪些目录绝对不能动。AGENTS.md / CLAUDE.md 就是解决这个问题的指令文件:它们会在每次会话时自动注入上下文,相当于给 AI 队友做一份"入职简报"。

一句话定位(来自 best-practices.md 的核心心智模型):

  • 它们不是 README 的替代品,不是 API 手册,更不是"要像资深工程师一样思考"的人设口号墙
  • 它们应该读起来像给资深工程师的技术交接简报:短、准、可执行
  • 每一行都要能回答:"删掉这行,Agent 是不是更容易犯错?"答"否"就删

AI Passport 演示设备:AI 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 给出的推荐章节顺序(可按项目裁剪):

  1. 项目概览 — 是什么、给谁用、最优先优化什么
  2. 技术栈 — 框架、包管理器、运行时版本、禁用的替代品
  3. 命令 — 先列文件级快速检查,再列全量检查
  4. 项目结构 — 关键目录职责与放置规则
  5. 关键规则 — 防重复犯错的最短约束清单
  6. 约定 — 只写非默认模式
  7. 测试与质量 — 测什么、怎么验证、完成的定义
  8. 安全与权限 — 允许做什么、什么需要批准
  9. 参考文档 — 带"Read when"触发器的链接
  10. 好模式 / 反模式 — 用真实文件路径举例

完整可复制的模板(最小版 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 或本地配置

快速上手清单:今天就建一个最小版

  1. 复制 templates.md 里的"Minimal AGENTS.md"
  2. 填项目一句话、5 条真实命令、目录地图、安全三条
  3. 用 Agent 跑一个常见任务,观察它在哪里犯错
  4. 每犯一次具体错误,补一条对应规则,同时删一行废话
  5. 文件超过 150 行时,开始拆 references 和嵌套文件

写 AGENTS.md / CLAUDE.md 的心法其实就一句:像给一位聪明但刚入职的工程师写交接简报——短、真、能照着动手。 掌握这一点,AI Agent 的项目协作水平会有一个肉眼可见的跃升。🚀

登录后查看全文
skills