Claude Code配置避坑指南：CLAUDE.md、钩子、MCP、子代理、代理团队到底怎么搭
内容提要
Claude Code配置复杂，九层体系（CLAUDE.md、钩子、MCP、子代理、代理团队）叠加易致上下文超载、成本高。建议精简CLAUDE.md至80行，钩子强制执行关键规则，MCP按需挂载，子代理限定输出，代理团队用于并行协作。上下文满时用/clear或重启，并警惕“上下文腐烂”问题。
延伸解读
配置叠加的隐性成本
CLAUDE.md、MCP服务器、子代理等每一层配置都会消耗上下文token，即使当前任务用不到。例如，CLAUDE.md每行都吃token，MCP服务器工具定义也占空间。九层配置叠加，容易导致上下文窗口迅速填满，触发压缩，影响推理质量。因此，配置时应考虑每层的token开销，避免过度堆叠。
CLAUDE.md的写作原则
CLAUDE.md应只记录代码中看不出的关键约束，如部署惯例、禁止操作等，而非通用风格或语言基础。判断标准是：同一纠正重复超过两次才写入。官方建议200行以内，实际最好压到80行，以减少token消耗。精简的CLAUDE.md能提升Claude的专注度，避免重要规则被淹没。
钩子与MCP的实用建议
钩子用于强制执行规则，如PreToolUse拦截危险操作，PostToolUse自动跑lint。但注意频繁触发格式化钩子可能烧掉大量token，建议会话间运行。MCP服务器应只挂当前需要的，项目专用放.mcp.json，全局放~/.claude/mcp.json，CI中可用--strict-mcp-config固定配置，避免上下文被无关工具占用。
上下文管理的信号与手段
当Claude开始不确定细节或引用错误时，表明上下文接近饱和。干预手段按成本排序：/clear清空上下文，--continue恢复会话，手动压缩提示建立参考点，或重启会话并附精炼规格。注意自动压缩阈值约83%，但长会话中“上下文腐烂”可能更早影响性能，需主动管理。
Q&A
Claude Code的九层配置体系包括哪些部分？
Claude Code的配置体系包括模型、上下文、钩子、MCP服务器、技能、子代理、代理团队等九层。其中CLAUDE.md管理记忆，模型开关控制质量和价格，钩子强制执行动作，MCP服务器提供外部工具，技能管理领域知识，子代理隔离任务，代理团队支持多实例协作。
CLAUDE.md文件应该写什么内容？行数控制在多少合适？
CLAUDE.md应只写从代码中看不出来的关键信息，如架构决策、扩展点、遗留文件注意事项、目录迁移状态等。避免写风格偏好、语言基础等通用内容。官方建议控制在200行以内，实际团队建议压到80行以内，因为每一行都会消耗token。
Claude Code中的钩子（Hooks）有什么作用？有哪些常用事件？
钩子用于强制执行规则，与CLAUDE.md的建议不同，钩子无法被忽略。常用事件包括PreToolUse（工具执行前触发，可拦截危险操作）、PostToolUse（工具执行后触发，可自动运行lint或测试）、Stop（响应结束时触发，可做编译检查）。注意避免每次文件写入都运行格式化钩子，以免消耗大量token。
如何避免MCP服务器消耗过多上下文？
只挂载当前会话真正需要的MCP服务器，避免同时连接多个。项目专用服务器放在项目根目录的.mcp.json中，全局通用的才放在~/.claude/mcp.json。在CI或自动化管道中使用--mcp-config和--strict-mcp-config固定服务器配置，确保确定性。
子代理和代理团队有什么区别？分别适用于什么场景？
子代理只向主代理汇报，适合“干完把结果给我”的任务，token成本较低。代理团队的队员之间可以互相沟通，适合需要讨论和协作的复杂工作，但token成本更高。代理团队目前是实验性功能，默认关闭，需手动开启。
上下文快满时有哪些干预手段？
干预手段按成本排序：/clear在不同任务间清空上下文；--continue恢复之前的会话；手动压缩提示（如“总结一下我们目前确定的关于认证模块的内容”）；如果会话已废，保存决策后重启，并用一份精炼的规格说明（约500 token）重新开始。
什么是“上下文腐烂”？自动压缩的触发阈值是多少？
上下文腐烂指上下文越长，模型性能越下降，注意力分散，老内容干扰当前任务。自动压缩的触发阈值默认约为83%，即会话可长到约830K token才压缩。但实际可用量未量化，长会话退化问题存在但无精确答案。
