Claude Code 终极指南（上）：从记忆系统到多代理架构

Claude Code 终极指南（上）：从记忆系统到多代理架构 Claude Code 终极指南（上）：从记忆系统到多代理架构 Modified February 28 Code block JSON Copy { "type": "command", "command": "node scripts/hooks/pre compact.js" } ] } ], "SessionStart": [ { "hooks": [ { "type": "command", "command": "node scripts/hooks/session start.js" } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "node scripts/hooks/session end.js" } ] } ] } } • SessionStart ：会话开始时加载上次的进度文件，检测包管理器类型 • PreCompact ：压缩前把关键状态保存到文件 • Stop ：会话结束时持久化本次的学习成果 4.7 持续学习系统 这是黑客松冠军仓库最有创意的实践之一——让 Claude 从每次会话中自动学习，把发现的模式固化为新的规则。 V1 版本：基于 Stop Hook 的模式提取 会话结束时，Stop Hook 触发一个脚本，分析本次会话中 Claude 的行为模式（用户纠正了什么、哪些方案失败了、哪些模式被重复使用），然后把提取到的模式写入 /.claude/skills/learned/ 目录。 问题是 Stop Hook 的触发率只有 50 80%（Claude 有时会以不同方式结束会话）。 V2 版本（Instinct Based）：基于 PreToolUse/PostToolUse 的观测 V2 彻底解决了触发率问题——用 Hook（而非 Skill）来观测 Claude 的行为， 100% 触发 。 核心概念是" Instinct（本能） "——原子级的行为模式，每个 Instinct 只有一个触发条件和一个动作： Code block YAML Copy id: prefer functional style trigger: "when writing new functions" confidence: 0.7 domain: "code style" source: "session observation" 偏好函数式风格 Action 使用函数式模式（map/filter/reduce），而非 class 和 for 循环。 Instinct 的置信度会动态变化： • 模式被重复观测到 → 置信度上升 • 用户纠正了这个行为 → 置信度下降 • 长期没有观测到 → 置信度衰减 当 3 个以上相关的 Instinct 聚集到一起，系统会自动把它们合并成一个 Skill 或 Command。 这意味着什么？ Claude 用得越多，越懂你的偏好。它会自动记住你喜欢函数式还是 OOP、喜欢 2 空格还是 4 空格、喜欢 commit 用英文还是中文——而且这些记忆有置信度评分，不是死板的规则。 4.8 高级 Hook 架构 Boris 团队的一个成员把权限请求通过 Hook 路由给 Opus 模型，让 AI 自动做安全扫描和审批。安全的操作自动放行，危险的操作自动拒绝。团队称这是"用 AI 来管 AI"。 黑客松冠军仓库的另一个高阶用法： PostToolUse Hook 检测 console.log 。每次编辑完文件，自动检查是否引入了新的 console.log ，如果有就发出警告。这个 Hook 配合 Stop Hook（检查所有修改的文件中是否有 console.log 残留），形成双重保障。 Code block JSON Copy { "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "node scripts/hooks/post edit console warn.js" } ] } ] } 五、多代理架构与并行开发 一个 Claude 能做的事情有限——但 5 个 Claude 分工协作，就能处理一个团队级别的任务。 Subagents 团队协作工作流 5.1 Subagents：Claude 的"分身术" Subagents 解决两个核心问题： 上下文污染 ：你让 Claude 去研究一个大型代码库的认证系统，它读了 50 个文件后，你的上下文窗口就被填满了，后续工作效率直线下降。 串行瓶颈 ：一次只做一件事，太慢了。三个独立的审查任务，串行做要 15 分钟，并行做只要 5 分钟。 Subagents 的解法：把任务委派给独立的子代理，它们有自己的上下文窗口，完成后只返回精简的结果给主会话。 隐式调用 ——直接告诉 Claude 用子代理： Code block Plain Text Copy 用 subagent 分析一下我们的认证系统是怎么处理 token 刷新的。 并行调用 ——同时启动多个子代理： Code block Plain Text Copy 帮我做一次全面的代码审查，用三个并行的子代理： 1. 一个审查安全漏洞 2. 一个检查性能问题 3. 一个检查测试覆盖率 最后汇总三份报告。 Claude 会同时 spawn 三个子代理，各自独立工作，最后汇总结果。 5.2 自定义 Agent 在 .claude/agents/ 目录下创建 Markdown 文件来定义专业化的 Agent。黑客松冠军仓库定义了 14 个 Agent，覆盖了开发全链路： Agent 模型 工具权限 职责 architect Opus Read, Grep, Glob（只读） 系统架构设计、技术决策、ADR 文档 planner Opus Read, Grep, Glob（只读） 任务分解、实现计划、风险评估 code reviewer Sonnet Read, Grep, Glob, Bash 代码审查、只报告 80% 置信度的问题 security reviewer Sonnet Read, Write, Edit, Bash, Grep, Glob OWASP Top 10 安全审查 database reviewer Sonnet 同上 查询优化、Schema 设计、RLS 策略 tdd guide Sonnet Read, Write, Edit, Bash, Grep 强制 TDD 流程，先写测试再写码 build error resolver Sonnet 同上 构建错误修复，最小化改动 refactor cleaner Sonnet 同上 死代码清理、依赖整合 e2e runner Sonnet 同上 E2E 测试编写和维护 doc updater Haiku 同上 文档生成和更新（成本敏感） chief of staff Opus 全部 多渠道通讯协调（邮件/Slack） 注意模型选择的逻辑： • 架构和规划 用 Opus（需要深度推理） • 代码审查和实现 用 Sonnet（性价比最优） • 文档生成 用 Haiku（结构简单，省钱） 创建一个 Agent 的示例： Code block YAML Copy .claude/agents/security reviewer.md name: security reviewer description: 安全漏洞检测与修复建议 model: claude sonnet 4 6 allowed tools: Read, Grep, Glob, Bash 你是一名安全审查专家。对给定的代码进行 OWASP Top 10 安全审查： 1. 注入攻击 ：SQL 注入、命令注入（是否用参数化查询？） 2. 认证缺陷 ：密码存储（是否用 bcrypt？）、JWT 验证 3. 敏感数据泄露 ：是否有硬编码密钥、日志中是否泄露 PII 4. XSS ：输出是否转义、CSP 头是否配置 5. CSRF ：是否有 CSRF token、SameSite cookie 是否设置 6. 不安全的依赖 ：运行 npm audit / pip audit 只报告置信度 80% 的问题。 按严重程度排序：CRITICAL HIGH MEDIUM LOW。 每个问题包含：文件路径、行号、漏洞描述、修复建议、修复代码示例。 5.3 迭代检索模式 子代理返回的结果有时不够好。因为它缺乏主会话的语义上下文——它只知道你的字面查询，不知道你的真正目的。 解法：迭代追问，最多 3 轮。 Code block Plain Text Copy DISPATCH（广泛查询）→ EVALUATE（评分相关性）→ REFINE（更新条件）→ LOOP（最多 3 轮） 关键是传给子代理的不只是"查询"，还要传"目的"： 差的做法： "搜索认证相关代码" 好的做法： "我要把 JWT 迁移到 Session。搜索所有需要改动的认证代码，包括中间件、token 验证、刷新逻辑、注销逻辑" 第一次返回后，主会话评估结果是否充分。如果缺少某些维度的信息，再追问具体的问题。最多三轮，避免无限循环。 5.4 编排流水线 把子代理串联成流水线，每个阶段有明确的输入和输出： Code block Plain Text Copy 阶段 1：RESEARCH (Explore agent) → research summary.md ↓ 阶段 2：PLAN (Planner agent) → plan.md ↓ 阶段 3：IMPLEMENT (TDD Guide agent) → 代码改动 ↓ 阶段 4：REVIEW (Code Reviewer agent) → review comments.md ↓ 阶段 5：VERIFY (Build Error Resolver) → 通过 → Done → 失败 → 回到阶段 3 • SessionStart ：会话开始时加载上次的进度文件，检测包管理器类型 • PreCompact ：压缩前把关键状态保存到文件 • Stop ：会话结束时持久化本次的学习成果 4.7 持续学习系统 这是黑客松冠军仓库最有创意的实践之一——让 Claude 从每次会话中自动学习，把发现的模式固化为新的规则。 V1 版本：基于 Stop Hook 的模式提取 会话结束时，Stop Hook 触发一个脚本，分析本次会话中 Claude 的行为模式（用户纠正了什么、哪些方案失败了、哪些模式被重复使用），然后把提取到的模式写入 /.claude/skills/learned/ 目录。 问题是 Stop Hook 的触发率只有 50 80%（Claude 有时会以不同方式结束会话）。 V2 版本（Instinct Based）：基于 PreToolUse/PostToolUse 的观测 V2 彻底解决了触发率问题——用 Hook（而非 Skill）来观测 Claude 的行为， 100% 触发 。 核心概念是" Instinct（本能） "——原子级的行为模式，每个 Instinct 只有一个触发条件和一个动作： Instinct 的置信度会动态变化： • 模式被重复观测到 → 置信度上升 • 用户纠正了这个行为 → 置信度下降 • 长期没有观测到 → 置信度衰减 当 3 个以上相关的 Instinct 聚集到一起，系统会自动把它们合并成一个 Skill 或 Command。 这意味着什么？ Claude 用得越多，越懂你的偏好。它会自动记住你喜欢函数式还是 OOP、喜欢 2 空格还是 4 空格、喜欢 commit 用英文还是中文——而且这些记忆有置信度评分，不是死板的规则。 4.8 高级 Hook 架构 Boris 团队的一个成员把权限请求通过 Hook 路由给 Opus 模型，让 AI 自动做安全扫描和审批。安全的操作自动放行，危险的操作自动拒绝。团队称这是"用 AI 来管 AI"。 黑客松冠军仓库的另一个高阶用法： PostToolUse Hook 检测 console.log 。每次编辑完文件，自动检查是否引入了新的 console.log ，如果有就发出警告。这个 Hook 配合 Stop Hook（检查所有修改的文件中是否有 console.log 残留），形成双重保障。 五、多代理架构与并行开发 一个 Claude 能做的事情有限——但 5 个 Claude 分工协作，就能处理一个团队级别的任务。 Subagents 团队协作工作流 5.1 Subagents：Claude 的"分身术" Subagents 解决两个核心问题： 上下文污染 ：你让 Claude 去研究一个大型代码库的认证系统，它读了 50 个文件后，你的上下文窗口就被填满了，后续工作效率直线下降。 串行瓶颈 ：一次只做一件事，太慢了。三个独立的审查任务，串行做要 15 分钟，并行做只要 5 分钟。 Subagents 的解法：把任务委派给独立的子代理，它们有自己的上下文窗口，完成后只返回精简的结果给主会话。 隐式调用 ——直接告诉 Claude 用子代理： 并行调用 ——同时启动多个子代理： Claude 会同时 spawn 三个子代理，各自独立工作，最后汇总结果。 5.2 自定义 Agent 在 .claude/agents/ 目录下创建 Markdown 文件来定义专业化的 Agent。黑客松冠军仓库定义了 14 个 Agent，覆盖了开发全链路： Agent 模型 工具权限 职责 architect Opus Read, Grep, Glob（只读） 系统架构设计、技术决策、ADR 文档 planner Opus Read, Grep, Glob（只读） 任务分解、实现计划、风险评估 code reviewer Sonnet Read, Grep, Glob, Bash 代码审查、只报告 80% 置信度的问题 security reviewer Sonnet Read, Write, Edit, Bash, Grep, Glob OWASP Top 10 安全审查 database reviewer Sonnet 同上 查询优化、Schema 设计、RLS 策略 tdd guide Sonnet Read, Write, Edit, Bash, Grep 强制 TDD 流程，先写测试再写码 build error resolver Sonnet 同上 构建错误修复，最小化改动 refactor cleaner Sonnet 同上 死代码清理、依赖整合 e2e runner Sonnet 同上 E2E 测试编写和维护 doc updater Haiku 同上 文档生成和更新（成本敏感） chief of staff Opus 全部 多渠道通讯协调（邮件/Slack） Agent Agent 模型 模型 工具权限 工具权限 职责 职责 architect architect Opus Opus Read, Grep, Glob（只读） Read, Grep, Glob（只读） 系统架构设计、技术决策、ADR 文档 系统架构设计、技术决策、ADR 文档 planner planner Opus Opus Read, Grep, Glob（只读） Read, Grep, Glob（只读） 任务分解、实现计划、风险评估 任务分解、实现计划、风险评估 code reviewer code reviewer Sonnet Sonnet Read, Grep, Glob, Bash Read, Grep, Glob, Bash 代码审查、只报告 80% 置信度的问题 代码审查、只报告 80% 置信度的问题 security reviewer security reviewer Sonnet Sonnet Read, Write, Edit, Bash, Grep, Glob Read, Write, Edit, Bash, Grep, Glob OWASP Top 10 安全审查 OWASP Top 10 安全审查 database reviewer database reviewer Sonnet Sonnet 同上 同上 查询优化、Schema 设计、RLS 策略 查询优化、Schema 设计、RLS 策略 tdd guide tdd guide Sonnet Sonnet Read, Write, Edit, Bash, Grep Read, Write, Edit, Bash, Grep 强制 TDD 流程，先写测试再写码 强制 TDD 流程，先写测试再写码 build error resolver build error resolver Sonnet Sonnet 同上 同上 构建错误修复，最小化改动 构建错误修复，最小化改动 refactor cleaner refactor cleaner Sonnet Sonnet 同上 同上 死代码清理、依赖整合 死代码清理、依赖整合 e2e runner e2e runner Sonnet Sonnet 同上 同上 E2E 测试编写和维护 E2E 测试编写和维护 doc updater doc updater Haiku Haiku 同上 同上 文档生成和更新（成本敏感） 文档生成和更新（成本敏感） chief of staff chief of staff Opus Opus 全部 全部 多渠道通讯协调（邮件/Slack） 多渠道通讯协调（邮件/Slack） 注意模型选择的逻辑： • 架构和规划 用 Opus（需要深度推理） • 代码审查和实现 用 Sonnet（性价比最优） • 文档生成 用 Haiku（结构简单，省钱） 创建一个 Agent 的示例： 5.3 迭代检索模式 子代理返回的结果有时不够好。因为它缺乏主会话的语义上下文——它只知道你的字面查询，不知道你的真正目的。 解法：迭代追问，最多 3 轮。 关键是传给子代理的不只是"查询"，还要传"目的"： 差的做法： "搜索认证相关代码" 好的做法： "我要把 JWT 迁移到 Session。搜索所有需要改动的认证代码，包括中间件、token 验证、刷新逻辑、注销逻辑" 第一次返回后，主会话评估结果是否充分。如果缺少某些维度的信息，再追问具体的问题。最多三轮，避免无限循环。 5.4 编排流水线 把子代理串联成流水线，每个阶段有明确的输入和输出： 关键规则： 1. 每个 Agent 一个输入，一个输出 2. 输出就是下一阶段的输入 3. 不要跳过阶段 4. 阶段之间用 /clear 清除上下文 5. 中间产物存到文件（.md），不要全放在上下文里 这个模式的价值在于：每个 Agent 只需要关注自己阶段的信息，不会被前面阶段的大量细节干扰。 5.5 Git Worktree：真正的并行开发 如果你开两个 Claude Code 会话指向同一个项目目录，灾难就来了——它们会互相覆盖对方的修改。 Git Worktree 让你从同一个仓库创建多个独立的工作目录，每个目录有自己的分支和文件状态，但共享 Git 历史： Claude Code 原生 Worktree 支持： Claude 会在 .claude/worktrees/ 下创建独立目录，自动管理分支。 5.6 两实例启动模式 黑客松冠军仓库推荐的新项目启动方式——同时开两个 Claude 实例： 实例 1：Scaffolding Agent（脚手架） • 搭建项目结构 • 创建配置文件（CLAUDE.md、rules、agents） • 初始化依赖和工具链 实例 2：Deep Research Agent（深度调研） • 连接外部服务、搜索文档 • 创建详细的 PRD（产品需求文档） • 生成架构 Mermaid 图 • 收集实际文档片段作为参考 两个实例并行工作，Research Agent 完成后把输出文件（PRD、架构图）交给 Scaffolding Agent 参考，大幅缩短项目启动时间。 5.7 Cascade Method 同时管理多个 Claude 实例时的任务管理方法： 1. 新任务在 右侧 打开新 tab 2. 从 左到右 扫描，最左边是最旧的任务 3. 同时关注的任务不超过 3 4 个 4. 完成一个关掉一个，持续扫描 配合 Ctrl+T 查看全局任务列表、 /rename 给每个会话起名、给不同 worktree 的终端标签设置不同颜色。 5.8 Agent Teams（实验性） Agent Teams 是 Claude Code 最前沿的功能——多个 Claude 实例组成团队，可以互相发消息、辩论、协作。 与 Subagents 的区别： 维度 Subagents Agent Teams 通信方式 只返回结果 可以互相发消息、辩论 成本 较低 较高（每个 agent 独立计费） 适用场景 独立子任务 需要协作和讨论的复杂任务 稳定性 稳定 实验性功能 维度 维度 Subagents Subagents Agent Teams Agent Teams 通信方式 通信方式 只返回结果 只返回结果 可以互相发消息、辩论 可以互相发消息、辩论 成本 成本 较低 较低 较高（每个 agent 独立计费） 较高（每个 agent 独立计费） 适用场景 适用场景 独立子任务 独立子任务 需要协作和讨论的复杂任务 需要协作和讨论的复杂任务 稳定性 稳定性 稳定 稳定 实验性功能 实验性功能 启用方式： 杀手级用法：竞争假说调试法 遇到诡异的 bug？同时 spawn 5 个 agent，每个调查不同的假说： 团队规模指南： • 最佳规模：3 5 个队友 • 每人任务量：5 6 个任务 • 铁律： 三个专注的队友 五个分散的队友 • 告诉 Team Lead："等你的队友完成任务后再继续"，否则它可能自己抢活干 下篇预告 上篇我们讲了 Claude Code 的核心体系——从 CLAUDE.md 记忆系统到多代理并行开发。下篇将进入更硬核的领域： • 无头模式 ：让 Claude 在后台批量处理、接入 CI/CD 管线 • MCP 与 Plugins ：连接外部工具、LSP 实时代码智能 • 安全工程 ：攻击面分析、AgentShield 扫描、供应链防护——大多数人完全忽略的关键领域 • 速查手册 ：所有快捷键、命令、CLI 参数一张表搞定 🔗 原文链接： https://mp.weixin.qq.com/s/wt s Mp9... https://mp.weixin.qq.com/s/wt s Mp9... 原创 星空 星空 星空作手2026年2月27日 19:09 上海 你以为你会用 Claude Code？ 大多数开发者打开 Claude Code，输入一句"帮我写个函数"，等它吐出代码，复制粘贴，结束。这跟用 ChatGPT 没有任何区别。 但 Claude Code 团队的创始人 Boris Cherny 说过一句话： "Claude Code 不是聊天工具，它是一个操作系统。" Anthropic x Forum Ventures 黑客松冠军 Affaan Mustafa 用 Claude Code 构建了一个拥有 50+ Skills、13 个专业 Agent、完整安全审计体系的开发系统——他的配置仓库 everything claude code 在 GitHub 上拿到了 50,000+ Stars。 这篇文章，我要把 Claude Code 的所有进阶用法，从底层原理到生产实践，一次性讲透。不管你是刚装上 Claude Code 的新手，还是已经用了几个月的老用户，我保证你至少能找到 5 个"原来还能这样"的瞬间。 全文很长，建议 先收藏，再慢慢看 。 本文导航（上篇） 章节 核心主题 你能学到什么 一 CLAUDE.md 记忆系统 六层记忆体系、规则拆分、动态上下文注入、5 种实战模板、自我进化 二 上下文工程与 Token 经济学 Token 优化、模型路由、MCP 成本陷阱、战略压缩、会话管理 三 Plan Mode 与质量驱动开发 规划模式、Eval Driven Development、六阶段验证、双 Claude 互审 四 Skills 与 Hooks：定制你的 Claude 技能系统、事件钩子、持续学习机制、记忆持久化 五 多代理架构与并行开发 Subagents、Agent Teams、Git Worktree、编排流水线 章节 章节 核心主题 核心主题 你能学到什么 你能学到什么 一 一 CLAUDE.md 记忆系统 CLAUDE.md 记忆系统 六层记忆体系、规则拆分、动态上下文注入、5 种实战模板、自我进化 六层记忆体系、规则拆分、动态上下文注入、5 种实战模板、自我进化 二 二 上下文工程与 Token 经济学 上下文工程与 Token 经济学 Token 优化、模型路由、MCP 成本陷阱、战略压缩、会话管理 Token 优化、模型路由、MCP 成本陷阱、战略压缩、会话管理 三 三 Plan Mode 与质量驱动开发 Plan Mode 与质量驱动开发 规划模式、Eval Driven Development、六阶段验证、双 Claude 互审 规划模式、Eval Driven Development、六阶段验证、双 Claude 互审 四 四 Skills 与 Hooks：定制你的 Claude Skills 与 Hooks：定制你的 Claude 技能系统、事件钩子、持续学习机制、记忆持久化 技能系统、事件钩子、持续学习机制、记忆持久化 五 五 多代理架构与并行开发 多代理架构与并行开发 Subagents、Agent Teams、Git Worktree、编排流水线 Subagents、Agent Teams、Git Worktree、编排流水线 下篇包含：无头模式与工程化集成、MCP 与 Plugins 生态、安全工程、速查手册。 一、CLAUDE.md：构建你的 AI 记忆系统 90% 的 Claude Code 使用问题，都可以通过一个文件解决——CLAUDE.md。 CLAUDE.md 是 Claude Code 启动时自动读取的记忆文件。没有它，Claude 每次打开你的项目都像个失忆的新人；有了它，Claude 上来就知道你用什么技术栈、什么代码风格、哪些命令能跑、哪些文件不能动。 Anthropic 官方文档的原话： "CLAUDE.md 应该像你最常用的 prompt 一样反复打磨。" 花 15 分钟配好它，能省几十个小时的纠正。 1.1 创建方法 方法 命令 适用场景 自动生成 /init 快速起步，自动检测技术栈（约 80% 完成度） 编辑器打开 /memory 大规模编辑，用你的 IDE 修改 快速追加 规则内容 对话中实时添加单条规则 方法 方法 命令 命令 适用场景 适用场景 自动生成 自动生成 /init /init 快速起步，自动检测技术栈（约 80% 完成度） 快速起步，自动检测技术栈（约 80% 完成度） 编辑器打开 编辑器打开 /memory /memory 大规模编辑，用你的 IDE 修改 大规模编辑，用你的 IDE 修改 快速追加 快速追加 规则内容 规则内容 对话中实时添加单条规则 对话中实时添加单条规则 推荐工作流 ：先跑 /init 得到 80% 的底子，然后用 /memory 精调。 1.2 写什么、不写什么——这是大多数人踩的第一个坑 很多人拿到 CLAUDE.md 就开始往里塞东西，结果写了一大堆 Claude 其实已经知道的信息，真正有用的规则反而被稀释了。 核心原则：把 CLAUDE.md 当成微调（fine tuning），不是当成架构文档。 简短的指令式规则比长篇大论有效得多。 该写的（高价值信息）： 内容 为什么重要 示例 技术栈和框架版本 消除 90% 的框架选择错误 React 19 + TypeScript 5.9 + Vite 命名规范和代码风格 代码一致性提升 70% 使用 named export，不用 default export 常用命令 避免每次重新解释 构建：pnpm build / 测试：pnpm test 测试规则和覆盖率要求 首次生成即符合规范 新 API 路由必须写测试，覆盖率 80% 项目架构和目录结构 减少文件搜索时间 API 路由在 src/