Claude Code：架构、治理与工程实践

这个文章想聊聊这几个事Claude Code 底层怎么运作、上下文为什么会乱以及怎么治理、Skills 和 Hooks 应该怎么设计、Subagents 的正确用法、Prompt Caching 的架构影响以及怎么写一个真正有用的 CLAUDE.md。我觉得最直接的理解方式是把 Claude Code 拆成六层来看只强化其中一层系统就会失衡CLAUDE.md 写太长上下文先污染自己了工具堆太多了选择就搞不清楚了subagents 开得到处都是状态就漂移了验证这步跳过了出了问题根本不知道是哪里挂的。一 它底层是怎么运行的Claude Code 的核心不是回答而是一个反复循环的代理过程收集上下文 → 采取行动 → 验证结果 → [完成 or 回到收集] ↑ ↓ CLAUDE.md Hooks / 权限 / 沙箱 Skills Tools / MCP Memory卡住的地方几乎从来不是模型不够聪明更多时候是给了它错误的上下文或者写出来了但根本没法判断对不对也没法撤回。真正要关注的五个层面二 概念边界MCP / Plugin / Tools / Skills / Hooks / Subagents简单记给 Claude 新动作能力用 Tool/MCP给它一套工作方法用 Skill需要隔离执行环境用 Subagent要强制约束和审计用 Hook跨项目分发用 Plugin。三 上下文工程最重要的系统约束很多人把上下文当容量问题但卡住的地方通常不是不够长而是太吵了有用的信息被大量无关内容淹没了。真实的上下文成本构成Claude Code 的 200K 上下文并非全部可用200K 总上下文 ├── 固定开销 (~15-20K) │ ├── 系统指令: ~2K │ ├── 所有启用的 Skill 描述符: ~1-5K │ ├── MCP Server 工具定义: ~10-20K ← 最大隐形杀手 │ └── LSP 状态: ~2-5K │ ├── 半固定 (~5-10K) │ ├── CLAUDE.md: ~2-5K │ └── Memory: ~1-2K │ └── 动态可用 (~160-180K) ├── 对话历史 ├── 文件内容 └── 工具调用结果一个典型 MCP Server如 GitHub包含 20-30 个工具定义每个约 200 tokens合计 4,000-6,000 tokens。接 5 个 Server光这部分固定开销就到了 25,000 tokens12.5%。我第一次算出这个数字的时候真没想到有这么多在要读大量代码的场景这 12.5% 真的很关键。推荐的上下文分层始终常驻 → CLAUDE.md项目契约 / 构建命令 / 禁止事项 按路径加载 → rules语言 / 目录 / 文件类型特定规则 按需加载 → Skills工作流 / 领域知识 隔离加载 → Subagents大量探索 / 并行研究 不进上下文 → Hooks确定性脚本 / 审计 / 阻断说白了偶尔用的东西就不要每次都加载进来。上下文最佳实践保持 CLAUDE.md 短、硬、可执行优先写命令、约束、架构边界。Anthropic 官方自己的 CLAUDE.md 大约只有 2.5K tokens可以参考, 以下是一些经验把大型参考文档拆到 Skills 的 supporting files不要塞进 SKILL.md 正文使用 .claude/rules/ 做路径/语言规则不让根 CLAUDE.md 承担所有差异长会话主动用 /context 观察消耗不要等系统自动压缩后再补救任务切换优先 /clear同一任务进入新阶段用 /compact把 Compact Instructions 写进 CLAUDE.md压缩后必须保留什么由你控制不由算法猜Tool Output 噪声另一个隐形上下文杀手前面算的是 MCP 工具定义的固定开销但动态部分同样有个坑容易被忽视Tool Output。cargo test 一次完整输出动辄几千行git log、find、grep 在稍大的仓库里也能轻松塞满屏幕。这些输出 Claude 并不需要全看但只要它出现在上下文里就是实实在在的 token 消耗同样会挤掉对话历史和文件内容的空间。后来看到RTKRust Token Killer这个思路觉得挺对的它做的事很简单在命令输出到 Claude 之前自动过滤只留决策需要的核心信息。比如 cargo test# Claude 看到的原始输出 running 262 tests test auth::test_login ... ok ...几千行 # 走 RTK 之后 ✓ cargo test: 262 passed (1 suite, 0.08s)Claude 真正需要知道的就是「过了还是挂了挂在哪里」其他都是噪声。它通过 Hook 透明重写命令对 Claude Code 来说完全无感。后面第 6 节会提到 | head -30 这种手动截断RTK 干的就是这件事只是覆盖面更广不用每条命令自己加项目开源在github压缩机制的陷阱默认压缩算法按可重新读取判断早期的 Tool Output 和文件内容会被优先删掉顺带把架构决策和约束理由也一起扔了。两小时后再改可能根本不记得两小时前定了什么莫名其妙的 Bug 就是这么来的。解决方案就是在 CLAUDE.md 里写明Compact Instructions When compressing, preserve in priority order: 1. Architecture decisions (NEVER summarize) 2. Modified files and their key changes 3. Current verification status (pass/fail) 4. Open TODOs and rollback notes 5. Tool outputs (can delete, keep pass/fail only)除了写 Compact Instructions还有一种更主动的方案在开新会话前先让 Claude 写一份 HANDOFF.md把当前进度、尝试过什么、哪些走通了、哪些是死路、下一步该做什么写清楚。下一个 Claude 实例只读这个文件就能接着做不依赖压缩算法的摘要质量在 HANDOFF.md 里写清楚现在的进展。解释你试了什么、什么有效、什么没用让下一个拿到新鲜上下文的 agent 只看这个文件就能继续完成任务。写完后快速扫一眼有缺漏直接让它补然后开新会话把 HANDOFF.md 的路径发过去就行。Plan Mode 的工程价值Plan Mode 的核心是把探索和执行拆开探索阶段不动文件确认方案后再执行探索阶段以只读操作为主Claude 可以先澄清目标和边界再提交具体方案执行成本在计划确认之后才发生对于复杂重构、迁移、跨模块改动这样做比急着出代码有用多了在错误假设上越跑越偏的情况会少很多。按两下 ShiftTab 进入 Plan Mode进阶玩法是开一个 Claude 写计划再开一个 Codex 以高级工程师身份审这个计划让 AI 审 AI效果很好。四 Skills 设计不是模板库是用的时候才加载的工作流Skill 官方描述是按需加载的知识与工作流描述符常驻上下文完整内容按需加载用起来和保存的 Prompt差别挺大的。一个好 Skill 应该满足什么描述要让模型知道何时该用我而不是我是干什么的这两个差很多有完整步骤、输入、输出和停止条件别写了个开头没有结尾正文只放导航和核心约束大资料拆到 supporting files 里有副作用的 Skill 要显式设置 disable-model-invocation: true不然 Claude 会自己决定要不要跑Skill 怎么做到按需加载Claude Code 团队在内部设计中反复强调 “progressive disclosure”意思不是让模型一次性看到所有信息而是先获得索引和导航再按需拉取细节SKILL.md 负责定义任务语义、边界和执行骨架supporting files 负责提供领域细节脚本负责确定性收集上下文或证据一个比较稳定的结构长这样.claude/skills/ └── incident-triage/ ├── SKILL.md ├── runbook.md ├── examples.md └── scripts/ └── collect-context.shSkill 的三种典型类型类型一检查清单型质量门禁发布前跑一遍确保不漏项---name:release-checkdescription:Use before cutting a release to verify build,version,and smoke test.---## Pre-flight (All must pass)-[]cargo build--release passes-[]cargo clippy---D warnings clean-[]Version bumped in Cargo.toml-[]CHANGELOG updated-[]kaku doctor passes on clean env## OutputPass / Fail per item. Any Fail must be fixed before release.类型二工作流型标准化操作配置迁移高风险显式调用 内置回滚步骤---name:config-migrationdescription:Migrate config schema. Run only when explicitly requested.disable-model-invocation:true---## Steps1. Backup:cp ~/.config/kaku/config.toml ~/.config/kaku/config.toml.bak2. Dry run:kaku config migrate--dry-run3. Apply:remove --dry-run after confirming output4. Verify:kaku doctor all pass## Rollbackcp ~/.config/kaku/config.toml.bak ~/.config/kaku/config.toml类型三领域专家型封装决策框架运行时出问题时让 Claude 按固定路径收集证据不要瞎猜---name:runtime-diagnosisdescription:Use when kaku crashes,hangs,or behaves unexpectedly at runtime.---## Evidence Collection1. Run kaku doctor and capture full output 2. Last 50 lines of ~/.local/share/kaku/logs/3. Plugin state:kaku--list-plugins## Decision Matrix|Symptom|First Check||---|---||Crash on startup|doctor output → Lua syntax error||Rendering glitch|GPU backend / terminal capability||Config not applied|Config path schema version|## Output FormatRoot cause / Blast radius / Fix steps / Verification command描述符写短点每个 Skill 都在偷你的上下文空间每个启用的 Skill描述符常驻上下文优化前后差距很大# 低效~45 tokensdescription:|This skill helps you review code changes in Rust projects. It checks for common issues like unsafe code, error handling... Use this when you want to ensure code quality before merging.# 高效~9 tokensdescription:Use for PR reviews with focus on correctness.还有一个很重要的 disable-auto-invoke 使用策略高频1 次/会话→ 保持 auto-invoke优化描述符低频1 次/会话→ disable-auto-invoke手动触发描述符完全脱离上下文极低频1 次/月→ 移除 Skill改为 AGENTS.md 中的文档Skills 反模式描述过短description: help with backend任何后端工作都能触发哈哈正文过长几百行工作手册全塞进 SKILL.md 正文一个 Skill 覆盖 review、deploy、debug、docs、incident 五件事有副作用的 Skill 允许模型自动调用五 工具设计怎么让 Claude 少选错给 Claude 的工具和给人写的 API 不是一回事。给人用的 API 往往会追求功能齐全但给 agent 用重点不是功能堆得多完整而是让它更容易用对。好工具 vs 坏工具几个实用设计原则名称前缀按系统或资源分层github_pr_、jira_issue_对大响应支持 response_format: concise / detailed错误响应要教模型如何修正不要只抛 opaque error code能合并成高层任务工具时不要暴露过多底层碎片工具避免 list_all_* 让模型自行筛选从 Claude Code 内部工具演进学到的Claude Code 团队内部工具的这段演进时感觉还挺有意思。像这种需要在任务中途停下来问用户的场景他们前后试了三种做法第一版给已有工具如 Bash加一个 question 参数让 Claude 在调用工具时顺带提问。结果 Claude 大多数时候直接忽略这个参数继续往下跑根本不停下来问。第二版要求 Claude 在输出里写特定 markdown 格式外层解析到这个格式就暂停。问题是没有强制约束Claude 经常忘了按格式写提问逻辑非常脆弱。第三版做成独立的 AskUserQuestion 工具。Claude 想提问就必须显式调用它调用即暂停没有歧义比前两版靠谱多了。下面这张图刚好能解释为什么第三版明显更稳左边markdown 自由输出太松模型格式随意、外层解析脆弱右边ExitPlanTool 参数太死等到退出计划阶段提问已经太晚AskUserQuestion 独立工具落在中间结构化且随时可调用是这三者里最稳定的设计。说白了既然你就是要 Claude 停下来问一句那就直接给它一个专门的工具。加个 flag 或者约定一段输出格式很多时候它一顺手就略过去了Todo 工具的演进早期用 TodoWrite 工具 每 5 轮插入提醒让 Claude 记住任务。随着模型变强这个工具反而成了限制Todo 提醒让 Claude 认为必须严格遵循无法灵活修改计划。挺有意思的教训当初加这个工具是因为模型不够强模型变强之后它反而变成了枷锁。值得过段时间回来检查一下当初加的限制还成不成立。搜索工具的演进最初用 RAG 向量数据库虽然快但需要索引、不同环境脆弱最重要的是Claude 不喜欢用。改成 Grep 工具让 Claude 自己搜索后好用很多。后来又发现一个顺带的好处Claude 读 Skill 文件Skill 文件又引用其他文件模型会递归读取按需发现信息不需要提前塞进去这个模式后来被叫做渐进式披露。什么时候不该再加 Tool本地 shell 可以可靠完成的事情模型只需要静态知识不需要真正与外部交互需求更适合 Skill 的工作流约束而不是 Tool 的动作能力还没验证过工具描述、schema 和返回格式能被模型稳定使用六 Hooks在 Claude 执行操作前后强制插入你自己的逻辑Hooks 很容易被当成自动运行的脚本但我自己用下来觉得它更像是把一些不能交给 Claude 临场发挥的事情重新收回到确定性的流程里。比如格式化要不要跑、保护文件能不能改、任务完成后要不要通知这些事真不要指望 Claude 每次都自己记得。当前支持的 Hook 点适合 vs 不适合放到 Hooks 的适合阻断修改受保护文件、Edit 后自动格式化/lint/轻量校验、SessionStart 后注入动态上下文Git 分支、环境变量、任务完成后推送通知。不适合需要读大量上下文的复杂语义判断、长时间运行的业务流程、需要多步推理和权衡的决策这些该在 Skill 或 Subagent 里。json{hooks:{PostToolUse:[{matcher:Edit,pattern:*.rs,hooks:[{type:command,command:cargo check 21 | head -30,statusMessage:Running cargo check...}]}],Notification:[{type:command,command:osascript -e display notification \Task completed\ with title \Claude Code\}]}}Hooks越早发现错误越省时间在 100 次编辑的会话中每次节省 30-60 秒累积节省 1-2 小时还挺可观的。注意限制输出长度| head -30避免 Hook 输出反而污染上下文。如果不想在每条命令后面手动加截断可以看看第 3 节提到的 RTK它把这件事系统化了。Hooks Skills CLAUDE.md 三层叠加CLAUDE.md声明提交前必须通过测试和 lintSkill告诉 Claude 在什么顺序下运行测试、如何看失败、如何修复Hook对关键路径执行硬性校验必要时阻断用下来感觉三样少任何一层都会有漏洞。只写 CLAUDE.md 规则Claude 经常当没看见只靠 Hooks细节判断又做不了放在一起才比较稳。七 Subagents派一个独立的 Claude 去干一件具体的事Subagent 就是从主对话派出去的一个独立 Claude 实例有自己的上下文窗口只用你指定的工具干完汇报结果。我用下来觉得它最大的价值不是并行而是隔离扫代码库、跑测试、做审查这类会产生大量输出的事塞进主线程很快就把有效上下文挤没了交给 Subagent 做主线程只拿一个摘要干净很多。Claude Code 内置了三个Explore只读扫库默认跑 Haiku 省成本、Plan规划调研、General-purpose通用也可以自定义。配置时要显式约束tools / disallowedTools限定能用什么工具别给和主线程一样宽的权限model探索任务用 Haiku/Sonnet重要审查用 OpusmaxTurns防止跑飞isolation: worktree需要动文件时隔离文件系统另一个实用细节长时间运行的 bash 命令可以按 CtrlB 移到后台Claude 之后会用 BashOutput 工具查看结果不会阻塞主线程继续工作。subagent 同理直接告诉它「在后台跑」就行。几个常见反模式子代理权限和主线程一样宽隔离没有意义输出格式不固定主线程拿到没法用子任务之间强依赖频繁要共享中间状态这种情况用 Subagent 不合适八 Prompt CachingClaude Code 内部架构的核心这块我之前在很多教程里都没怎么看到有人展开讲但它其实很影响 Claude Code 的成本结构和很多设计取舍。工程界有句话 “Cache Rules Everything Around Me”对 agent 同样如此Claude Code 的整个架构都是围绕 Prompt 缓存构建的高命中率不光省钱速率限制也会松很多Anthropic 甚至会对命中率跑告警太低直接宣布 SEV。为缓存设计的 Prompt LayoutPrompt 缓存是按前缀匹配工作的从请求开头到每个 cache_control 断点之前的内容都会被缓存。所以这里的顺序很重要Claude Code 的 Prompt 顺序 1. System Prompt → 静态锁定 2. Tool Definitions → 静态锁定 3. Chat History → 动态在后面 4. 当前用户输入 → 最后破坏缓存的常见陷阱在静态系统 Prompt 中放入带时间戳的内容让它每次都变非确定性地打乱工具定义顺序会话中途增删工具那像当前时间这种动态信息怎么办别去动系统 Prompt放到下一条消息里传进去就行。Claude Code 自己也是这么做的用户消息里加 标签系统 Prompt 不动缓存也就不会被打坏。会话中途不要切换模型Prompt 缓存是模型唯一的。假如你已经和 Opus 对话了 100K tokens想问个简单问题切换到 Haiku 实际上比继续用 Opus 更贵因为要为 Haiku 重建整个缓存。确实需要切换的话用 Subagent 交接Opus 准备一条交接消息给另一个模型说明需要完成的任务就行。Compaction 的实际实现上图是 Compaction上下文压缩的执行流程左边是上下文快满时的状态中间是 Claude Code 开一个 fork 调用把完整对话历史喂给模型加一句Summarize this conversation这一步命中缓存所以只需 1/10 的价格右边是压缩完之后原来几十轮对话被替换成一段 ~20k tokens 的摘要System Tools 还在再挂上之前用到的文件引用腾出空间继续新的轮次。直觉上 Plan Mode 应该切换成只读工具集但这会破坏缓存。实际实现是EnterPlanMode 是模型可以自己调用的工具检测到复杂问题时自主进入 plan mode工具集不变缓存不受影响。defer_loading工具的延迟加载Claude Code 有数十个 MCP 工具每次请求全量包含会很贵但中途移除会破坏缓存。解决方案是发送轻量级 stub只有工具名标记 defer_loading: true。模型通过 ToolSearch 工具发现它们完整的工具 schema 只在模型选择后才加载这样缓存前缀保持稳定。九. 验证闭环没有 Verifier 就没有工程上的 Agent「Claude 说完成了」其实没啥用你得能知道它做没做对、出了问题能退回来、过程还能查这才算数。Verifier 的层级最低层命令退出码、lint、typecheck、unit test中间层集成测试、截图对比、contract test、smoke test更高层生产日志验证、监控指标、人工审查清单在 Prompt、Skill 和 CLAUDE.md 中显式定义验证## Verification For backend changes: - Run make test and make lint - For API changes, update contract tests under tests/contracts/ For UI changes: - Capture before/after screenshots if visual Definition of done: - All tests pass - Lint passes - No TODO left behind unless explicitly tracked写任务 Prompt 或 Skill 的时候最好把验收标准提前说清楚。哪些命令跑完算完成失败了先查什么截图和日志看到什么才算过这些越早讲明白后面越省事。我自己有个很简单的判断假如一个任务你都说不清楚「Claude 怎么才算做对了」那它大概率也不适合直接丢给 Claude 自动完成十. 高频命令的工程意义这些命令说白了就干一件事主动管理上下文别等系统自己处理。上下文管理/context# 查看 token 占用结构排查 MCP 和文件读取占比/clear# 清空会话同一问题被纠偏两次以上就重来/compact# 压缩但保留重点配合 Compact Instructions/memory# 确认哪些 CLAUDE.md 真的被加载了能力与治理/mcp# 管理 MCP 连接检查 token 成本断开闲置 server/hooks# 管理 hooks控制平面入口/permissions# 查看或更新权限白名单/sandbox# 配置沙箱隔离高自动化场景必备/model# 切换模型Opus 用于深度推理Sonnet 用于常规Haiku 用于快速探索会话连续性与并行claude--continue# 恢复当前目录最近会话隔天接着做claude--resume# 打开选择器恢复历史会话claude--continue--fork# 从已有会话分叉同一起点不同方案claude--worktree# 创建隔离 git worktreeclaude-pprompt# 非交互模式接入 CI / pre-commit / 脚本claude-p--output-format json# 结构化输出便于脚本消费几个不常见但很好用的命令/simplify对刚改完的代码做三维检查代码复用、质量和效率发现问题直接修掉。特别适合改完一段逻辑后立刻跑一遍代替手动 review。/rewind不是撤销而是回到某个会话 checkpoint 重新总结。适合Claude 已沿错误路径探索太久想保留前半段共识但丢掉后半段失败。/btw在不打断主任务的前提下快速问一个侧问题适合两个命令有什么区别这类单轮旁路问答不适合需要读仓库或调用工具的问题。claude -p --output-format stream-json实时 JSON 事件流适合长任务监控、增量处理、流式集成到自己的工具。/insight让 Claude 分析当前会话提炼出哪些内容值得沉淀到 CLAUDE.md。用法是会话做了一段之后跑一次它会指出这个约定你们反复提到但没有写进契约之类的盲点是迭代优化 CLAUDE.md 的好手段。双击 ESC 回溯按两次 ESC 可以回到上一条输入重新编辑不用重新手打。Claude 走偏了、或者上一句话没说清楚双击 ESC 修改后重发比重新开会话省事得多。对话历史都在本地所有会话记录存放在 ~/.claude/projects/ 下文件夹名按项目路径命名斜杠变横杠每个会话是一个 .jsonl 文件。想找某个话题的历史直接 grep -rl “关键词” ~/.claude/projects/ 就能定位或者直接告诉 Claude「帮我搜一下之前关于 X 的讨论」它会自己去翻。