上下文工程：理解 AGENTS.md、SKILL.md 与 CLAUDE.md
输入“/”快速插入内容
上下文工程：理解 AGENTS.md、SKILL.md 与 CLAUDE.md
上下文工程：理解 AGENTS.md、SKILL.md 与 CLAUDE.md
用户4242用户42428月4日修改
原帖链接
如果你在 2026 年花过时间使用 AI 编程智能体，可能已经注意到一个奇怪的现象：每个工具都希望你的仓库根目录里放着属于自己的 Markdown 文件。CLAUDE.md、AGENTS.md、SKILL.md、.cursorrules、.windsurfrules、copilot-instructions.md。它们看起来像杂物，但每个文件都在解决一个真实问题；理解它们之间的差异，能避免你用五种不同方式重复维护同一份上下文。
这些文件存在，是因为 LLM 智能体并不像人类同事那样了解你的代码库。新工程师会阅读 README，问几个问题，再通过耳濡目染掌握团队约定；智能体没有这个过程。每次启动会话时，它都需要明确写下来的上下文。Markdown 自然成了合适的格式，因为它是纯文本、便于查看差异，也能被人和模型直接阅读。
AGENTS.md：通用上下文文件
AGENTS.md 已成为行业中最接近共同标准的存在。它现由 Agentic AI Foundation 管理，采用与 MCP 相同的治理模式；目前已有 30 多种智能体工具在超过 6 万个仓库中读取它。思路很简单：每个仓库维护一个权威文件，记录构建命令、测试命令、代码风格以及智能体必须遵守的限制。
AGENTS.md 有意思的地方，在于关于如何写好它的研究。今年被工具厂商引用的研究发现，架构概览对智能体几乎没有帮助；相反，精确命令、版本限制和明确的“完成”条件，能够切实减少错误。“尽可能”“确保全面覆盖”这样的模糊指令往往会被忽略，因为智能体需要的是可执行的策略，而不是写给人看的散文。
还有一条值得记住的警示：让 LLM 为你生成 AGENTS.md，往往会适得其反。今年早些时候的研究表明，自动生成的文件会降低任务成功率、增加成本，主要原因是其中重复了智能体本可从仓库本身推断出来的信息。一份简短、经过人工编辑的文件，优于一篇很长、由 AI 撰写的文件。
SKILL.md：描述能力，而不是项目上下文
AGENTS.md 描述的是项目，SKILL.md 描述的则是一项能力。一个技能由包含 SKILL.md 的目录构成，还可以附带脚本、参考资料和资源文件；它可在 Claude Code、Codex、Copilot 及其他兼容智能体之间移植。
真正巧妙之处在于渐进式加载。会话开始时，智能体只读取 YAML 元数据区（frontmatter）中的技能名称与描述；只有当任务确实匹配该技能领域时，才加载完整正文。附带的脚本或参考文档会在更晚阶段才加载。这样无需在一开始就塞入每一条可能永远用不到的指令，能够保持上下文窗口轻量。
对于维护可复用提示词或工作流库的人来说，这比把所有内容硬塞进一个巨大的 AGENTS.md 更合适。这也解释了 skills.sh 等市场为什么会快速发展：技能只是一个装有 Markdown 的目录，发布与安装都非常容易。
CLAUDE.md 与工具专属文件
CLAUDE.md、.cursorrules、.windsurfrules 与 copilot-instructions.md 是 AGENTS.md 的工具专属亲属。行业收敛到共享标准之前，每个编辑器或智能体都曾发明自己的约定；其中大多数至今仍被支持，以维持向后兼容。
已经形成的一种实用模式，尤其适合团队同时维护多种工具的情况：把 AGENTS.md 当作唯一事实来源，再从它生成各个工具专属文件。这样可以避免经典的失败方式：更新了一个文件，却忘了其余四个，悄然重新引入这些文件本应防止的上下文漂移。
DESIGN.md 与值得关注的新参与者
除了上述文件，还开始出现一些更专门的格式。例如 DESIGN.md 用于编码项目的视觉识别系统：它把机器可读的设计令牌（design token）与人类可读的设计理由结合起来，使生成 UI 代码的智能体不仅理解颜色值，也理解选择这些颜色的原因。这还处于早期阶段，但已暗示出这个模式的走向：为上下文的特定切片使用狭窄、专用的 Markdown 文件，而不是试图用一个文件包办一切。
上下文工程：这些文件存在的真正原因
这件事的核心并不是 Markdown，而是智能体的可靠性极度依赖它接收到的上下文质量；Markdown 恰好是大家都能接受的最低摩擦格式。它们的覆盖范围不同：AGENTS.md 面向项目，SKILL.md 面向能力，工具专属文件则主要是为兼容性而存在。
当你编写其中任何一个文件时，本质上是在做上下文工程：决定 LLM 看见什么、何时看见、以什么形式看见，让它能良好行动，又不会把词元（token）浪费在不需要的信息上。应把下面每个文件都视为达成这一目标的杠杆，而不只是工具链要求的一种形式。
如何使用 AGENTS.md 与 SKILL.md？
先从 AGENTS.md 开始，并克制把它写得面面俱到的冲动。这个文件中的每一句话，都会在每次会话中被读取，因此都是持续发生的词元成本。与其写散文式描述，不如给出精确命令；与其解释架构，不如说明约束；任何智能体能够从仓库自行推断的信息都应删除。研究表明，那些内容既不会改善结果，只会抬高成本。
以下几个具体做法可以带来可衡量的改进：
•
用带参数的字面测试命令替换“请恰当地运行测试”，避免智能体额外花一轮去摸索命令。
•
删除“架构概览”一节，只保留非标准模式，以及智能体绝不能触碰的文件。
•
为常见任务加入明确的“完成”条件，因为模糊性会导致智能体过度探索和反复阅读文件。
•
不要放任智能体自行生成这份文件；自己编辑，或至少在生成后大幅精简。
当 AGENTS.md 开始累积只适用于某些任务的能力专属指令，例如部署步骤或小众的内部 API 时，再转向 SKILL.md。渐进式加载正是在这里真正为词元预算发挥作用。
会话开始时，智能体只为元数据区的描述付出成本；只有当任务确实匹配时，才会加载完整技能正文。因此，十个闲置技能几乎不会产生额外成本。
要真正获得这项收益，技能描述必须简洁且足够具体，让智能体无需打开文件就能正确匹配。描述太模糊时，智能体会为了判断相关性而加载正文，这就失去了渐进式加载的意义。
应把 SKILL.md 留给偶尔才会调用的能力，而不是每个会话都需要遵守的限制；后者应放在 AGENTS.md 中。
对于工具专属文件，即 CLAUDE.md、.cursorrules、.windsurfrules 和 copilot-instructions.md，完全不必再手写。维护 AGENTS.md 作为唯一事实来源，再用一段短同步脚本从中生成其他文件。
这首先不是词元优化，而是正确性优化。文件彼此分歧，正是悄悄重新引入这些文件原本用来消除的歧义的原因。
最后，请像对待代码一样对待这些文件：在描述改动的同一个合并请求（pull request）中审查它们；一旦某段内容不再真实，立刻删除；并定期审计那些已经迁移进代码库、不必重复声明的内容。一个精简、准确且每次都能被正确读取的文件，优于一份详尽却被草草浏览、忽略，或与周围代码相互矛盾的文件。
2026 年真正从这些文件中获得价值的团队，并不是拥有最详细 AGENTS.md 的团队，而是将上下文工程视为持续纪律的团队：每一份文件都必须在词元预算中证明自己的价值，否则就应删掉。