Claude Code实战指南：上下文工程与多代理协作技巧

Claude Code 的能力由六个核心模块组成：CLAUDE.md（项目记忆）、MCP（工具连接）、Hooks（自动化触发）、Skills（可复用工作流）、子袋里（上下文隔离）、以及贯穿一切的上下文管理。

很多人装好 Claude Code 就开始用，从来没有认真配置过这六个模块。结果是：Claude 不知道你的项目约定、没有趁手的外部工具、每次操作都弹权限确认、做完任务不验证就交付——能用，但远没到好用。

这篇文章按模块逐个拆解。每个模块都给出该配什么、为什么这么配、最热门的用法是什么。如果你已经有基础使用经验，读完这篇可以直接升级你的配置。如果你刚接触 Claude Code，建议先看 Claude Code 是什么 了解基本概念，再看 Claude Code 完整学习指南 了解全貌。不确定该用 App、CLI 还是 IDE 的，看 三入口怎么选。

一、CLAUDE.md — 项目记忆

CLAUDE.md 是 Claude Code 每次会话启动时自动读取的指令文件。它决定了 Claude 知道哪些项目约定、遵守哪些编码规范、按什么流程工作。

为什么它是第一优先级

没有 CLAUDE.md 的项目，Claude 每次都在猜：用什么模块系统？测试文件放哪？提交（commit）消息什么格式？提交前要不要跑代码检查（lint）？这些猜测有时对有时错，错了你就得手动纠正。

写好 CLAUDE.md 相当于给 Claude 一份入职手册——它读一遍就知道这个项目的规矩，不用你每次口头交代。

最佳实践：精简 + 分层

CLAUDE.md 的每一行都会永久占用上下文窗口。窗口就那么大，被 CLAUDE.md 占太多，留给实际任务的空间就不够了。实际使用经验表明，CLAUDE.md 越短，Claude 的执行准确率越高。控制在 200 行以内时几乎每条规则都能被稳定执行；一旦超过 500 行，Claude 开始无法分辨哪些重要哪些不重要，很多规则会被打折执行或直接忽略。

精简铁律：每一行都做一个测试——"删掉这行，Claude 会不会犯错？"如果 Claude 从代码本身就能推断出来（比如看到 import 语法就知道你用 ESM），那这行就该删。

但精简不等于什么都不写。关键是分层：

第一层：全局 CLAUDE.md（~/.claude/CLAUDE.md）——写所有项目通用的个人偏好。比如"思考语言用英文、交互语言用中文"、"提交消息格式"、"禁止在日志中输出密钥"。通常只需要 10-20 行。

第二层：项目级 CLAUDE.md（项目根目录）——写这个项目独有的约定。技术栈选型、构建命令、测试命令、架构决策、目录结构说明。提交到 Git，团队共享。只写和全局的差异，不重复全局已有的内容。

第三层：条件规则（.claude/rules/ 目录）——特定文件类型才生效的规则。比如 python.md 里写"包管理用 uv，禁止 pip"、"全量类型标注"，文件头用通配符模式（glob）指定匹配路径（如 **/*.py），只有 Claude 处理匹配的文件时才加载。这样 Python 的规则不会在你改 TypeScript 时浪费上下文。

第四层：@import 引用——CLAUDE.md 支持 @docs/git-workflow.md 语法引入外部文件。但引用等于把文件全文永久塞入上下文。只引用短小的、每次会话都必须用的约定文件。长文档（API 参考、完整规范）让 Claude 用 Read 工具按需读取，读完处理完就释放了。

真实案例

我自己的全局 CLAUDE.md 只有 15 行：语言偏好、简称定义、归档策略。项目级的知识库 CLAUDE.md 有 333 行，但其中大部分是路由表和触发词——Claude 不会一次性把 333 行全部"记住"，而是按你的请求关键词匹配到对应的路由条目，然后只读取那个条目指向的子目录 CLAUDE.md。这种"索引式"写法远比"百科全书式"高效。

? 实战提示词

审计现有 CLAUDE.md：把以下提示词粘贴到 Claude Code 中，它会帮你精简你的 CLAUDE.md。

从零生成 CLAUDE.md：对于还没有 CLAUDE.md 的新项目，用 /init 命令自动生成一份基础版本，然后用以下提示词优化。

→ 深入阅读：CLAUDE.md 怎么写？项目记忆文件新手指南 · CLAUDE.md 最佳实践

二、MCP — 工具连接

MCP（Model Context Protocol，模型上下文协议）是 Anthropic 推出的开放标准，定义了 AI 工具与外部服务之间的通信方式。通过 MCP，Claude 能调用外部服务——搜索引擎、代码仓库、网页抓取、浏览器操作、编程文档查询。没有 MCP，Claude 只能操作本地文件和跑终端命令；有了 MCP，它能搜互联网、读 GitHub 议题（Issue）、抓网页内容、查最新的库文档。

? 通俗讲：MCP 就像 AI 工具的 USB-C 接口。USB-C 让所有电子设备用同一根线连接，MCP 让所有 AI 工具用同一套协议连接外部服务。一个 MCP 服务器写一次，Claude Code、Cursor、VS Code 都能用。

不是越多越好

每个 MCP 服务器的工具列表和描述都会占用上下文空间。装了 15 个 MCP、每个暴露 5 个工具，就是 75 个工具描述永久塞在窗口里。Claude 在决定用哪个工具时会产生选择困难——就像你面前摆了 75 把不同的扳手，每次都得花时间辨认该用哪把——推理速度变慢，有时甚至选错工具。

推荐策略是"最小集常驻 + 按需启用"：保留 3-5 个高频使用的 MCP 常驻配置，其余注释掉，需要时解开。判断标准很简单：一周内用不到两次的就不该常驻。

推荐配置清单

以下是基于社区热度和实际验证的推荐清单，按优先级排序：

这五个覆盖了日常开发 90% 的外部工具需求。如果你做数据分析，可以按需加 PostgreSQL 或 SQLite MCP；如果你做项目管理，可以加 Notion 或 Linear MCP。但不要一开始就全装上。

密钥管理

MCP 通常需要 API Key。绝对不要把密钥明文写在配置文件里——配置文件可能被提交到 Git、被同步工具散播、被日志扫描。

正确做法是把密钥写入一个独立的文件（权限设为 600，仅自己可读），配置文件中只写环境变量名称，用一个包装脚本（wrapper，就是一个在启动目标程序之前先加载密钥的中间脚本）在 MCP 服务器启动时注入真实值。这样配置文件可以安心共享和版本控制，密钥只存在于每台机器本地。

避免启动卡顿

MCP 服务器在 Claude Code 启动时加载。如果你在配置中写了需要联网下载的动态安装命令，每次启动都会多等 2-5 秒做版本解析。正确做法是先把 MCP 服务器全局安装到固定路径，配置文件直接指向安装后的可执行文件。

? 实战提示词

一键配置推荐 MCP 组合：

审计现有 MCP 配置：

→ 深入阅读：Claude Code MCP 新手指南 · MCP 最佳实践 · Plugins 扩展机制

三、Hooks — 自动化触发

钩子（Hooks）是挂在 Claude 工作流特定节点上的自动化脚本——每当 Claude 执行到这个节点（比如准备调用工具、准备停止工作），钩子脚本就自动触发。和 CLAUDE.md 的本质区别在于：CLAUDE.md 是建议，钩子是强制。

? 通俗讲：CLAUDE.md 像公司的员工手册——大部分人会遵守，但赶进度时可能跳过。钩子像门禁系统——没有权限卡你物理上就进不了门，不存在"跳过"的可能。

CLAUDE.md 里写"禁止执行 rm -rf"，Claude 99% 的时候会遵守，但在复杂场景中可能为了走捷径而忽略。如果你把同样的规则做成 PreToolUse（工具调用前）钩子——一个检测到危险命令就返回错误的脚本——Claude 物理上就执行不了这个命令，不管它多想这么做。

该放 CLAUDE.md 还是做 Hook？

判断标准：违反后果可以事后修复的偏好写 CLAUDE.md，违反后果不可逆的硬规则做钩子。

代码风格偏好（缩进、命名）→ 写 CLAUDE.md，违反了事后格式化就行。禁止删除某个关键目录 → 做钩子，删了可能就没了。改完代码必须跑测试 → 做 Stop（停止前）钩子，不跑测试直接交付是质量事故。

最实用的四个钩子

基于社区热度和实际使用经验，以下四个钩子的投入产出比最高：

UserPromptSubmit（用户提交提示词时）— 时间注入

Claude 不知道"现在几点"。如果你的任务和时间相关（比如"帮我检查今天的日志"），Claude 会猜一个时间或者直接忽略。挂一个 UserPromptSubmit Hook，每次你提交提示词时自动注入当前时间和时区，Claude 就能准确理解时间上下文了。

这个钩子实现极简——脚本获取系统时间，格式化后输出。但它解决的问题非常高频，几乎所有认真配置 Claude Code 的人都会装这个。

PreToolUse（工具调用前）— 危险命令拦截

在 Claude 执行任何工具之前触发。你可以写一个脚本检查即将执行的命令是否匹配危险模式（如 rm -rf /、git push --force、删除生产配置等）。匹配到就阻止执行，输出警告信息。脚本通过退出码（exit code）控制行为——返回非零值表示拦截，返回零表示放行。

这是 Claude Code 安全体系的最后一道防线。即使权限模式设为完全放开，PreToolUse 钩子仍然能拦住你明确禁止的操作。

PostToolUse（工具调用后）— 自动代码检查

在 Claude 修改文件之后自动触发。典型用法是挂一个代码检查工具（linter，检测代码风格和潜在错误的静态分析工具）——Claude 每次写完代码，钩子自动跑检查。如果有问题，输出直接反馈给 Claude，它会在下一步修正。

实际使用中，加了 PostToolUse 自动检查后，代码审查中格式相关的来回大幅减少——因为格式问题在 Claude 写完的瞬间就被自动修正了，不用等到审查阶段才发现。

Stop（停止前）— 验证 + 通知

Claude 准备停止工作时触发。两个典型用法：一是挂验证脚本，测试没通过就阻止停止、Claude 继续迭代修复（这就是"无人值守模式"的核心）；二是发通知（推送到手机、发消息到聊天工具），让你知道 Claude 干完了。

无人值守模式的完整流程是：你给 Claude 一个任务然后走开 → Claude 工作 → 准备停止 → Stop 钩子跑测试 → 测试没过 → 阻止停止 → Claude 继续修 → 再次准备停止 → 再跑测试 → 通过 → 允许停止 + 推送通知到你手机。连续多次失败后 Claude 会强制停止，防止无限循环。

? 实战提示词

一键配置四个核心钩子：

诊断现有钩子是否正常工作：

→ 深入阅读：Claude Code Hooks 新手指南

四、Skills — 可复用工作流

技能（Skill）是一个定义好的多步操作流程，用 /skill-name 手动触发。比如你定义一个 fix-issue 技能：获取 GitHub 议题详情 → 分析问题 → 搜索相关源文件 → 实现修复 → 写测试 → 通过代码检查 → 提交并创建拉取请求（PR）。以后每次修 Issue，输入 /fix-issue 1234 就自动走完这套流程。

如果你的需求比 Skill 更轻量——只是想把一段常用提示词存成快捷命令——可以用 Slash Commands，不需要定义完整的工作流结构。

Skill 和子袋里、MCP 的区别

三者经常被混淆，其实解决的问题完全不同：

? 通俗讲：Skill 是菜谱（步骤固定，照做就行），子袋里是外派调研员（过程随意，只要报告），MCP 是工具箱里的扳手（需要时拿起来用）。

好 Skill 的五个特征

Firecrawl 团队总结了设计高质量 Skill 的五个判断标准，社区广泛认可：

精确的触发描述。技能定义文件 SKILL.md 的文件头元数据（frontmatter）中有一个 description 字段，它决定了 Claude 什么时候自动激活这个技能。"帮助处理文档"太模糊——Claude 不知道什么时候该激活。"用户要求从 PDF 中提取表单字段、填写、脱敏或解析表格时使用"足够具体——Claude 看到匹配请求就会自动调用。好的描述读起来像一个条件判断语句：满足条件就触发，不满足就跳过。

脚本做确定性工作。需要排序、解析、格式化的操作不要靠 Claude 推理，用脚本完成。Claude 负责理解意图和做判断，脚本负责可重复的机械操作。

SKILL.md 要精简。内容在手机屏幕上能看完——如果你的 SKILL.md 超过 50 行，大概率该拆成两个 Skill。太长的 Skill 执行失败率显著上升。

单一职责。每个 Skill 只做一件事。不要把"修 Issue"和"写文档"合并成一个 Skill——它们是两个独立的工作流。

具体示例胜过抽象规则。3 个写明输入输出的真实示例，比 20 条抽象约束更能让 Claude 理解你想要什么。

热门 Skill 类型

根据社区使用频率，最热门的五类 Skill：

1. 文档处理——Word、PDF、Excel、PPT 的创建和编辑
2. 安全审查——静态代码分析、依赖漏洞扫描、密钥泄露检测
3. Web 测试——Playwright 端到端自动化测试（社区反馈省时最显著，从 15 分钟降到 2 分钟）
4. 配图生成——用 AI 模型生成文章封面和正文插图
5. 数据处理——Google Workspace 自动化、Notion 同步、批量格式转换

? 实战提示词

创建你的第一个 Skill：

批量审计已有 Skill 质量：

→ 深入阅读：Skill 开发完全指南 · Skill 工作流开发教程 · Skill 从入门到便现 · Skill 应用商店 · Agent 自动调 Skill 实战

五、子袋里 — 上下文隔离

子袋里（subagent）在独立的上下文窗口中运行。它去读文件、做分析，完成后只把结论返回给你的主会话。那些被读取的文件内容留在子袋里的窗口里，不污染你的主会话。

为什么需要隔离

假设你要了解一个陌生模块的实现逻辑。Claude 需要读十几个文件、理清调用关系。如果在主会话中做，这十几个文件的内容全部进入上下文窗口。分析完之后这些内容对后续工作已经没用了——但它们还占着空间，挤压你做下一个任务的容量。

子袋里解决的就是这个问题：读很多文件、但只返回结论。

三种最实用的模式

研究隔离——探索陌生代码时，让子袋里去读、去分析，回来给你一段摘要。你的主会话保持干净，上下文全留给后续的实际编码。

写作者/审查者分离（Writer/Reviewer）——写代码和审代码用两个独立会话。写代码的会话（写作者）实现功能后，启动一个审查子袋里（审查者）从干净的上下文审查代码。审查者没有"自己写的代码"产生的确认偏误——人审查自己写的代码时会不自觉地跳过问题，AI 也一样。用独立上下文的审查者打破这个偏误，实际效果是审查质量显著提高——因为审查者的上下文完全干净，没有"自己写的代码"产生的认知盲区。

多角色审查——定义多个专家子袋里（安全审查员、架构审查员、性能审查员），对同一段代码从不同维度独立审查。每个审查员在自己的上下文窗口里工作，互不影响，降低了单一视角的盲区。

自定义子袋里

在 .claude/agents/ 目录下创建 Markdown 文件定义专家角色。文件的头部元数据（frontmatter）声明名称、描述、可用工具列表和模型选择，正文写角色定义和关注点。定义好之后在对话中说"用 security-reviewer 审查这个目录"即可触发。

自定义子袋里的价值在于可复用的专家视角——你不用每次都在提示词里重复描述审查维度，定义一次、反复使用。

什么时候不需要子袋里

改动小、涉及文件少、或者你需要在对话中持续引用上下文（一边改一边讨论设计）的场景。启动子袋里有固定开销，任务本身 30 秒能完成的话，开销不划算。

? 实战提示词

创建安全审查子袋里：

用 Writer/Reviewer 模式审查代码：

→ 深入阅读：Claude Code Subagents 新手指南 · 动态工作流：多 Agent 编排模式

六、上下文管理 — 贯穿一切的底层逻辑

前五个模块本质上都在做同一件事：管理上下文窗口的质量。

CLAUDE.md 管的是会话启动时加载什么指令。MCP 的工具描述占用多少上下文空间。Hooks 在不占用上下文的前提下提供确定性控制。Skills 在主会话上下文中执行标准化工作流。子袋里把高消耗的探索隔离到独立窗口。

理解了这个底层逻辑，剩下的就是几个日常操作习惯。

/clear 的节奏

/clear 清空当前上下文，重新开始。很多人觉得"之前聊了这么多，清掉不是白聊了吗？"恰恰相反——在两个不相关的任务之间不清上下文，是 Claude 产出质量下降最常见的原因。

前一个任务的文件内容、失败尝试、中间推理全部留在窗口里，挤占新任务的空间。更危险的是，Claude 可能被前一个任务的"残留记忆"误导——它记得上个任务里某个文件的旧版本，然后在新任务里用了错误的假设。

建议的节奏：一个任务做完 commit 之后，立刻 /clear。 想接着聊用 claude --continue，想回到之前的会话用 claude --resume。

/compact 精准瘦身

/compact 比 /clear 温和——不清空，只压缩。更好用的是你可以指定保留重点：/compact Focus on the API changes 告诉压缩器"API 相关改动是重点，其他大幅精简"。

当上下文使用率接近上限时（默认约 80-95%，不同版本有差异），Claude 会自动触发压缩（Auto-Compact，自动精简）。你可以通过环境变量 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 调整触发阈值——比如设为 60 意味着更早触发，给复杂任务留更多余量。对于涉及大量文件操作的长会话，建议把阈值调低一些，避免窗口快满时才压缩导致关键信息丢失。

连续纠正两次还不对：信号灯亮了

如果你对 Claude 的同一个错误纠正了两次它还是没改对——不要继续第三次。窗口里已经积累了两轮失败方案和你的纠正指令，Claude 反而更容易被这些"失败记忆"干扰。

正确做法：/clear，重新写一个更清晰的初始提示词，从干净的上下文开始。

权限模式

五档模式从严到松：default（所有操作需确认）→ acceptEdits（文件编辑自动通过，终端命令仍需确认）→ plan（只允许读取和规划，禁止写操作）→ dontAsk（除高危操作外全部自动放行）→ bypassPermissions（跳过所有权限检查，全部放行）。

长期使用的推荐组合是全部放行（bypassPermissions）配合钩子硬拦截。权限完全放开（效率最高），但用 PreToolUse 钩子拦住真正危险的操作。同时在 settings 中设置敏感路径黑名单（如 .env、.ssh、.aws），Claude 物理上无法读取这些文件。

这比逐个确认高效得多——你不会被"是否允许 Claude 读取 src/index.ts"的弹窗打断几十次，但 rm -rf / 和读取密钥文件仍然被硬性阻止。

环境变量调优

几个值得设置的环境变量（在 settings.json 的 env 字段中）：

? 实战提示词

一键优化 settings.json：

诊断上下文健康度：

想实时监控上下文消耗，可以配一个状态栏脚本，在终端底部显示 token 用量、模型、缓存命中率等信息——详见 状态栏教程。

如果想降低 token 成本，可以把部分任务分流到第三方模型（如 DeepSeek）——配置方法和实测效果见 DeepSeek V4 接入实测。

→ 深入阅读：上下文窗口指南 · 权限指南 · thinking modes 指南 · 四机同步方案

验证：给 Claude 一个可以自证的标准

Anthropic 官方把"给 Claude 可执行的验证条件"列为头号最佳实践。原因很直接：有验证条件时，Claude 会进入"实现→验证→修复"的自我迭代闭环，产出质量远高于"做完就停"的模式。

没有验证的指令："实现一个邮箱验证函数。"Claude 做完就停——它自认为完成了，但可能漏了边界情况。

有验证的指令："实现 validateEmail 函数。[email protected] 返回 true，invalid 返回 false，[email protected] 返回 false。实现后跑测试，修复失败的用例。"Claude 会进入一个自我迭代的闭环：实现 → 跑测试 → 失败 → 修复 → 再跑 → 通过 → 交付。

验证的四个层次从低到高：在提示词中要求跑测试（最基础）→ /goal 设置持续验证守卫（每轮自动检查）→ Stop Hook 确定性拦截（不通过不让停）→ 子袋里对抗性审查（独立视角复查）。

建议至少做到第二层。对于重要的任务，第三层（Stop Hook）是质量底线。

? 实战提示词

带验证的任务模板（每次给 Claude 下任务时套用这个结构）：

设置持续验证守卫（给当前会话设一个质量底线）：

→ 深入阅读：Claude Code 提示词工程指南

获取完整配置模板

本文介绍的所有最佳实践——CLAUDE.md 层级设计、MCP 推荐配置、Hook 脚本、Skill 定义、子袋里模板、环境变量调优——都有可直接复用的完整配置文件，收录在翔宇的 AI 编程实操课中。

? 查看 AI 编程实操课完整目录

延伸阅读

• Claude Code 完整学习指南——从零开始的 13 个知识点地图
• CLAUDE.md 最佳实践——Karpathy 四原则 + 6 套完整模板
• Claude Code 动态工作流——六大编排模式 + ultracode 实战
• Claude Code 官方最佳实践——Anthropic 官方文档