Claude Code 深度指南（Hooks、Skills、SDK 与生产级编排）

这不是「Claude Code 入门」——入门看完整指南。这是给已经把它跑顺了几个月、想把它当生产系统用的人写的：怎么用 Hooks 强制规则、Skills 替代 MCP、SDK 跑大规模批处理、GHA 当后台智能体、上下文窗口怎么不被吃光。

文章基于真实大规模仓库的运营经验整理，每月数十亿 token 的工程实践。如果你需要的只是把通道接好，先一行命令搞定再往下读：

curl -fsSL https://cp.bizq.net/setup.sh | bash -s -- claude-max-20x

1. CLAUDE.md：当成宪法，不是文档

业余项目里 CLAUDE.md 怎么写都行；生产仓库里它是智能体的唯一真理来源，必须严格维护。我们的单体仓库这个文件大约 13KB，能感觉到压力让它涨到 25KB——但我们死守 13KB 这条线。

核心思路：从护栏开始，不要写手册

CLAUDE.md 应该从小处起步，基于 Claude 哪里出错来加内容。每一段都该能回答：「这条规则不存在的话，模型会犯什么具体错误？」

如果回答不上来，那条规则不该存在。

反模式清单

反模式 1：@- 引用大量外部文档

# 不要这样
重要细节见 @-docs/architecture.md

@- 引用会把整个被引文件展开进上下文。每次会话都会展开。如果 architecture.md 有 5KB，那是每次会话起步多吃 5KB。

正确做法：写明「什么时候应该读这个文件」，让 Claude 按需加载：

# 这样
对于复杂的多服务交互，或如果遇到 FooBarError，
读 docs/architecture.md 拿高级故障排除步骤。

反模式 2：纯否定约束

# 不要这样
绝不使用 --foo-bar 标志

智能体认为它必须用这个标志时会卡死循环。永远配套替代方案：

# 这样
不要用 --foo-bar 标志（已废弃）。改用 --new-flag。

反模式 3：把 CLAUDE.md 当工具文档

如果 CLI 命令复杂到需要 3 段文字解释，问题在 CLI 不在文档。写一个 bash 包装提供清晰 API，CLAUDE.md 里只放包装器。CLAUDE.md 是简化代码库的强制函数。

模板骨架

# 单体仓库
 
## Python
- 始终 ...
- 用 <command> 测试
- ... 还有 8 条
 
## <内部 CLI 工具>
- 80% 的用例就这 10 条
- <使用示例>
- 不要 <X>，改用 <Y>
- 复杂用法或 <e> 见 path/to/<tool>_docs.md

兼容多家 IDE

把 CLAUDE.md 与 AGENTS.md 同步，团队里有人用 Cursor、Cline、其他 AI IDE 时它们也读得到。

2. 上下文管理：不要相信 /compact

每个 Claude Code 会话起步约 20K token（10% 上下文）。剩下 180K 用来做事——能很快填满。

三套工作流

流程	适用	操作
`/compact`（避免）	—	自动压缩，不透明、易丢关键信息、优化质量差
`/clear` + `/catchup`	简单重启	清空上下文，自定义 `/catchup` 让它读当前 git 分支所有变更文件
「文档化并清除」	大型任务	让 Claude 把计划和进度写进 `progress.md`，`/clear`，新会话读 `progress.md` 继续

`/catchup` 的实现

.claude/commands/catchup.md：

读取我当前 git 分支相对于 main 的所有变更文件：
 
1. 跑 `git diff --name-only main...HEAD` 拿文件列表
2. 逐个读这些文件
3. 总结当前分支的工作主线，并准备好继续
 
不要做任何修改。

文档化并清除模式

适合多日跨度的大任务。让 Claude 把状态外化到磁盘：

我们要做的事大概要 5-8 小时。请：
1. 先写 progress.md 记录任务背景和你的整体计划
2. 边做边更新 progress.md，每完成一个里程碑写一段
3. 你认为上下文快满时，告诉我「需要 clear」，我会重启会话让你读 progress.md 继续

把状态外化到 .md 文件本质上是给智能体一个外部内存——重启会话不丢信息。

/context 任意时候查上下文占用。超过 75% 就该考虑清理。

3. Slash Command：当快捷方式，不是 DSL

我个人就两个 slash command：

/catchup：上面那个
/pr：清理代码、暂存、准备 PR

反模式：写 30 个 slash command。如果工程师必须背一个魔法命令列表才能干活，你就把 Claude 退化成了一个比 CLI 还难学的 DSL。智能体的全部意义是任意自然语言输入都能产生有用结果。

slash command 仅适用「我个人每天用 5 次的同一个 prompt」。其他情况优化 CLAUDE.md 和工具。

4. Sub-agent vs Task()：选后者

Claude Code 自带 sub-agent 功能在理论上很强：把 (X+Y)*N 的工作外包给专门智能体，主上下文只接收 Z token 的最终结果。N 个任务不再线性消耗主上下文。

但实践中自定义 sub-agent 制造两个新问题：

限制上下文访问——创建了 PythonTester sub-agent 后，主智能体看不到测试上下文了，它无法整体推理一个改动。每次想知道「这测试怎么跑」都要派一个 sub-agent，浪费且笨。
强制人类工作流——你在替 Claude 决定怎么委托。这正是你想让智能体自己做的事。

替代方案：Task()

Claude Code 内置的 Task(...) 工具生成主智能体的克隆，继承全部上下文，没有「角色僵化」问题。你让主 Claude 自己决定何时委托、委托什么。

我要重构 src/payments/。这是个大任务。请：
- 先列出所有受影响文件
- 对每个独立子模块用 Task() 派一个克隆并行处理
- 自己把汇总和最终验证留给主上下文

主 Claude 就会动态编排——这是智能体的本来用法。

5. 会话挖掘：~/.claude/projects/ 是宝藏

ls ~/.claude/projects/

每个项目一个目录，里面是完整会话历史。

实用操作

# 几天前那个修了认证 bug 的会话，让 Claude 总结教训
claude --resume
 
# 接最近一个会话
claude --continue

进阶：元分析

我自己写了脚本对这些日志做元分析——找重复出现的权限请求、bash 错误、相同的失败模式。每一个常见错误都是 CLAUDE.md 或内部工具应该改进的地方：

# 简化版：找最近一周的 bash 错误
grep -h "tool_use_error" ~/.claude/projects/*/sessions/*.jsonl \
  | jq -r '.error' | sort | uniq -c | sort -rn | head

把这种分析跑成 cron job，输出反馈给 CLAUDE.md 维护——错误 → 改进 → 更少错误，飞轮跑起来。

6. Hooks：确定性必须做，对应 CLAUDE.md 的应该做

CLAUDE.md 是「应该做」的建议；Hooks 是「必须做」的硬约束。两者互补，缺一不可。

阻塞型钩子：在提交时校验

主要策略：用 PreToolUse 钩子包装 Bash(git commit)，检查一个标记文件是否存在：

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "scripts/precommit-gate.sh"
      }
    ]
  }
}

#!/bin/bash
# scripts/precommit-gate.sh
# 只在 git commit 时拦截
if [[ "$CLAUDE_TOOL_INPUT" =~ "git commit" ]]; then
  if [[ ! -f /tmp/agent-pre-commit-pass ]]; then
    echo "BLOCK: 测试没过。先跑 pnpm test 让它创建标记文件。"
    exit 1
  fi
fi
exit 0

/tmp/agent-pre-commit-pass 由测试脚本在全部测试通过时创建。Claude 想 git commit 必须先跑测试，跑测试必须全过——它会自己进入「测试-修复」循环直到构建成功。

提示型钩子：非阻塞反馈

简单的「发射后不管」钩子，给 Claude 软引导：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "echo '提醒：改完代码记得跑 pnpm typecheck'"
      }
    ]
  }
}

不要在 Edit/Write 时阻塞

写到一半被打断会让智能体困惑甚至「沮丧」（你能从输出风格看出来）。让它把整段计划做完，最后在 commit 阶段统一校验。这是关键经验。

7. Plan Mode：大改动前的对齐成本

任何「大型」功能更改前，规划是必要的。

内置 plan mode

按 Shift+Tab 切换。Claude 会先输出计划，等你审批，才动手。

经常用这个能建立一种直觉：「最少给多少上下文，能产出可接受的计划」。这个直觉值得花时间培养。

自定义规划工具（基于 SDK）

我们在工作单仓里基于 Claude Code SDK 写了内部规划工具，输出格式与公司的技术设计文档对齐，开箱内置数据隐私和安全检查。让工程师能像高级架构师一样快速规划新功能。

如果你的团队规模够大，值得这么做。SDK 入口：

npm install @anthropic-ai/claude-code-sdk

参考文档 docs.openclaw.ai/sdk。

8. Skills 与 MCP：脚本编写时代

智能体自主性的心智模型有三档：

单提示——所有上下文塞一个大 prompt（脆弱、不可扩展）
工具调用——经典智能体模型，手工制作工具抽象现实（更好，但创造新瓶颈）
脚本编写——给智能体原始环境（二进制、脚本、文档），它即时写代码交互

Agent Skills 是第 3 档的正式产品化。SKILL.md 文件就是把 CLI 和脚本组织好暴露给智能体的标准方式。

Skills 不是干掉 MCP

很多人写过臃肿的 MCP——几十个工具镜像 REST API（read_thing_a()、read_thing_b()、update_thing_c()）。这种 MCP 应该死。

好的 MCP 是网关，不是 API。它的工作不是替智能体抽象现实，而是管认证、网络、安全边界，然后让开：

download_raw_data(filters…)
take_sensitive_gated_action(args…)
execute_code_in_environment_with_state(code…)

智能体拿到一两个高级入口点，剩下的工作用脚本和 markdown 上下文完成。

实战：我还在用的唯一 MCP

Playwright。理由很合理——它是复杂的、有状态的环境，不可能用单纯 CLI 暴露。所有无状态工具（Jira、AWS、GitHub）都已经迁到简单 CLI。

9. Claude Code SDK：把它当通用智能体框架

Claude Code 不仅是交互式 CLI，也是 SDK。我新业余项目的默认智能体框架已经从 LangChain/CrewAI 切到 Claude Code SDK——更简单、更直观、能用同一套 hooks 和 skills。

三种用法

1. 大规模并行脚本

大重构、bug fix、迁移用这个，不要交互式聊天：

# 把 src/ 里所有 foo 改成 bar
ls src/*.py | xargs -P 8 -I {} \
  claude -p "in {} change all refs from foo to bar" \
  --allowedTools Edit,Bash

-P 8 让 xargs 并行 8 个。比让一个主 Claude 编排 8 个 sub-agent 任务简单且可控得多。

2. 内部聊天工具

用 SDK 把复杂流程包成简单聊天界面给非技术用户。比如安装程序出错时退到 SDK 让 Claude 修，或者一个内部「v0-at-home」让设计师在公司 UI 框架里快速 mock。

3. 智能体快速原型

任何「想做一个 X 智能体」的想法（自定义 CLI、专属 MCP），先用 SDK 快速搭原型，验证完再投入完整脚手架。

OpenClaw 拼车 + SDK

SDK 调用走 OpenClaw 时，配置完全复用 auth.profiles：

import { ClaudeCode } from '@anthropic-ai/claude-code-sdk';
 
const cc = new ClaudeCode({
  authProfile: 'anthropic:carpool',  // OpenClaw profile
});
 
const result = await cc.run({ prompt: '...', allowedTools: ['Edit'] });

并行批处理也走拼车配额，统一计入 openclaw carpool usage。

10. GitHub Actions：Claude 的终极运营化

Claude Code GHA 可能是被低估最严重的功能。概念简单——在 GHA 里跑 Claude Code——但简单正是它的力量。

优于其他后台智能体的点

你控制整个容器环境
数据访问范围你定
沙箱与审计能力比任何托管产品都强
全部高级功能（Hooks、MCP、Skills）开箱可用

实际用法：从任何地方触发 PR

我们用 GHA 构建「从任何地方创建 PR」的工具。Slack、Jira、CloudWatch 警报都能触发——GHA 修 bug 或加功能，返回测试过的 PR。

飞轮：GHA 日志 → 改进

GHA 日志就是完整的智能体日志。我们有运营流程定期审查公司层面的这些日志，找常见错误、bash 失败、不一致的工程实践：

$ query-claude-gha-logs --since 5d \
  | claude -p "看看其他 claude 在哪里卡住了，修一下，提 PR"

错误 → 改进 CLAUDE.md / CLI → 更好的智能体。这就是把 Claude 从个人工具变成工程系统核心可审计部件的方式。

11. settings.json 的高级旋钮

{
  // 调试用：所有流量过本地代理，能看 Claude 实际发什么
  "env": {
    "HTTPS_PROXY": "http://127.0.0.1:8888",
    "HTTP_PROXY":  "http://127.0.0.1:8888"
  },
 
  // 默认超时太保守，长任务会被切
  "MCP_TOOL_TIMEOUT": 300000,
  "BASH_MAX_TIMEOUT_MS": 600000,
 
  // 企业 API key 由 helper 动态拿（按使用计费而不是按席位）
  "apiKeyHelper": "/usr/local/bin/get-claude-key",
 
  // 自动批准的命令白名单（定期审计）
  "permissions": {
    "allow": ["Edit", "Bash(pnpm:*)", "Bash(git status)"]
  }
}

apiKeyHelper：让企业账号合理分配

按席位许可的问题是工程师使用差异巨大（实测 1:100 倍）。apiKeyHelper 让所有调用走同一企业账号，按使用计费——更经济，也让工程师能跑非 Claude Code 的脚本（自己用 SDK 的工具）。

OpenClaw 拼车天然就是这个模式——拼车池按 token 用量公平分配，而不是按人头硬切。

定期自审

每月一次：

claude config get permissions.allow | jq

看看半年前白名单里塞的某个 Bash(rm -rf:*) 是不是还有必要存在。

12. 拼车场景下的高级编排

场景	配置建议
多模型路由	`models.fallbacks` 里 Opus → 拼车，Haiku → 自有 key
多账号热备	`auth.profiles` 配 carpool + carpool-backup，OpenClaw 自动 failover
GHA 用拼车	不推荐——CI 调用频率不可控，建议单独 API key
大批量 SDK 任务	走拼车，但跑前估算 token，单次任务 > 10M token 切官方 API

OpenClaw 客户端 fallback 链示例：

{
  "models": {
    "fallbacks": {
      "anthropic:claude-sonnet-4-6": {
        "profile": "anthropic:carpool",
        "fallback": [
          { "profile": "anthropic:carpool-backup" },
          { "model": "openrouter:anthropic/claude-sonnet-4-6" }
        ]
      }
    }
  }
}

主拼车 → 备用拼车 → OpenRouter 兜底，每层切换 200ms 内。

总结

如果你已经把 Claude Code 当 CLI 用熟了，下一步是把它当工程系统：

CLAUDE.md = 宪法，写护栏不写手册
Hooks = 硬约束，提交时阻塞而不是写入时阻塞
Skills > MCP，让智能体写脚本对原始环境
SDK 跑批处理，不要让交互式 Claude 编排大规模任务
GHA = 运营化，把它放进工程系统的核心
~/.claude/projects/ = 宝藏，从历史会话挖出系统改进点

Claude Code 是个 SDK，不是 CLI——理解这一点是从「会用」到「精通」的分水岭。

参考阅读：How I use every Claude Code feature

立即开始

curl -fsSL https://cp.bizq.net/setup.sh | bash -s -- claude-max-20x

更多：cp.bizq.net

Claude Code 完整指南 — 安装到精通的全景
Claude Code 最佳实践 — 实战工作流模式
OpenClaw Claude Code 拼车配置指南 — 一键接入流程
Claude Code MCP Server 指南 — MCP 生态完整索引
Claude Code Commands 指南 — 命令全集

Claude Code 完整指南（从安装到精通）Claude Code 速查手册（2026 完整版）