Claude Code 速查手册

好指令的三要素：目标 + 约束 + 上下文

• 目标：要实现什么效果（"点击按钮后跳转到 /dashboard"）
• 约束：不要做什么（"不要改其他文件""用现有的组件风格"）
• 上下文：相关文件和背景（"@src/auth.ts 这个是认证模块"）

引用文件的花式用法

• @src/app.js — 引用整个文件
• @src/app.js#5-30 — 只看第 5-30 行
• @src/ — 引用整个目录

给验证标准，让它自己检查

不要只说"修这个 bug"，而是："修完后跑 @tests/auth.test.ts 确认通过"。给 Claude 一个可以自我验证的标准，它会自己跑测试确认。

模糊指令也有用武之地

探索性任务用模糊指令反而更好："这个文件有什么可以改进的？""帮我理解一下这个模块的架构"。但到了实现阶段，切回精确模式。

Plan Mode 的精髓

改一个计划只需要一句话，改已经写好的代码要花十倍的时间。所以大任务一定先规划。

• 按 Ctrl+G 可以在编辑器里直接改计划——删掉不同意的部分，补充你的想法
• Plan Mode 下 Claude 只能读文件、搜代码，不能做任何修改，放心让它看

什么时候不需要 Plan Mode

判断标准：如果实现方式只有一种，直接做。如果有多种选择，先规划。

• 改一个变量名 → 直接做
• 修一个明显的 typo → 直接做
• 加一个新功能模块 → 先规划

Writer/Reviewer 双会话模式（高级）

用两个独立会话分别"写代码"和"审查代码"，Reviewer 不受 Writer 思路影响，能发现盲点：

• 会话 A（Writer）："实现 API 限流中间件"
• 会话 B（Reviewer）："审查这个文件，重点看边界情况和竞态条件"
• 会话 A："修复审查反馈：[粘贴 B 的输出]"

🧪 测试

• test-driven-development — 强制 RED-GREEN-REFACTOR 循环：先写失败测试 → 写最小代码通过 → 重构。还附带测试反模式参考

🔍 调试

• systematic-debugging — 4 阶段 root cause 定位（调查→分析→假设→实施），包含防御性编程和条件等待技术
• verification-before-completion — 确认真的修好了，不是"看起来好了"

🤝 协作流程

• brainstorming — 苏格拉底式提问，帮你想清楚需求再动手
• writing-plans — 把设计拆成 2-5 分钟的小任务，每个写清文件路径和验证步骤
• executing-plans — 分批执行，每批有人工检查点
• dispatching-parallel-agents — 多个子 agent 并行干活
• subagent-driven-development — 每个任务派子 agent，两轮 review（规格 + 质量）

📝 代码审查

• requesting-code-review — 提交前自查清单
• receiving-code-review — 收到反馈后怎么处理

🌿 Git 管理

• using-git-worktrees — 自动创建隔离分支开发
• finishing-a-development-branch — 完成后选择合并/PR/保留/丢弃

🛠️ 元技能

• writing-skills — 教你写新的 skill
• using-superpowers — 入门指引

💡 想法阶段

• /office-hours — YC 式头脑风暴，帮你想清楚再动手

📋 规划阶段

• /plan-ceo-review — 战略评审，评估范围和方向
• /plan-eng-review — 架构评审，锁定技术方案
• /plan-design-review — 设计评审
• /autoplan — 自动跑完全部评审流程

🎨 设计阶段

• /design-consultation — 生成设计系统（字体、配色、布局）
• /design-review — 视觉 QA，找间距/层级/一致性问题并修复

🔍 审查 & 测试

• /review — Staff 级代码审查（SQL 安全、竞态条件、信任边界）
• /qa — 真实浏览器跑测试，自动修 bug + 回归测试
• /qa-only — 只报告不修复
• /investigate — 系统化 debug，4 阶段定位 root cause
• /codex — 调 OpenAI 做独立交叉审查（第二意见）
• /cso — 安全审计（OWASP Top 10、威胁建模）

🚀 发布

• /ship — 测试→审查→版本号→CHANGELOG→PR 一条龙
• /land-and-deploy — 合并 PR + 等 CI + 验证生产环境
• /document-release — 自动更新文档
• /retro — 周报指标和趋势分析

🛡️ 安全护栏

• /guard — 全保护模式（危险命令警告 + 目录锁定）
• /careful — 只警告危险操作
• /freeze / /unfreeze — 锁定/解锁指定目录

🌐 其他

• /browse — 内置无头浏览器（100ms 级操作）
• /benchmark — 性能基准测试
• /canary — 部署后监控

读取优先级（从高到低）

• ~/.claude/CLAUDE.md — 个人全局配置（所有项目都读）
• 项目根/CLAUDE.md — 项目级（提交到 git，团队共享）
• 项目根/CLAUDE.local.md — 本地覆盖（不提交，个人偏好）

全局 CLAUDE.md 推荐写法

这几行能省掉你几百次重复纠正：

## 身份
- 叫我大哥，用中文，简洁直接
- 非程序员，不要给我看代码/日志/报错，只要结论和结果

## 沟通
- 禁止废话客套，一句话能说清就别一段
- 能直接做就做，不要反复确认
- 犯错直说，有观点就站一边

## 工作方式
- 先做后报：动手→结果→汇报一句
- 快速迭代：先能用再好用

## 红线
- 不编造信息，不确定就说不确定
- 不删除任何东西（用 trash 不用 rm）

项目 CLAUDE.md 应该包含什么

• 怎么跑项目、怎么跑测试（具体命令）
• 编码规范（格式化工具、命名风格）
• 架构决策（"为什么选 X 而不是 Y"）
• 常见陷阱（"数据库连接池上限 20，别在循环里开新连接"）

三个关键原则

• 写 Claude 从代码里读不出来的东西 — "为什么"比"是什么"重要
• 控制在 200 行以内 — 太长会导致 Claude 忽略规则
• 不要放频繁变化的内容 — 详细 API 文档放链接就好

进阶：用 .claude/rules/ 拆分规则

项目大了之后，把规则拆到 .claude/rules/ 目录下，用 YAML frontmatter 限定到特定文件：

# .claude/rules/api-style.md
---
paths: ["src/api/**/*.ts"]
---
API 路由必须包含输入验证和错误处理。
所有新端点需要添加集成测试。

这样规则只在 Claude 访问匹配的文件时才加载，节省上下文空间。

上下文里都装了什么

• 你的对话历史
• Claude 读取的所有文件内容
• 命令执行的输出
• CLAUDE.md 文件（每次都加载）
• Memory 文件（前 200 行）
• MCP 工具定义（每个吃 4-6K token）

五个实用策略

• /clear — 一件事做完就清，不要在同一个对话里混着干
• /compact 专注于 API 改动 — 压缩时加焦点，Claude 会优先保留你关心的内容
• /context — 查看哪些文件和 MCP 占了多少 token，经常发现没用的 MCP 占了大量空间
• 用子 Agent 隔离噪声 — 跑测试、分析日志让子 Agent 去做，主对话保持干净
• 在 CLAUDE.md 里写压缩保留指令 — 告诉 Claude 压缩时必须保留什么

Memory vs CLAUDE.md

• Memory 适合存：你的偏好、项目约定、历史决策
• Memory 不适合存：代码细节、Git 历史、临时状态
• 用 /memory 命令查看和管理

Worktree 用法

• claude --worktree feature-auth — 指定名字
• claude --worktree — 自动生成名字
• 在 .claude/worktrees/ 下创建独立副本，退出时没改动自动清理，有改动提示保留或删除

四条 Git 铁律

• 永远不要让 Claude 自动 push — 它可以 commit，但 push 由你确认
• 频繁 commit — 做完一个小功能就 commit，用 /rewind 可以回退到任意 checkpoint
• 警惕破坏性操作 — git reset --hard、git push --force 没有 undo
• 从 PR 恢复上下文 — claude --from-pr 123 自动加载 PR 的改动和讨论

MCP 完整安装命令

• Context7：claude mcp add context7 --transport http https://mcp.context7.com/mcp
• GitHub：claude mcp add github --transport http https://api.githubcopilot.com/mcp/
• Playwright：claude mcp add playwright -- npx -y @playwright/mcp@latest
• Sequential Thinking：claude mcp add thinking -- npx -y @modelcontextprotocol/server-sequential-thinking
• PostgreSQL：claude mcp add postgres --env DATABASE_URL=连接串 -- npx -y @modelcontextprotocol/server-postgres
• SQLite：claude mcp add sqlite -- npx -y @modelcontextprotocol/server-sqlite /数据库路径.db

作用范围：--scope user（所有项目）、--scope local（当前项目，默认）、--scope project（团队共享）

Hooks 自动化（铁律，不是建议）

CLAUDE.md 里的指令是"建议"，Hooks 是"铁律"——无论如何都会执行。配置在 ~/.claude/settings.json 里。

四种触发时机：

• PreToolUse — 工具执行前（可拦截危险命令）
• PostToolUse — 工具执行后（自动格式化）
• Stop — Claude 回答完毕时（弹通知）
• SessionStart — 会话开始时（注入关键信息）

实用示例 — 任务完成弹 macOS 通知：

{ "hooks": { "Stop": [{ "matcher": "", "hooks": [{
  "type": "command",
  "command": "osascript -e 'display notification \"任务完成\" with title \"Claude Code\" sound name \"Glass\"'"
}]}]}}

实用示例 — 拦截 rm -rf 和 force push：

{ "hooks": { "PreToolUse": [{ "matcher": "Bash", "hooks": [{
  "type": "command",
  "command": "bash -c 'CMD=$(cat | jq -r .tool_input.command); echo \"$CMD\" | grep -qE \"rm\\s+-rf\\s+/|git\\s+push.*--force\" && { echo BLOCKED >&2; exit 2; } || true'"
}]}]}}

权限五种模式

用 Shift+Tab 循环切换：

• Yolo Mode — 全自动，不问你（危险但高效）
• Auto-edit — 文件编辑自动通过，命令需确认
• Normal — 默认，敏感操作需确认
• Plan Mode — 只读，不能修改
• Manual — 每步都要确认

精细控制在 .claude/settings.json：

{ "permissions": {
  "allow": ["Bash(npm run *)", "Bash(git commit *)", "Edit(src/**/*.ts)"],
  "deny": ["Bash(rm -rf *)", "Edit(.env)"]
}}

规则优先级：deny → ask → allow（deny 最优先）