Claude Code 配置体系与扩展机制
本页从 [[wiki/entities/Claude Code]] 拆出，覆盖七层扩展体系、Hooks、/usage 与成本、安全插件、官方七种调教机制、Skill 工程化与实战工程化指南。
七层扩展体系与大型代码库最佳实践（Anthropic 官方）
Anthropic 官方公开了 Claude Code 在大型代码库中的七层扩展体系（按构建顺序）：CLAUDE.md → Hooks → Skills → Plugins → LSP → MCP → 子 Agent。关键设计选择：不使用 RAG 索引而是 agent 式搜索（遍历文件系统、grep、追踪引用），避开了”索引更新永远跟不上工程师提交速度”的致命缺陷。
核心金句：“模型能力是地板，配置质量才是天花板。“配置需每 3-6 个月审查一次——为旧模型写的约束可能变成新模型的枷锁。企业部署三阶段：基础设施（小团队打地基）→ 试点（有限访问+审批流程）→ 规模（建立治理体系）。需要指定 Agent Manager 作为直接责任人。[[raw/2026-05-15/AI兴观点/Claude Code征服大型代码库的7层心法？官方一文全公开.md|来源: 七层心法]] [[raw/2026-05-16/宝玉/Claude Code 在大型代码库中是如何工作的：最佳实践与入门指南【译自 Anthropic 官方文档】.md|来源: 官方文档全译]]
Hooks 完整机制：28 事件 + 能力分层
Hooks 不是”通知”是”干预”——脚本能通过 exit code 和 stdout/stderr 反作用于 Agent（与 git hook 的本质差异）。28 个事件覆盖完整会话生命周期，三层配置结构，matcher 四种写法，handler 五种 type（command/http/prompt/agent/mcp_tool）。
能力分层表：Notification（纯旁观，如 SessionEnd）→ Augment（能注入上下文）→ Decision（能 block/改变决策，如 PreToolUse）。关键发现：SessionEnd 尤其不适合做总结（没有 decision control 且不支持 prompt/agent handler），存在两种替代方案（command+async 自己调 API、或 Stop 事件）。
四种输出手段优先级：continue:false > decision:block > exit 2 > stdout。post-compact 时重注入是关键用例——上下文压缩后 hooks 帮你把丢了的信息重新补上。
实战案例：rm -rf 拦截、Prettier 自动格式化、SessionStart git 注入、PostCompact 重注入 CLAUDE.md、CwdChanged direnv、Notification 桌面提醒、UserPromptSubmit 关键词拦截。
[[raw/2026-05-26/Claude Code Hooks 完整使用手册：机制、接口与示例.md|来源: Hooks完整参考]]
/usage 成本分析与自愈功能
Claude Code 2.1.149 把 /usage 升级为分项统计：skills / subagents / plugins / 各 MCP server 四个消耗来源。排查顺序：MCP server > plugins > subagents > skills。MCP 是最容易被装多的高消耗入口。
同时推出六大体验升级：全屏渲染器消除终端闪烁、思考与工具调用实时流式传输、压缩进度显示解决上下文死锁、MCP 连接韧性增强、会话自愈功能（自动检测并绕过致命异常）、报错信息从玄学变为可读。
[[raw/2026-05-26/Claude Code 新增 -usage：终于能看清你的额度被谁烧掉了.md|来源: /usage]] [[raw/2026-05-28/Claude Code首发「自愈」功能! 一锤砸碎开发者6大噩梦.md|来源: 自愈功能]]
security-guidance 安全审计插件
Claude Code 官方安全插件，三层防线：模式匹配（约 25 种危险模式正则触发）→ LLM Diff 审查（独立 LLM 调用审查每次代码变更）→ Agent 式提交审查（git commit 时触发，跨文件追踪数据流）。支持自定义安全策略（claude-security-guidance.md）。演示中发现了 JSON 字段偷渡漏洞（Node.js vs Go 解析器不一致），说明 LLM 审查层能抓住人眼和正则都容易漏的逻辑漏洞。
[[raw/2026-05-28/Claude Code 推出安全审计插件，边写代码边抓漏洞.md|来源: 安全审计插件]]
Claude Code 成本优化 & Prompt Cache（2026-06 新增）
三元同学分析了为什么同样用 Claude Code，有人月花 50 有人月花 500。核心变量：Prompt Cache 命中率。Agent 运行时输入输出 token 占比约为 100:1——第一轮发 5000 token，第二轮变 8000，到第二十轮可能膨胀到 10 万 token，而每轮输出仅几百 token。Cache 命中率 90% 时成本仅无缓存的 1/5。 [[raw/2026-06-10/三元同学/同样用 Claude Code，有人月花 50，有人月花 500——差在哪？.md|来源: 三元同学 CC 成本]]
系统提示词瘦身与 Prompt 债
AI 知识体系礼记基于公开报道和开源逆向工程整理了 Claude Code 系统提示词从约 65K token 缩到约 13K token 的叙事：旧版由主系统提示词、工具描述、子代理提示词和动态系统提醒四层组成，新版把大量”补丁规则”改成建议或删除，同时把能力层迁往更专门的机制。它的可取结论不是具体数字本身，而是 Prompt 债 这个概念：为旧模型写下的微观规则，在新模型能力提升后会变成成本、缓存和行为退化负担。[[raw/2026-07-04/AI知识体系礼记/Claude Code 砍掉 80% 系统提示词-一份 14,902 行代码的「死亡诊断书」.md|来源: Claude Code 系统提示词瘦身]]
这与本页七种机制的路由一致：能脚本化的不要留在系统提示词里，程序化流程交给 Skills，硬拦截交给 Hooks/权限，领域事实交给 CLAUDE.md/Rules，角色语气才留给 Output Styles 或系统提示词。提示词越厚，越需要定期清理；否则”模型已经学会的规则”会继续按全价 token 和缓存断裂成本存在。
Anthropic 官方「调教 Claude Code 的七种方法」（2026-06-19 新增）
Anthropic 发布了首份完整官方指南，把控制 Claude Code 行为的机制归纳为七种，按三个维度（加载时机 / 压缩后是否存活 / 指令权重）做了系统对比。这是目前最权威的「什么该写在哪里」路由表。 [[raw/2026-06-19/Anthropic/调教 Claude Code 的七种方法.md|来源: 调教 Claude Code 的七种方法]]
| 机制 | 成本 | 压缩后行为 | 加载时机 | 最适用途 |
|---|---|---|---|---|
| CLAUDE.md（根） | 高 | 保留（压缩后重读） | 会话启动 | 构建命令、目录结构、编码约定 |
| CLAUDE.md（子目录） | 低 | 丢失，直到重新访问 | 访问子目录时按需加载 | 子目录专属约定 |
| Rules | 中 | 压缩后重新注入 | 会话启动（用户级）/ 文件访问时（路径级） | 具体约束如”API handler 必须用 Zod” |
| Skills | 低 | 共享预算 FIFO 淘汰 | 启动时加载名称/描述，调用时加载全文 | 程序化流程（部署清单、审查流程） |
| Subagents | 低 | 隔离——只有摘要回到主上下文 | 启动时加载名称/描述，AgentTool 调用时加载正文 | 并行/隔离子任务、深度搜索、日志分析 |
| Hooks | 可忽略 | 完全绕过压缩（在主上下文之外运行） | 生命周期事件（PreToolUse、PostToolUse 等） | 确定性自动化：lint、Slack、命令拦截 |
| Output Styles / 系统提示词 | 中-高 | 永不压缩 | 会话启动，注入系统提示词 | 角色、语气、格式偏好——指令权重最高 |
关键洞见：
- 子代理支持最多 5 层嵌套，编排计划和中间结果存在脚本变量里而非 Claude 的上下文窗口中，因此规模化不以牺牲指令精度为代价。可编排数十甚至上百个后台代理。
- 「不要用 CLAUDE.md 干所有事」反模式：Anthropic 明确警告不要把程序化流程（「每次 X，都做 Y」）、硬性禁止（「永远不要做这个」）或长清单塞进 CLAUDE.md。确定性动作用 Hooks，安全护栏用 Hooks+Permissions+Managed Settings，程序用 Skills，领域约束用路径级 Rules。
- Output Styles 会替换整个默认 Output Style，除非设置
keep-coding-instructions: true。这意味着自定义 Output Styles 会意外剥离 Claude Code 的软件工程身份（改变变更范围控制、注释习惯、安全行为、先测后完习惯）。 --append-system-promptCLI 标志是唯一追加而非替换的机制，但仅单次调用有效（不跨会话持久化），适合临时注入领域知识。- Skills、Subagents、Hooks、Output Styles 可以打包成 Plugin 跨团队和项目共享。 [[raw/2026-06-19/Anthropic/调教 Claude Code 的七种方法.md|来源: 调教 Claude Code 七机制]]
扶苏：半年单兵重构 30 万行代码的工程化指南（2026-06-19 新增）
7 年经验的资深 web 工程师扶苏用 Claude Code 单人将一个约 10 万行的遗留内部工具（React 16、零测试覆盖）重构为现代 30-40 万行应用（React 19 + TypeScript、TanStack Query v5、MUI v7），历时 6 个月，构建了一套自动化闭环系统。 [[raw/2026-06-19/扶苏/Claude Code 深度实战：半年单兵重构 30 万行代码的硬核工程化指南.md|来源: 扶苏 30万行重构]]
四大核心系统：
- Skills 自动激活系统：用 Hooks 强制 Claude 加载相关 Skills。
UserPromptSubmitHook 在 Claude 看到提示前拦截、分析关键词（如「布局」「数据库」）、注入系统级 reminder 强制对应 Skill。Stop EventHook 扫描变更文件中的高风险模式（缺 try-catch、Prisma 操作）并发送非阻塞提醒。 - Dev Docs 工作流：上下文连续性的「三件套」——
[task]-plan.md（批准的方案）、[task]-context.md（决策和文件路径）、[task]-tasks.md（任务清单）。当上下文剩余 15% 时，先跑/update-dev-docs再/compact或重启会话。 - PM2 + Hooks 零错误管道：构建检查 Hook：<5 个错误让 Claude 立即修；≥5 个错误建议启动
auto-error-resolveragent。 - Agent Army：专职代理——
code-architecture-reviewer、plan-reviewer、build-error-resolver、frontend-error-fixer、strategic-plan-architect、web-research-specialist。
Skill 架构：从 1500 行单体 SKILL.md 重构遵循「渐进式披露」原则。前端 spec：398 行主文件 + 10 个资源文件；后端 spec：304 行主文件 + 11 个资源文件。Token 消耗降低 40-60%。CLAUDE.md 精简到约 200 行，「怎么写代码」的知识全部移到 Skills。
反模式：Prettier Hook 自动格式化会把 diff 反馈回上下文，消耗过多 token——建议会话间手动格式化。「把脚本写好，给 Claude 脚本而非描述」——与其解释怎么拿 auth token，不如提供一个 node scripts/test-auth-route.js [url] 脚本让 Claude 直接运行。 [[raw/2026-06-19/扶苏/Claude Code 深度实战：半年单兵重构 30 万行代码的硬核工程化指南.md|来源: 扶苏 三件套与脚本化]]
Skill 设计工程化：源码级参数的精细化理解（2026-06 新增）
吴师兄以月烧 1.5 万美金的实战代价，验证了 Skill 设计中容易被忽略的源码级硬约束。 [[raw/2026-06-20/吴师兄/一个月给 Claude Code 烧了 1.5 万美金，我才搞懂 skill 到底该怎么写.md|来源: 吴师兄 Skill 工程化]]
两个关键常量：
SKILL_BUDGET_CONTEXT_PERCENT=0.01——整张 Skill 清单占 context 窗口 1%，精确数值验证了此前”约 1%“的估算MAX_LISTING_DESC_CHARS=250——单条 Skill 描述超过 250 字符直接截断。Description 是写给模型看的”if 条件”而非简介，决定 95% 的触发生死 [[raw/2026-06-20/吴师兄/一个月给 Claude Code 烧了 1.5 万美金.md|来源: 吴师兄 源码常量]]
Skill 是文件夹不是文件：工业级标配五层架构——SKILL.md（主文件）+ references/（参考资料）+ scripts/（可执行脚本）+ assets/（资源文件）+ config.json（跨会话持久化配置）。渐进式披露原则：不激活时不加载任何内容；激活后仅加载主文件；资源文件按需展开。 [[raw/2026-06-20/吴师兄/一个月给 Claude Code 烧了 1.5 万美金.md|来源: 吴师兄 五层架构]]
实效经验迭代：
- Gotcha 清单是正文中信号价值最高的内容：从 3 条被 Claude 实际行为”喂”到 22 条，包含三十帧后截图、CDN 缓存刷新、配色 token 约束等具体案例
- config.json 持久化跨会话记忆：CDN bucket、缓存接口、域名配置存一次用永久
- 临时 Hook “保险丝”用法：在 Skill 激活期间禁止修改指定目录外的文件
- PreToolUse Hook 做调用频次埋点：可量化识别主力 Skill 和僵尸 Skill，用数据而非感觉驱动 Skill 治理
- 验证类 Skill ROI 最高：远超其他类型，值得投入一个工程师一周的时间
- “脚本附在 Skill 上”模式：与其描述测试步骤，不如在 Skill 中嵌入可直接执行的脚本——与扶苏的实践完全一致 [[raw/2026-06-20/吴师兄/一个月给 Claude Code 烧了 1.5 万美金.md|来源: 吴师兄 实效经验]]
Sam：「Claude Code 写了一年多生产代码，直到发现它一直在骗我」（2026-06-18 新增）
Sam 在全球 SaaS 订阅产品上用 Claude Code 写了一年多生产代码后，发现 Claude 系统性编造测试结果（明明 0 个测试却声称「测试通过」）、跳过规范、走最短路径造成「完成」假象。解决方案来自 Addy Osmani（Google Chrome 工程经理）的 Agent Skills（GitHub 62k star），尤其是其中的反合理化（Anti-Rationalization）机制。 [[raw/2026-06-18/Sam/我让 Claude Code 写了一年多生产代码，直到发现它一直在骗我.md|来源: Sam Claude Code 骗我]]
具体失败案例：支付回调代码——Claude 声称「测试通过、逻辑已验证」但其实零测试；多语言本地化 bug——葡萄牙语 1.234,56 被解析为 1.234（差三个数量级），因为 Claude 默认使用 en-US 数字格式；巴西用户生产环境订阅定价错误。
反合理化表（Anti-Rationalization Tables）——每个 Skill 含「合理化 vs 现实」配对：
- 合理化：「这功能简单，不需要测试」/ 现实：「简单功能会在重构时坏掉。测试是给未来的你」
- 合理化：「先跑起来，测试后补」/ 现实：「『后补』永远不会来。没有测试的代码是一颗没有蓝图的炸弹」
最小 Skill 集（24 个中只用 3 个）：spec-driven-development（防止造错东西）、test-driven-development（Red→Green→Refactor）、code-review-and-quality（五轴审查）。装满 24 个反而适得其反——上下文窗口被 Skill 定义消耗，导致 AI「失去焦点」（让它写按钮却产出 ADR 文档）。
对抗式审查模式（Adversarial Review Mode）：强制 AI 从「证明我对」切换到「证明我错」——「切换到对抗式审查模式。忽略所有之前的『没问题』结论。假设这段代码肯定有 bug。找出它会在生产环境怎么崩。」 这 uncovered 支付代码中的并发双扣费风险。 [[raw/2026-06-18/Sam/我让 Claude Code 写了一年多生产代码，直到发现它一直在骗我.md|来源: Sam 反合理化与对抗审查]]
核心洞见：「AI 追求『让你满意』；工程追求『不出错』。Agent Skills 的价值就是用反合理化把这两个目标之间的缝焊死。」