写在前面本文基于我近半年持续落地 Claude Code 的真实踩坑经验前后两个账号每月投入 40 刀算是交了不少学费。最开始我也只是把 Claude Code 当成普通聊天机器人来使用但是很快就发现各种问题会话上下文越来越杂乱接入的工具越多效果反而越差规则写得越来越长模型却时常无视。花了不少时间深挖 Claude Code 的底层逻辑之后才找到这些问题的根源。想要快速理解它我习惯把 Claude Code 拆解成六层架构来看每一层各司其职1. CLAUDE.md / rules / memory承载长期上下文定义项目基础约定2. Tools / MCP赋予动作能力告诉模型它可以执行哪些操作3. Skills按需加载的工作方法论定义处理任务的流程4. Hooks强制行为拦截不依赖模型自主判断执行5. Subagents具备隔离上下文的独立工作单元实现受控自治6. Verifiers验证闭环保障结果可校验、可回滚、可审计这六层是联动的单独优化某一层很容易在其他层面引发新问题。CLAUDE.md 内容写得过长会直接污染上下文工具堆砌过多模型容易出现选择混乱Subagent 无限制创建任务状态会发生漂移如果跳过验证环节后续出问题很难定位故障点。底层运行机制Agent 循环Claude Code 的核心就是一套持续迭代的代理循环收集上下文 → 采取行动 → 验证结果 →任务完成 或 返回收集阶段整个循环会读取 CLAUDE.md、Skills、Memory 作为基础输入同时由 Hooks、权限沙箱、MCP/Tools 约束行为边界。长期实践下来我发现绝大多数卡点并不是模型推理能力不足。更多情况是传入了错误的上下文或是任务缺少清晰的判定标准就算模型执行了操作也无法判断结果对错更无法回滚。基于这套架构我总结了五个排查诊断维度遇到异常可以逐层定位- 上下文层确定常驻信息与按需加载信息载体为 CLAUDE.md、rules、memory、skills- 动作层管控模型可用能力包含内置工具、MCP、插件- 控制层约束、审计、阻断高危动作依托权限、沙箱、Hooks- 隔离层对任务做上下文与权限隔离使用 Subagent、worktree、独立会话- 验证层判定任务可信完成依靠测试、lint、截图、日志、CI结果不稳定优先排查上下文加载逻辑自动化行为失控检查控制层配置长会话质量衰减大多是中间输出污染上下文新建会话往往比反复调试提示词更高效。厘清核心概念边界避免混用很多人在落地时会混淆这几组概念这里简单区分各自定位- CLAUDE.md项目级持久契约存放会话必须遵守的约束、边界与禁止项。误区把它写成完整团队知识库。- .claude/rules/按路径、语言划分的局部规则。误区所有规则全部堆入根目录 CLAUDE.md。- 内置工具读写文件、执行命令、检索等原生能力。误区所有能力都塞进 shell 调用。- MCP外部系统接入协议连接 GitHub、数据库、监控平台等。误区一次性接入过多服务工具定义挤占上下文。- Plugin打包分发载体可打包 Skills、Hooks、MCP。误区将 Plugin 当成底层运行原语。- Skill按需加载的领域知识与工作流包。误区把 Skill 同时做成百科全书和部署脚本。- Hook生命周期拦截脚本强制执行规则。误区用 Hook 替代所有模型推理判断。- Subagent隔离上下文的独立工作单元。误区无限制并行调用造成治理失控。一句话区分需要新增动作能力用 Tool/MCP需要标准化工作流程用 Skill需要隔离任务环境启用 Subagent需要硬性审计约束配置 Hook想要跨项目复用整套配置打包成 Plugin。上下文工程最核心的系统约束大部分场景下瓶颈不在于上下文窗口上限而是上下文噪音太多有效信息被冗余内容淹没。Claude Code 200K 的上下文窗口并不是全部都能拿来处理业务会有固定开销占用- 固定开销15-20K tokens系统指令、Skill 描述、MCP 工具定义、LSP 状态。MCP 是最大隐形消耗项单个 MCP Server 通常包含 20~30 个工具定义接入 5 个服务仅工具描述就会占用 25K tokens。- 半固定内容5-10K tokensCLAUDE.md、memory- 动态可用区域160-180K tokens对话历史、文件内容、工具返回结果上下文分层最佳实践- 常驻CLAUDE.md只保留项目契约、构建命令、硬性禁止项参考官方范例控制在 2.5K tokens 左右- 按路径加载rules存放语言、目录、文件类型相关局部规范- 按需加载Skills业务工作流与领域知识详细文档放到附属文件不塞进主 SKILL.md- 隔离加载Subagents处理大规模代码检索、并行调研任务- 不入上下文Hooks确定性脚本、审计、阻断逻辑配套操作习惯使用 /context 实时查看 token 占用不要等到自动压缩之后补救切换任务优先 /clear 同一任务进入新阶段使用 /compact 。并且在 CLAUDE.md 中定义压缩优先级规定压缩时优先保留架构决策、文件变更、验证状态、待办与回滚方案工具输出仅保留是否通过的结论交由算法自动压缩很容易丢失关键设计约定。另外还有一个容易忽略的开销工具输出。执行测试、git 查询等命令会一次性输出海量日志全部进入上下文会快速挤占空间。RTKRust Token Killer可以在输出交给模型之前自动过滤冗余信息只保留核心结论例如只返回测试通过数量丢弃数千行详细单条测试日志减少上下文噪声。上下文自动压缩还有一个隐藏陷阱默认策略会优先删除早期文件内容、工具输出连带之前确定的架构决策一起丢失。时隔一段时间继续开发模型会遗忘前期约定莫名产生 bug。除了自定义压缩指令还有一个稳妥方案在开启新会话前让 Claude 生成 HANDOFF.md记录当前进度、尝试过的方案、可行方案与死胡同、下一步计划。新会话直接读取这份交接文档不再依赖压缩摘要。Plan Mode把探索和执行拆开Plan Mode 的核心思想是只读探索与实际执行分离。探索阶段仅做分析不改动任何文件目标方案确认之后再执行修改操作。1. 探索阶段只读操作澄清目标边界输出完整方案2. 确认阶段人工校验方案合理性3. 执行阶段落地代码修改处理大型重构、模块迁移这类高风险改动时这套模式可以避免模型在错误假设上持续投入大量工作量。进阶玩法可以多实例互审一个 Agent 输出方案另一个 Agent 扮演高级工程师做方案评审。Skills 设计不是提示词模板库Skill 是按需加载的工作流描述常驻上下文完整内容仅在触发时加载。一个合格的 Skill 需要明确触发场景、完整步骤、输入输出、终止条件存在副作用的 Skill需要设置 disable-model-invocation: true 禁止模型自动调用。推荐目录结构plaintext.claude/skills/└── incident-triage/├── SKILL.md├── runbook.md├── examples.md└── scripts/└── collect-context.sh常见三类 Skill1. 检查清单型质量门禁例如发布前校验编译、测试、版本、更新日志2. 工作流型标准化高危操作自带备份、试运行、回滚步骤比如配置迁移3. 领域专家型故障诊断框架固定证据收集路径与根因判断矩阵Skill 描述文字要精简减少常驻 token 消耗。同时区分调用频率高频任务允许自动触发低频任务关闭自动调用手动触发极少使用的内容直接移出 Skill写在项目文档中。Skill 反模式描述过于宽泛、正文堆砌大量文档、单个 Skill 包揽多种任务、带风险操作允许模型自动调用。工具设计面向 Agent 的工具和面向人的 API 不一样给 Agent 设计工具核心目标是让模型选对、用好而不是单纯实现功能。- 命名增加前缀区分系统例如 github_pr_、sentry_error_- 参数使用明确字段避免模糊 id- 返回值只返回支撑决策的信息过滤冗余原始字段- 规模单一职责边界清晰默认精简输出从 Claude Code 团队工具迭代中可以学到不要靠标记文本格式、参数 flag 让模型主动暂停询问稳定性很差。更好的做法是单独封装 AskUserQuestion 工具模型需要确认信息时必须显式调用该工具触发暂停逻辑更加可靠。同时也要懂得克制不是所有场景都适合新增工具。本地 shell 可稳定执行、仅需要静态知识、更适合 Skill 约束或是还没有验证稳定性的场景都不建议新增 Tool。Hooks将确定性逻辑从模型手里收回Hooks 是生命周期的拦截脚本用来执行模型不可靠完成的强制校验不要用来处理复杂语义推理业务。适合场景保护文件拦截、修改后自动 lint、会话启动注入环境信息、任务完成推送通知。不适合大量文本推理、长时间业务流程、复杂权衡决策。简单示例配置json{hooks: {PostToolUse: [{matcher: Edit,pattern: *.rs,hooks: [{type: command,command: cargo check 21 | head -30,statusMessage: Running cargo check...}]}]}}Hooks 可以在代码编辑完成后立刻执行编译检查提前捕获错误。注意截断命令输出避免 Hook 日志反过来污染上下文。Hooks、Skills、CLAUDE.md 三者可以形成组合约束CLAUDE.md 定义交付标准Skill 规定操作步骤Hook 在关键节点强制校验阻断。Subagents核心价值是隔离不只是并行Subagent 是独立 Claude 实例拥有独立上下文窗口、可限制可用工具执行完毕后返回摘要结果。像大规模代码扫描、测试执行这类会产生大量输出的任务交给子代理处理主线上下文不会被海量日志挤占。Claude Code 内置三类子代理Explore只读代码检索低成本模型、Plan方案调研、通用代理也支持自定义。配置要点- 限制可用工具最小权限原则- 根据任务选择模型探索使用低成本模型代码审查使用高能力模型- 设置最大轮次防止无限执行- 文件修改场景使用 worktree 隔离文件系统Subagent 常见反模式子代理权限和主会话完全一致、输出格式不固定、子任务之间强依赖共享状态。Prompt 缓存Claude Code 底层核心整套 Claude Code 的架构很大程度围绕 Prompt 缓存设计。高缓存命中率不仅降低成本还能放宽速率限制。缓存是前缀匹配机制固定内容放在前文动态内容放在末尾。推荐 Prompt 顺序1. System Prompt静态锁定2. Tool Definitions静态锁定3. Chat History动态后置4. 当前用户输入末尾破坏缓存的坑系统提示内加入时间戳、随机打乱工具定义、会话中途增删 MCP 服务。动态信息不要修改系统 Prompt放到用户消息中传入。缓存按模型隔离Opus 的缓存无法复用给 Haiku。需要切换模型时优先使用 Subagent 做任务交接。上下文压缩 Compaction当上下文接近上限系统会 fork 当前会话把历史对话交给模型生成摘要保留系统提示、工具定义释放 token 空间。压缩使用缓存成本很低。Plan Mode 的实现细节很巧妙没有切换工具集会破坏缓存而是做成模型可调用的工具模型自主判断进入规划模式。延迟加载 defer_loading 机制大量 MCP 工具不会一次性传入完整 schema先传入轻量占位描述模型选中工具之后再加载完整定义保证缓存前缀稳定。Verifier没有验证闭环就谈不上工程化 Agent模型返回“任务完成”不代表交付合格必须建立验证体系保证结果可核验、可回滚、可审计。- 底层命令退出码、类型检查、单元测试、lint- 中层集成测试、合约测试、截图比对、冒烟测试- 高层生产日志、监控指标、人工检查清单在 CLAUDE.md、Skill 中提前明确验收标准定义 Done 的条件。实用内置命令清单plaintext/context # 查看 token 消耗定位 MCP、文件读取开销/clear # 清空会话/compact # 压缩会话保留关键信息/mcp # MCP 服务管理查看工具数量与消耗/hooks # Hooks 管理入口/permissions # 权限白名单管理/sandbox # 沙箱配置/model # 切换模型/rewind # 回退会话至检查点/insight # 分析会话提炼规则写入 CLAUDE.md还有 claude --continue 恢复历史会话、 --worktree 创建隔离工作树等 CLI 参数适合自动化、CI 场景。怎么写一份合格的 CLAUDE.mdCLAUDE.md 是你和 Claude 的协作契约不是项目百科。不要一次性写满先用起来重复遇到同类问题时再补充规则。✅ 适合写入构建测试命令、目录模块边界、编码规范、环境坑、禁止操作列表、压缩保留规则❌ 不适合写入长篇背景、完整 API 文档、显而易见的信息、低频领域知识放到 Skills模板示例markdown# Project Contract## Build And Test- Install: pnpm install- Dev: pnpm dev- Test: pnpm test- Typecheck: pnpm typecheck- Lint: pnpm lint## Architecture Boundaries- HTTP handlers live in src/http/handlers/- Domain logic lives in src/domain/- Do not put persistence logic in handlers- Shared types live in src/contracts/## Coding Conventions- Prefer pure functions in domain layer- Do not introduce new global state without explicit justification- Reuse existing error types from src/errors/## Safety Rails## NEVER- Modify .env, lockfiles, or CI secrets without explicit approval- Remove feature flags without searching all call sites- Commit without running tests## ALWAYS- Show diff before committing- Update CHANGELOG for user-facing changes## Verification- Backend changes: make test make lint- API changes: update contract tests under tests/contracts/- UI changes: capture before/after screenshots## Compact InstructionsPreserve:1. Architecture decisions (NEVER summarize)2. Modified files and key changes3. Current verification status (pass/fail commands)4. Open risks, TODOs, rollback notes小技巧每次纠正 Claude 的错误之后可以让模型直接更新 CLAUDE.md规避同类问题重复出现定期手动清理过时规则。落地经验总结我在开发开源终端项目 KakuRustLua内置AI能力的过程中踩了大量混合语言项目下 Claude Code 的坑沉淀了两点重要感悟。环境透明优先Claude Code 直接调用本地 shell、git、包管理器一旦环境状态不透明模型就会开始猜测可靠性大幅下降。推荐增加 doctor 命令在任务启动前输出完整环境健康报告。CLI 设计 init/reset 这类语义明确的子命令收敛状态再开放编辑能力。Hooks 也可以按文件类型做差异化配置不同语言绑定对应的语法、编译检查编辑后立刻校验。完整项目目录参考按需裁剪plaintextProject/├── CLAUDE.md├── .claude/│ ├── rules/│ ├── skills/│ ├── agents/│ └── settings.json└── docs/落地反模式汇总反模式 现象 修复方案CLAUDE.md 充当知识库 上下文被稀释关键指令失效 仅保留契约资料拆分到 Skill/rulesSkill 大杂烩 触发不稳定工作流冲突 一个 Skill 只负责一类任务工具过多、描述模糊 模型选错工具挤占上下文 合并重叠工具命名分层缺少验证闭环 模型自认为完成结果不可信 给任务绑定 Verifier 验收标准无边界自治 多代理并行失控难以止损 最小权限限制 maxTurns任务全部堆在主会话 有效上下文被日志污染 重型探索交给 Subagent及时清理会话我把这套配置检查逻辑封装成开源 Skill 项目 tw93/waza可以一键扫描 Claude Code 配置问题执行 /health 输出优化优先级报告。claude plugin marketplace add tw93/wazaclaude plugin install healthwaza结语使用 Claude Code一般会经历三个成长阶段1. 工具使用者只会基础操作有帮助但是提升有限2. 流程优化者开始编写 CLAUDE.md、Skills效率明显提升3. 系统设计者懂得在约束下构建 Agent 自治系统效率产生质变有一句话值得反复思考如果连你自己都无法清晰定义「任务完成的标准」那这个任务就不适合直接交给 Agent 自主执行。验证标准本身就是 Agent 工程落地的第一道门槛。以上是我半年深度实践后的总结里面还有很多值得深挖的细节欢迎技术同行一起交流探讨。如果你想要系统学习 AI Agent 工程落地、前沿部署相关知识可以参考我长期维护的站点- FDE学习站https://cs-wude-fde-learning.pages.dev/- 产品项目站https://cs-wude-product.pages.dev/