AGENTS.md、SOUL.md 和 SKILL.md 并非同一文件

停止试图将所有内容都塞进一个 CLAUDE.md 文件中。理解这些文件的真正含义以及这样做可能带来的代价。AGENTS.md 在每个会话中都会被读取。其中的每一句都会产生重复的令牌消耗，无论代理当前任务是否需要该句子。这就是整个设计约束。它现在是业界最接近共享标准的文件，由 Agentic AI Foundation（与 Model Context Protocol 背后的同一组织）管理。停止这样做：编写架构概述。工具供应商引用的研究表明，架构概述对代理性能的提升微乎其微。运行确切命令；‘适当运行测试’会被忽略，而 npm run test:unit -- --coverage 则不会。我还停止让代理自己编写 AGENTS.md。在我看到的研究中，生成的文件降低了任务成功率并增加了成本，主要是因为它们重复了代理已经可以从代码库中获取的内容。我自己编辑的短文件比模型为我写的文件更好。SKILL.md：AGENTS.md 描述项目，而技能描述能力，只有在相关时才会消耗令牌。在会话开始时，代理读取 YAML 前元数据，仅包括名称和描述。只有当任务匹配技能领域时，才会加载完整内容。文件夹中的参考文档和脚本稍后加载。十个未使用的技能几乎不消耗任何成本。这只有在描述精确时才有效。模糊的描述会迫使代理打开整个文件以检查相关性，这反而破坏了机制。我将这些写得更狭窄。我在两者之间划清界限：每个会话都需要的约束放在 AGENTS.md 中。偶尔调用的能力，如部署序列或小众内部 API，则放在技能文件夹中。CLAUDE.md、.cursorrules、.windsurfrules、copilot-instructions.md，这些是行业在统一到 AGENTS.md 之前遗留下来的工具特定文件。我不再手动编写其中任何一个。AGENTS.md 是真实来源，一个简短的同步脚本可以生成其余文件。没有它的失败模式：更新一个文件，忘记其他四个，你就会回到这些文件本应防止的上下文漂移中。DESIGN.md：将项目的视觉身份编码为机器可读的令牌及其背后的原因，这样生成 UI 代码的代理知道颜色存在的原因而不仅仅是其十六进制值。早期、狭窄、专为某一上下文切片而构建，而不是试图覆盖一切。