Claude Code
完全指南
融合 Anthropic 官方文档、Claude Code Best Practices 博文与内部团队使用经验。从安装到多 Agent 编排,12 章节一本读透 AI 编程全貌。
Chapter 01
什么是 Claude Code
Claude Code 是 Anthropic 的 Agentic 编程工具。它不是聊天机器人——它能读代码、改文件、跑命令、自主解决问题,而你只需描述想要什么。
核心理念
Claude Code 刻意做得底层、不固执——接近原始模型访问,不强制任何工作流。这种设计创造了一个灵活、可定制、可脚本化的强大工具。
五种使用方式
Terminal CLI
全功能命令行,核心入口。一行安装,cd 到项目目录即可开始。
VS Code / JetBrains
IDE 扩展,支持内联 diff、@-mentions、Plan 审查和对话历史。
Desktop / Web
独立桌面应用或浏览器运行,无需本地环境。支持多会话并排。
安装方式一览
需要 Claude 订阅(Max/Team/Enterprise)或 Anthropic Console API 账号。Terminal CLI 和 VS Code 还支持第三方模型提供商。
Claude Code 能做什么?
- 自动化日常琐事 — 写测试、修 lint、解决合并冲突、更新依赖、写 release notes
- 开发功能和修 Bug — 用自然语言描述你想要什么
- 创建提交和 PR — 直接操作 git
- 连接外部工具 (MCP) — Google Drive、Jira、Slack、Notion、数据库
- 定制化 — CLAUDE.md 指令、Skills、Hooks、自定义 Agents
- 多 Agent 团队 — 多个 Agent 同时工作,还有 Agent SDK 构建自定义流程
- Unix 风格管道 — 可 pipe、script、自动化,遵循 Unix 哲学
- 定时任务 — 云端定时、桌面端定时、/loop 循环
关键约束
大多数最佳实践基于一个核心约束:Claude 的上下文窗口会填满,性能随之下降。上下文包含整个对话、每个读过的文件、每条命令输出。一次调试就能产生上万 token。
Chapter 02
环境配置
Claude Code 自动拉取上下文到 prompt 里。这会消耗时间和 token,但通过环境调优可以大幅优化。
四大配置维度
权限模式
默认保守策略——任何可能修改系统的操作都需要确认。可自定义 allowlist 跳过安全操作的确认。
四种管理方式
- Always allow — 会话中弹窗时选择"始终允许"
- /permissions — 启动后用命令管理
- settings.json — 手动编辑
.claude/settings.json或~/.claude.json - --allowedTools — CLI 启动参数,针对单次会话
Auto 模式:分类器自动审查命令安全性,适合批量操作。
CLI 工具集成
Claude 继承你的 shell 环境,能使用你所有的命令行工具。
推荐集成的工具
- gh — GitHub CLI,Claude 直接创建 PR、读 issue、处理 review comments
- aws / gcloud — 云服务操作
- sentry-cli — 错误追踪
- 自定义脚本 — 在 CLAUDE.md 中记录用法
Claude 知道常见工具,但不知道你的自定义工具——在 CLAUDE.md 里写清楚名称和用法示例。
Skills:可复用的领域知识
在 .claude/skills/ 目录下创建 SKILL.md 文件,给 Claude 领域知识和可复用的工作流。
- Skills 可以定义通过
/skill-name调用的可重复工作流 - 适合不需要每次都加载、但某些场景需要的领域知识
- 比写进 CLAUDE.md(每次都加载)更轻量
Plugins:一键安装的能力包
运行 /plugin 浏览插件市场。Plugin 打包了 Skills + Hooks + Sub-agents + MCP servers,一键安装。
自定义 Slash 命令
在 .claude/commands/ 目录下存储 Markdown 文件,它们会变成可用的 slash 命令。
支持 $ARGUMENTS 关键字传参。可以 check 进 git 共享给团队。
用法:/project:fix-github-issue 1234
Chapter 03
CLAUDE.md 指令系统
CLAUDE.md 是 Claude 启动时自动加载的特殊文件。你的项目规则、代码风格、常用命令——都写在这里。
核心定位
CLAUDE.md = 你写给 Claude 的"入职手册"。只写 Claude 猜不到的,太长反而被忽略。
文件位置与优先级
| 位置 | 作用域 | 说明 |
|---|---|---|
~/.claude/CLAUDE.md | 全局 | 所有项目的所有会话都加载 |
./CLAUDE.md | 项目 | check 进 git 共享给团队(推荐) |
./CLAUDE.local.md | 个人 | 项目级但不提交,加入 .gitignore |
| 父目录 CLAUDE.md | 继承 | Monorepo 场景,子目录继承父目录指令 |
| 子目录 CLAUDE.md | 按需 | Claude 操作子目录文件时按需加载 |
该写什么
- Claude 猜不到的 Bash 命令
- 不同于默认的代码风格规则
- 测试指令和首选测试框架
- Git 规范(分支命名、PR 约定)
- 项目特有的架构决策
- 开发环境的坑
- 非显而易见的行为
不该写什么
- Claude 看代码就能推断的东西
- 标准语言惯例(Claude 已经知道)
- 详细 API 文档(给链接就好)
- 频繁变化的信息
- 长篇解释或教程
- 逐文件的代码描述
- 不言自明的做法(如"写干净代码")
示例 CLAUDE.md
高级技巧:# 键快速记录 + Import 语法
# 键:在对话中按 # 键给 Claude 一条指令,它会自动存入对应的 CLAUDE.md 文件。很多工程师在编码过程中频繁使用 # 来记录命令、文件路径和风格偏好,然后在 commit 时一并提交。
Import 语法:CLAUDE.md 可以用 @path/to/import 语法引入其他文件的内容,适合拆分大型配置。
迭代优化:Anthropic 内部会用 prompt improver 跑 CLAUDE.md,用 "IMPORTANT" 或 "YOU MUST" 等强调词来提升指令遵从率。
AGENTS.md 兼容
Claude Code 也支持 AGENTS.md 文件名,和 CLAUDE.md 功能完全一致。有些团队用 AGENTS.md 作为跨工具的通用 Agent 指令文件。
.claude/rules/ 目录:路径级指令
在 .claude/rules/ 目录下创建规则文件,可以指定特定路径才生效的指令。适合 monorepo 中不同模块有不同规范的场景。
Chapter 04
核心工作流
Anthropic 内部团队和外部工程师验证过的高效工作流模式。
探索 → 规划 → 编码 → 提交
最通用的工作流,适合大多数问题。用 Plan Mode 分阶段推进。
四阶段详解
- Explore(探索) — 进入 Plan Mode(Shift+Tab)。Claude 只读文件、回答问题,不做修改。用 Subagent 做复杂调研。
- Plan(规划) — 让 Claude 制定实现方案。按
Ctrl+G在编辑器中直接修改方案。用 "think" / "think hard" / "ultrathink" 触发不同深度的推理。 - Implement(实现) — 切回 Normal Mode,让 Claude 编码,同时对照方案验证合理性。
- Commit(提交) — 让 Claude 提交并创建 PR。
跳过前两步的后果:Claude 倾向于直接跳到写代码,没有充分理解问题就动手,结果往往需要返工。
TDD 工作流
先写测试,再写实现。Agentic 编码让 TDD 更强大。
五步操作
- 让 Claude 基于期望输入/输出写测试。明确说 TDD,防止它写 mock 实现
- 让 Claude 跑测试,确认测试失败。明确说"不要写实现代码"
- 测试满意后让 Claude 提交测试
- 让 Claude 写通过测试的代码,"不要修改测试"。让它持续跑直到全部通过
- 代码满意后提交
截图迭代工作流
给 Claude 视觉目标,让它实现后截图对比,迭代直到匹配。
操作步骤
- 给 Claude 截图能力(如 Puppeteer MCP)
- 拖入或粘贴设计稿图片
- 让 Claude 实现、截图、对比、迭代
- 满意后提交
Codebase Q&A:问项目问题
像问高级工程师一样问 Claude。这已成为 Anthropic 内部的核心 onboarding 方式:
- "日志系统怎么工作的?"
- "怎么新建一个 API endpoint?"
- "foo.rs 第 134 行的
async move { ... }做了什么?" - "为什么第 333 行调 foo() 而不是 bar()?"
- "baz.py 第 334 行用 Java 怎么写?"
Git 操作与 GitHub 集成
Git(Anthropic 工程师 90%+ 的 git 操作都交给 Claude):
- 搜索 git 历史回答问题
- 写 commit message
- 复杂操作:revert、rebase 冲突解决、patch 对比和嫁接
GitHub:
- 创建 PR
- 一键解决简单的 code review comments
- 修复 CI 构建失败和 linter 警告
- 分类和 triage 开放 issues
让 Claude 采访你:大功能的需求澄清
对于大型功能,不用写完美 prompt——给个最小描述,让 Claude 用 AskUserQuestion 工具采访你。
需求澄清完毕后,开新会话执行(用干净的上下文)。
进阶能力
MCP 工具扩展、Hooks 自动化、Sub-agents 与 Agent Teams
Chapter 05
提示技巧与上下文管理
给 Claude 精确指令和验证能力,是提升产出质量的最高杠杆。
最高优先级
给 Claude 自我验证的方式(测试、截图、期望输出)——这是你能做的单一最有效的优化。
提示对比:模糊 vs 精确
| 差的提示 | 好的提示 |
|---|---|
| "给 foo.py 加测试" | "给 foo.py 写测试,覆盖用户已登出的边界情况。不要用 mock。" |
| "ExecutionFactory 的 API 为啥这么奇怪?" | "查看 ExecutionFactory 的 git 历史,总结它的 API 是怎么演变成现在这样的" |
| "加个日历组件" | "看看首页现有 widget 的实现方式来理解模式... HotDogWidget.php 是好示例。按这个模式来..." |
| "修复登录 bug" | "用户反馈超时后登录失败。检查 src/auth/ 的认证流程,特别是 token 刷新。先写失败测试复现问题,再修复" |
提供丰富内容的方式
@引用文件
Tab 补全
粘贴图片
Ctrl+V / 拖入
给 URL
Claude 自动抓取
Pipe 数据
cat file | claude
上下文管理
/clear — 重置上下文
不相关的任务之间必须用 /clear 清空。长会话的上下文积累是性能下降的主因。
/compact — 压缩上下文
用 /compact <指令> 让 Claude 压缩对话历史,保留你指定的关键信息。
/btw — 旁白提问
快速问不进入对话历史的问题,不污染主上下文。
Subagent 调研
把调研任务委托给 Subagent(独立上下文窗口),主对话保持干净。
纠错技巧:越早越好
- Esc — 随时中断 Claude
- Esc + Esc 或 /rewind — 回退到之前的检查点
- "Undo that" — 让 Claude 撤销刚才的修改
- 规则:如果你在同一个问题上纠正 Claude 超过两次,
/clear然后写一个更好的 prompt 重新开始
Extended Thinking(深度思考)
默认启用。用特定关键词触发不同深度:
| 关键词 | 思考深度 |
|---|---|
| "think" | 标准(适合中等复杂度) |
| "think hard" | 深度 |
| "think harder" | 更深 |
| "ultrathink" | 最大深度(单次最强推理) |
其他控制方式:/effort 命令、Option+T / Alt+T 切换、/config 设全局默认。
Chapter 06
MCP 工具扩展
Model Context Protocol (MCP) 让 Claude 连接外部世界——Notion、Figma、数据库、任何 API。
MCP 是什么
Claude Code 既是 MCP 服务器(被其他工具调用),也是 MCP 客户端(连接其他 MCP 服务)。作为客户端,它可以连接任意数量的 MCP 服务器来获取工具。
三种传输协议
HTTP (Streamable)
远程服务器,推荐的现代协议。
SSE
Server-Sent Events,远程服务器。
stdio
本地进程,通过标准输入/输出通信。
三种配置作用域
- 项目级 (.mcp.json) — check 进 git,团队共享。任何克隆代码库的人自动获得配置
- 项目本地 (.claude/settings.local.json) — 不提交,个人使用
- 全局 (~/.claude.json) — 所有项目可用
安装与管理
MCP 服务器可以有环境变量配置(API Key 等),支持 OAuth 认证。
实用 MCP 推荐
- Puppeteer — 浏览器截图,UI 开发必备
- Notion — 读写 Notion 数据库和页面
- Figma — 设计稿直接给 Claude
- Google Drive — 读设计文档
- 数据库 — 直连 PostgreSQL/MySQL 查询数据
- Slack — 读消息、发通知
Chapter 07
Hooks 自动化
Hooks = 确定性的自动化。和 CLAUDE.md(建议性指令)不同,Hooks 是强制执行的——每次触发都必然运行。
CLAUDE.md vs Hooks
CLAUDE.md 是"建议"——Claude 可能忘记或忽略。Hooks 是"铁律"——机械化执行,零例外。凡是"每次X必须Y"的规则,都应该用 Hook 实现。
Hook 事件类型
| 事件 | 触发时机 | 典型用途 |
|---|---|---|
PreToolUse | 工具调用前 | 检查文件/阻止操作/注入上下文 |
PostToolUse | 工具调用后 | 自动格式化/同步更新/验证结果 |
Notification | Claude 需要注意力 | macOS 通知/Telegram 告警/声音提示 |
SessionStart | 会话启动 | 环境检查/注入上下文 |
SessionEnd | 会话结束 | 清理/日志/统计 |
Stop | Claude 认为任务完成 | 质量门禁/自动测试 |
配置格式与 Matcher
Hooks 配置在 ~/.claude/settings.json 或项目的 .claude/settings.json 中。
Matcher 用正则匹配工具名(如 Write|Edit 匹配写入和编辑操作)。空 matcher 匹配所有事件。
三种 Hook 类型
- Command Hook — 执行 shell 命令。最常用。通过 exit code 控制:0=通过,2=阻止操作
- Prompt Hook — 给 Claude 注入额外 prompt 指令
- Agent Hook — 启动一个 Agent 来处理。适合需要判断力的自动化
实战示例:通知 Hook
Matcher 选项:permission_prompt(权限请求)、idle_prompt(空闲等待)、auth_success(认证成功)。
实战示例:自动格式化 + 文件保护
自动格式化:PostToolUse 监听 Write/Edit 事件,自动跑 prettier。
文件保护:PreToolUse 监听 Write/Edit 事件,检查目标路径是否为受保护文件,exit 2 阻止。
上下文压缩后重注入:SessionStart 或 compact 后自动注入关键上下文。
Chapter 08
Sub-agents 与 Agent Teams
Sub-agents 是独立上下文窗口中运行的专业助手。Agent Teams 让多个 Claude 实例协同工作。
内置 Sub-agents
Explore
快速探索代码库。搜索文件、关键词、回答代码库问题。
Plan
设计实现方案。识别关键文件、考虑架构取舍。只读不写。
General-purpose
通用 Agent,可执行复杂多步任务。有完整工具集。
自定义 Sub-agents
在 .claude/agents/ 目录下创建 Markdown 文件定义自定义 Agent。
Frontmatter 支持字段:
- model — 指定模型(opus/sonnet/haiku)
- tools — 控制可用工具(include/exclude)
- mcpServers — 指定 MCP 服务器
- permissions — 设置权限模式
- skills — 预加载 Skills
- isolation: worktree — 在独立 git worktree 中运行
示例 Agent:code-reviewer、debugger、data-scientist、db-reader。
用 /agents 查看所有可用 Agent。
Agent Teams:多 Agent 协作
Agent Teams 让多个 Claude 实例同时工作在同一个项目上。
何时用 Teams vs Sub-agents:
- Sub-agents — 独立的调研任务、不需要互相通信、结果回报给主 Agent
- Teams — 需要协作、互相通信、同时修改不同部分
显示模式:in-process(同窗口)或 split panes(分屏)。
关键特性:
- 指定 teammate 和使用的模型
- Plan 审批机制
- 直接消息和任务分配
- Hooks 做质量门禁
Git Worktrees:并行隔离
用 .worktreeinclude 文件指定需要复制到 worktree 的 gitignored 文件(如 .env)。
实战与进阶
记忆系统、常见工作流、自动化扩展、反模式排障
Chapter 09
记忆与持久化
Claude 的记忆系统让上下文跨会话持久化——不只是 CLAUDE.md,还有自动记忆和 /memory 命令。
三层记忆体系
CLAUDE.md 文件
手动编写的项目指令。每次会话自动加载。团队共享(check 进 git)。
Auto Memory
Claude 自动学习的记忆。存储在 ~/.claude/projects/ 下的记忆文件里。跨会话持久。
.claude/rules/
路径级规则。只在操作特定路径的文件时加载。适合 monorepo 不同模块。
Auto Memory 工作原理
Claude 会自动将重要信息(用户偏好、项目上下文、纠正反馈等)保存到记忆文件中。
- /memory — 查看和管理记忆
- # 键 — 快速给 Claude 一条指令,自动存入 CLAUDE.md
- 记忆文件存储在
~/.claude/projects/{project}/memory/下 - 包含 MEMORY.md 索引文件和多个主题记忆文件
记忆类型:user(用户画像)、feedback(行为纠正)、project(项目上下文)、reference(外部资源指引)。
CLAUDE.md 加载顺序
~/.claude/CLAUDE.md— 全局(最先加载)- 父目录链上的 CLAUDE.md — 继承
./CLAUDE.md— 项目根./CLAUDE.local.md— 项目本地- 子目录 CLAUDE.md — 按需加载
- Auto Memory — 始终加载
会话恢复
会话选择器快捷键:↑↓ 导航、Enter 选择、P 预览、R 重命名、/ 搜索、A 切换全部项目、B 按分支过滤。
Chapter 10
常见工作流实战
Anthropic 官方文档中的 step-by-step 操作指南。
代码库探索与理解
Bug 修复流程
代码重构
四步重构法
- 识别 — "find deprecated API usage in our codebase"
- 建议 — "suggest how to refactor utils.js to use modern JavaScript features"
- 执行 — "refactor utils.js to use ES2024 features while maintaining the same behavior"
- 验证 — "run tests for the refactored code"
创建 PR 完整流程
PR 工作流
直接说 "create a pr for my changes",或者分步引导。
自动关联:用 gh pr create 创建 PR 时,会话自动关联到该 PR。以后可以用 claude --from-pr <number> 恢复。
测试生成
测试工作流
- 识别未测试代码 — 让 Claude 找到覆盖盲区
- 生成测试脚手架 — 基本结构
- 添加有意义的测试用例 — 边界情况、异常路径
- 运行验证 — 确保通过
Jupyter Notebook 协作
Notebook 工作流
Anthropic 的研究员和数据科学家用 Claude Code 读写 Jupyter notebooks。Claude 能解释输出(包括图片)。
推荐:在 VS Code 中并排打开 Claude Code 和 .ipynb 文件。
Chapter 11
自动化与规模化
Headless 模式、CI 集成、批量任务扇出——把 Claude 当 Unix 工具用。
Headless 模式 (-p)
非交互式上下文:CI、pre-commit hooks、构建脚本、自动化。
三种规模化模式
扇出 (Fan-out)
批量迁移或分析。循环调用 claude -p 处理每个文件/任务。
管道 (Pipeline)
嵌入现有数据/处理管道。前一步输出作为下一步输入。
定时任务
云端定时 / Desktop 定时 / GitHub Actions / /loop。
CI/CD 集成实例
Issue Triage:GitHub 事件触发 → Headless Claude 自动分类和响应 issues。
代码审查 Linter:Claude 提供超越传统 lint 的主观代码审查——检测 typo、过时注释、误导性命名。
PR 自动审查:用 GitHub Actions 配合 Claude Code GitHub Code Review 功能。
多 Claude 会话并行
Writer + Reviewer 模式:
- 一个 Claude 写代码
- /clear 或开第二个 Claude 来 review
多 Checkout 并行:
- 创建 3-4 个 git checkout 在不同目录
- 每个打开独立终端 tab
- 每个 Claude 处理不同任务
Git Worktrees(推荐):
Safe YOLO 模式
claude --dangerously-skip-permissions 跳过所有权限检查。适合修 lint、生成样板代码等低风险操作。
风险:可能导致数据丢失、系统损坏甚至数据泄露。务必在无网络的容器中使用。
Chapter 12
反模式与排障
常见失败模式和对应解法,加上安装排障指南。
五大反模式
厨房水槽会话
在一个会话里塞太多不相关的任务,上下文被无关信息淹没。
解法:不相关任务之间用 /clear 重置上下文。
反复纠正
在同一个问题上纠正 Claude 两次以上,Claude 仍然搞不对。
解法:/clear,然后写一个更好的 prompt 重新开始。
过长的 CLAUDE.md
CLAUDE.md 写太多,Claude 反而忽略重要指令。
解法:无情地精简。只保留 Claude 猜不到的、高频适用的指令。
信任-验证缺口
让 Claude 写代码但不提供验证方式(测试、截图、期望输出)。
解法:始终给 Claude 自我验证的手段。
无限探索
调研范围太宽,Claude 不断读文件但迟迟不动手。
解法:缩窄调研范围,或委托给 Sub-agent。
安装排障
macOS 常见问题
- PATH 问题 — 确认
~/.local/bin在 PATH 中。运行echo $PATH检查 - 权限问题 —
chmod +x ~/.local/bin/claude - 冲突 — 检查是否有其他名为 claude 的程序:
which claude
TLS/SSL 错误
常见于企业网络或使用代理的环境。检查:
- 代理配置是否正确
- 证书是否过期或自签名
- 环境变量
NODE_EXTRA_CA_CERTS是否需要设置
认证/OAuth 问题
- 运行
claude auth重新认证 - 检查
~/.claude/目录下的配置文件 - 确认订阅状态有效
心智模型
随着使用增多,你会逐渐建立直觉——什么时候该具体、什么时候该开放,什么时候该规划、什么时候该探索,什么时候该清理上下文、什么时候该让它积累。注意观察什么有效,持续迭代你的工作方式。
发现更多能力
Claude 内置了自己文档的访问能力,可以直接问它关于自身功能的问题。运行 /powerup 获得带动画演示的互动教程。