本文档是对 Everything Claude Code 项目的系统性教学汇总，面向新手，包含术语解释、架构图解、深度分析和知识点详解。
目录
一、目录结构与术语解释
项目目录结构
everything-claude-code/
├── agents/ <- 13个专业"子代理"，相当于你的团队成员
├── skills/ <- 55个"技能包"，是领域知识库
├── commands/ <- 33个"斜杠命令"，用户直接输入的快捷指令
├── hooks/ <- "钩子"，自动化触发器（编辑后自动格式化等）
├── rules/ <- "规则"，永远遵守的编码标准和约束
├── mcp-configs/ <- "MCP服务器配置"，连接外部系统的桥梁
├── scripts/ <- Node.js脚本，hooks的具体实现逻辑
├── contexts/ <- 示例CLAUDE.md，不同工作模式的预设上下文
├── schemas/ <- JSON Schema定义，约束配置文件格式
├── tests/ <- 测试套件
├── docs/ <- 多语言文档（中文、日文等）
└── examples/ <- 不同项目类型的CLAUDE.md示例
关键术语对照表
| 术语 | 中文 | 类比 |
|---|---|---|
| Agent | 子代理/专员 | 公司里的专业岗位（架构师、测试员、审计员） |
| Skill | 技能/知识包 | 岗位培训手册，详细告诉你"怎么做" |
| Command | 斜杠命令 | 快捷键，一键触发复杂工作流 |
| Hook | 钩子/触发器 | 自动化流水线上的传感器，事件发生时自动执行 |
| Rule | 规则 | 公司制度手册，所有人必须遵守 |
| MCP | 模型上下文协议 | 统一的"外部系统接口标准" |
| Instinct | 本能/直觉 | 从经验中提炼的"肌肉记忆" |
| Orchestrate | 编排 | 乐队指挥，按顺序调度多个Agent协作 |
| Handoff | 交接 | Agent之间的工作交接文档 |
| TDD | 测试驱动开发 | 先写考试题，再写答案 |
二、宏观框架理解
框架1：与外部系统的沟通架构
+---------------------------+
| 你（开发者） |
| 输入: /plan /tdd /e2e |
+-------------+-------------+
|
+-------------v-------------+
| Claude Code 主进程 |
| （读取 CLAUDE.md + Rules） |
+-------------+-------------+
|
+-------------------+-------------------+
| | |
+---------v--------+ +------v---------+ +------v-----------+
| Agents (子代理) | | Hooks (自动化) | | MCP (外部连接) |
| planner | | 编辑后格式化 | | GitHub |
| code-reviewer | | TypeScript检查 | | Supabase |
| tdd-guide | | 构建分析 | | Vercel |
| security-review | | 持续学习 | | Context7 |
| architect | | 会话持久化 | | Exa搜索 |
+------------------+ +----------------+ +------------------+
| |
| +------------------------+
| |
+---------v--------------v---------+
| Skills (知识库) |
| coding-standards, tdd-workflow, |
| postgres-patterns, etc. |
| <- Agent执行时查阅的参考手册 |
+----------------------------------+
MCP 是什么？ 可以理解为"万能适配器"。Claude Code 本身不能直接操作 GitHub、数据库、部署平台，但通过 MCP 协议，可以连接到这些外部系统。mcp-configs/mcp-servers.json 就是这些适配器的配置清单。
框架2：5层功能分类
整个系统可以分为 5 个层次：
+-------------------------------------------------------------+
| 第5层：编排层 (Orchestration) |
| /orchestrate -> 串联多个Agent按流水线执行 |
| /multi-workflow -> 多模型协作（Claude + Gemini + Codex） |
+-------------------------------------------------------------+
| 第4层：命令层 (Commands) |
| 用户接口：/plan /tdd /e2e /code-review /build-fix 等 |
| 每个命令对应一个或多个Agent |
+-------------------------------------------------------------+
| 第3层：执行层 (Agents) |
| 实际干活的专员：planner, tdd-guide, code-reviewer 等 |
| 每个Agent有指定的模型（opus/sonnet/haiku）和工具权限 |
+-------------------------------------------------------------+
| 第2层：知识层 (Skills + Rules) |
| Skills = 操作手册（怎么做），Rules = 制度手册（必须怎样） |
| Agent执行时参考这一层 |
+-------------------------------------------------------------+
| 第1层：自动化层 (Hooks + MCP) |
| Hooks = 被动自动化（事件驱动） |
| MCP = 主动连接外部系统 |
+-------------------------------------------------------------+
框架3：一个典型Feature的完整生命周期
你说: "帮我实现用户认证功能"
1. /plan（或/orchestrate feature）
|
v
[Planner Agent] -- 分析需求 -> 输出实施计划
| v HANDOFF文档
v
[你确认: "OK, 开始吧"]
|
v
2. /tdd
|
v
[TDD-Guide Agent] -- 先写测试(RED) -> 实现代码(GREEN) -> 重构(REFACTOR)
| v HANDOFF文档
v
3. 自动触发 Hooks
|-- post-edit-format.js -> 自动格式化代码
|-- post-edit-typecheck.js -> TypeScript类型检查
+-- post-edit-console-warn.js -> 警告遗留的console.log
|
v
4. /code-review
|
v
[Code-Reviewer Agent] -- 审查质量、安全、可维护性
| v HANDOFF文档
v
5. /security-review（可选但推荐）
|
v
[Security-Reviewer Agent] -- OWASP Top 10检查
|
v
6. 提交代码 + 创建PR
+-- Hook自动记录PR URL
框架4：学习与进化系统
你的日常编码操作
|
| Hooks 100%捕获
v
[observations.jsonl] <- 原始观察数据（你用了什么工具、做了什么操作）
|
| 后台 Haiku 分析
v
[Instinct 本能] <- 提炼出的原子模式
confidence: 0.3->0.9 （如："编辑前先Grep"、"优先函数式风格"）
|
| /evolve 聚类
v
[Skill/Command/Agent] <- 进化成完整的技能、命令或代理
关键概念：
- Project-scoped Instinct：React 项目学到的模式不会污染 Go 项目
- Confidence scoring：0.3=试探性，0.9=几乎确定
- Promotion：一个模式在2+个项目中出现且高置信 -> 自动提升为全局
三、高频 Agent/Skill 分析与 Orchestrate 重点讲解
日常工作最高频的 Agent/Command
| 频率 | Agent/Command | 场景 |
|---|---|---|
| 最高 | /plan -> planner | 任何新功能开始前，先做计划 |
| 最高 | /tdd -> tdd-guide | 写代码的核心工作流 |
| 高 | code-reviewer | 代码写完自动触发 |
| 高 | /build-fix -> build-error-resolver | 构建失败时 |
| 中 | /orchestrate | 复杂任务全流程自动化 |
| 中 | security-reviewer | 涉及认证/支付/敏感数据时 |
| 低 | architect | 系统设计决策时 |
| 低 | /learn -> continuous-learning | 每次会话结束提炼经验 |
/orchestrate 深度讲解
Orchestrate 是流水线指挥官。它的核心价值是：你不需要手动一个个调Agent，它帮你按正确顺序串联。
四种预设工作流：
/orchestrate feature "添加用户认证"
-> planner -> tdd-guide -> code-reviewer -> security-reviewer
/orchestrate bugfix "修复登录失败问题"
-> planner -> tdd-guide -> code-reviewer
/orchestrate refactor "重构缓存层"
-> architect -> code-reviewer -> tdd-guide
/orchestrate security "安全审计支付模块"
-> security-reviewer -> code-reviewer -> architect
自定义工作流：
/orchestrate custom "architect,tdd-guide,code-reviewer" "重新设计缓存层"
核心机制 -- Handoff（交接）：
Agent之间不是各干各的，而是通过结构化的Handoff文档传递上下文：
## HANDOFF: planner -> tdd-guide
### Context
实施计划已完成：用户认证使用JWT + Refresh Token
### Findings
- 需要3个新endpoint: /login, /register, /refresh
- 需要中间件验证token
### Files Modified
- 无（规划阶段不修改文件）
### Open Questions
- Token过期时间选15分钟还是30分钟？
### Recommendations
- 从/register endpoint开始TDD
并行优化： 当Agent之间无依赖时，可以并行执行：
code-reviewer --+
security-reviewer --+--> 合并结果
architect --+
四、教练组深度报告
教练1：Agent编排深度分析
两套编排体系
体系A：单模型编排 (/orchestrate)
* 纯 Claude 内部 Agent 链
* 通过 Handoff 文档传递上下文
* 零外部依赖，简单可靠
* 适合：日常功能开发、Bug修复、重构
体系B：多模型协作 (multi-* 系列)
* Claude 当指挥 + Codex(后端专家) + Gemini(前端专家)
* 外部模型只能输出 Diff，Claude 拥有"代码主权"
* 需要 ace-tool MCP + codeagent-wrapper
* 适合：全栈复杂功能、高质量交付
命令横向对比
| 命令 | 外部模型 | 复杂度 | 适用场景 |
|---|---|---|---|
/orchestrate feature | 无 | 低 | 日常功能开发 |
/orchestrate bugfix | 无 | 低 | Bug修复 |
/orchestrate refactor | 无 | 低 | 代码重构 |
/orchestrate security | 无 | 低 | 安全审查 |
/orchestrate custom | 无 | 低 | 自定义Agent链 |
/workflow | Codex+Gemini | 最高 | 全栈复杂功能（6阶段） |
/ccg:plan | Codex+Gemini | 中 | 单独规划（禁止写代码） |
/ccg:execute | Codex或Gemini | 高 | 执行已规划的任务 |
/frontend | 仅Gemini | 中 | 纯前端UI任务 |
/backend | 仅Codex | 中 | 纯后端逻辑任务 |
多模型协作的信任体系
后端领域 前端领域
+---------+ +---------+
| CODEX | | GEMINI |
| (权威) | | (权威) |
| API设计 | | 组件设计 |
| 算法实现 | | 样式布局 |
| DB优化 | | 动画交互 |
+----+----+ +----+----+
| 只输出Diff | 只输出Diff
+--------+----------+
v
+----------+
| CLAUDE | <- 代码主权者
| 综合重构 | <- 唯一能写文件的
| 质量把关 |
+----------+
铁律：外部模型零文件写入权限，所有 Edit/Write 只能由 Claude 执行。
选择命令的决策树
你的任务是什么？
+-- 日常功能/Bug修复 -> /orchestrate feature/bugfix
+-- 纯前端 UI -> /frontend
+-- 纯后端逻辑 -> /backend
+-- 全栈复杂功能
| +-- 想一步到位 -> /workflow
| +-- 先规划再执行 -> /ccg:plan -> /ccg:execute
+-- 重构/安全审计 -> /orchestrate refactor/security
编排的5个陷阱
| 陷阱 | 说明 | 正确做法 |
|---|---|---|
| 超时 | Codex/Gemini可能需要10分钟+ | 设置 timeout: 600000 |
| 代码主权混淆 | 以为外部模型可以直接改文件 | 外部模型只出Diff |
| 越级执行 | /ccg:plan阶段偷偷写代码 | 规划阶段严禁写代码 |
| 需求不完整 | 评分<7就开干 | 强制停下来问清楚 |
| 信任倒置 | 前端问题听Codex的 | 各领域只听对应权威 |
教练2：Hooks自动化深度分析
完整的Hook事件生命周期
会话开始
|
v SessionStart
+-- 加载上次会话摘要
+-- 检测包管理器(npm/pnpm/yarn/bun)
+-- 列出已学技能数量
|
v [工具调用循环，每次都走这个流程]
|
| PreToolUse（工具执行前）
| +-- Dev Server阻断器 -> 匹配Bash -> exit 2 阻断
| +-- Tmux提醒 -> 匹配Bash -> exit 0 警告
| +-- Git Push审查提醒 -> 匹配Bash -> exit 0 提示
| +-- 非标文档警告 -> 匹配Write -> exit 0 警告
| +-- 压缩建议(每50次) -> 匹配Edit|Write -> exit 0 提示
| +-- 持续学习观察 -> 匹配* -> 异步捕获
| |
| v [工具实际执行]
| |
| PostToolUse（工具执行后）
| +-- PR URL记录器 -> 匹配Bash -> 提取PR链接
| +-- 构建分析 -> 匹配Bash -> 异步后台分析
| +-- JS/TS自动格式化 -> 匹配Edit -> Biome/Prettier
| +-- TypeScript类型检查 -> 匹配Edit -> tsc --noEmit
| +-- console.log警告 -> 匹配Edit -> 实时提示行号
| +-- 持续学习观察 -> 匹配* -> 异步捕获(含输出)
| |
| v
| Stop（Claude回复完成后）
| +-- console.log全局审计 -> 扫描所有本次修改的文件
|
v [用户执行 /compact 时]
PreCompact -> 记录压缩日志 + 标注会话文件
|
v 会话结束
SessionEnd
+-- Hook1: 提取摘要 -> 写入 ~/.claude/sessions/
+-- Hook2: 评估是否值得提取模式 -> 信号持续学习系统
Hook数据流原理
Claude Code
| 通过 stdin 传入 JSON
v
+-----------------------------+
| Hook 脚本读取 stdin |
| 处理逻辑 -> 决策 |
| |
| stdout: 必须原样透传JSON | <- 不传回去工具就挂了！
| stderr: 警告信息给用户看 |
| |
| exit 0: 放行 |
| exit 2: 阻断（仅Pre） |
+-----------------------------+
实用Hook配方
| 配方 | 效果 |
|---|---|
| 文件超800行阻断 | Write + exit 2 如果 lines > 800 |
| 新源文件提醒写测试 | Write + 检测对应 .test 文件是否存在 |
| Python自动格式化 | Edit + 检测 .py -> 执行 ruff format |
| TODO/FIXME警告 | Edit + 正则检测 new_string |
教练3：学习进化系统深度分析
v1 -> v2 -> v2.1 进化史
v1 (基础版) v2 (本能架构) v2.1 (项目隔离)
-------------- -------------- --------------
Stop Hook触发 Pre/PostToolUse + 项目作用域
(50-80%可靠) (100%可靠) (默认隔离)
整个会话提取 原子"本能" + 晋升机制
(粗粒度) (细粒度) (project->global)
无置信度 0.3-0.9评分 + 跨项目检测
全局存储 全局存储 + 每项目独立存储
(污染风险) (污染风险) (安全隔离)
Instinct（本能）的完整生命周期
第1步：观察捕获
每次工具调用 -> observe.sh -> observations.jsonl
（截断到5000字符，超10MB自动归档）
第2步：项目检测
git remote URL -> SHA256哈希前12位 = project_id
（同一仓库不同机器 = 同一ID，跨机器可移植）
第3步：模式分析（后台Haiku代理）
4类模式检测：
* 用户纠正 -> "不用X，用Y"
* 错误解决 -> 同一错误同样修复多次
* 重复工作流 -> 同样的工具序列反复出现
* 工具偏好 -> 总是Grep->Edit而不是直接Edit
第4步：本能文件创建
写入 YAML frontmatter + Markdown
包含：id、trigger、confidence、domain、scope、evidence
第5步：本能成熟
+------------------------------------+
| 置信度增长规则： |
| 观察1-2次 -> 0.3 (试探) |
| 观察3-5次 -> 0.5 (中等) |
| 观察6-10次 -> 0.7 (强，自动应用) |
| 观察11+次 -> 0.85 (核心行为) |
| |
| 确认观察 -> +0.05 |
| 矛盾观察 -> -0.10 |
| 无观察/周 -> -0.02 (自然衰减) |
+------------------------------------+
第6步：晋升（project -> global）
条件：2+个项目中出现 + 平均置信度 >= 0.8
命令：/promote
第7步：进化（instinct -> skill/command/agent）
命令：/evolve
* 相关本能聚类 -> 自动生成高级结构
* 工作流本能 -> Command（/new-table 等）
* 行为本能 -> Skill（functional-patterns 等）
* 多步骤本能 -> Agent（debugger 等）
项目隔离的关键设计
~/.claude/homunculus/
+-- instincts/personal/ <- 全局本能（跨项目通用）
| +-- always-validate-input.yaml
+-- projects/
+-- a1b2c3d4e5f6/ <- React项目
| +-- instincts/personal/
| +-- use-react-hooks.yaml <- 不会污染Django项目
+-- f6e5d4c3b2a1/ <- Django项目
+-- instincts/personal/
+-- use-drf-serializers.yaml <- 不会污染React项目
冲突解决： 同ID本能，项目作用域优先于全局（项目覆盖全局）。
五、新手友好知识点图解
5.1 Claude Code 的"公司架构"比喻
把整个系统想象成一家软件公司：
+-------------------------------------------------------------+
| 你（CEO / 老板） |
| 下达指令："帮我实现用户认证" |
+----------------------------+--------------------------------+
|
v
+-------------------------------------------------------------+
| Claude Code（总经理 / COO） |
| |
| 读取公司制度（Rules）-> 查看操作手册（Skills） |
| -> 安排对应部门（Agents）干活 |
| -> 自动化流程（Hooks）在后台默默运行 |
| -> 需要外部资源时通过 MCP 对接 |
+----------------------------+--------------------------------+
|
+------------------+------------------+
| | |
v v v
+----------+ +----------+ +----------+
| 规划部 | | 研发部 | | 质量部 |
| planner | | tdd-guide| | reviewer |
| architect| | | | security |
+----------+ +----------+ +----------+
用 Opus 模型 用 Sonnet 模型 用 Sonnet 模型
(高管级思考) (中层级执行) (中层级审查)
5.2 Model 选择 = 雇人选择
为什么有 Opus、Sonnet、Haiku 三种模型？
+-------------+ +-------------+ +-------------+
| Opus 4.6 | | Sonnet 4.6 | | Haiku 4.5 |
| ============| | ============| | ============ |
| 首席架构师 | | 高级工程师 | | 初级工程师 |
| | | | | |
| 能力：最强 | | 能力：很强 | | 能力：够用 |
| 速度：较慢 | | 速度：适中 | | 速度：最快 |
| 成本：最贵 | | 成本：适中 | | 成本：最便宜 |
| | | | | |
| 适合： | | 适合： | | 适合： |
| * 架构决策 | | * 写代码 | | * 后台分析 |
| * 复杂规划 | | * 代码审查 | | * 格式化任务 |
| * 深度推理 | | * 测试编写 | | * 持续学习 |
+-------------+ +-------------+ +-------------+
核心原则：用最合适（而非最贵）的模型做对应的事
不需要首席架构师去跑格式化，也不要让初级员工做架构决策
5.3 什么是 MCP？（Model Context Protocol）
想象 Claude Code 是一个人，他坐在一间封闭的办公室里。
他很聪明，但：
x 看不到互联网
x 打不开 GitHub
x 连不上数据库
x 部署不了代码
MCP 就是给这间办公室装上的"电话线"：
+------------------------------------------------------------+
| Claude Code 的办公室 |
| |
| +--------------+ |
| | Claude Code | |
| +------+-------+ |
| | |
| MCP 协议（统一接口标准） |
| | |
| +-------+-------+---+----+--------+-----------+ |
| | | | | | | |
| v v v v v v |
| +------++------++------++------++------++----------+ |
| |GitHub||Supa- ||Vercel||Exa ||Click-||Context7 | |
| | ||base || ||搜索 ||House ||(文档查询)| |
| |PR/ ||数据库||部署 ||网络 ||分析 ||最新API | |
| |Issue ||操作 ||管理 ||搜索 ||查询 ||文档 | |
| +------++------++------++------++------++----------+ |
| 电话1 电话2 电话3 电话4 电话5 电话6 |
+------------------------------------------------------------+
每根"电话线"就是一个 MCP Server。
mcp-configs/mcp-servers.json 就是电话簿 -- 记录了每根线怎么拨。
注意：同时开启不超过10个MCP，否则会占用太多"上下文窗口"。
5.4 什么是"上下文窗口"？为什么要 /compact？
上下文窗口 = Claude 的"工作记忆"（短期记忆）
想象 Claude 的大脑是一张有限大小的桌子：
开始时：桌子很空
+--------------------------------------------------+
| [你的指令] [CLAUDE.md] [Rules] ...空... |
| ========... |
| 已用 20% 剩余 80% |
+--------------------------------------------------+
工作一段时间后：桌子快满了
+--------------------------------------------------+
| [指令][Rules][文件1][文件2][修改1][修改2]... |
| ================================================ |
| 已用 90% 剩余 10% |
+--------------------------------------------------+
到了这个阶段，Claude 可能会：
* 忘记之前的对话内容
* 做出不一致的决策
* 自动触发压缩（可能丢失重要上下文）
/compact 的作用 = 整理桌面
+--------------------------------------------------+
| [压缩后的摘要] ...空... |
| ========... |
| 已用 15% 剩余 85% |
+--------------------------------------------------+
这就是为什么 suggest-compact.js 每50次工具调用会提醒你：
"你的桌子快满了，要不要整理一下？"
5.5 stdin / stdout / stderr 是什么？
这是 Hook 系统的基础：
每个程序都有3个"管道"，可以理解为3条传送带：
stdin (标准输入) <- 数据进来的管道
就像：收件箱
Hook 从这里读取 Claude 传过来的 JSON 数据
stdout (标准输出) <- 数据出去的管道
就像：发件箱
Hook 必须把原始 JSON 原样传回去
注意：如果不传回去，Claude 的工具调用会失败！
stderr (标准错误) <- 消息/警告管道
就像：便签纸
Hook 把警告信息写到这里，用户会看到
不影响数据传输
具体流程：
Claude Code Hook 脚本 用户
| | |
|---- stdin (JSON数据) ------->| |
| | 处理逻辑... |
| | |
|<--- stdout (原样JSON) ------| |
| | |
| |---- stderr (警告) -->|
| | "[Hook] 超800行!" |
| | |
|<--- exit code --------------| |
| exit 0 = 放行 | |
| exit 2 = 阻断 | |
5.6 Exit Code（退出码）是什么？
每个程序结束时都会返回一个数字，告诉调用者"我执行得怎么样"：
+----------+--------------------------------------------+
| Exit Code| 含义 |
+----------+--------------------------------------------+
| 0 | 一切正常，继续执行 |
| | 用于：警告（显示信息但不阻止操作） |
|----------+--------------------------------------------+
| 2 | 阻断！停止工具执行 |
| | 仅 PreToolUse 有效 |
| | 用于：危险操作必须阻止（如非tmux跑dev） |
|----------+--------------------------------------------+
| 其他 | 出错了，但不阻断 |
| (1,3..) | Claude 会记录错误但继续执行 |
+----------+--------------------------------------------+
类比：
exit 0 = 保安说"你可以进去，但注意安全" <- 放行+提醒
exit 2 = 保安说"不行，禁止通行" <- 硬拦截
exit 1 = 保安自己摔倒了，但不影响你进去 <- 出错但不阻断
5.7 Matcher（匹配器）工作原理
匹配器决定 Hook 在哪些工具调用时触发：
"*" -> 所有工具都触发
Edit Y Write Y Bash Y Read Y Grep Y
"Bash" -> 只在 Bash 工具时触发
Edit x Write x Bash Y Read x Grep x
"Edit" -> 只在 Edit 工具时触发
Edit Y Write x Bash x Read x Grep x
"Edit|Write" -> Edit 或 Write 时触发（正则表达式的"或"）
Edit Y Write Y Bash x Read x Grep x
"|" 就是正则里的"或"符号
5.8 同步 vs 异步 Hook
同步（默认）：Hook 执行完才能继续
-------------------------------------------
时间 ---------------------------------------->
Claude: [准备工具]--等--等--等--[继续执行]
| ^
Hook: +--[执行]--+
如果 Hook 执行很慢，Claude 就被堵住了
异步（"async": true）：Hook 在后台跑，不阻塞
-------------------------------------------
时间 ---------------------------------------->
Claude: [准备工具]--[继续执行]--[继续工作]--
|
Hook: +--[后台执行中...]--[完成]
适合：持续学习的 observe.sh（每次都跑，不能阻塞主流程）
适合：构建分析（耗时，但不需要立即结果）
5.9 什么是 JSONL 格式？
JSON = 一个完整的数据对象
{
"name": "张三",
"age": 25,
"skills": ["JS", "Python"]
}
JSONL = JSON Lines = 每行一个JSON对象
{"event":"tool_start","tool":"Edit"} <- 第1行
{"event":"tool_done","tool":"Edit"} <- 第2行
{"event":"tool_start","tool":"Bash"} <- 第3行
{"event":"tool_done","tool":"Bash"} <- 第4行
为什么用 JSONL 而不是 JSON？
Y 可以一行一行追加（append），不用读取整个文件
Y 文件再大也不怕，可以一行一行读
Y 某一行坏了不影响其他行
x 普通 JSON 每次追加要先读取->解析->修改->全量写入（大文件很慢）
这就是为什么 observations.jsonl 用这个格式 --
每次工具调用追加一行，几千次调用也不卡。
5.10 SHA256 哈希 = 指纹
为什么项目检测用 SHA256？
SHA256 是一个"指纹函数"，任何输入都会产生唯一的固定长度输出：
输入: "https://github.com/oker/my-react-app.git"
|
v SHA256
输出: "a1b2c3d4e5f6..." <- 取前12位作为 project_id
关键特性：
Y 同样的输入 -> 永远同样的输出
你的Mac上：git remote = 同一URL -> 同一hash
同事的Linux上：同一URL -> 同一hash
-> 跨机器可移植！
Y 不同的输入 -> 几乎不可能相同
React项目URL -> "a1b2c3..."
Django项目URL -> "f6e5d4..."
-> 项目之间不会混淆！
Y 不可逆：从hash推不出原始URL
-> 隐私安全
5.11 YAML Frontmatter 是什么？
很多文件（Agent、Skill、Instinct）的开头都有这个结构：
+-- YAML Frontmatter（元数据区）----+
| --- |
| name: planner |
| description: Expert planning... |
| model: opus |
| tools: [Read, Grep, Glob] |
| --- |
+-----------------------------------+
+-- Markdown 正文（内容区）---------+
| # Planner Agent |
| |
| 你是一个规划专家... |
| ...具体的指令和模板... |
+-----------------------------------+
两个 "---" 之间的部分就是 YAML Frontmatter：
* 用 YAML 格式（key: value）
* 定义了这个文件的"属性"
* 系统读取这些属性来决定怎么使用这个文件
类比：
YAML Frontmatter = 书的封面信息（作者、出版社、ISBN）
Markdown 正文 = 书的正文内容
5.12 Unified Diff Patch 是什么？
在多模型协作中，外部模型只能输出 Unified Diff Patch。
这是一种"补丁格式"，描述文件的修改方式：
--- a/src/auth.ts <- 修改前的文件
+++ b/src/auth.ts <- 修改后的文件
@@ -10,6 +10,8 @@ <- 修改的位置（第10行开始）
import { User } from './models'
export function login(email: string, password: string) {
+ // 输入验证 <- "+" 开头 = 新增的行
+ if (!email) throw new Error('Email required')
const user = await findUser(email)
- return user <- "-" 开头 = 删除的行
+ return generateToken(user) <- "+" 替换的新行
}
看懂规则：
无符号 = 上下文（没改的行）
+ = 新增或替换的行（绿色）
- = 删除的行（红色）
为什么外部模型只输出 Diff 而不直接改文件？
-> 安全！Claude 审查 Diff 后才决定是否采纳
-> 相当于：外部专家只能提"修改建议"，Claude 是最终拍板的人
5.13 TDD 的 Red-Green-Refactor 图解
TDD = Test-Driven Development（测试驱动开发）
传统方式（先写代码，后补测试）：
写代码 -> 写测试 -> "测试怎么老过不了..."
问题：测试变成了给代码"打补丁"，容易遗漏边界情况
TDD方式（先写测试，再写代码）：
RED（红灯）
+----------------------------------+
| 写一个测试 |
| 运行 -> 失败 x |
| 这是对的！因为代码还没写 |
+----------------+-----------------+
|
v
GREEN（绿灯）
+----------------------------------+
| 写最少的代码让测试通过 |
| 运行 -> 通过 Y |
| 不要多写！刚好通过就行 |
+----------------+-----------------+
|
v
REFACTOR（重构）
+----------------------------------+
| 改善代码质量（提取常量、优化结构） |
| 运行 -> 仍然通过 Y |
| 有测试保护，重构不怕改坏 |
+----------------+-----------------+
|
v
回到 RED（下一个功能点）
循环往复，直到所有功能点都覆盖
覆盖率要求：80%+（关键业务逻辑要100%）
为什么先写测试这么重要？
1. 迫使你先想清楚"要什么"，而不是"怎么做"
2. 每一行代码都有存在的理由（为了通过某个测试）
3. 重构时有安全网，改坏了测试会立刻告诉你
5.14 置信度衰减 = 记忆遗忘曲线
本能的置信度不是只升不降的，它会"遗忘"：
置信度
1.0 |
|
0.9 | --- 反复观察到，持续增长
| ---
0.8 |---- 晋升线 ----/-------------------------------
| ---
0.7 | ---
| ---
0.6 | ---
| ---
0.5 |-
|
0.4 |
| 如果长期不再观察到...
0.3 | \
| \-- 每周 -0.02
0.2 | \
| \
0.1 | \-- 最终淡出
|
0.0 |-----------------------------------------
第1周 第2周 第3周 第4周 ... 第20周
这个设计很巧妙：
Y 你换了编码风格？旧习惯会自然淡出
Y 不用手动删除过时的本能
Y 真正核心的行为（一直在用的）不会衰减
Y 类似人脑的"遗忘曲线" -- 不用的知识自然遗忘
5.15 /orchestrate feature 完整动画
/orchestrate feature "添加购物车功能"
阶段1 Planner Agent (Opus) [只读]
+----------------------------------------------+
| 读取代码库结构 |
| 分析已有的商品模块 |
| 制定实施计划： |
| Phase A: 购物车数据模型 |
| Phase B: API endpoints |
| Phase C: 前端组件 |
| 输出 HANDOFF -> tdd-guide |
+--------------------------+-------------------+
| 传递
v
阶段2 TDD-Guide Agent (Sonnet) [可写]
+----------------------------------------------+
| RED: 写 cart.test.ts（测试先行） |
| GREEN: 写 cart.ts（最小实现通过测试） |
| REFACTOR: 重构代码 |
| 输出 HANDOFF -> code-reviewer |
| 附带：修改的文件列表 + 测试覆盖率 |
+--------------------------+-------------------+
| 传递
v
阶段3 Code-Reviewer Agent (Sonnet) [只读]
+----------------------------------------------+
| 审查代码质量 |
| 检查命名规范 |
| 检查错误处理 |
| 检查性能问题 |
| 输出 HANDOFF -> security-reviewer |
| 附带：发现的问题列表 + 严重程度 |
+--------------------------+-------------------+
| 传递
v
阶段4 Security-Reviewer Agent (Sonnet) [可写修复]
+----------------------------------------------+
| OWASP Top 10 检查 |
| 输入验证检查 |
| SQL注入风险检查 |
| XSS攻击风险检查 |
| 输出最终报告 |
| 结论：SHIP / NEEDS WORK / BLOCKED |
+----------------------------------------------+
六、整体全景图
+======================================================================+
| Everything Claude Code 全景图 |
+======================================================================+
| |
| 你 ---- /command -----> Claude Code 主进程 |
| | |
| +-------------+-------------+ |
| | | | |
| Rules 规则 Skills 技能 CLAUDE.md |
| (必须遵守) (参考手册) (项目说明) |
| | | | |
| +-------------+-------------+ |
| | |
| +------------------+------------------+ |
| | | | |
| Agents 代理 Hooks 钩子 MCP 外部连接 |
| (专业团队) (自动化流程) (电话线) |
| | | | |
| +----+----+ +-----+-----+ +----+----+ |
| |规划组 | |编辑时 | |GitHub | |
| |planner | |*自动格式化 | |Supabase | |
| |architect| |*类型检查 | |Vercel | |
| | | |*console警告| |Context7 | |
| |研发组 | | | |Exa搜索 | |
| |tdd-guide| |会话时 | +---------+ |
| | | |*加载上下文 | |
| |质量组 | |*保存摘要 | |
| |reviewer | |*持续学习 | |
| |security | +-----------+ |
| +---------+ | |
| | 持续学习系统 |
| | +------+------+ |
| | | 观察 -> 分析 | |
| | | -> 本能 -> 进化| |
| | +-------------+ |
| | |
| +----+---- /orchestrate ----+ |
| | planner -> tdd -> reviewer | <- 单模型编排 |
| | -> security -> 最终报告 | |
| +-----------------------------+ |
| |
| +---- /workflow (multi-*) --+ |
| | Claude + Codex + Gemini | <- 多模型协作 |
| | 6阶段全栈开发流程 | |
| +---------------------------+ |
| |
+======================================================================+
