如何结构化CLAUDE.md、技能和Agent配置
原文：https://dev.to/hash01/how-to-structure-claudemd-skills-and-agents-2p7a
嗨，各位朋友
这里有一个小技巧，适合你在真实代码库中配置 Claude Code（或任何编程代理）时使用——当我发现我们的代理文档竟然在主动生成有问题的代码时，这招帮了大忙。
问题所在
大多数项目最终会包含四类指令文件：
而同样的知识会被复制粘贴到所有这些文件中。每个副本各自漂移。当我最终对照实际代码逐一核对我们文档中的每一个声明时，情况比我预想的更糟：
文档看起来完整。但它们自信地错了。而每份错误的文档都会在你代理遇到问题时，耗费你成千上万的 token 用于调试。
经验法则
关键在于它何时加载，以及谁需要它：
| 形式 | 加载时机 | 应拥有的内容 |
|---|---|---|
| CLAUDE.md / AGENTS.md | 始终加载，每次会话 | 适用于每次编辑的通用规则 |
| Skill | 按需加载，按任务类型 | 深层的“如何做”知识 |
| Agent | 当被委派时加载 | 工作流和关卡，而非知识 |
| Hook | 由代码强制加载 | 绝不能跳过的规则 |
用四个问题来决定每段内容的归属：
阻止腐化的一条规则
每个事实只存在于一个文件中。其他所有文件都链接到它。
我们文档的漂移恰恰是因为一个测试模板被粘贴到三个地方，然后各自演化。清理之后：
CLAUDE.md / AGENTS.md → 最多三行规则 + 链接到 skill
skill → 深层模式，引用真实源文件
agent → 工作流 + “运行检查命令并观察其通过”
参考文档 → 重型 API 参考的唯一归宿
所以我们可以用一句话定义边界：如果一个模式需要超过几行，就放到 skill 中，CLAUDE.md 仅保留链接。
像验证代码一样验证你的文档
这一步很有趣。文档声明是可测试的，所以测试它们：
首先，在信任之前先 grep。你文档中的每个示例都应该在代码库中存在。我们的就不满足：
# 文档中的“最佳实践” vs 现实
grep -rl "prefetchQuery" src/ | wc -l # 0 次使用
grep -rl "recommendedHelper" src/ | wc -l # 50 个测试文件中只有 1 个使用
然后，用一个子代理运行检索测试。只给它文档文件，不给仓库访问权限，让它回答真实的实现问题：
“为一个数据获取组件编写测试。”
“这个组件来自哪个包？”
“全局 store 在哪里？”
对照代码库给答案打分。如果遵循你文档的代理写出的代码会失败，那么你的文档没通过测试——在合并前修复它们。我们用这种方法捕获了所有回归，没有让任何人为此浪费一次调试会话。
取得的成果
这个例子说明：代理文档是一个具有加载语义的系统，而不是维基百科——将每个事实放到与其加载模型匹配的位置，每个事实只有一个主文件，并且像测试代码一样测试文档。
希望有用！
哈希
