Claude Code 实战工作流：CLAUDE.md、子智能体与 Hooks

Claude Code 是 Anthropic 出品、跑在终端里的编程智能体：它不是编辑器里的补全插件，而是在 REPL 会话中像一名坐在命令行前的工程师那样自主读写文件、执行 shell 命令、跑测试、提交代码。本站此前发过它的发布报道与编程智能体的原理拆解，这篇是具体用法的深度篇——聚焦决定它好不好用的三个机制：CLAUDE.md 记忆体系、子智能体（subagents）与 Hooks，外加一条实战工作流与成本边界。所有配置与命令均以官方文档（code.claude.com/docs，原 docs.anthropic.com 已 308 跳转至此）为准，截至 2026-10-07。

一、安装与形态

截至 2026-10-07，Claude Code 以 CLI 形态分发，版本号在 2.1.x 系列（官方文档示例打印 2.1.211）。官方推荐原生安装脚本：

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# 或 npm 全局安装（要求 Node.js 22+，官方明确警告不要用 sudo）
npm install -g @anthropic-ai/claude-code

另有 Homebrew（brew install --cask claude-code）与 Windows winget 渠道。原生安装后台自动更新，可选 latest 与 stable 双通道（stable 约滞后一周、跳过有 bug 的版本）；claude doctor 体检安装状态。登录需要付费订阅（Pro/Max/Team/Enterprise）或 Console API 账号。

二、CLAUDE.md：把记忆写对

CLAUDE.md 是每次会话启动自动注入上下文的记忆文件，官方设计分五层：

层级	路径	作用范围
企业	/Library/Application Support/ClaudeCode/CLAUDE.md（macOS）	全组织，不可排除
用户	~/.claude/CLAUDE.md	你的所有项目
项目	./CLAUDE.md 或 ./.claude/CLAUDE.md	团队共享，进 git
本地	./CLAUDE.local.md	仅自己，记得 gitignore
子目录	foo/bar/CLAUDE.md	Claude 读写该目录文件时按需加载

两条加载规则最容易被误解：其一，各层是拼接而非覆盖——用户级规则不会被项目级「顶掉」，离启动目录越近读取越晚（权重感更强）；其二，启动目录之上的文件启动即载，之下的文件要等 Claude 操作到对应子目录才加载。

什么内容才值得写？官方判据是「删掉这一行，Claude 会犯错误吗？不会就删」。真正有用的是：

• Claude 猜不到的构建/测试命令与验证方式；
• 与常见默认不一致的风格约定（缩进、命名、错误处理习惯）；
• 仓库礼仪：分支命名、commit 规范、提交前要不要跑 lint；
• 架构决策与坑：哪些目录是生成物不能手改、缓存有多少秒延迟、某个模块的隐藏依赖。

反面清单同样明确：目录结构、依赖清单、详细 API 文档——这些能从代码里推出来的都别写。篇幅建议控制在 200 行以内，臃肿的记忆文件会被模型整体忽略。写法上要具体可验证：「使用 2 空格缩进」有用，「写出优雅的代码」是噪音。

可直接抄改的模板：

# 项目记忆

## 常用命令
- 构建：npm run build（改 TS 源码后必须跑，tsc + esbuild）
- 本地启动：npm run dev，访问 http://127.0.0.1:5002
- 提交前：npm run lint && npm run test

## 架构约定
- server/ 是 Express SSR，shared/ 放共享类型，tools/ 是脚本
- build/ 是生成物：不进 git、严禁手工编辑

## 坑
- IMPORTANT: 价格以「分」为整数存储，禁止浮点数
- 数据库是 WASM SQLite，写操作必须走 service 层落盘

## 详细规则
@docs/api-conventions.md

@path/to/file 是导入语法：相对路径以当前文件为基准解析，最大递归 4 层，路径含空格要转义（@Design\ Docs/api.md），代码块里的 @ 不会展开。规则多的项目可改用 .claude/rules/*.md，在 frontmatter 写 paths: 把规则按文件路径限定生效范围。工具链上：/init 分析代码库生成初版，/memory 查看并编辑所有记忆文件，/context 确认实际加载了什么。

三、子智能体：把上下文隔离用足

子智能体是主会话派出的独立 Claude 实例：有自己的上下文窗口、系统提示词与工具白名单，看不到主对话历史（只拿到自己的系统提示、任务描述、CLAUDE.md 与 git 状态快照），完成后只把结果摘要交回主会话。价值在于把探索性、大输出量的工作（全库检索、读日志、跑长测试）挡在主上下文之外，并支持并行。

定义放在 .claude/agents/（项目级，进版本控制）或 ~/.claude/agents/（用户级），Markdown + YAML frontmatter，改完几秒内热加载：

---
name: code-reviewer
description: 审查代码质量与安全问题
tools: Read, Glob, Grep
model: sonnet
---

你是代码评审员。每次被调用时阅读代码，给出具体、可执行的
质量、安全与最佳实践反馈。

必填只有 name 与 description；tools 是白名单（省略则全量），model 可指定 sonnet/haiku 等或 inherit 跟随主会话。官方内置 Explore（只读代码检索）与 Plan（plan 模式的调研员）两个最常用角色。派发两条路：Claude 依据 description 自动匹配任务（所以这个字段要当成「路由键」认真写），或在提示词里点名、@-提及，也可以整个会话以 claude --agent code-reviewer 启动。

并发注意点（截至 2026-10-07）：最多 20 个子智能体并行，嵌套派发默认最多 3 层（CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 可调）；用量照常计入配额；结果会整段回流主上下文——十个并行子代理各交回五千字报告，主上下文照样爆，提示词里要约束「只要结论与必要代码位置」。值得拆的场景：只读调研、大规模搜索、互相独立的并行任务、需要工具限制的评审；需要与你逐轮往来的任务留在主会话。

四、Hooks：用脚本兜住确定性

CLAUDE.md 是建议性的，模型可能不遵守；Hooks 是挂在生命周期事件上的确定性脚本，必然执行。官方的分工口径很清楚：硬约束用 Hooks，软约定写 CLAUDE.md。

常用事件：PreToolUse/PostToolUse（工具调用前后）、UserPromptSubmit、SessionStart/SessionEnd、Stop、SubagentStart/SubagentStop 等。配置写在 .claude/settings.json（项目）或 ~/.claude/settings.json（用户），结构为 事件 → matcher → 处理器数组：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format.sh"
          }
        ]
      }
    ]
  }
}

matcher 规则：纯字母数字为工具名精确匹配或列表（Edit|Write）；含其他字符按正则处理（mcp__.* 匹配全部 MCP 工具）；省略或 * 全匹配。钩子脚本从 stdin 收到 JSON（含 tool_name、tool_input 等字段）。退出码语义：0 通过，2 阻断当前操作（stderr 内容作为原因反馈给模型），其余码不阻断。

片段一：写完文件自动格式化（PostToolUse，脚本假设装了 jq）：

#!/bin/bash
# .claude/hooks/format.sh
f=$(jq -r '.tool_input.file_path')
case "$f" in
  *.ts|*.tsx|*.js|*.jsx) npx prettier --write "$f" ;;
  *.py) ruff format "$f" ;;
esac

片段二：拦截危险命令（PreToolUse）：

#!/bin/bash
# .claude/hooks/block-rm.sh
cmd=$(jq -r '.tool_input.command // ""')
if echo "$cmd" | grep -q 'rm -rf'; then
  echo "已被钩子拦截：rm -rf 禁止执行，请人工确认" >&2
  exit 2
fi

PreToolUse 还可输出 JSON 做细粒度控制：hookSpecificOutput.permissionDecision 取 allow/deny/ask，additionalContext 能向模型注入补充上下文。处理器除 command 外还有 http、mcp_tool、prompt（单轮 LLM 判断）等类型；匹配到的钩子并行执行，/hooks 可查看现有配置，disableAllHooks: true 一键关闭。

五、实战工作流循环

官方反复强调的节奏是探索 → 计划 → 实现 → 提交：

1. 探索：先让 Claude 读代码、回答问题，不动手；大范围调研直接派 Explore 子智能体；
2. 计划：进 plan 模式（Shift+Tab 切换，或 claude --permission-mode plan 启动）要一份实现计划，人工修订后确认；
3. 实现：按计划落地，并给它一个可验证的闭环——测试、lint、构建退出码；官方建议「要求证据，不信断言」，还可以用 Stop 钩子做确定性门禁；
4. 提交：让它写 commit 信息、开 PR。

一行 diff 级的小任务别套这个流程，计划环节的开销不值得。

自动化与 CI 走 headless 模式：claude -p "提示词" 非交互运行，stdin/stdout 像普通 Unix 工具一样进管道，退出码可作流水线分支依据：

# PR 安全审查：diff 进 stdin，JSON 出结果
gh pr diff "$1" | claude -p \
  --append-system-prompt "你是安全工程师，只审查漏洞" \
  --output-format json

关键参数：--output-format json 输出结构化结果（含 total_cost_usd 花费与 session_id，可 --resume 续会话）；--allowedTools "Bash(git diff *),Bash(git commit *)" 白名单放行工具；CI 无人值守配 --permission-mode dontAsk，凡会弹交互确认的一律拒绝；--bare 跳过 CLAUDE.md/hooks/skills/MCP 加载，启动更快更确定，官方注明未来将成为 -p 的默认。轻量集成如把 git diff | claude -p "找 typo" 挂进 package.json 脚本，或在 GitHub Actions 里对每个 PR 跑一遍审查。

六、成本与边界

Token 消耗结构（按官方上下文管理指引）：主会话上下文 = 系统提示 + CLAUDE.md + 对话历史 + 工具输出，其中文件读取与命令输出通常是大头。成本控制的核心是别让主上下文装满——窗口越满性能越差：不相关任务之间 /clear 清空；长会话 /compact 带指令压缩；/rewind 回滚到检查点重来；调研类需求派子智能体消化原始材料。注意计费口径：子智能体的独立上下文照常计入用量——它省的是主会话的 token，不是账单；一次性小任务拆子智能体反而更贵。CLAUDE.md 每轮都在场，200 行的长度会直接换算成每次请求的基础开销。

什么不适合交给它（本文作者判断，边界依据官方文档）：

• 一行 diff 的微任务：流程开销不成比例，IDE 内置补全更直接；
• 需要确定性保证的动作：CLAUDE.md 是建议，模型可能视而不见，「必须发生」的事交给 Hooks 或 CI 门禁；
• 能从代码直接推导的信息维护：目录清单、依赖列表这类让它背下来是浪费。

与 IDE 内置助手的分工：光标处的内联补全、单文件快速修改留给 IDE 助手——反馈是毫秒级、零上下文装配成本；跨文件多模块的改动、需要跑测试验证的重构、环境操作与 CI 自动化交给 Claude Code。两者是互补关系：前者是自动补全的延伸，后者是能在你的代码库里干活的智能体。

参考资料

1. Claude Code 官方文档 · Extend Claude with memory（CLAUDE.md）— https://code.claude.com/docs/en/memory
2. Claude Code 官方文档 · Subagents — https://code.claude.com/docs/en/sub-agents
3. Claude Code 官方文档 · Hooks guide — https://code.claude.com/docs/en/hooks
4. Claude Code 官方文档 · Best practices — https://code.claude.com/docs/en/best-practices
5. Claude Code 官方文档 · Headless (non-interactive) mode — https://code.claude.com/docs/en/headless
6. Claude Code 官方文档 · Setup and installation — https://code.claude.com/docs/en/setup