组织 CLAUDE.md、Skills 与 Agents 的最佳实践

为 Claude Code 等编码代理配置指令文件时，常见误区是同一套知识被复制到 CLAUDE.md、skills、agent 定义和参考文档四类文件中，导致各份独立漂移。经审计发现，这种“自信的错误”成本极高——样式文档推荐了与构建配置不匹配的 CSS-Modules 模式，测试模板在 beforeAll 中设置 mock 却被 test setup 文件在每个测试后重置，渲染组件缺少必要 Provider。每个错误文档都会让代理多花数千 token 的调试循环。

正确做法是按“何时加载、谁需要”决定内容归属：
- 每次会话都加载的规则放 CLAUDE.md / AGENTS.md，保持简短（3 行内 + 链接到 skill）
- 只有特定任务需要的深度知识放 skill（如样式机制、数据获取模式、测试配方），描述加载后才触发
- 角色或流程而非知识放 agent（定义工作流完成标准，调用哪些 skill），保持薄层
- 绝不可跳过的检查用 hook（格式化、lint）——代码规则比文字要求可靠

核心原则：每个事实只存在于一个文件，其他文件均引用它。模式超过几行就放入 skill，CLAUDE.md 仅放链接。

验证文档像验证代码一样：先用 grep 检查文档示例是否真实存在于代码库（如“prefetchQuery”零使用，“recommendedHelper”仅 1/50 测试文件使用）；再用子代理仅凭文档回答实现问题，对比实际代码评分。若代理按文档生成的代码会失败，则文档未通过，修复后再合并。

这一重组成果显著：典型功能任务上下文缩小约 11%，约定变更现在只需改 1 个文件而非 3 个，且文档不再生成损坏的样式和失败测试——每次代理踩坑省去数千 token 调试。

#开发者 #工具 #Claude #ClaudeCode #Agent #工程效率 #文档管理 #CodingAgent
@DevToolboxHub