Claude Code 高阶实战手册

定位：纯中高阶技巧，零入门废话。来源涵盖 Anthropic 官方工程博客、incident.io / Abnormal Security 等月耗数十亿 token 的生产团队、社区开源配置。2025-2026 实战验证。

1. 并行工作流：Git Worktrees

1.1 核心原理

Git worktree 在同一 .git 数据库上签出多个分支到独立目录，每个目录运行自己的 Claude Code 会话，文件完全隔离，互不污染。

# 一口气创建 3 个并行工作区
git worktree add ../proj-auth    -b feat/auth    main
git worktree add ../proj-payment -b feat/payment main
git worktree add ../proj-dash    -b feat/dash    main

# 收工清理
git worktree remove ../proj-auth

1.2 用 Cursor 管理 Worktree 🖥️

每个 worktree 是独立目录 → Cursor 中直接 File > Open Folder 打开对应 worktree 目录，每个窗口自带独立终端、独立 Claude Code 会话。

💡 技巧：Cursor 窗口标题栏会显示目录名。用 feat-auth、fix-bug、analysis 等语义化命名 worktree，一眼分辨哪个窗口干什么。

1.3 高效模式

⚠️ 铁律：不要让两个 worktree 同时改同一批文件。每个 worktree 要独立 npm install / pip install。

1.4 incident.io 实战

四个月内从零到同时跑 4-5 个 Claude 代理并行推不同 feature。封装了 bash 函数一键创建 worktree + 启动 Claude + Tab 补全已有 worktree。串行变并行，效率指数级跃升。

2. CLAUDE.md 工程化 📐（需要吸收扩散规则）

2.1 文件层级与加载机制

💡 monorepo 关键：子目录 CLAUDE.md 是懒加载的，不会启动时全量灌入，避免上百 KB 无关上下文吃掉你宝贵的 token 额度。

2.2 生产级写法规则

来自 Abnormal Security（月耗数十亿 token、13KB monorepo CLAUDE.md）的经验：

不要 @-file 整个文档。每次运行都嵌入全文，上下文白白膨胀。改用引导语："遇到 FooBarError 时参阅 docs/auth.md"。

不要只说"禁止"。纯否定约束让 agent 卡住。永远给替代方案："不要用 --foo-bar，改用 --baz"。

CLI 命令太复杂？ 写个 bash wrapper 而不是在 CLAUDE.md 里塞说明书。

2.3 指令容量天花板

HumanLayer 研究：前沿 LLM 能稳定遵循 ~150-200 条指令。Claude Code 系统提示词已占 ~50 条 → 留给你的只有 100-150 条。指令越多，所有指令的遵循率均匀下降。

⚠️ 永远不要让 LLM 干 linter 的活。格式化用 PostToolUse Hook 确定性执行（见第 12 节），别写进 CLAUDE.md。

2.4 自改进循环 🔄

Claude 犯错后说 "写进 CLAUDE.md"，它会分析错误 → 抽象模式 → 添加规则。Session 1 捕获 3 个错误；Session 2 这 3 个不再重犯，暴露更深层问题 → 复利式学习。

Arize 用自动化 prompt 优化在 CLAUDE.md 上迭代，SWE Bench Lite 准确率提升 +10.87%。

2.5 模板参考

# 代码风格
- TypeScript 严格模式，禁止 any
- 使用命名导出，不用 default export
- Python 3.12+ 类型标注：用 str | int 而非 Union[str, int]

# 常用命令
- `npm run dev`：开发服务器 (port 3000)
- `npm run test`：Jest 测试
- `npm run db:migrate`：Prisma 迁移

# 安全红线
- 绝不提交 .env 文件 — 用 Vault 管理密钥
- 数据库操作必须走 migration，禁止直接 SQL
- 遇到 OAuth 报错，参阅 @docs/authentication.md

根目录 CLAUDE.md 控制在 300 行以内（有团队压到 60 行），用渐进式披露 — 不告诉 Claude 所有知识，告诉它去哪找。

3. Skill 系统深度应用 🧩

3.1 Skill vs Slash Command

💡 Skill 的本质：把你反复教 Claude 的东西固化为一个"技能包"，提交 git，团队共享。遵循"一天做一次以上就自动化"原则。

3.2 Skill 目录结构

.claude/skills/
├── code-review/
│   ├── SKILL.md          # 入口 — 描述何时触发、如何执行
│   ├── checklist.md      # 审查清单模板
│   └── examples/         # 好/坏代码对比示例
├── db-migration/
│   ├── SKILL.md
│   ├── migration-template.sql
│   └── rollback-guide.md
├── api-design/
│   ├── SKILL.md
│   ├── openapi-template.yaml
│   └── naming-conventions.md
└── techdebt/
    ├── SKILL.md
    └── scan-patterns.json

3.3 SKILL.md 编写模板

---
name: code-review
description: >
  资深代码审查。代码变更后主动触发。
  聚焦：安全漏洞、性能瓶颈、设计模式违规、测试覆盖率。
tools: Read, Grep, Glob, Bash
---

# Code Review Skill

## 触发条件
- 用户说 "review"、"审查"、"看看代码"
- 新 feature 完成后自动建议

## 执行流程
1. 读取当前 branch 的所有 diff：`git diff main...HEAD`
2. 按 checklist.md 逐项检查
3. 对每个问题给出：严重级别 / 具体位置 / 修复建议
4. 生成汇总报告

## 审查维度（见 checklist.md）
## 输出格式
- 🔴 Critical / 🟡 Warning / 🟢 Good
- 每条带文件名 + 行号 + 修复代码

## 参考
- 好坏代码对比见 examples/ 目录

3.4 高价值 Skill 清单

3.5 Skill 与子代理结合

在 .claude/agents/ 中定义的子代理可以引用 Skill：

# .claude/agents/reviewer.md
---
name: reviewer
description: 代码变更后必须主动调用的审查员。
tools: Read, Grep, Glob, Bash
model: sonnet
---
你是高级代码审查员。执行审查时，参照 .claude/skills/code-review/ 中的
checklist 和 examples 完成逐项检查。

⚠️ 反模式警告："如果你有一长串复杂自定义命令，你搞反了。Claude 的核心优势是自然语言交互。Slash command 做简短快捷方式，Skill 做完整能力包，别把两者混着用。"

4. Plan Mode 计划模式 🗺️

4.1 机制

Plan Mode 下 Claude 进入只读状态，只能用 Read / LS / Glob / Grep / Task / TodoRead / TodoWrite / WebFetch / WebSearch，所有写操作被阻断。

4.2 模型策略 🧠

默认原则：永远用允许范围内最强的模型。 如果 Opus 4.5 可用，规划和执行都用 Opus。只在 token 预算受限、或任务确实简单时才降级：

💡 Boris Cherny（Anthropic）确认 Plan Mode 对复杂任务"轻松 2-3 倍提效"。

4.3 标准流程

1. Shift+Tab ×2 进入 Plan Mode
2. 反复迭代方案直到满意（此阶段显著更快，无工具执行开销）
3. Shift+Tab ×2 切到 Auto-Edit 模式
4. Claude 自动实施，最小干预
5. 保持小范围："规划接下来 30 分钟能完成的事"
6. 代码跑通立刻 commit

大型规划写入 docs/PLAN.md，跨会话持久化。

4.4 何时必须用 Plan Mode

• 改动涉及 3 个以上文件
• 跨模块重构
• Bug 修到一半方向不对，需要重新想方案
• 架构设计决策（搭配高 thinking budget，见第 14 节）

5. 子代理（Subagents）调度 🤖

5.1 基本参数

5.2 内置类型

5.3 自定义子代理

放在 .claude/agents/ 下，Markdown + YAML frontmatter：

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: 资深代码审查员。代码变更后必须主动调用。
tools: Read, Grep, Glob, Bash
model: sonnet
---
你是高级代码审查员。参照 .claude/skills/code-review/ 执行审查。

description 字段极关键 — Claude 靠它决定何时委派。加 "PROACTIVELY" / "MUST BE USED" 强制触发。

5.4 Master-Clone vs 专家代理

Abnormal Security 的反直觉经验：别做专家代理拆分。把所有上下文放 CLAUDE.md，让主代理用内置 Task(...) 生成自身克隆去干子任务。

原因：专家代理导致"上下文门控"（对主代理隐藏测试知识等），刚性工作流反而限制灵活性。

5.5 实用模式

• 7 路并行：组件 / 样式 / 测试 / 类型 / Hooks / 集成 / 收尾 → 汇总协调
• Explore → Plan → Execute 流水线
• 后台异步：Ctrl+B 将运行中的子代理放后台，继续主任务，/tasks 监控

核心价值：保持主上下文干净 — 中间文件读取和推理留在子代理里，不回流。

6. MCP 服务器选型 🔌

6.1 配置方式

项目根目录 .mcp.json：

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

6.2 值得跑的服务器

数据库方案还有 Bytebase dbhub、pgEdge（多数据库 + TLS）、Neon（OAuth 自动配置）、Prisma MCP。

6.3 上下文代价 ⚠️

每个 MCP 服务器的 tool 定义都吃上下文。 有开发者报告启用过多 MCP 后 200k 上下文缩水到 70k。用 /context 监控，disabledMcpServers 禁用闲置服务，MAX_MCP_OUTPUT_TOKENS=50000 调整返回上限。

6.4 何时不用 MCP

Abnormal Security："唯一还在用的 MCP 是 Playwright — 复杂有状态环境。所有无状态工具（Jira、AWS、GitHub CLI）已迁移到简单 bash wrapper。" 对无状态集成，bash 脚本通过 Bash tool 调用往往更高效。

7. Agent Team（多代理协作）🐝

7.1 与子代理的本质区别

💡 一句话判断：成员之间需要互相沟通吗？需要 → Agent Team；不需要 → 子代理。

7.2 启用

# 环境变量（当次生效）
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# 或写入 settings.json（持久化）
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

7.3 架构四组件

每个 Teammate 启动时加载项目的 CLAUDE.md、MCP 服务器、Skills — 但不继承 Lead 的对话历史，只接收 spawn prompt。

7.4 键盘操作

7.5 四大黄金场景

① 多维度 Code Review

单个 reviewer 容易偏向某类问题。拆分为独立视角，每个维度都得到充分关注：

创建 agent team 审查 PR #142：
- 安全审查员：检查 token 处理、输入验证、auth 流程
- 性能分析员：排查 N+1 查询、内存泄漏、不必要的渲染
- 测试审查员：验证边界 case、查找未覆盖路径
让他们各自审查后共享发现，Lead 汇总为统一报告。

② 竞争性假设 Debug

单个 agent 倾向找到一个"说得通"的解释就停下来。多个 agent 互相质疑，通过辩论收敛到正确答案：

这个支付回调偶尔丢失。创建 agent team：
- 假设 A：网络层超时导致 webhook 未到达
- 假设 B：消息队列消费失败后未重试
- 假设 C：数据库死锁导致事务回滚
每个 teammate 验证自己的假设，同时尝试否证其他假设。

③ 跨层 Feature 开发

前端、后端、测试三层各由一个 teammate 负责，通过消息协调接口契约：

新增用户通知模块。创建 agent team：
- 后端 teammate：实现 Notification API + 消息队列
- 前端 teammate：实现通知中心 UI + WebSocket 连接
- 测试 teammate：编写集成测试验证前后端联调
后端先完成 API 接口定义，通知前端和测试 teammate 开始工作。

④ 大型代码库研究

单 agent 在 50,000+ 行代码库上挣扎 — 上下文被架构理解吃光。分布式探索，每个 teammate 认知负载独立：

Create an agent team to analyze our monorepo architecture:
- Teammate 1: 映射模块依赖图
- Teammate 2: 识别循环依赖和死代码
- Teammate 3: 统计各模块测试覆盖率
汇总为架构健康报告。

7.6 Token 成本与决策框架

⚠️ Agent Team 的 token 消耗是单会话的 3-5 倍以上。每个 teammate 都是独立的完整 Claude 实例。

7.7 最佳实践

• 从 review 开始练手：审查类任务边界清晰、不涉及代码冲突，最适合入门
• 明确指定角色和 scope：模糊的 prompt 导致 teammate 重叠，浪费 token
• 用 in-process 模式起步：默认模式，所有 IDE 兼容；熟练后切 split-pane（需 tmux/iTerm2，VS Code 终端不支持）
• 让 Lead 做清理：Teammate 不应执行 cleanup，可能留下不一致的共享资源
• 关注共享任务列表：Ctrl+T 是你的项目看板，所有 teammate 的进度一目了然

8. /insights：AI 教练的工作流诊断 📊

8.1 是什么

/insights 是 Claude Code 的内置自省命令 — 分析你过去 30 天的所有会话数据，生成一份交互式 HTML 报告。相当于一个了解你所有工作细节的 AI 教练做的月度绩效复盘。

# 在 Claude Code 中直接运行
/insights

# 报告输出位置
~/.claude/usage-data/report.html

8.2 报告包含什么

8.3 底层机制

/insights 的处理流程相当精巧：

1. 收集：扫描 ~/.claude/projects/ 下所有 JSONL 会话日志
2. 过滤：排除子代理会话和内部操作
3. 摘要：超过 30,000 字符的会话先用 Haiku 分块摘要
4. 分面分析：对每个会话（最多 50 个新会话/次）提取结构化"分面" — 目标类别、工具使用、摩擦点、结果
5. 合成报告：汇总所有分面，生成可视化 HTML 报告

分面数据缓存在 ~/.claude/usage-data/facets/，后续运行增量更新，只分析新会话。

8.4 高价值用法

① 发现隐藏瓶颈

有开发者在报告中发现自己的 "File Too Large" 错误率异常高 — 原来是因为没有配置子目录 CLAUDE.md 做渐进式披露，每次都强制加载完整文件。修正后 token 消耗下降 12%。

② 将建议直接写入 CLAUDE.md

/insights 报告里的 "Suggestions" 部分会给出可直接复制粘贴的代码片段（Skill 定义、Hook 配置、Agent 模板）。最佳实践：

跑完 /insights 后：
1. 读报告中的 Suggestions 部分
2. 把相关建议直接加入 CLAUDE.md 的规则
3. 下次 /insights 时验证改进效果

这与"每个错误只犯一次"原则形成闭环 — /insights 帮你发现你自己没意识到的重复性错误。

③ 定期运行，追踪趋势

建议每两周跑一次 /insights。对比两次报告可以看到：

• 会话完成率是否提升
• 中途放弃的比例是否下降
• 新 Skill/Hook 是否真的减少了摩擦点
• Token 消耗趋势（是否在优化）

④ 校准你的 AI 使用认知

"最大的收获是意识到：我以为自己用得很好，但数据告诉我并非如此。" — 一位跑完 /insights 的开发者

/insights 会指出你以为自己在做但实际没做的事：比如你以为自己经常用 TDD，但数据显示你的测试相关会话只占 8%。

8.5 注意事项

• 报告重近期：最近一周的高强度使用可能主导整体评分
• 每次运行分析最多 50 个新会话，海量历史需要多次运行
• 建议与报告进行对话 — /insights 后继续在同一会话中追问"为什么你觉得我的 X 模式有问题？"

9. 实战场景：复杂 Debug 🐛

核心三步法：对齐思路 → 观测闭环 → 追踪日志。不是"甩给 Claude 让它随便试"，而是结构化引导 agent 定位问题。

9.1 第一步：对齐思路 — 修正解决问题方向 🎯

最常见的浪费：Claude 拿到错误信息后冲进一个错误的修复方向，越修越偏。

你：这个 API 在高并发下偶尔返回 500，看看 error log：
[粘贴日志]

⚠️ 先不要修代码。进入 Plan Mode，分析可能的原因，列出 Top 3 假设，
每个假设给出验证方法。

💡 关键心法：两次修正失败后立刻停下来，/clear 重新描述问题。不要在错误方向上追加要求 — 这是"修正死亡螺旋"。

9.2 第二步：观测闭环 — 自动化完成 🔄

方向对了之后，让 Claude 自建观测手段，形成"修改 → 验证 → 再修改"的自动闭环：

方向已确认是连接池泄漏。现在：
1. 先写一个重现脚本（可重复触发这个 bug）
2. 在关键路径加 instrumentation（连接获取/释放计数）
3. 跑重现脚本，把输出喂回来分析
4. 修复后再跑同一个脚本验证

graph LR
    A[写重现脚本] --> B[加观测点]
    B --> C[执行 + 收集数据]
    C --> D{问题复现?}
    D -->|是| E[定位 + 修复]
    D -->|否| F[调整观测粒度]
    F --> B
    E --> G[再跑重现脚本]
    G --> H{修复成功?}
    H -->|是| I[提交]
    H -->|否| E

关键配置：让 Claude 拥有运行测试的权限，形成全自动闭环——

{
  "permissions": {
    "allow": ["Bash(npm run test:*)", "Bash(node scripts/repro-*:*)"]
  }
}

9.3 第三步：追踪日志 — 持久化经验 📝

修完 Bug 不是终点。把排查过程写进知识库，让下次遇到同类问题时秒定位：

Bug 已修复。现在：
1. 把这次的排查路径、根因、修复方案写进 CLAUDE.md 的 Learned Rules
2. 如果涉及架构陷阱，更新 docs/PITFALLS.md
3. 补充回归测试，确保这个 bug 不再出现

自改进循环实战：

# CLAUDE.md - Learned Rules（自动积累）
- 连接池泄漏排查：先检查 connection.release() 是否在 finally 块中
- Prisma timeout：不要改 connection_limit，先查 idle connection 是否被正确回收
- Redis pub/sub 内存泄漏：subscriber 断开后 channel 不会自动清理

这就是"模型即正义"的落地：每次 debug 都让 CLAUDE.md 变得更聪明。

9.4 Anthropic 工程团队的 5 个调试策略

1. Slack MCP + 粘贴 bug 线程：说 "fix"，零上下文切换
2. "去修 CI 失败的测试"：不微管，让 Claude 自己搞定
3. Docker 日志排查：分布式系统直接把容器日志喂进去
4. "证明给我看这能跑"：让 Claude 对比两个分支的行为差异
5. "推倒重来"：修得凑合时说"知道了所有信息后，扔掉这版，实现优雅方案"

10. 实战场景：大型重构 🏗️

10.1 重构 = Plan Mode 的主场

大型重构（改 50+ 文件、跨模块依赖变更）是最容易翻车的场景。核心策略：分阶段、小步提交、每步可回滚。

10.2 标准流程

graph TD
    A[Shift+Tab×2 进 Plan Mode] --> B[Claude 分析影响范围]
    B --> C[输出分阶段方案到 docs/REFACTOR-PLAN.md]
    C --> D{方案审核通过?}
    D -->|否| B
    D -->|是| E[Phase 1: 接口层变更]
    E --> F[跑测试 + commit]
    F --> G[Phase 2: 实现层迁移]
    G --> H[跑测试 + commit]
    H --> I[Phase N: 清理旧代码]
    I --> J[全量测试 + 最终 commit]

10.3 给 Claude 的提示词结构

## 重构任务
把 UserService 从 class-based 迁移到 functional + dependency injection 模式。

## 约束
- 分阶段执行，每阶段改不超过 10 个文件
- 每阶段完成后必须跑 `npm run test` 全部通过才继续
- 保持向后兼容：旧接口加 @deprecated 注解，不直接删除
- 每阶段完成立刻 commit，commit message 包含 phase 编号

## 阶段建议（可由你调整）
Phase 1: 定义新的函数式接口 + 类型
Phase 2: 实现新函数，旧 class 内部委托到新函数
Phase 3: 逐步迁移调用方
Phase 4: 删除旧 class + @deprecated 标记

先进入 Plan Mode，输出完整方案到 docs/REFACTOR-PLAN.md，我审核后再执行。

10.4 关键技巧

用子代理做影响分析：主代理规划，子代理 Explore 扫描所有引用点。

专建重构 Skill：

# .claude/skills/refactor/SKILL.md
---
name: safe-refactor
description: 大型重构执行器。确保分阶段、可回滚、每步有测试。
---
## 铁律
1. 先 Plan Mode 出方案，方案写入 docs/REFACTOR-PLAN.md
2. 每阶段改不超过 10 个文件
3. 每阶段结束跑全量测试
4. 每阶段通过后立刻 git commit
5. 任何阶段测试失败 → 立刻 git stash，回到 Plan Mode 重新评估

⚠️ 绝不要一个 prompt 里说"重构整个模块"然后让 Claude 自由发挥。 这是最昂贵的 anti-pattern — 大概率改到一半上下文爆炸，半成品代码散落一地。

11. 实战场景：新增复杂模块 🧱

11.1 复杂度来源

新增模块不像修 bug 有现成线索，挑战在于：从零定义接口、处理多方依赖、确保与现有系统集成。

11.2 四阶段推进法

11.3 配套 Skill

# .claude/skills/new-module/SKILL.md
---
name: new-module
description: 新模块脚手架。从契约到集成的完整流程。
---
## 流程
1. 让用户描述模块职责和依赖关系
2. 输出接口定义（types + API spec），等用户确认
3. 生成目录骨架（stub 实现，项目可编译）
4. 逐函数 TDD：测试 → 红 → 实现 → 绿 → commit
5. 集成测试 + E2E 验证

## 模板文件
- module-template/        # 标准模块目录结构模板
- test-template.ts        # 测试文件模板
- integration-template.ts # 集成测试模板

11.4 实战提示词示例

我要新增一个 NotificationModule，职责：
- 支持 Email / SMS / Push 三种渠道
- 消息模板管理（CRUD）
- 发送队列（异步，支持重试）
- 发送记录查询

现有依赖：
- UserModule（获取用户联系方式）
- QueueModule（Bull MQ）

请按以下步骤执行：
1. Plan Mode：设计公共接口 + 类型定义，输出到 src/modules/notification/types.ts
2. 我确认后：创建目录骨架 + stub 实现
3. TDD 逐个实现核心函数
4. 最后做与 UserModule / QueueModule 的集成测试

先进 Plan Mode。

12. Hooks：确定性护栏 🛡️

12.1 核心机制

Hook 在生命周期节点确定性触发。退出码 0 = 正常继续；退出码 2 = 阻断操作（stderr 反馈给 Claude）。

三种类型：command（shell 命令）、prompt（Haiku 快速 LLM 评估）、agent（启动有工具的子代理）。

12.2 完整事件表

12.3 生产配置示例

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "python3 -c \"import json,sys;d=json.load(sys.stdin);p=d.get('tool_input',{}).get('file_path','');sys.exit(2 if any(x in p for x in ['.env','package-lock.json','.git/']) else 0)\""
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "jq -r '.tool_input.file_path' | { read f; echo \"$f\" | grep -q '\\.ts$' && npx prettier --write \"$f\"; exit 0; }"
        }]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "terminal-notifier -message 'Claude Code 干完了' -sound default"
        }]
      }
    ]
  }
}

12.4 设计原则

⚠️ 在 commit 时拦截，而非在 write 时拦截。 中途阻断会"迷惑甚至激怒"agent。让它完成工作，最后验证。PreToolUse 挂在 Bash(git commit) 上检查测试通过标志。

• PreToolUse hooks 可返回 permissionDecision: "allow|deny|escalate" + modifiedToolInput
• Stop hooks 检查 stop_hook_active 防死循环
• Hook 是唯一可靠的强制机制 — CLAUDE.md 规则只是"建议"，Claude 可被说服忽略

13. 上下文窗口管理 🧠

13.1 Token 感知

13.2 两种重启策略

简单重启：/clear + 自定义 /catchup，让 Claude 读当前分支所有改动文件。

复杂重启（Document & Clear）：让 Claude 把计划/进度写入 .md → /clear → 新会话指向该 .md。保留战略上下文，重置窗口。

💡 社区共识：不要依赖 auto-compact（~75-95% 时自动触发）— "不透明、易出错"。主动管理上下文。

13.3 交接模式

创建 HANDOFF.md：目标 / 进度 / 有效方案 / 失败方案 / 下一步。HN 上的生产工作流："写计划到 markdown → 新会话 → 实现几件事 → 更新计划 → 新会话"。

禁用闲置 MCP 服务器后再 /compact，先释放被 tool 定义占据的空间。

14. Extended Thinking 深度思考 🧪

14.1 现状

Extended thinking 默认开启，预算 31,999 token。关键词触发（ultrathink 等）已废弃。

14.2 隐藏解锁：64K 模型双倍思考

MAX_THINKING_TOKENS=63999 claude          # 当次生效
echo 'export MAX_THINKING_TOKENS=63999' >> ~/.zshrc  # 永久

Ctrl+O 切换 verbose 模式看 thinking 内容。

14.3 何时值得 / 不值得

15. 自动化 Code Review 🔍

15.1 GitHub Action

name: Code Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "/review"
          claude_args: "--max-turns 5"

内置 /code-review 启动 4 个并行审查代理，各自独立打分（阈值 80/100），过滤误报。

15.2 CI 自动修测试

- name: Fix Failing Tests
  if: steps.tests.outcome == 'failure'
  run: |
    claude -p "修复失败测试。输出: $(cat test-output.txt)
    做最小修改。" \
    --allowedTools "Read,Edit,Bash(bun test:*)" || true

永远加 || true 作为 fallback，防止 Claude 失败阻塞流水线。

16. 血泪教训：烧钱的错误 💀

16.1 真实事故

16.2 必配安全规则

{
  "permissions": {
    "deny": [
      "Bash(*drop*database*)", "Bash(*truncate*)",
      "Bash(*migrate*reset*)", "Bash(*rm -rf*)",
      "Edit(.env*)", "Read(./secrets/**)"
    ],
    "ask": ["Bash(*migrate*)", "Bash(prisma db push)"]
  }
}

16.3 反模式速查

⚠️ 铁律：不以 root 运行；容器外不用 --dangerously-skip-permissions；Claude 的删除不进回收站，永久消失。

17. 六条操作纪律 🎯

不是理念，是判断标准。每条对应一个具体的操作决策点 — 遇到时直接查表执行。

原则一：30 分钟提交法 ⏱️

一个 prompt 的范围，不超过 30 分钟能 commit 的量。

超过 → 说明你没拆够。这一条同时解决三个问题：防上下文腐烂（长会话后 CLAUDE.md 指令衰减）、可回滚（每次 commit 是安全检查点）、强制你做分解设计而非"给 Claude 扔一整个需求"。

原则二：两次不中就停手 ✋

同一个修复方向失败两次，立刻 /clear，重新描述问题。

"修正死亡螺旋"是最大的 token 黑洞 — Claude 在错误方向上越补越偏，你追加的约束只会进一步污染上下文。停下来的成本远低于在泥潭里多挣扎 5 轮。正确做法：/clear → 用全新视角重新描述现象 → Plan Mode 先列假设再动手。

原则三：先只读、后动手 🔍

改 3 个文件以上 → 必须 Plan Mode 先行。

这是"欲速则不达"的可执行版本。Plan Mode 无写权限，Claude 只分析不改代码，出方案的速度反而更快（无工具执行开销）。方案确认后切 Auto-Edit 一次成型。适用于：跨模块改动、架构决策、修 Bug 方向不明确时。方案写入 docs/PLAN.md，跨会话可追溯。

原则四：护栏焊死、不靠嘴说 🛡️

不能容忍出错的事，用 Hook；可以容忍偶尔出错的事，写 CLAUDE.md。

这是最重要的设计判断。CLAUDE.md 里的规则本质是"建议" — Claude 可以被上下文说服忽略它。Hook 的退出码 2 是物理阻断，不存在"被说服"的可能。

原则五：上下文如内存，主动回收 🧠

不是等它满了再管，而是每完成一个子任务就评估：继续还是 /clear？

200k token 听起来很多，但 MCP tool 定义 + 文件读取 + 对话历史消耗极快。把上下文当 RAM 管理：worktree 做进程隔离、子代理做临时线程（用完释放）、/clear 是 GC、CLAUDE.md 是持久化存储。会话越短越精准 — 一个 10 轮的精确会话远优于一个 50 轮的模糊会话。

原则六：每个错误只犯一次 🔄

每次 debug 结束，问 Claude："把这次的教训写进 CLAUDE.md 的 Learned Rules。"

这不是可选的好习惯，而是与 Claude Code 协作的核心增长飞轮。Session 1 犯 3 个错 → 写入规则 → Session 2 不再犯这 3 个 → 暴露更深层问题 → 继续写入。一个月后你的 CLAUDE.md 就是一份高度定制化的项目"避坑指南"，新人、新会话、新 worktree 都能即刻受益。配合 Skill 固化为可复用能力包，复利效应指数增长。