逸尘的AI知识库

Claude Code 从入门到熟练：完整教程

51分钟阅读

最后更新：2026 年 3 月 适合人群：零基础到进阶用户

目录

  • 第一章：认识 Claude Code
  • 第二章：安装与配置
  • 第三章：第一次使用
  • 第四章：核心功能详解
  • 第五章：CLAUDE.md — 给 AI 的项目说明书
  • 第六章：权限管理与安全
  • 第七章：上下文管理与性能优化
  • 第八章：斜杠命令（Slash Commands）
  • 第九章：自定义斜杠命令
  • 第十章：子代理（Sub-agents）
  • 第十一章：技能（Skills）
  • 第十二章：钩子（Hooks）
  • 第十三章：MCP 服务器集成
  • 第十四章：Git 工作流
  • 第十五章：IDE 集成
  • 第十六章：实战案例
  • 第十七章：进阶技巧与最佳实践
  • 第十八章：常见问题排查
  • 附录：速查表

第一章：认识 Claude Code

1.1 什么是 Claude Code？

Claude Code 是 Anthropic 推出的一款智能编程代理工具（Agentic Coding Tool）。和你在浏览器里使用的 Claude 聊天不同，Claude Code 直接运行在你的**终端（Terminal）**里，能够：

  • 阅读你的整个代码库
  • 编辑项目中的任意文件
  • 执行终端命令（如运行测试、安装依赖）
  • 管理 Git 版本控制（提交代码、创建分支、发起 PR）

简单来说，Claude Code 就像一个住在你终端里的 AI 程序员队友，你用自然语言告诉它要做什么，它就会帮你完成。

1.2 Claude Code vs 其他 AI 编程工具

特性Claude CodeGitHub CopilotCursor
运行环境终端 / IDE / 桌面 / 浏览器IDE 插件独立 IDE
工作方式自主代理（读、写、执行）代码补全/聊天代码补全/聊天/Agent
多文件编辑✅ 自动跨文件操作❌ 单文件为主✅ 支持
执行命令✅ 直接运行终端命令❌有限支持
Git 操作✅ 完整支持❌有限支持
理解整个项目✅ 自动索引代码库有限✅ 支持

1.3 Claude Code 能做什么？

以下是一些真实的使用场景：

claude "给 auth 模块写单元测试，运行测试，修复失败的用例"
claude "把这个 Python 2 项目迁移到 Python 3"
claude "解释一下 src/core/engine.ts 这个文件在做什么"
claude "修复这个报错：TypeError: Cannot read properties of undefined"
claude "用有意义的描述提交我的改动"
claude "帮我把这个 REST API 重构为 GraphQL"

1.4 使用前提

  • 付费账户：你需要 Claude Pro（100-200/月）、Team、Enterprise 或 API Console 账户。免费版的 Claude 不包含 Claude Code。 但是：也可以使用国产大模型如 Minimax 和 GLM 来激活 Claude Code。所以，要分清楚一个概念——Claude Code本身是免费的，只是接入的大模型（API）是收费的。一般接入的“动能”有两种，一种是订阅制套餐（五小时限额，对大多数人友好）；一种是按 API 计费（贵，一般只有大型企业才会接入）。
  • 操作系统：macOS 13+、Ubuntu 20.04+/Debian 10+、Windows 10+（需 Git for Windows 或 WSL）
  • 内存：至少 4GB RAM（推荐 8GB）
  • 网络：接入官方 Claude需要稳定的网络连接，国产不需要任何科学上网环境。
  • 不需要 GPU：所有计算都在大模型服务器上进行

第二章：安装与配置

2.1 macOS / Linux 安装（推荐方式：原生安装器）

打开终端，运行以下命令：

curl -fsSL https://claude.ai/install.sh | bash

安装完成后，关闭并重新打开终端窗口，然后验证安装：

claude --version

你应该会看到类似 2.x.x (Claude Code) 的版本号。

✅ 原生安装器的优势：零依赖（不需要 Node.js）、自动后台更新、安装速度快（不到一分钟）。

2.2 macOS / Linux 安装（Homebrew）

如果你习惯用 Homebrew 管理软件：

brew install --cask claude-code

⚠️ 注意：Homebrew 安装不会自动更新，需要手动运行 brew upgrade claude-code 来获取新版本。Homebrew 升级后旧版本会留在磁盘上，定期运行 brew cleanup claude-code 来释放空间。

2.3 Windows 安装

前置条件： 必须先安装 Git for Windows（安装时确保勾选”Add Git to PATH”）。Claude Code 内部使用 Git Bash 来执行命令。

方式一：PowerShell 安装（推荐）

打开 PowerShell（不需要管理员权限），运行：

irm https://claude.ai/install.ps1 | iex

方式二：WinGet 安装

winget install Anthropic.ClaudeCode

⚠️ 注意：WinGet 安装也不会自动更新，需要手动 winget upgrade Anthropic.ClaudeCode。有时 Claude Code 会通知有新版本，但 WinGet 仓库还没同步——等几个小时再试。

方式三：WSL（Windows Subsystem for Linux）

如果你使用 WSL，在 WSL 终端中按 Linux 方式安装即可：

curl -fsSL https://claude.ai/install.sh | bash

💡 提示：在 WSL 中，项目文件建议放在 Linux 文件系统（~/projects/）而不是挂载的 Windows 驱动器（/mnt/c/...），文件操作会快很多。

2.4 npm 安装（已弃用，不推荐）

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

⚠️ 此方法已被官方标记为弃用。需要 Node.js 18+。如果之前通过 npm 安装，建议迁移到原生安装器：

# 安装原生版本
curl -fsSL https://claude.ai/install.sh | bash
# 卸载旧的 npm 版本
npm uninstall -g @anthropic-ai/claude-code

⚠️ 不要使用 sudo npm install -g，这会导致权限问题。如果遇到权限错误，请使用 nvm 来管理 Node.js。

2.5 首次登录认证

安装完成后，在任意项目目录下运行：

claude

首次运行时，会自动打开浏览器进行 OAuth 认证（登录你的 Anthropic 账户）。认证成功后回到终端，即可开始使用。认证信息会保存在 ~/.claude/ 目录，之后不需要重复登录。

如果在服务器/CI 环境无法打开浏览器，可以使用 API Key：

export ANTHROPIC_API_KEY=sk-ant-your-key-here
claude

也支持第三方云服务提供商：

# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
 
# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-central1

2.6 验证安装成功

# 查看版本
claude --version
 
# 进入交互模式
claude
 
# 在交互模式中检查状态
/status

如果 claude 命令找不到，先试试关闭终端重新打开。大多数情况下这能解决 PATH 问题。

第三章：第一次使用

3.1 启动 Claude Code

# 启动 Claude Code
claude

启动后，你会看到一个交互式的终端界面，你可以直接用自然语言和 Claude 对话。

3.2 两种使用模式

交互模式（Interactive Mode） ：启动 claude 后进入持续对话状态，适合探索、调试和持续性工作。

claude
# 然后在交互界面中输入你的请求

非交互模式（One-shot Mode） ：使用 -p 参数直接传入提示，Claude 执行完后自动退出。适合脚本和自动化场景。

claude -p "给 README 添加安装说明"

3.3 你的第一个任务

启动 Claude Code 后，试试这些简单的命令：

解释一下这个项目的结构

Claude 会自动扫描你的项目目录，然后给出项目结构的概述。

再试试：

找到项目中所有的 TODO 注释

或者：

帮我创建一个 .gitignore 文件，适合 Node.js 项目

3.4 理解 Claude 的工作方式

当你给 Claude 一个任务时，它的工作流程大致是：

  1. 理解意图 — 分析你的请求
  2. 读取代码 — 使用内置工具浏览相关文件
  3. 制定计划 — 决定如何完成任务
  4. 执行操作 — 编辑文件、运行命令
  5. 验证结果 — 运行测试或检查输出
  6. 报告结果 — 告诉你做了什么

在这个过程中，每当 Claude 要执行可能有风险的操作（比如编辑文件、运行命令），它会先请求你的许可。你可以选择允许、拒绝或修改。

3.5 基本快捷键

快捷键功能
Enter发送消息
Escape取消当前输入 / 中断当前操作
Shift+Tab切换到计划模式（Plan Mode）
Tab切回正常模式
Ctrl+C中断 Claude 当前的操作
↑查看/编辑上一条消息
!命令直接执行 shell 命令（不经过 Claude 对话）
Ctrl+D退出 Claude Code

第四章：核心功能详解

4.1 文件操作

Claude Code 可以读取、创建、编辑和删除文件：

创建一个 utils/helpers.ts 文件，包含日期格式化和字符串处理的工具函数

把 config.js 中的数据库连接字符串改为环境变量读取

在 src/components/ 下找到所有使用了旧版 API 的组件，并更新为新版

你也可以用 @ 符号引用特定文件，让 Claude 关注它们：

看一下 @src/api/auth.ts 和 @src/middleware/jwt.ts，帮我找出认证逻辑的 Bug

4.2 执行终端命令

Claude 可以直接在你的终端中运行命令：

运行测试并修复所有失败的用例

安装 axios 和 lodash 依赖

运行 npm run build，如果有错误就修复

如果你想自己直接执行命令而不经过 Claude 的对话处理，在命令前加 !：

!npm test

这样会直接运行 npm test，不消耗 Claude 的对话额度。

4.3 代码解释

Claude 擅长解释复杂的代码逻辑：

解释一下 @src/core/scheduler.ts 的工作原理，用通俗的语言

这段正则表达式是什么意思？/^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]{8,}$/

画一个 ASCII 流程图，展示用户登录的完整流程

4.4 代码搜索

在整个项目中搜索所有使用了 deprecated API 的地方

找到所有没有错误处理的 async 函数

哪些文件导入了 @/utils/legacy 模块？

4.5 重构与优化

把 UserService 类重构成更小的、职责单一的模块

这个函数太长了，帮我拆分成更小的函数

把所有回调函数风格的代码改成 async/await

4.6 Bug 修复

直接粘贴报错信息给 Claude：

修复这个错误：
TypeError: Cannot read properties of undefined (reading 'map')
  at UserList (src/components/UserList.tsx:23:18)

Claude 会根据报错信息定位到代码，分析原因，然后修复。

第五章：CLAUDE.md — 给 AI 的项目说明书

5.1 什么是 CLAUDE.md？

CLAUDE.md 是放在项目根目录的一个 Markdown 文件，相当于你给 Claude 写的”项目入职手册”。它告诉 Claude 关于你项目的重要信息，让 Claude 在每次对话中都能了解项目的上下文。

这是 Claude Code 中最能立竿见影提升体验的功能——一个好的 CLAUDE.md 能让 Claude 的回答质量大幅提升。

5.2 快速生成

在 Claude Code 交互模式中运行：

/init

Claude 会自动扫描你的项目，生成一个初始的 CLAUDE.md 文件。然后你可以根据需要手动编辑和完善。

5.3 CLAUDE.md 应该包含什么

一个好的 CLAUDE.md 文件通常包含以下内容：

# 项目概述
 
这是一个使用 Next.js 14 + TypeScript + Prisma 构建的电商平台后台管理系统。
 
# 技术栈
 
- 框架：Next.js 14（App Router）
- 语言：TypeScript（严格模式）
- 数据库：PostgreSQL + Prisma ORM
- 状态管理：Zustand
- 样式：Tailwind CSS
- 测试：Vitest + Playwright
 
# 常用命令
 
- `npm run dev` — 启动开发服务器
- `npm run build` — 构建生产版本
- `npm test` — 运行单元测试
- `npm run test:e2e` — 运行端到端测试
- `npm run lint` — 代码检查
- `npx prisma migrate dev` — 运行数据库迁移
 
# 代码规范
 
- 使用函数组件 + Hooks，不使用 Class 组件
- 组件文件使用 PascalCase 命名
- 工具函数使用 camelCase 命名
- 每个组件必须有对应的测试文件
- 提交信息遵循 Conventional Commits 规范
- 禁止使用 any 类型，必须明确定义类型
 
# 项目结构
 
src/
├── app/          # Next.js App Router 页面
├── components/   # 可复用 UI 组件
├── lib/          # 核心业务逻辑
├── hooks/        # 自定义 React Hooks
├── types/        # TypeScript 类型定义
├── utils/        # 工具函数
└── prisma/       # 数据库模型与迁移
 
# 重要提醒
 
- 修改 API 路由后，一定要更新对应的 API 文档
- 数据库 schema 修改后必须生成迁移文件
- 不要直接操作 production 分支

5.4 CLAUDE.md 的层级

Claude Code 会按优先级查找多个位置的 CLAUDE.md：

位置作用范围用途
项目根目录/CLAUDE.md当前项目项目特定的配置和规范（提交到 Git，团队共享）
项目根目录/CLAUDE.local.md当前项目你的个人偏好（不提交到 Git）
~/.claude/CLAUDE.md所有项目全局的个人习惯和偏好
子目录/CLAUDE.md特定子目录子模块特定的说明

5.5 编写 CLAUDE.md 的最佳实践

  • 保持简洁：不要写太长（建议 200 行以内），过于庞大的文件反而会让 Claude 忽略内容
  • 突出重要信息：把最关键的规范和命令放在前面
  • 定期更新：项目变化后及时更新 CLAUDE.md
  • 写具体的规则：比如”用 Vitest 而不是 Jest”比”使用合适的测试框架”更有效
  • 包含常用命令：Claude 不需要猜测如何运行测试或构建项目

第六章：权限管理与安全

6.1 默认权限模型

Claude Code 采用”先请求后执行”的安全模型。默认情况下，Claude 会在以下操作前征求你的许可：

  • ✅ 读取文件 — 通常自动允许
  • ⚠️ 编辑文件 — 会展示 diff 并等待确认
  • ⚠️ 执行命令 — 会显示要执行的命令并等待确认
  • ⚠️ 删除文件 — 需要确认

当 Claude 请求权限时，你有三个选择：

  • 允许（Allow） — 允许这一次
  • 永久允许（Always Allow） — 以后这类操作不再询问
  • 拒绝（Deny） — 不允许执行

6.2 权限配置

在交互模式中运行 /permissions 来管理权限白名单。

也可以直接在配置文件中设置：

{
  "permissions": {
    "allowedTools": [
      "Read",
      "Write",
      "Bash(npm run lint)",
      "Bash(npm test)",
      "Bash(git *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Write(./production.config.*)"
    ]
  }
}

上面的配置表示：

  • 允许读写文件
  • 允许运行 lint、test 和 git 命令（不需要每次确认）
  • 禁止读取 .env 文件（保护 API 密钥等敏感信息）
  • 禁止修改生产配置文件

6.3 危险模式（—dangerously-skip-permissions）

claude --dangerously-skip-permissions

这个参数会跳过所有权限确认，Claude 可以自由读写文件、执行任何命令。这个名字故意起得吓人，提醒你这有潜在风险。

适合使用的场景不适合使用的场景
对 Claude Code 非常熟悉之后刚开始学习时
个人学习/实验项目重要的生产代码库
完全自动化的 CI/CD 流程你不熟悉的项目
有一个小技巧：可以告诉你的 Claude Code：“请你帮我配置一下，我希望我每次打开 Claude Code 输入 ai，就等同于输入了claude —dangerously-skip-permissions，这样以后就不用记一大长串命令来启动了。

6.4 配置文件位置

文件位置作用
全局设置~/.claude/settings.json你的所有项目共享的设置
项目设置项目/.claude/settings.json只影响当前项目

第七章：上下文管理与性能优化

7.1 理解上下文窗口

Claude Code 的默认上下文窗口是 200,000 个 token（Sonnet 和 Opus 在 Beta 中支持 100 万 token）。随着对话进行，上下文会逐渐填满——你的对话历史、文件内容、命令输出都会占用空间。

当上下文接近满时，Claude 会自动进行压缩（Compaction）——清理旧的工具输出，总结之前的对话。但主动管理效果更好。

7.2 手动管理上下文

清除上下文（在完成一个任务后，开始新任务前）：

/clear

手动压缩：

/compact

你还可以带上提示来指导压缩过程：

/compact 保留关于数据库迁移的所有信息

7.3 什么时候该清除上下文？

  • 完成一个 Bug 修复后，要开始一个新功能开发
  • Claude 的回答质量明显下降
  • Claude 开始重复之前的错误
  • Claude 的回答变得缓慢

7.4 优化 Claude 的表现

  • 一次只做一件事：不要在一个长对话中混杂多个不相关任务
  • 给出具体指令："重构 UserService" 比 "改进代码" 好得多
  • 提供验证方式："写完测试后运行 npm test 确认通过" 让 Claude 能自我验证
  • 使用 @ 引用文件：@src/api/users.ts 让 Claude 精确定位，避免浪费 token 搜索

7.5 计划模式（Plan Mode）

按 Shift+Tab 进入计划模式。在这个模式下，Claude 只会分析和制定计划，不会执行任何操作。这非常适合：

  • 探索复杂问题时，先看看 Claude 打算怎么做
  • 评估一个大型重构的影响范围
  • 让 Claude 先想清楚再动手，避免走弯路
[计划模式] 如果我要把这个项目从 JavaScript 迁移到 TypeScript，需要哪些步骤？

审查完计划后，按 Tab 切回正常模式，然后让 Claude 执行计划。

💡 Anthropic 自己的建议是：多用计划模式。因为 AI 模型往往”太急于动手写代码”，先让它想清楚再行动效果更好。

第八章：斜杠命令（Slash Commands）

8.1 内置命令一览

命令说明
/help查看所有可用命令（包括自定义命令）
/init为当前项目生成 CLAUDE.md
/clear清除对话历史，重新开始
/compact压缩当前对话以释放上下文空间
/status查看当前状态（模型、认证、用量等）
/model切换使用的模型（Sonnet / Haiku / Opus）
/permissions管理权限白名单
/hooks管理钩子（Hooks）配置
/mcp管理 MCP 服务器连接
/bug向 Anthropic 报告 Bug
/review让 Claude 审查当前的代码改动
/install-github-app安装 GitHub App，实现自动 PR 审查

💡 输入 /help 可以看到所有命令，包括你自定义的命令和 MCP 服务器提供的命令。

8.2 模型切换

/model

Claude Code 支持三个模型层级：

模型特点适用场景
Sonnet速度和质量平衡最好日常编码、Bug 修复（默认）
Haiku最快、最省 token简单查询、格式化、代码搜索
Opus最强大、最聪明架构设计、复杂重构、多步推理

Pro 账户默认使用 Sonnet，用量达到 50% 后自动切换以节省额度。Max 账户可以更多地使用 Opus。

第九章：自定义斜杠命令

9.1 基本概念

自定义命令本质上就是保存为 Markdown 文件的提示词模板。当你输入 /命令名 时，Claude 会读取对应的 Markdown 文件作为提示。

命令存放位置：

位置作用范围
.claude/commands/命令名.md只在当前项目可用
~/.claude/commands/命令名.md在所有项目可用

9.2 实例：创建一个 /commit 命令

创建文件 .claude/commands/commit.md：

分析当前的 git diff，生成一条遵循 Conventional Commits 规范的提交信息。
 
规则：
1. 先运行 `git diff --staged` 查看暂存的改动
2. 如果没有暂存改动，运行 `git diff` 查看所有改动
3. 根据改动内容，选择合适的类型前缀：feat/fix/refactor/docs/test/chore
4. 提交信息用英文，简洁明了
5. 如果改动较大，添加详细描述body
6. 查看最近几条提交，匹配项目的提交风格
 
示例格式：
feat(auth): add OAuth2 login support
fix(api): handle null response in user endpoint

然后在 Claude Code 中直接输入：

/commit

9.3 实例：创建一个代码审查命令

创建文件 .claude/commands/code-review.md：

对 $ARGUMENTS 进行代码审查。
 
请检查以下方面：
1. **Bug 风险**：潜在的空指针、类型错误、边界条件
2. **安全问题**：SQL 注入、XSS、敏感信息泄露
3. **性能问题**：不必要的循环、内存泄漏、N+1 查询
4. **代码风格**：命名是否清晰、函数是否过长、是否有重复代码
5. **测试覆盖**：关键逻辑是否有测试
 
输出格式：
- 🔴 必须修复：严重问题
- 🟡 建议修改：改善建议
- 🟢 写得好的地方：值得肯定的部分
 
最后给出总体评价和改进优先级。

使用时：

/code-review @src/api/payment.ts

9.4 为命令指定模型和工具权限

在命令文件的头部可以添加 YAML 前置元数据（frontmatter）：

---
description: 运行安全漏洞扫描
allowed-tools: Read, Grep, Glob
model: claude-opus-4-6
---
 
分析代码库中的安全漏洞，包括：
- SQL 注入风险
- XSS 漏洞
- 暴露的凭据
- 不安全的配置
  • description：命令的描述，显示在 /help 中
  • allowed-tools：限制这个命令只能使用指定的工具（只读不写更安全）
  • model：强制使用特定模型来执行

9.6 更多命令创意

命令名功能
/push暂存、提交、推送一条龙
/lint运行 lint 并自动修复
/test运行测试，修复失败用例
/pr根据分支差异生成 PR 描述并创建
/branch 功能名按规范创建并切换到新分支
/doc为指定代码生成文档注释
/migrate生成数据库迁移
/translate 语言翻译文档到指定语言
/fix-pipeline获取 CI 失败日志并修复问题

第十章：子代理（Sub-agents）

10.1 什么是子代理？

在 Claude Code 中，有三种”代理”概念：

  1. Claude 本身：主代理，拥有所有工具，负责理解你的请求并协调工作
  2. 内置子代理（Task）：Claude 自动创建的通用子代理，用于分担子任务
  3. 自定义子代理：你定义的专门化代理，有特定的职责和工具限制

当你看到 Claude 使用 Task 工具时，那就是它在创建一个子代理。

10.2 为什么需要子代理？

  • 隔离上下文：每个子代理有自己独立的上下文窗口，不会污染主对话
  • 专门化：可以为特定领域创建专家型代理
  • 并行执行：Claude 可以同时派出多个子代理并行工作
  • 节省 token：子代理完成后只返回结果，过程信息不带回主对话

实际场景：当你让 Claude 翻译 25 篇文档时，它可能会自动创建 8 个子代理并行处理。

10.3 自定义子代理

在 .claude/agents/ 目录下创建 Markdown 文件来定义子代理：

.claude/agents/security-reviewer.md：

---
name: security-reviewer
description: 专注于代码安全审查的子代理
allowed-tools: Read, Grep, Glob
model: claude-opus-4-6
---
 
你是一个安全审查专家。你的职责是：
 
1. 审查提供的代码，找出安全漏洞
2. 检查 OWASP Top 10 中的常见问题
3. 检查依赖项是否有已知的安全漏洞
4. 给出修复建议
 
不要修改任何代码，只提供审查报告。
  • allowed-tools: Read, Grep, Glob — 这个代理只能读取代码，不能修改，更安全
  • model — 安全审查用更强的模型

当你对 Claude 说”审查这段代码的安全性”，它可能会调用这个子代理。

第十一章：技能（Skills）

11.1 技能 vs 斜杠命令

这两者的核心区别在于谁来决定使用：

特性斜杠命令技能（Skills）
触发方式你手动输入 /命令名Claude 自动判断是否需要
适合场景你明确知道要做什么时让 Claude 在合适时机自动应用
文件位置.claude/commands/.claude/skills/
调用者人类AI

11.2 创建一个技能

在 .claude/skills/ 目录下创建文件夹，每个技能是一个包含 SKILL.md 的文件夹：

.claude/skills/
└── api-design/
    └── SKILL.md

SKILL.md 示例：

---
name: api-design
description: 当用户要求设计或创建 REST API 端点时使用
---
 
# API 设计规范
 
当设计新的 API 端点时，遵循以下规范：
 
## URL 命名
- 使用复数名词：/users 而不是 /user
- 使用 kebab-case：/user-profiles 而不是 /userProfiles
- 嵌套不超过两层：/users/:id/orders
 
## 响应格式
所有响应使用统一的 JSON 格式：
{
  "success": true,
  "data": {},
  "message": "操作成功"
}
 
## 必须包含
- 输入验证（使用 zod）
- 速率限制
- 认证中间件
- 请求日志
- 单元测试

当你说”帮我创建一个用户管理的 API”时，Claude 会自动发现并应用这个技能——你不需要手动告诉它。

11.3 技能的层级

和命令类似，技能也有项目级和全局级：

位置范围
.claude/skills/当前项目
~/.claude/skills/所有项目

第十二章：钩子（Hooks）

12.1 什么是钩子？

钩子是在 Claude 执行特定操作之前或之后自动运行的脚本。类似于 Git Hooks，但作用于 Claude 的操作。它让你可以在 Claude 的工作流程中”插入”自动化步骤。

12.2 钩子类型

钩子触发时机典型用途
PreToolUse在 Claude 使用工具之前预检查、拦截不安全操作
PostToolUse在 Claude 使用工具之后自动格式化、自动检查
Notification当 Claude 需要你注意时发送通知到手机
Stop当 Claude 完成任务时自动运行验证脚本

12.3 配置钩子

在 .claude/settings.json 中配置：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write(*.py)",
        "hooks": [
          {
            "type": "command",
            "command": "python -m black $file"
          }
        ]
      },
      {
        "matcher": "Write(*.ts)",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $file"
          }
        ]
      },
      {
        "matcher": "Write(*.{js,ts,jsx,tsx})",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --fix $file"
          }
        ]
      }
    ]
  }
}

上面的配置效果：

  • Claude 每次写入 .py 文件 → 自动运行 Black 代码格式化
  • Claude 每次写入 .ts 文件 → 自动运行 Prettier 格式化
  • Claude 每次写入 JS/TS 文件 → 自动运行 ESLint 修复

12.4 交互式配置

如果你觉得手动编辑 JSON 麻烦，可以使用交互式菜单：

/hooks

Claude Code 会引导你一步步配置钩子。

12.5 让 Claude 帮你配置

你甚至可以让 Claude 本身来帮你设置钩子：

帮我配置一些钩子：
1. 写 Python 文件后自动运行 black 格式化
2. 写 TypeScript 文件后自动运行类型检查
3. 任何文件写入后自动运行对应的 lint

Claude 会查看你的项目，然后帮你生成合适的配置。

第十三章：MCP 服务器集成

13.1 什么是 MCP？

MCP（Model Context Protocol，模型上下文协议）是一个标准化的协议，让 Claude Code 能够连接外部工具和数据源。你可以把 MCP 想象成 Claude 的”USB 接口”——通过它可以插入各种外部能力。

13.2 MCP 能做什么？

通过配置 MCP 服务器，Claude Code 可以扩展能力：

  • 搜索并操作你的 Google Drive 文件
  • 读取和发送 Slack 消息
  • 查询数据库（PostgreSQL、SQLite 等）
  • 访问 Jira/Linear 等项目管理工具
  • 搜索网页
  • 操作 GitHub 的 Issue 和 PR
  • 连接浏览器自动化工具
  • …基本上任何有 MCP 服务器的工具

13.3 配置 MCP 服务器

在 .claude/settings.json 中添加 MCP 配置：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

13.4 在交互模式中管理 MCP

/mcp

这个命令会打开一个管理界面，让你启用/禁用服务器、重新连接、管理 OAuth 认证等。

13.5 常用 MCP 服务器

服务器功能
@modelcontextprotocol/server-githubGitHub 操作
@modelcontextprotocol/server-filesystem文件系统访问
@modelcontextprotocol/server-slackSlack 消息
@modelcontextprotocol/server-postgresPostgreSQL 查询
@modelcontextprotocol/server-sqliteSQLite 查询
@anthropic-ai/claude-code-chromeChrome 浏览器自动化

更多 MCP 服务器可以在 GitHub MCP servers 仓库 中找到。

第十四章：Git 工作流

14.1 基本 Git 操作

Claude Code 可以直接处理所有 Git 操作：

看看当前有哪些改动

把当前改动提交，用有意义的提交信息

创建一个新分支 feature/user-auth，并切换过去

根据这个分支的所有提交，创建一个 PR 到 main 分支

14.2 自动化 PR 审查

运行 /install-github-app 可以安装 Claude 的 GitHub App。安装后，每当团队成员发起 PR，Claude 会自动审查代码并留下评论。

你可以通过项目中的 .github/claude-code-review.yml 文件来自定义审查提示词——默认的审查可能太啰嗦，建议根据团队需要调整。

14.3 处理合并冲突

解决当前的合并冲突，保留我们分支的业务逻辑，但使用 main 分支的基础设施代码

Claude 会理解冲突的上下文，智能地合并代码。

14.4 Git 工作流最佳实践

  1. 用 Claude 写提交信息：Claude 分析 diff 后写出的提交信息通常比手写的更准确、更规范
  2. 用 Claude 做 PR 描述：Claude 可以总结所有变更并生成结构化的 PR 描述
  3. 让 Claude 帮你 rebase：交互式 rebase 可能很复杂，Claude 可以代劳
  4. 代码审查前先自审：让 Claude 在你提交 PR 前先审查一遍，避免低级错误
  5. 用 Claude 写 release notes：根据版本间的提交记录自动生成发布说明

第十五章：IDE 集成

15.1 VS Code 扩展

在 VS Code 的扩展商店中搜索 “Claude Code” 并安装。

安装后，按 Cmd+Shift+P（Mac）或 Ctrl+Shift+P（Win/Linux），搜索 “Claude Code”，选择 “Open in New Tab”。

VS Code 扩展提供的额外功能：

  • 内联 diff 预览：直接在编辑器中看到 Claude 要做的代码改动
  • @ 提及文件：在聊天中引用当前打开的文件和选中的代码
  • 计划审查：在编辑器中查看和评论 Claude 的执行计划
  • 对话历史：查看过往的对话记录
  • 用量提示：在状态栏显示用量百分比和重置时间
  • MCP 管理：直接在编辑器中管理 MCP 服务器，无需切到终端
  • 多会话管理：在侧边栏查看所有 Claude Code 会话

15.2 JetBrains IDE 插件

支持 IntelliJ IDEA、PyCharm、WebStorm 等 JetBrains 全家桶。

从 JetBrains Marketplace 安装 “Claude Code” 插件，重启 IDE 即可使用。提供交互式 diff 查看和选中代码上下文共享功能。

15.3 桌面应用

Anthropic 提供了 Claude Code 桌面应用（Desktop App），这是一个独立的应用程序，支持：

  • 可视化 diff 审查
  • 多会话并行运行
  • 定时任务调度
  • 云端会话（Cloud Sessions）

安装后登录你的 Anthropic 账户，切换到 Code 标签即可使用。

15.4 Web 端使用

访问 claude.ai/code 可以在浏览器中使用 Claude Code，无需本地安装。适合：

  • 在不是自己电脑上临时使用
  • 启动耗时较长的任务后离开查看
  • 处理本地没有克隆的仓库
  • 在 iOS Claude 应用上使用

第十六章：实战案例

16.1 案例一：为现有项目添加测试

看看 src/services/ 目录下的所有服务文件。
找出没有对应测试文件的服务。
然后为每个文件编写单元测试，使用 Vitest 框架。
写完后运行 npm test，修复所有失败的测试。
确保覆盖率达到 80% 以上。

16.2 案例二：修复生产环境 Bug

用户报告登录后偶尔会被踢出登录状态。
请检查 src/auth/ 目录下的所有文件，特别关注：
1. Token 刷新逻辑
2. Session 过期处理
3. 并发请求时的竞态条件
4. Cookie 的 domain 和 path 配置
找到问题后修复，并添加回归测试防止问题复发。

16.3 案例三：新项目初始化

初始化一个新的 React + TypeScript 项目，使用 Vite 构建。要求：
1. 配置 ESLint + Prettier（使用最新的 flat config）
2. 配置 Vitest 作为测试框架
3. 设置 Tailwind CSS v4
4. 创建规范的目录结构（components, hooks, utils, types, services）
5. 添加 .gitignore 和 .editorconfig
6. 配置 husky + lint-staged 做提交前检查
7. 创建一个简单的页面确认一切正常运行
8. 初始化 git 并做第一次提交

16.4 案例四：代码迁移

把这个项目从 Express.js 迁移到 Fastify。要求：
1. 先列出所有需要迁移的路由和中间件
2. 保持所有 API 端点的路径和行为不变
3. 迁移所有中间件到 Fastify 插件
4. 更新测试文件
5. 每完成一个路由就运行测试确认，确保增量迁移不会破坏现有功能
6. 最后做一个全量测试确认

16.5 案例五：性能优化

这个页面加载很慢。请帮我：
1. 分析 src/pages/Dashboard.tsx 和它引用的所有组件
2. 找出性能瓶颈（不必要的重渲染、大数据量处理、图片未优化等）
3. 实施优化方案
4. 添加 React.memo、useMemo、useCallback 等必要的性能优化
5. 确保优化后功能不变（运行测试验证）

16.6 案例六：文档自动化

扫描 src/api/ 目录下的所有 API 路由文件。
为每个端点生成 OpenAPI (Swagger) 文档。
包含请求参数、响应格式、状态码说明和示例。
输出到 docs/api.yaml 文件。

第十七章：进阶技巧与最佳实践

17.1 给 Claude 提供验证方式

这是最重要的一条实践：告诉 Claude 如何验证自己的工作。

❌ 不好的做法：

给 API 添加分页功能

✅ 好的做法：

给 /api/users 端点添加分页功能。
完成后：
1. 运行 npm test 确认所有现有测试通过
2. 为分页功能添加新的测试
3. 用 curl 测试新的分页参数：
   curl http://localhost:3000/api/users?page=1&limit=10
4. 确认返回的 JSON 包含 pagination 对象

当 Claude 能自己运行测试、看到结果，它就会进入一个自我修复的循环——写代码→运行测试→发现问题→修复→再测试→通过。

17.2 分步给出复杂任务

对于大型任务，不要一次全部塞给 Claude。分步进行，每步确认后再继续：

第一步：先分析现有的认证系统架构，画个图告诉我你的理解。

（确认理解正确后）

第二步：设计 OAuth2 集成方案，不要写代码，只写方案文档。

（确认方案后）

第三步：开始实现。先从 Google OAuth 登录开始，完成后运行测试。

17.3 使用非交互模式自动化

结合 shell alias，创建你的自动化快捷键：

# 添加到 ~/.zshrc 或 ~/.bashrc
 
alias clint="claude -p '/lint'"
alias cpush="claude -p '/push'"
alias ccommit="claude -p '/commit'"
alias creview="claude -p '/review'"
alias cbranch="claude -p '/branch'"

之后在终端中直接运行 ccommit 就能自动生成提交信息并提交——连 Claude Code 交互界面都不需要打开。

17.4 多实例并行

你可以在不同的终端窗口打开多个 Claude Code 实例，分别处理不同的任务：

  • 终端 1：Claude 在写测试
  • 终端 2：Claude 在修复 Bug
  • 终端 3：Claude 在更新文档

使用 Git worktrees 可以让多个实例在同一仓库的不同分支上工作而不冲突：

# 创建工作树
git worktree add ../feature-auth feature/auth
git worktree add ../fix-bug fix/login-bug
 
# 分别在不同目录启动 Claude Code
cd ../feature-auth && claude
cd ../fix-bug && claude

17.5 有效的提示词编写

具体 > 模糊：

  • ❌ “改善代码质量”
  • ✅ “把 UserService 中超过 50 行的方法拆分成更小的方法，每个方法只做一件事”

提供上下文：

  • ❌ “修复 Bug”
  • ✅ “用户在 Safari 浏览器上点击支付按钮后页面白屏，控制台报错 ReferenceError: structuredClone is not defined”

说明约束：

  • ❌ “添加搜索功能”
  • ✅ “添加用户搜索功能，使用现有的 Prisma 全文搜索，不引入 Elasticsearch，兼容现有的分页组件”

说明不要做什么：

  • ✅ “重构这个文件，但不要改变公开的 API 接口，不要修改测试文件”

17.6 选择合适的模型

任务类型推荐模型原因
日常编码、Bug 修复Sonnet（默认）速度快，质量好
简单查询、代码搜索Haiku最快最省
架构设计、复杂重构Opus推理能力最强
长时间运行的任务Sonnet更省 token
安全审查Opus需要深度分析

使用 /model 切换模型，在任务需要时灵活调整。

17.7 利用 Remote Control

Claude Code 支持远程控制功能——在终端启动任务后，可以在手机上的 Claude 应用中监控和管理。适合需要长时间运行的任务。

/remote-control "重构项目"

第十八章：常见问题排查

18.1 安装问题

问题：claude 命令找不到

# 第一步：关闭终端，重新打开
# 第二步：检查 PATH
which claude
 
# 第三步：如果还找不到，手动 source 配置文件
source ~/.zshrc  # 如果你用 zsh
source ~/.bashrc # 如果你用 bash

问题：npm 权限错误

不要使用 sudo npm install -g！正确做法是使用 nvm：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
# 安装并使用 Node.js 18
nvm install 18
nvm use 18
# 然后再安装（如果你选择 npm 方式的话）
npm install -g @anthropic-ai/claude-code

但更好的方案是直接用原生安装器，根本不需要 Node.js。

问题：Windows 上 Git Bash 找不到

在 ~/.claude/settings.json 中手动指定路径：

{
  "bashPath": "C:\\Program Files\\Git\\bin\\bash.exe"
}

问题：WinGet 安装后 claude 命令不可用

关闭所有终端窗口并重新打开。如果还不行，重启电脑（Windows 有时需要重启来注册 PATH 变更）。

18.2 使用问题

问题：Claude 的回答质量变差了

这通常是上下文被污染或过长了。解决方案：

  1. 运行 /compact 压缩上下文
  2. 如果还没改善，运行 /clear 完全清除，重新开始
  3. 检查你的 CLAUDE.md 是否过时或过长

问题：Claude 执行了错误的操作

  1. 按 Ctrl+C 立即中断
  2. 用 git diff 检查 Claude 做了哪些改动
  3. 用 git checkout -- . 撤销所有改动（如果需要）
  4. 或者用 git stash 暂存改动以备后用

问题：额度用完了（Rate Limited）

  • Pro 账户的额度每 5 小时重置一次，还有每周的总额度上限
  • 切换到 Haiku 模型可以节省额度
  • 使用 /compact 减少上下文大小
  • 如果经常不够用，考虑升级到 Max 5x（200/月）

问题：网络连接问题

# 检查状态
/status
 
# 重新认证
claude auth login
 
# 如果使用代理，确保环境变量正确
export HTTPS_PROXY=http://your-proxy:port

18.3 性能问题

问题：Claude 反应很慢

  • 运行 /compact 压缩上下文
  • 切换到更快的模型（/model → Haiku）
  • 确保网络连接稳定
  • 任务之间用 /clear 清理

问题：大项目中 Claude 表现不佳

  • 在 CLAUDE.md 中精确描述项目结构，让 Claude 不需要猜测
  • 把大任务拆分成小任务
  • 使用 @ 精确引用相关文件，避免 Claude 浪费时间搜索整个项目
  • 使用子代理处理独立的子任务

问题：Claude 不遵循 CLAUDE.md 中的规范

  • 检查 CLAUDE.md 是否太长（建议 200 行以内）
  • 把最重要的规则放在文件开头
  • 用更明确、具体的措辞
  • 在提示中直接提醒：“请按照 CLAUDE.md 中的规范来”

18.4 诊断工具

# 运行诊断
claude doctor
 
# 查看详细状态
/status
 
# 报告 Bug
/bug

附录：速查表

启动与退出

claude                              # 进入交互模式
claude -p "任务描述"                  # 非交互模式（单次执行）
claude --resume                     # 恢复上一次会话
claude --dangerously-skip-permissions  # 跳过权限确认
claude --version                    # 查看版本
claude update                       # 更新到最新版
claude uninstall                    # 卸载
claude doctor                       # 运行诊断
claude auth login                   # 重新认证
Ctrl+C                              # 中断当前操作
Ctrl+D                              # 退出 Claude Code

交互模式快捷键

Shift+Tab       计划模式（只分析不执行）
Tab             切回正常模式
!命令           直接执行 shell 命令
@文件路径       引用文件
↑               上一条消息
Escape          取消输入 / 中断操作

内置斜杠命令

/help           查看所有命令
/init           生成 CLAUDE.md
/clear          清除对话
/compact        压缩上下文
/status         查看状态
/model          切换模型
/permissions    管理权限
/hooks          管理钩子
/mcp            管理 MCP 服务器
/bug            报告 Bug
/review         审查代码改动

文件与目录结构

~/.claude/                          # Claude Code 全局配置目录
├── settings.json                   # 全局设置
├── CLAUDE.md                       # 全局项目说明
├── commands/                       # 全局自定义命令
│   └── commit.md
└── skills/                         # 全局技能
    └── my-skill/
        └── SKILL.md

项目根目录/
├── CLAUDE.md                       # 项目说明书（团队共享）
├── CLAUDE.local.md                 # 个人偏好（不提交 Git）
└── .claude/
    ├── settings.json               # 项目设置
    ├── commands/                    # 项目自定义命令
    │   └── review.md
    ├── skills/                     # 项目技能
    │   └── api-design/
    │       └── SKILL.md
    └── agents/                     # 项目子代理
        └── security-reviewer.md

安装命令速查

# macOS / Linux（推荐）
curl -fsSL https://claude.ai/install.sh | bash
 
# macOS Homebrew
brew install --cask claude-code
 
# Windows PowerShell（推荐）
irm https://claude.ai/install.ps1 | iex
 
# Windows WinGet
winget install Anthropic.ClaudeCode
 
# 更新
claude update                           # 原生安装（通常自动更新）
brew upgrade claude-code                # Homebrew
winget upgrade Anthropic.ClaudeCode     # WinGet
 
# 卸载
claude uninstall                        # 原生安装
brew uninstall claude-code              # Homebrew
winget uninstall Anthropic.ClaudeCode   # WinGet

环境变量

ANTHROPIC_API_KEY=sk-ant-...           # API Key（替代 OAuth 认证）
CLAUDE_CODE_USE_BEDROCK=1              # 使用 Amazon Bedrock
CLAUDE_CODE_USE_VERTEX=1               # 使用 Google Vertex AI
AWS_REGION=us-east-1                   # Bedrock 区域
CLOUD_ML_REGION=us-central1            # Vertex 区域

延伸资源

  • 官方文档：code.claude.com/docs
  • GitHub 仓库：github.com/anthropics/claude-code
  • CLI 参考：code.claude.com/docs/en/cli-reference
  • Discord 社区：Claude Developers Discord
  • 更新日志：GitHub Releases
  • Reddit 社区：r/ClaudeAI

关系图谱