先说清楚两者的关系
Hooks 和 Subagents 是 Claude Code 两个完全独立的进阶功能：
- Hooks：Claude Code 在每次工具调用（Bash / Edit / Read 等）前后， 自动 exec 你写的 shell 命令。命令的 stdout / exit code 能影响 Claude 的下一步。
- Subagents：让 Claude Code 派生一个独立 context 的子 agent去做特定任务（比如「让一个专门的 reviewer agent 看下我刚写的代码」），子 agent 跑完返回结果。
两者经常搭配 —— Hooks 触发 subagent，subagent 跑完用 Hooks 收尾。
一、Hooks 完整用法
Hook 类型（2026 年版）
PreToolUse：工具调用前。可拒绝（exit code 非 0）阻止本次调用。PostToolUse：工具调用后。用 stdout 给 Claude 补充信息（如 lint 结果）。UserPromptSubmit：每次用户输入消息时。可注入额外上下文。Stop：Claude 准备结束本轮回复时。可让它继续干（如「先把测试跑了再停」）。SubagentStop：subagent 结束时触发。
配置位置
在 ~/.claude/settings.json（全局）或项目 .claude/settings.json（项目级）里：
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "cd $CLAUDE_PROJECT_DIR && npm run lint:fix --silent || true"
}
]
}
]
}
}这个 hook 的意思：每次 Claude 用 Edit 或 Write 工具改了文件，自动跑 npm run lint:fix。 Claude 看到 lint 结果（如果有 error）会自动再改。从此你不再需要手动喊“别忘了 lint”。
5 个真实有用的 Hook 案例
1. 自动 lint + format
同上例。PostToolUse 上挂 lint 脚本，避免 Claude 留下不符合项目规范的代码。
2. 提交前自动跑测试
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "echo $TOOL_INPUT | grep -qE 'git commit|git push' && npm test || true"
}
]
}
]
}
}Claude 准备跑 git commit 或 git push 时，先跑测试。 测试挂了 hook 返回非 0，commit 被阻止。
3. 写代码自动 generate types
改了 Prisma schema 后自动 prisma generate，改了 GraphQL schema 后自动 codegen。 把「人脑记忆里的链式步骤」交给 Hook。
4. 操作敏感目录前要求确认
{
"matcher": "Bash|Write",
"hooks": [
{
"type": "command",
"command": "echo $TOOL_INPUT | grep -qE 'rm -rf|/etc|~/.ssh' && echo 'DENIED: sensitive path' >&2 && exit 2 || exit 0"
}
]
}exit code = 2 是约定的「拒绝」信号，Claude 看到拒绝原因会换方式（或问你）。
5. UserPromptSubmit 注入项目状态
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "echo '\n[Project status: branch=' && git branch --show-current && echo ', staged='; git diff --cached --name-only"
}
]
}每次你提交消息时，自动把「当前分支 + 已 stage 文件」注入到 prompt。Claude 不用问就知道项目状态。
二、Subagents 完整用法
什么时候用 Subagent
三种典型场景：
- 专家分工：让 review agent 看代码 + fix agent 改 + test agent 跑测试
- 并行加速：3 个 subagent 同时探索 3 个不同文件，最后主 agent 汇总
- 上下文隔离：长任务里某个子任务很大（如读 50 个文件），让 subagent 独立 context 跑完， 结果短摘要返主 agent，主 agent 的 context 不被污染
定义一个 Subagent
项目里建 .claude/agents/code-reviewer.md：
--- name: code-reviewer description: 用 when 用户要 review 刚改的代码、检查 diff、做 PR 审核 tools: Read, Grep, Glob, Bash --- 你是一位资深 TypeScript / React reviewer。 每次被调用时： 1. 跑 `git diff --cached` 看暂存区改动（或用户指定的范围） 2. 按以下标准 review： - 类型安全（禁止 any、unknown 用对地方） - React 性能（不必要的 useEffect、缺 useMemo 的复杂计算） - 错误处理（try/catch 缺少时指出） 3. 输出格式： ## 总评：通过 / 需修改 / 阻塞 ## 主要问题 1. file:line — 问题描述 — 建议 ## 小建议 - ...
然后在主对话里说“让 code-reviewer 看看我刚写的”，Claude Code 自动派一个独立 context 的 subagent 用你定义的 prompt + 工具集去做。完成后摘要返回。
并行调度
告诉 Claude：“同时派 3 个 subagent 分别 grep src/api/、src/components/、src/lib/ 找所有 catch 空块的地方，最后汇总”。Claude 会真的并行 spawn 3 个 subagent。 总耗时 ≈ max(3 个 agent) 而不是 sum，大型项目搜索/审计提速明显。
3 个真实有用的 Subagent
1. code-reviewer
上面示例。把 PR review 流程标准化。
2. doc-writer
专门写函数 / 模块的 docstring 和 README。配 markdown 写作风格，确保全项目 doc 一致。
3. test-generator
专门写测试。给一个改过的源文件，subagent 读它、读项目里现有测试风格、写一份新测试。
Hooks + Subagents 组合的最佳实践
典型工作流：
- 你说“实现功能 X”
- Claude 主 agent 写代码、改文件
- PostToolUse Hook 自动跑 lint，发现 error 让 Claude 改
- Claude 改完，主动喊“让 code-reviewer 看一遍”
- code-reviewer subagent 派出去独立 review，返回意见
- Claude 按 review 意见再改
- 你说“commit”
- PreToolUse Hook 拦截 git commit，先跑
npm test - 测试过了再 commit
全程你只发了 2 句话（“实现 X” + “commit”），中间所有「专业流程」都自动了。
常见坑
① Hook 写得太慢拖累主流程
Hook 是同步阻塞的，PostToolUse 每次工具调用都跑。如果你的 lint 跑 10 秒，Claude Code 体感变巨慢。 重 hook 改用 PreToolUse 限定特定 matcher（如“只在 commit 前跑”）而不是每次 Edit 都跑。
② Subagent 滥用导致用量爆炸
每个 subagent 是独立 context，消耗的 token 独立计算。 派 5 个 subagent 同时跑 = 当时 5 倍 token 消耗。Pro 账号秒限流。 重度 subagent 工作流建议 Max 5x 起，详见 三档对比。
③ Hook 命令的 exit code 含义
约定：0 = 成功放行，2 = 拒绝（Claude 看到 stderr 内容会换方式）。 其他非 0 = 警告（Claude 看到但仍继续）。写 hook 时注意 exit code 别乱给。
④ Subagent 之间无法共享 context
每个 subagent 是独立 session，看不到别的 subagent 在干啥。 要让多个 subagent 协作，主 agent 必须做协调（汇总 A 的结果再传给 B）。
用量与订阅
Hooks 不额外消耗 Claude token（你的 shell 脚本是本机跑的）。Subagent 显著消耗。 如果你打算把这套进阶玩法日常用：
- Pro：只够偶尔用，subagent 多了限流
- Max 5x：日常重度玩家的起点
- Max 20x：经常并行 3+ subagent 的人
国内订阅见 ClaudeMax 代付平台，微信支付，5 分钟到账。
常见问题
Q：Hook 配置改了要重启 Claude Code 吗？
要。Claude Code 启动时读 settings.json，运行中改了不生效。/exit 后 claude 重启。
Q：Subagent 能调用别的 Subagent 吗？
理论上能（subagent 也有完整的 Task 工具），但强烈不推荐。 嵌套 subagent 调度成本高、context 隔离让协调极难。需要复杂协作时，主 agent 居中调度更清晰。
Q：我能在 hook 里调用 Claude Code 自己吗？
能但要小心死循环。比如 PostToolUse hook 里调 claude -p "..."， 新的 claude 又触发 hook 又调 claude……指数爆炸。如果非要，在 hook 里加环境变量护栏阻止递归。