claude-code-best-practice 使用教程
本教程将引导你从零开始掌握 claude-code-best-practice 项目，涵盖 Claude Code 的核心概念（子代理、命令、技能、工作流、钩子、MCP 服务器、插件、设置、记忆、检查点等）以及最佳实践。通过循序渐进的学习，你将能够高效配置和扩展 Claude Code，实现从“氛围编码”到“代理工程”的进阶。
1. 项目简介与适用人群
项目简介与适用人群
项目定位
claude-code-best-practice 是一个实战驱动的 Claude Code 最佳实践集合。它的核心理念是：
从“氛围编码”（vibe coding）走向“智能体工程”（agentic engineering）——实践让 Claude 更完美。
简单来说，这个项目不是一份枯燥的官方文档翻译，而是一套可下载、可运行、可直接复用的配置模板与示例代码库。它涵盖了 Claude Code 的几乎所有核心功能，包括子代理、命令、技能、工作流、钩子、MCP 服务器、插件、记忆系统、检查点等，并提供了经过验证的最佳实践。
项目结构概览
当你克隆或下载该项目后，会看到以下关键目录结构：
claude-code-best-practice/
├── .claude/ # Claude Code 配置目录
│ ├── agents/ # 子代理定义
│ ├── commands/ # 斜杠命令
│ ├── skills/ # 技能包
│ ├── hooks/ # 钩子脚本
│ ├── settings.json # 全局设置
│ └── rules/ # 自定义规则
├── reports/ # 深度分析报告
├── best-practice/ # 最佳实践文档
└── CLAUDE.md # 项目级记忆文件每个目录都对应 Claude Code 的一个核心扩展机制，后续章节会逐一详解。
适用人群
这个项目适合以下三类开发者：
| 人群 | 典型场景 | 能获得什么 |
|---|---|---|
| Claude Code 新手 | 刚接触 Claude Code，想快速上手并避免踩坑 | 完整的配置模板、开箱即用的示例、常见问题解答 |
| 中级用户 | 已经会用基本功能，但想提升效率、实现自动化工作流 | 子代理编排、钩子自动化、MCP 服务器集成等进阶技巧 |
| 团队/项目负责人 | 需要在团队内推广 Claude Code 使用规范 | 标准化的 .claude/ 目录结构、权限配置、记忆系统最佳实践 |
核心功能一览
下表列出了本项目覆盖的所有 Claude Code 功能及其在仓库中的位置：
| 功能 | 配置位置 | 说明 |
|---|---|---|
| 子代理 | .claude/agents/<name>.md |
定义专用 AI 助手，如代码审查代理、测试生成代理 |
| 命令 | .claude/commands/<name>.md |
自定义斜杠命令，如 /review、/test |
| 技能 | .claude/skills/<name>/SKILL.md |
可复用的能力包，支持官方技能和社区技能 |
| 工作流 | .claude/commands/ 中的编排命令 |
多步骤自动化流程，如天气查询编排器 |
| 钩子 | .claude/hooks/ |
在特定事件（如文件保存、命令执行前后）触发的脚本 |
| MCP 服务器 | .claude/settings.json、.mcp.json |
通过 Model Context Protocol 连接外部工具和数据源 |
| 插件 | 可分发包 | 封装好的功能模块，可从插件市场安装 |
| 设置 | .claude/settings.json |
权限、模型配置、输出样式、沙箱、快捷键等 |
| 状态栏 | .claude/settings.json |
自定义终端状态栏显示内容 |
| 记忆 | CLAUDE.md、.claude/rules/、~/.claude/rules/ |
持久化上下文和项目规则 |
| 检查点 | 自动（文件编辑追踪） | 自动保存操作历史，支持回滚 |
热特性（Beta）
项目还收录了 Claude Code 的最新 Beta 功能：
- Ultrareview (
/code-review ultra) — 超深度代码审查，支持任务追踪 - Ultraplan (
/ultraplan) — 高级规划能力 - Devcontainers (
.devcontainer/) — 开发容器支持 - Channels (
--channels) — 多通道通信 - No Flicker Mode (
/tui fullscreen) — 无闪烁全屏模式 - Auto Mode (
--permission-mode auto) — 自动权限模式，减少确认提示 - Power-ups (
/powerup) — 增强功能包
如何开始使用
克隆仓库：
git clone https://github.com/shanraisshan/claude-code-best-practice.git cd claude-code-best-practice查看目录结构，了解各功能模块的存放位置。
阅读下一章「安装与环境准备」，完成 Claude Code 的安装和基础配置。
按需使用：你可以直接复制
.claude/目录中的配置文件到自己的项目中，也可以参考示例代码学习如何编写自己的子代理、命令和技能。
注意事项
- 本项目假设你已经拥有 Claude Code 的访问权限（需要 Anthropic 账户）。
- 部分 Beta 功能可能需要更新到最新版本的 Claude Code 才能使用。
- 项目中的配置和示例基于 Claude Code 的最新稳定版本，如果遇到兼容性问题，请检查版本号。
准备好开始了吗？进入下一章，我们将完成安装与环境配置。
2. 安装与环境准备
安装与环境准备
本章将指导你完成 Claude Code 的安装和基础环境配置，确保你能够顺利启动第一个会话。
系统要求
在开始安装之前，请确认你的系统满足以下要求：
- 操作系统：macOS 10.15+ 或 Linux（Ubuntu 20.04+ / Debian 11+ / CentOS 8+）
- Node.js：版本 18.0.0 或更高
- npm：版本 9.0.0 或更高
- 终端：支持 Unicode 和 256 色（推荐 iTerm2、Terminal.app、Windows Terminal 等）
- 网络：能够访问
code.claude.com和 Anthropic API
注意：Windows 用户可以通过 WSL2（Windows Subsystem for Linux）运行 Claude Code，但不支持原生 Windows 环境。
步骤 1：安装 Node.js 和 npm
如果你尚未安装 Node.js 和 npm，请按以下方式安装：
macOS（使用 Homebrew）：
brew install nodeLinux（Ubuntu/Debian）：
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs验证安装：
node --version
npm --version预期输出类似：
v20.11.0
10.2.4步骤 2：安装 Claude Code
使用 npm 全局安装 Claude Code CLI：
npm install -g @anthropic-ai/claude-code安装完成后，验证是否成功：
claude --version如果看到版本号输出（例如 0.1.0），说明安装成功。
注意：如果遇到权限错误，可以尝试使用
sudo（macOS/Linux）或使用 nvm 管理 Node.js 版本。
步骤 3：获取并配置 API 密钥
Claude Code 需要 Anthropic API 密钥才能工作。请按以下步骤操作：
- 访问 Anthropic Console 并登录或注册账号。
- 在控制台中生成一个 API 密钥（API Key）。
- 将密钥设置为环境变量：
export ANTHROPIC_API_KEY="sk-ant-你的密钥"为了持久化配置，将上述命令添加到你的 shell 配置文件中（例如 ~/.zshrc、~/.bashrc 或 ~/.bash_profile）：
echo 'export ANTHROPIC_API_KEY="sk-ant-你的密钥"' >> ~/.zshrc
source ~/.zshrc安全提示：切勿将 API 密钥提交到版本控制系统。建议使用环境变量或
.env文件（并确保.env被.gitignore忽略）。
步骤 4：验证安装与连接
创建一个临时目录并启动 Claude Code 来验证一切正常：
mkdir ~/claude-test
cd ~/claude-test
claude首次启动时，Claude Code 会进行以下操作：
- 检查 API 密钥是否有效
- 下载必要的依赖
- 显示欢迎信息
如果看到类似以下输出，说明安装成功：
Claude Code 0.1.0
Type /help for available commands
>输入 /exit 退出当前会话。
步骤 5：初始化项目配置（可选但推荐）
在你的实际项目目录中初始化 Claude Code 配置：
cd /path/to/your/project
claude init此命令会在项目根目录创建 .claude/ 文件夹，包含默认的配置文件结构：
.claude/
├── agents/
├── commands/
├── hooks/
├── rules/
├── skills/
└── settings.json说明：
claude init是可选的，但强烈推荐。它为你后续使用子代理、命令、技能等高级功能奠定了基础。
步骤 6：配置编辑器集成（可选）
Claude Code 可以与主流编辑器集成，提供更流畅的开发体验：
VS Code 集成：
在 VS Code 中安装 Claude Code 扩展（在扩展市场搜索 "Claude Code"），然后通过命令面板（Cmd+Shift+P）运行 Claude Code: Start Session。
Neovim 集成：
安装 claude-code.nvim 插件（通过你喜欢的插件管理器），然后在 Neovim 中运行 :ClaudeCode。
常见安装问题
问题 1：安装时出现 EACCES 错误
npm ERR! code EACCES
npm ERR! syscall mkdir解决方案：使用 nvm 管理 Node.js 版本，或使用 sudo 安装：
sudo npm install -g @anthropic-ai/claude-code问题 2：启动时提示 "API key not found"
解决方案：确认 ANTHROPIC_API_KEY 环境变量已正确设置：
echo $ANTHROPIC_API_KEY如果输出为空，请重新执行步骤 3 中的 export 命令。
问题 3：启动时提示 "Network error"
解决方案：检查网络连接和防火墙设置，确保可以访问 api.anthropic.com。如果你使用代理，请设置：
export HTTP_PROXY="http://你的代理地址:端口"
export HTTPS_PROXY="http://你的代理地址:端口"环境检查清单
在继续下一章之前，请确认以下项目全部完成：
- Node.js 版本 ≥ 18.0.0
- npm 版本 ≥ 9.0.0
-
claude --version输出版本号 -
ANTHROPIC_API_KEY环境变量已设置 -
claude命令可以正常启动并显示提示符 - （可选）项目目录已运行
claude init
安装完成后，你已经准备好进入下一章：快速上手：第一个 Claude Code 会话，在那里你将学习如何与 Claude Code 进行第一次交互。
3. 快速上手：第一个 Claude Code 会话
快速上手：第一个 Claude Code 会话
本章将引导你完成从零开始的第一个 Claude Code 会话。你将学会如何启动 Claude Code、执行基本命令、理解交互模式，并完成一个简单的开发任务。
3.1 启动 Claude Code
确保你已经按照第 2 章的步骤完成了安装和 API 密钥配置。现在，打开终端并进入你的项目目录：
cd /path/to/your/project在项目根目录下启动 Claude Code：
claude首次启动时，Claude Code 会显示欢迎信息并询问你是否要创建 CLAUDE.md 文件（用于项目记忆）。建议选择“是”，后续章节会详细介绍记忆功能。
启动成功后，你会看到类似如下的提示符：
Claude Code (v0.x.x) — 正在加载...
> 现在你已经进入了 Claude Code 的交互式会话。
3.2 理解交互界面
Claude Code 的交互界面包含几个关键区域：
- 状态行：顶部显示当前模式、使用的模型、项目名称等信息
- 对话区域：显示 Claude 的回复和操作日志
- 输入提示符：底部的
>符号，等待你输入指令
基本交互方式：
| 操作 | 说明 |
|---|---|
| 输入自然语言指令 | 直接描述你想做的事情 |
输入 / 命令 |
使用斜杠命令执行特定操作 |
Ctrl+C |
中断当前操作 |
Ctrl+D |
退出 Claude Code |
| 方向键上下 | 浏览历史命令 |
3.3 执行第一个命令
让我们从最简单的命令开始。在 > 提示符后输入：
/helpClaude Code 会显示所有可用的斜杠命令列表。这是你探索功能的好起点。
接下来，尝试询问 Claude 关于当前项目的信息：
这个项目是做什么的？请分析项目结构。Claude 会自动读取项目文件并给出分析结果。你会看到它列出文件、读取内容、然后生成回答。
3.4 完成一个实际任务
让我们通过一个具体任务来体验 Claude Code 的工作流程。假设你有一个空的 Python 项目，想要创建一个简单的 Web 服务器。
在 Claude Code 提示符中输入：
请帮我创建一个简单的 Python Flask Web 服务器，包含一个返回 "Hello, Claude Code!" 的路由。同时创建一个 requirements.txt 文件。Claude Code 会：
- 分析当前项目结构
- 创建
app.py文件 - 创建
requirements.txt文件 - 显示创建的文件内容
- 询问你是否需要安装依赖
你会看到类似这样的输出：
让我为你创建这个项目。
首先创建 app.py：
```python
from flask import Flask
app = Flask(__name__)
@app.route('/')
def hello():
return "Hello, Claude Code!"
if __name__ == '__main__':
app.run(debug=True)然后创建 requirements.txt：
flask==3.0.0文件已创建。是否需要我安装依赖并启动服务器？
输入 `yes` 或 `y` 确认安装依赖：
y
Claude Code 会自动执行 `pip install -r requirements.txt`。安装完成后，它会询问是否要启动服务器。
### 3.5 使用文件编辑功能
Claude Code 可以直接修改项目文件。让我们修改刚才创建的服务器：
请修改 app.py，添加一个 /about 路由，返回 JSON 格式的信息：{"app": "My Flask App", "version": "1.0"}
Claude Code 会读取当前文件内容，进行修改，并显示 diff 差异：
我将修改 app.py 添加 /about 路由。
修改前： from flask import Flask
修改后： from flask import Flask, jsonify
新增路由： @app.route('/about') def about(): return jsonify({"app": "My Flask App", "version": "1.0"})
是否应用这些修改？ (y/n)
输入 `y` 确认修改。Claude Code 会直接写入文件。
### 3.6 使用斜杠命令
斜杠命令是 Claude Code 的核心功能之一。尝试以下常用命令：
/status
显示当前会话状态、已修改的文件列表。
/clear
清除对话历史，开始新的会话上下文。
/compact
压缩对话历史，保留关键上下文但减少 token 消耗。
### 3.7 理解权限模式
Claude Code 默认使用交互式权限模式。当你执行需要文件写入、命令执行等操作时，它会请求你的确认：
Claude 想要执行命令：pip install flask 是否允许？ (y/n/a/s)
选项说明：
- `y`：允许本次操作
- `n`：拒绝本次操作
- `a`：始终允许（当前会话内不再询问）
- `s`：跳过本次操作
### 3.8 退出与重新进入会话
完成工作后，退出 Claude Code：
Ctrl+D
或者输入：
/exit
下次进入项目时，Claude Code 会读取 `CLAUDE.md` 和项目文件，恢复上下文。但注意，对话历史不会自动保存——除非你使用了检查点功能（见第 8 章）。
### 3.9 常见问题与排查
**问题：启动后提示“未找到 API 密钥”**
确保已设置环境变量：
```bash
export ANTHROPIC_API_KEY="your-api-key-here"或者创建 .env 文件。
问题：命令执行超时
Claude Code 默认有执行超时限制。对于耗时操作，可以：
- 拆分成多个小步骤
- 使用
--timeout标志（见第 9 章）
问题：文件修改被拒绝
检查文件权限，或使用 sudo 启动 Claude Code（不推荐，建议修改目录权限）。
3.10 下一步
恭喜！你已经完成了第一个 Claude Code 会话。接下来建议：
- 阅读第 4 章，深入了解子代理和命令系统
- 尝试创建自己的
.claude/commands/自定义命令 - 探索第 5 章的技能和工作流功能
记住，Claude Code 的最佳实践是：先描述目标，再逐步细化。不要一次性给出过于复杂的指令，而是让 Claude 理解你的意图后，通过对话逐步完善。
4. 核心功能详解（一）：子代理与命令
4. 核心功能详解（一）：子代理与命令
本章深入讲解 Claude Code 的两个基础扩展机制：子代理（Subagents） 和 命令（Commands）。它们是构建可复用、专业化工作流的核心构件。
4.1 子代理（Subagents）
子代理本质上是预定义角色的专用 AI 助手。你可以为特定任务（如代码审查、数据库设计、安全审计）创建一个子代理，然后在会话中随时调用它，让 Claude Code 以该角色的身份和知识库来工作。
4.1.1 子代理文件结构
每个子代理对应一个 Markdown 文件，存放在项目根目录下的 .claude/agents/ 文件夹中。
你的项目/
└── .claude/
└── agents/
├── code-reviewer.md
├── sql-designer.md
└── security-auditor.md4.1.2 创建子代理
创建一个子代理文件，例如 .claude/agents/code-reviewer.md：
# Code Reviewer
你是资深代码审查专家，专注于发现代码中的潜在缺陷、安全漏洞和性能问题。
## 审查原则
1. 先理解整体架构，再深入细节
2. 对每个发现的问题，给出严重等级（Critical / Major / Minor / Info）
3. 每个问题必须附带具体的改进建议和代码示例
4. 关注可读性、可维护性和测试覆盖率
## 输出格式
使用以下格式报告问题：
### [严重等级] 问题描述
- **文件**: `path/to/file.ts:行号`
- **原因**: 简要说明为什么这是个问题
- **建议**:
```typescript
// 改进后的代码
#### 4.1.3 调用子代理
在 Claude Code 会话中，使用 `@` 符号后跟子代理文件名（不含 `.md` 扩展名）来激活它：
@code-reviewer 请审查 src/services/user-service.ts 这个文件
Claude Code 会加载 `code-reviewer.md` 中的角色定义，然后以该角色身份执行任务。
**注意事项：**
- 子代理文件名必须唯一，且不能包含空格（建议使用连字符 `-`）
- 子代理只在当前会话中生效，不会影响其他会话
- 你可以同时调用多个子代理，但建议一次只激活一个以避免角色冲突
#### 4.1.4 子代理最佳实践
1. **角色定位要精准**：子代理的角色描述越具体，输出质量越高。避免过于宽泛的描述。
2. **提供示例输出**：在子代理文件中包含输出格式示例，有助于获得结构化的结果。
3. **包含约束条件**：明确告诉子代理什么能做、什么不能做，避免它偏离任务。
4. **版本管理**：将 `.claude/agents/` 目录纳入 Git 版本控制，方便团队共享。
### 4.2 命令（Commands）
命令是**可复用的斜杠指令**，允许你通过 `/command_name` 的方式快速执行预定义的任务。命令比子代理更轻量，适合执行固定的操作序列。
#### 4.2.1 命令文件结构
每个命令对应一个 Markdown 文件，存放在项目根目录下的 `.claude/commands/` 文件夹中。
你的项目/ └── .claude/ └── commands/ ├── test.md ├── lint.md └── deploy.md
#### 4.2.2 创建命令
创建一个命令文件，例如 `.claude/commands/test.md`：
```markdown
# Test
运行项目的单元测试和集成测试。
## 步骤
1. 检查 `package.json` 中的测试脚本配置
2. 运行 `npm test` 执行单元测试
3. 如果存在 `tests/integration/` 目录，运行 `npm run test:integration`
4. 汇总测试结果，列出失败的测试用例及其错误信息
## 输出
- 测试通过率
- 失败的测试用例列表（如果有）
- 代码覆盖率摘要（如果可用）4.2.3 调用命令
在 Claude Code 会话中，直接输入 / 后跟命令文件名（不含 .md 扩展名）：
/testClaude Code 会读取 test.md 中的指令，并按照定义的步骤执行。
注意事项：
- 命令名称必须唯一，不能与内置命令（如
/help、/clear）冲突 - 命令文件中的步骤是指导性的，Claude Code 会根据实际情况灵活执行
- 命令可以包含代码块，Claude Code 会尝试执行其中的命令
4.2.4 命令进阶：带参数的命令
你可以在命令文件中使用 {{placeholder}} 语法定义参数：
# Deploy
部署应用到 {{environment}} 环境。
## 步骤
1. 确认当前分支是 `main` 或 `release/{{environment}}`
2. 运行 `npm run build:{{environment}}`
3. 执行 `npm run deploy:{{environment}}`
4. 验证部署状态
## 参数
- `environment`: 部署目标环境（staging / production）调用时提供参数：
/deploy environment=staging4.2.5 命令最佳实践
- 步骤要可执行：命令中的每个步骤都应该是 Claude Code 可以实际执行的操作，避免模糊描述。
- 包含错误处理：在命令中考虑失败场景，例如“如果测试失败，则停止部署”。
- 保持命令简短：一个命令最好只做一件事，复杂的流程可以拆分为多个命令。
- 文档化参数：如果命令接受参数，在文件末尾清晰列出每个参数的用途和可选值。
4.3 子代理 vs 命令：如何选择
| 特性 | 子代理 | 命令 |
|---|---|---|
| 调用方式 | @agent-name |
/command-name |
| 主要用途 | 角色扮演、专业分析 | 执行固定操作流程 |
| 复杂度 | 高（可包含完整角色设定） | 低（步骤列表） |
| 参数支持 | 通过对话自然传递 | 支持 {{placeholder}} 参数 |
| 适用场景 | 代码审查、架构设计、安全审计 | 运行测试、部署、代码格式化 |
选择建议：
- 需要角色扮演或深度分析时，使用子代理
- 需要快速执行固定操作时，使用命令
- 两者可以结合使用：在子代理中调用命令，或在命令中激活子代理
4.4 实战示例：构建代码审查工作流
结合子代理和命令，创建一个完整的代码审查流程。
步骤 1：创建审查子代理
.claude/agents/code-reviewer.md（内容见 4.1.2 节）
步骤 2：创建审查命令
.claude/commands/review.md：
# Review
对指定文件或目录进行代码审查。
## 步骤
1. 激活 `@code-reviewer` 子代理
2. 审查指定的文件或目录
3. 输出审查报告
## 参数
- `target`: 要审查的文件或目录路径步骤 3：执行审查
在会话中运行：
/review target=src/components/Claude Code 会：
- 加载
code-reviewer子代理的角色定义 - 以代码审查专家的身份分析
src/components/目录 - 按照子代理中定义的格式输出审查报告
4.5 常见问题
Q: 子代理和命令可以嵌套调用吗？ A: 可以。你可以在命令中调用子代理（如上面的审查示例），也可以在子代理的描述中建议用户运行特定命令。
Q: 如何调试子代理或命令？
A: 在会话中直接询问 Claude Code 它当前的角色或正在执行的命令。你也可以检查 .claude/ 目录下的文件内容是否正确。
Q: 子代理和命令会影响性能吗？ A: 影响很小。它们只是文本指令，不会增加额外的计算开销。但过于复杂的子代理定义可能会增加响应时间。
Q: 可以分享子代理和命令给团队成员吗？
A: 可以。将 .claude/ 目录纳入版本控制，团队成员 git pull 后即可使用相同的配置。
5. 核心功能详解（二）：技能与工作流
5. 核心功能详解（二）：技能与工作流
本章深入讲解 Claude Code 的 技能（Skills） 与 工作流（Workflows）。技能是预定义的、可复用的能力模块，让 Claude 快速掌握特定领域的知识或执行特定任务；工作流则是将多个命令、技能或步骤编排成自动化流程，以完成更复杂的任务。
5.1 技能（Skills）
技能本质上是存放在 .claude/skills/ 目录下的结构化指令集。每个技能是一个独立的文件夹，内含一个 SKILL.md 文件，用于描述该技能的目标、规则和操作步骤。
5.1.1 技能的结构
一个技能文件夹的典型结构如下：
.claude/
└── skills/
└── my-skill/ # 技能名称（文件夹名）
└── SKILL.md # 技能定义文件SKILL.md 文件使用 Markdown 格式，内容通常包括：
- 技能名称：简要描述技能的作用。
- 目标：说明该技能要解决什么问题。
- 规则：Claude 在执行该技能时应遵循的约束或行为准则。
- 步骤：具体的操作流程，可以包含代码示例、命令等。
5.1.2 创建你的第一个技能
假设你想让 Claude 在编写 Python 代码时自动遵循 PEP 8 风格指南，并自动运行 pylint 检查。可以创建如下技能：
创建技能文件夹：
mkdir -p .claude/skills/python-linter创建
SKILL.md文件：touch .claude/skills/python-linter/SKILL.md编辑
SKILL.md，写入以下内容：# Python Linter Skill ## 目标 确保所有 Python 代码符合 PEP 8 标准，并在修改后自动运行 pylint 检查。 ## 规则 - 在生成或修改 `.py` 文件后，必须运行 `pylint <文件名>`。 - 如果 pylint 报告错误或警告，必须修复它们，直到 pylint 评分达到 9.0/10 以上。 - 优先使用 `black` 格式化代码，然后再运行 pylint。 ## 步骤 1. 使用 `black` 格式化修改后的 Python 文件。 2. 运行 `pylint <文件名>` 检查代码质量。 3. 如果评分低于 9.0，根据 pylint 输出修复问题。 4. 重复步骤 1-3，直到通过检查。在对话中激活技能： 在 Claude Code 会话中，你可以通过自然语言告诉 Claude 使用该技能：
请使用 python-linter 技能，为我创建一个新的 Python 脚本，实现一个简单的计算器。Claude 会读取
SKILL.md的内容，并按照其中的规则和步骤执行。
5.1.3 使用官方技能
Anthropic 官方维护了一套技能库，涵盖多种常见场景。你可以从 官方技能仓库 获取它们。
安装官方技能示例（以 code-review 技能为例）：
下载技能文件夹： 你可以直接克隆整个仓库，或只复制需要的技能文件夹。
# 克隆官方技能仓库（如果尚未克隆） git clone https://github.com/anthropics/skills.git /tmp/skills-repo # 将 code-review 技能复制到你的项目 cp -r /tmp/skills-repo/skills/code-review .claude/skills/验证安装： 确保你的项目结构如下：
.claude/skills/code-review/SKILL.md使用技能： 在 Claude Code 中，你可以直接说：
请使用 code-review 技能，审查我最近修改的所有代码。
5.1.4 技能的最佳实践
- 单一职责：每个技能只做一件事，并做好。例如，不要将“代码格式化”和“部署到服务器”放在同一个技能里。
- 明确规则：规则要具体、可执行。避免模糊的描述，如“提高代码质量”，而应写“运行
pylint并确保评分高于 9.0”。 - 版本控制：将
.claude/skills/目录纳入 Git 版本控制，方便团队共享和追踪变更。 - 命名规范：技能文件夹名使用小写字母和连字符（
kebab-case），如python-linter、deploy-aws。
5.2 工作流（Workflows）
工作流是将多个步骤、命令或技能编排成一个可重复执行的流程。在 Claude Code 中，工作流通常通过 命令（Commands） 来实现，尤其是使用 .claude/commands/ 目录下的 Markdown 文件。
5.2.1 工作流与命令的关系
- 命令：是单个可执行的指令，通常对应一个
.claude/commands/<name>.md文件。 - 工作流：是一个更高级的概念，它可能由多个命令、技能和手动步骤组成。一个工作流可以封装成一个命令，也可以由用户通过一系列对话步骤手动执行。
5.2.2 创建一个简单的工作流命令
假设你有一个常见的开发流程：先运行测试，然后构建项目，最后部署到测试环境。你可以创建一个名为 deploy-to-staging 的命令来封装这个工作流。
创建命令文件：
touch .claude/commands/deploy-to-staging.md编辑命令文件，内容如下：
# Deploy to Staging ## 工作流步骤 1. 运行所有单元测试： ```bash npm test- 如果测试全部通过，构建项目：
npm run build - 将构建产物部署到 staging 服务器：
rsync -avz ./dist/ user@staging-server:/var/www/app/ - 重启服务：
ssh user@staging-server 'sudo systemctl restart my-app'
注意事项
- 确保
staging-server的 SSH 密钥已配置。 - 如果测试失败，流程将中止，不会继续部署。
- 如果测试全部通过，构建项目：
在对话中使用工作流： 在 Claude Code 中，输入斜杠命令：
/deploy-to-stagingClaude 会读取该文件，并按照定义的步骤逐一执行。它会询问你每个步骤的执行权限（除非你已启用自动模式）。
5.2.3 复杂工作流：编排多个技能和命令
你可以创建一个更高级的工作流，它内部调用其他技能或命令。例如，一个“完整代码审查与部署”工作流：
创建命令文件
.claude/commands/full-review-and-deploy.md：# Full Review and Deploy ## 工作流步骤 1. **代码审查**：使用 `code-review` 技能审查所有未提交的更改。 - 技能路径：`.claude/skills/code-review/SKILL.md` - 执行方式：Claude 将读取该技能文件并执行审查。 2. **运行测试**：执行 `test` 命令（假设你已定义 `.claude/commands/test.md`）。 ```bash /test构建项目：
npm run build部署到生产环境：执行
deploy命令。/deploy
规则
- 任何步骤失败，整个工作流立即停止。
- 部署到生产环境前，必须获得用户明确确认。
使用工作流：
/full-review-and-deploy
5.2.4 工作流中的条件与分支
虽然 .claude/commands/ 中的 Markdown 文件本身不支持编程逻辑（如 if/else），但你可以通过以下方式实现条件分支：
- 在步骤描述中写明条件：例如，“如果测试通过，则继续部署；否则，停止并报告错误。”
- 依赖 Claude 的推理能力：Claude 会理解你的自然语言指令，并做出判断。例如，你可以写：
1. 运行 `npm test`。 2. 如果测试全部通过，运行 `npm run build`。 3. 如果有测试失败，列出失败原因并停止工作流。
5.2.5 工作流示例：天气编排器
项目仓库中提供了一个名为 weather-orchestrator 的工作流示例，位于 .claude/commands/weather-orchestrator.md。这个工作流展示了如何编排多个步骤来获取天气信息并生成报告。
查看并使用该示例：
查看文件内容：
cat .claude/commands/weather-orchestrator.md在对话中使用：
/weather-orchestrator然后根据 Claude 的提示输入城市名称等信息。
5.3 技能与工作流的协同
技能和工作流可以无缝协同工作：
- 工作流调用技能：在工作流的步骤中，可以指定使用某个技能。例如，在代码审查工作流中，第一步就是调用
code-review技能。 - **
6. 核心功能详解（三）：钩子与 MCP 服务器
6. 核心功能详解（三）：钩子与 MCP 服务器
本章深入讲解 Claude Code 的两个高级扩展机制：Hooks（钩子） 和 MCP 服务器。钩子让你在特定事件发生时自动执行脚本，MCP 服务器则允许 Claude Code 与外部工具和服务进行交互。
6.1 钩子（Hooks）
钩子是放置在 .claude/hooks/ 目录下的可执行脚本，在 Claude Code 的特定生命周期事件中被自动触发。它们类似于 Git 钩子，但专为 Claude Code 设计。
6.1.1 支持的钩子类型
| 钩子名称 | 触发时机 | 典型用途 |
|---|---|---|
pre-command |
执行任何命令之前 | 检查环境、加载配置 |
post-command |
命令执行完成后 | 清理、记录日志 |
pre-skill |
技能执行之前 | 验证输入、准备上下文 |
post-skill |
技能执行完成后 | 结果处理、通知 |
pre-agent |
子代理启动前 | 初始化资源 |
post-agent |
子代理结束后 | 资源释放、汇总 |
6.1.2 创建钩子
创建钩子目录：
mkdir -p .claude/hooks编写钩子脚本（以
pre-command为例）： 创建.claude/hooks/pre-command文件：#!/bin/bash # 在执行任何命令前记录时间 echo "[$(date)] Running command: $CLAUDE_COMMAND" >> /tmp/claude-hooks.log赋予执行权限：
chmod +x .claude/hooks/pre-command
6.1.3 钩子可用的环境变量
Claude Code 在执行钩子时会设置以下环境变量：
| 变量名 | 说明 |
|---|---|
CLAUDE_COMMAND |
当前执行的命令名称 |
CLAUDE_SKILL_NAME |
当前执行的技能名称（技能钩子专用） |
CLAUDE_AGENT_NAME |
当前运行的子代理名称（代理钩子专用） |
CLAUDE_PROJECT_DIR |
项目根目录路径 |
CLAUDE_HOOK_TYPE |
钩子类型（如 pre-command） |
6.1.4 实用钩子示例
示例 1：自动代码格式化（post-command 钩子）
创建 .claude/hooks/post-command：
#!/bin/bash
# 在每次命令执行后自动格式化修改的文件
if [ -n "$CLAUDE_COMMAND" ]; then
# 检查是否有未提交的更改
if git diff --name-only | grep -q "\.py$"; then
echo "🔧 自动格式化 Python 文件..."
black $(git diff --name-only | grep "\.py$") 2>/dev/null
fi
fi示例 2：安全检查（pre-command 钩子）
创建 .claude/hooks/pre-command：
#!/bin/bash
# 在执行危险命令前发出警告
DANGEROUS_COMMANDS=("rm -rf" "drop table" "delete from")
for cmd in "${DANGEROUS_COMMANDS[@]}"; do
if [[ "$CLAUDE_COMMAND" == *"$cmd"* ]]; then
echo "⚠️ 警告：检测到危险命令 '$cmd'"
echo "请确认是否继续？(y/N)"
read -r response
if [[ "$response" != "y" ]]; then
echo "❌ 命令已取消"
exit 1
fi
fi
done6.1.5 钩子调试
- 钩子脚本的输出会显示在 Claude Code 的日志中
- 使用
stderr输出调试信息：echo "Debug: hook triggered" >&2 - 钩子返回非零退出码会中断当前操作
注意：钩子脚本应尽量轻量，避免长时间阻塞。如果钩子执行时间过长，Claude Code 会显示超时警告。
6.2 MCP 服务器
MCP（Model Context Protocol）服务器允许 Claude Code 与外部工具、API 和服务进行交互。通过 MCP，你可以让 Claude Code 访问数据库、调用 REST API、操作文件系统等。
6.2.1 MCP 服务器配置
MCP 服务器可以在两个地方配置：
- 项目级配置：
.claude/settings.json - 独立配置文件：
.mcp.json（推荐用于共享配置）
6.2.2 配置格式
基本结构（.mcp.json）：
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["path/to/server.js"],
"env": {
"API_KEY": "${API_KEY}"
}
}
}
}字段说明：
command：启动 MCP 服务器的可执行文件args：传递给命令的参数数组env：环境变量（支持${VAR_NAME}语法引用系统环境变量）
6.2.3 常用 MCP 服务器示例
示例 1：文件系统操作
配置一个允许 Claude Code 读写文件的 MCP 服务器：
.mcp.json：
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/path/to/allowed/directory"
]
}
}
}示例 2：数据库查询
配置 PostgreSQL 数据库访问：
.mcp.json：
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@anthropic/mcp-server-postgres",
"postgresql://user:password@localhost:5432/mydb"
]
}
}
}示例 3：GitHub API 集成
{
"mcpServers": {
"github": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
}
}
}
}6.2.4 在 settings.json 中配置 MCP
你也可以在 .claude/settings.json 中配置 MCP 服务器：
{
"mcpServers": {
"weather-api": {
"command": "python",
"args": ["mcp_servers/weather_server.py"],
"env": {
"WEATHER_API_KEY": "${WEATHER_API_KEY}"
}
}
}
}6.2.5 编写自定义 MCP 服务器
Python 示例（mcp_servers/weather_server.py）：
import json
import sys
import requests
def handle_request(request):
"""处理 MCP 请求"""
action = request.get("action")
if action == "get_weather":
city = request.get("params", {}).get("city")
# 调用外部 API
response = requests.get(
f"https://api.weather.com/v1/{city}",
headers={"Authorization": f"Bearer {API_KEY}"}
)
return {"result": response.json()}
elif action == "list_tools":
return {
"tools": [
{
"name": "get_weather",
"description": "获取指定城市的天气信息",
"parameters": {
"city": {"type": "string", "description": "城市名称"}
}
}
]
}
return {"error": "Unknown action"}
# 主循环
for line in sys.stdin:
try:
request = json.loads(line.strip())
response = handle_request(request)
print(json.dumps(response), flush=True)
except Exception as e:
print(json.dumps({"error": str(e)}), flush=True)Node.js 示例（mcp_servers/calculator.js）：
const readline = require('readline');
const rl = readline.createInterface({
input: process.stdin,
output: process.stdout,
terminal: false
});
rl.on('line', (line) => {
try {
const request = JSON.parse(line);
const action = request.action;
if (action === 'list_tools') {
console.log(JSON.stringify({
tools: [
{
name: 'calculate',
description: '执行数学计算',
parameters: {
expression: { type: 'string', description: '数学表达式' }
}
}
]
}));
} else if (action === 'calculate') {
const expr = request.params?.expression;
const result = eval(expr); // 注意：生产环境应使用安全求值
console.log(JSON.stringify({ result }));
}
} catch (error) {
console.log(JSON.stringify({ error: error.message }));
}
});6.2.6 MCP 服务器安全最佳实践
限制访问范围：
- 文件系统服务器只开放必要目录
- 数据库服务器使用只读账户（如可能）
使用环境变量管理密钥：
{ "mcpServers": { "api-server": { "command": "node", "args": ["server.js
7. 核心功能详解（四）：插件与设置
7. 核心功能详解（四）：插件与设置
本章将深入讲解 Claude Code 的插件系统和设置配置。插件允许你将可复用的功能打包分发，而设置则让你精细控制 Claude Code 的行为、权限和外观。
7.1 插件系统
插件（Plugins）是 Claude Code 的可分发功能包，你可以从官方市场或第三方市场安装，也可以创建自己的插件并发布到市场。
7.1.1 插件市场
Claude Code 支持多个插件市场，你可以通过以下命令浏览和搜索插件：
# 列出所有可用的插件市场
claude plugins list-markets
# 搜索插件
claude plugins search "test"
# 查看插件详情
claude plugins show <plugin-name>官方市场地址：https://code.claude.com/docs/en/discover-plugins
7.1.2 安装与卸载插件
# 从市场安装插件
claude plugins install <plugin-name>
# 从本地路径安装插件
claude plugins install /path/to/plugin
# 卸载插件
claude plugins uninstall <plugin-name>
# 列出已安装的插件
claude plugins list注意事项：
- 安装插件前请确认其来源可信
- 部分插件可能需要额外的依赖或权限
- 插件安装后通常需要重启 Claude Code 会话才能生效
7.1.3 创建自定义插件
插件本质上是一个包含特定文件结构的目录。创建插件的基本步骤：
- 创建插件目录结构：
my-plugin/
├── plugin.json # 插件元数据
├── commands/ # 自定义命令（可选）
│ └── my-command.md
├── skills/ # 自定义技能（可选）
│ └── my-skill/
│ └── SKILL.md
└── hooks/ # 自定义钩子（可选）
└── pre-commit.sh- 编写
plugin.json：
{
"name": "my-plugin",
"version": "1.0.0",
"description": "我的第一个 Claude Code 插件",
"author": "Your Name",
"commands": ["my-command"],
"skills": ["my-skill"],
"hooks": ["pre-commit"]
}- 安装本地插件：
claude plugins install ./my-plugin7.1.4 创建插件市场
如果你有多个插件需要团队共享，可以创建私有插件市场：
# 初始化插件市场
claude plugins init-market ./my-market
# 添加插件到市场
claude plugins add-to-market ./my-market ./my-plugin
# 发布市场
claude plugins publish-market ./my-market市场配置文件示例（market.json）：
{
"name": "team-plugins",
"description": "团队内部插件市场",
"plugins": [
{
"name": "my-plugin",
"version": "1.0.0",
"url": "https://my-registry.com/plugins/my-plugin.tar.gz"
}
]
}7.2 设置系统
Claude Code 的设置通过 .claude/settings.json 文件进行配置。这个文件控制着权限、模型参数、输出样式、沙箱行为等方方面面。
7.2.1 设置文件位置
设置文件可以放在多个层级，优先级从高到低为：
- 项目级：
<project-root>/.claude/settings.json - 用户级：
~/.claude/settings.json - 全局默认：Claude Code 内置默认值
最佳实践：将项目特定的设置放在项目级，将个人偏好放在用户级。
7.2.2 权限配置
权限控制 Claude Code 可以执行的操作类型：
{
"permissions": {
"allow": {
"read": true,
"write": true,
"execute": true,
"network": false,
"browser": false
},
"deny": {
"network": ["*.internal.company.com"],
"execute": ["rm", "sudo"]
}
}
}权限选项说明：
| 权限 | 说明 | 默认值 |
|---|---|---|
read |
读取文件 | true |
write |
写入文件 | true |
execute |
执行命令 | true |
network |
网络访问 | false |
browser |
浏览器操作 | false |
7.2.3 模型配置
控制 Claude 模型的参数：
{
"model": {
"provider": "anthropic",
"model": "claude-sonnet-4-20250514",
"max_tokens": 8192,
"temperature": 0.7,
"top_p": 0.9,
"top_k": 40
}
}常用模型参数：
| 参数 | 说明 | 建议值 |
|---|---|---|
max_tokens |
最大输出 token 数 | 4096-8192 |
temperature |
创造性程度 (0-1) | 0.3-0.7 |
top_p |
核采样阈值 | 0.9 |
top_k |
Top-K 采样 | 40 |
7.2.4 输出样式
自定义 Claude Code 的输出外观：
{
"output": {
"theme": "dark",
"font_size": 14,
"line_height": 1.5,
"show_line_numbers": true,
"word_wrap": true,
"code_highlighting": true
}
}主题选项："dark", "light", "high-contrast"
7.2.5 沙箱配置
沙箱用于隔离 Claude Code 的执行环境：
{
"sandbox": {
"enabled": true,
"type": "docker",
"image": "claude-code-sandbox:latest",
"volumes": [
"/path/to/project:/workspace"
],
"resource_limits": {
"memory": "4g",
"cpu": "2"
}
}
}沙箱类型：
"docker"：使用 Docker 容器"none"：不使用沙箱
7.2.6 快捷键绑定
自定义键盘快捷键：
{
"keybindings": {
"submit": "Enter",
"interrupt": "Ctrl+C",
"newline": "Shift+Enter",
"autocomplete": "Tab",
"search_history": "Ctrl+R",
"toggle_sidebar": "Ctrl+B",
"toggle_fullscreen": "Ctrl+Shift+F"
}
}7.2.7 自动模式配置
当启用自动模式时，可以配置其行为：
{
"auto_mode": {
"enabled": true,
"max_iterations": 50,
"timeout_seconds": 300,
"approval_threshold": "medium",
"auto_retry": true
}
}approval_threshold 选项：
"low"：仅高风险操作需要确认"medium"：中高风险操作需要确认"high"：所有操作都需要确认
7.2.8 状态栏配置
自定义状态栏显示内容：
{
"statusline": {
"left": ["mode", "model", "branch"],
"right": ["permissions", "memory", "time"],
"separator": " | ",
"show_icons": true
}
}可用组件：
mode：当前模式（交互/自动）model：当前模型branch：Git 分支permissions：权限状态memory：内存使用time：当前时间progress：任务进度
7.3 完整设置示例
以下是一个完整的 .claude/settings.json 示例：
{
"permissions": {
"allow": {
"read": true,
"write": true,
"execute": true,
"network": false
}
},
"model": {
"provider": "anthropic",
"model": "claude-sonnet-4-20250514",
"max_tokens": 8192,
"temperature": 0.5
},
"output": {
"theme": "dark",
"font_size": 14,
"show_line_numbers": true
},
"sandbox": {
"enabled": false
},
"keybindings": {
"submit": "Enter",
"interrupt": "Ctrl+C"
},
"auto_mode": {
"enabled": false,
"max_iterations": 30
},
"statusline": {
"left": ["mode", "model"],
"right": ["permissions"]
}
}7.4 常见问题
Q: 如何临时覆盖设置？
A: 使用 CLI 标志，例如 claude --model claude-opus-4-20250514 会临时覆盖模型设置。
Q: 插件安装失败怎么办？ A: 检查网络连接，确认插件名称正确，或尝试从本地路径安装。
Q: 如何重置所有设置为默认值？
A: 删除对应的 settings.json 文件，Claude Code 会自动使用默认值。
Q: 设置更改后需要重启吗？ A: 大部分设置更改后需要
8. 核心功能详解（五）：记忆与检查点
8. 核心功能详解（五）：记忆与检查点
本章将深入讲解 Claude Code 的两项关键功能：记忆（Memory） 和 检查点（Checkpointing）。记忆让 Claude 在会话间保持对项目、规则和用户偏好的认知；检查点则允许你随时回溯到文件编辑的某个历史状态，如同代码的“时光机”。
8.1 记忆（Memory）
Claude Code 的记忆系统通过多个层级和文件来存储信息，确保 Claude 在每次对话中都能理解项目的上下文、你的偏好以及需要遵循的规则。
8.1.1 核心记忆文件：CLAUDE.md
CLAUDE.md 是项目根目录下的一个 Markdown 文件，是 Claude Code 最重要的记忆载体。每次启动新会话时，Claude 都会自动读取此文件，以了解项目概况、架构、约定和你的要求。
创建 CLAUDE.md：
你可以手动创建，也可以让 Claude 为你生成。在项目根目录下运行：
# 让 Claude 分析项目并生成 CLAUDE.md
claude然后在对话中输入类似以下指令：
请分析当前项目的结构、技术栈和关键约定，然后创建一个 CLAUDE.md 文件，包含项目概述、目录结构、构建命令、测试命令和代码风格指南。CLAUDE.md 推荐内容结构：
# 项目名称
## 项目概述
简要描述项目的目的、技术栈和主要功能。
## 目录结构
- `src/` - 源代码
- `tests/` - 测试文件
- `docs/` - 文档
## 构建与运行
- 安装依赖：`npm install`
- 启动开发服务器：`npm run dev`
- 运行测试：`npm test`
## 代码约定
- 使用 TypeScript 严格模式
- 函数命名采用 camelCase
- 组件命名采用 PascalCase
- 优先使用函数式组件和 Hooks
## 关键依赖
- React 18
- Next.js 14
- Prisma ORM
## 常见任务
- 添加新 API 路由：在 `src/app/api/` 下创建新文件
- 添加数据库迁移：`npx prisma migrate dev`注意：
CLAUDE.md应保持简洁且聚焦于项目级信息。避免放入过于琐碎或频繁变化的内容。
8.1.2 规则文件：.claude/rules/ 与 ~/.claude/rules/
规则文件用于定义更细粒度的指令和行为约束。它们分为两个层级：
- 项目级规则：
.claude/rules/目录下的 Markdown 文件，仅对当前项目生效。 - 全局规则：
~/.claude/rules/目录下的 Markdown 文件，对所有项目生效。
创建项目级规则：
# 创建规则目录
mkdir -p .claude/rules
# 创建一条规则文件
touch .claude/rules/code-style.md在 code-style.md 中写入：
# 代码风格规则
1. 所有错误处理必须使用 try-catch 块，不得忽略异常。
2. 日志输出必须使用项目统一的 logger 实例，禁止直接使用 console.log。
3. 所有公共函数和类必须包含 JSDoc 注释。创建全局规则：
# 创建全局规则目录
mkdir -p ~/.claude/rules
# 创建全局规则文件
touch ~/.claude/rules/general-preferences.md在 general-preferences.md 中写入：
# 通用偏好
1. 代码注释使用英文，变量命名使用英文。
2. 优先使用 const 而非 let，避免使用 var。
3. 每行代码不超过 100 个字符。注意：全局规则适用于所有项目，因此内容应保持通用。项目特定的规则应放在
.claude/rules/中。
8.1.3 自动记忆（Auto Memory）
Claude Code 的自动记忆功能会记录会话中的关键信息，并在后续对话中自动引用。这些信息存储在 ~/.claude/projects/<project>/memory/ 目录下。
工作原理：
- 当你在对话中提到重要信息（如“记住我更喜欢使用 pnpm”）时，Claude 会自动将其写入记忆文件。
- 在后续会话中，Claude 会读取这些记忆，并据此调整行为。
查看和管理自动记忆：
# 查看当前项目的记忆目录
ls ~/.claude/projects/$(basename $(pwd))/memory/手动添加记忆条目：
在对话中，你可以直接说：
请记住：我所有的数据库迁移文件都应该放在 src/db/migrations/ 目录下。Claude 会自动处理并将其写入记忆。
注意：自动记忆是隐式的，你无需手动管理文件。但如果需要清除记忆，可以删除
~/.claude/projects/<project>/memory/目录下的对应文件。
8.1.4 记忆的优先级与合并
当多个记忆源存在时，Claude Code 按以下优先级处理：
- 会话内指令（当前对话中的直接要求）> 项目级规则（
.claude/rules/）> 全局规则（~/.claude/rules/）> 自动记忆 >CLAUDE.md
这意味着如果你在对话中临时说“忽略代码风格规则”，它会覆盖规则文件中的设定。
8.2 检查点（Checkpointing）
检查点功能允许 Claude Code 自动记录文件编辑的历史状态，你可以随时回退到任意一个检查点，就像 Git 的自动提交，但粒度更细且无需手动操作。
8.2.1 检查点的工作原理
- 自动触发：每次 Claude 执行文件编辑操作（创建、修改、删除文件）时，系统会自动创建一个检查点。
- 无感记录：检查点的创建是透明的，你无需执行任何额外命令。
- 会话级作用域：检查点仅在当前 Claude Code 会话中有效。会话结束后，检查点会被清理。
8.2.2 使用检查点
查看检查点列表：
在 Claude Code 会话中，输入：
/checkpointsClaude 会列出当前会话中的所有检查点，包括时间戳和简要描述。
回退到指定检查点：
/checkpoint restore 3其中 3 是检查点的索引号（从 /checkpoints 命令的输出中获取）。
回退到上一个检查点：
/undo这是最常用的快捷命令，相当于回退到最近的一个检查点。
重做（前进到下一个检查点）：
/redo注意：
/undo和/redo仅作用于文件编辑状态，不会影响对话历史。如果你需要完全回退对话，应使用/compact或重新启动会话。
8.2.3 检查点与 Git 的对比
| 特性 | 检查点 | Git |
|---|---|---|
| 触发方式 | 自动（每次文件编辑） | 手动（git commit） |
| 作用范围 | 当前会话 | 整个仓库历史 |
| 持久性 | 会话结束后清除 | 永久保存（除非手动删除） |
| 粒度 | 每次编辑 | 每次提交 |
| 回退操作 | /checkpoint restore |
git checkout / git revert |
最佳实践： 检查点适合在探索性编码或复杂重构时使用，让你可以大胆尝试而不必担心破坏代码。当找到正确的方案后，再用 Git 进行正式提交。
8.2.4 检查点的高级用法
创建手动检查点：
虽然检查点是自动的，但你也可以手动创建检查点，以便在关键节点标记状态：
请创建一个检查点，标记为“重构完成前的安全点”。查看检查点详情：
/checkpoint show 5这会显示检查点 5 所包含的所有文件变更详情。
比较两个检查点：
/checkpoint diff 3 5这会显示检查点 3 和检查点 5 之间的文件差异。
8.3 实战：结合记忆与检查点
以下是一个典型的工作流程，展示了如何将记忆与检查点结合使用：
初始化项目记忆：
claude在对话中：
请分析项目并创建 CLAUDE.md，包含项目结构、构建命令和测试命令。添加规则：
请在 .claude/rules/ 下创建一条规则：所有 API 响应必须包含 status 和 message 字段。开始重构：
请将 src/utils/ 下的所有工具函数迁移到 src/helpers/ 目录，并更新所有引用。执行过程中使用检查点：
- 如果 Claude 开始修改文件，系统会自动创建检查点。
- 如果某一步出错，使用
/undo回退。 - 如果发现方向不对，使用
/checkpoints查看列表，然后/checkpoint restore 2回到更早的状态。
确认结果后提交 Git：
git add . git commit -m "refactor: migrate utils to helpers"
8.4 注意事项与最佳实践
CLAUDE.md不要过大：保持文件在 100-200 行以内，过长的文件会降低 Claude 的处理效率。- 规则文件按主题拆分：将不同类别的规则（如代码风格、测试规范、部署流程）放在不同的文件中，便于管理和维护。
- 检查点不是 Git 替代品：检查点用于
9. 进阶用法与技巧：CLI 标志、自动模式与热特性
CLI 启动标志
Claude Code 提供了丰富的 CLI 标志，让你在启动时就能精确控制行为。这些标志可以组合使用，实现高度定制化的启动配置。
常用 CLI 标志
| 标志 | 说明 | 示例 |
|---|---|---|
--model |
指定使用的模型 | claude --model claude-sonnet-4-20250514 |
--permission-mode |
设置权限模式 | claude --permission-mode auto |
--channels |
启用频道功能 | claude --channels |
--verbose |
输出详细日志 | claude --verbose |
--help |
查看帮助信息 | claude --help |
实际使用示例
# 使用指定模型启动
claude --model claude-sonnet-4-20250514
# 启用自动模式（跳过确认提示）
claude --permission-mode auto
# 组合多个标志
claude --model claude-sonnet-4-20250514 --permission-mode auto --verbose
# 查看所有可用标志
claude --help注意事项：
- 模型名称会随 Claude 版本更新而变化，请查阅官方文档获取最新列表
--verbose会输出大量调试信息，仅在排查问题时使用
自动模式
自动模式（Auto Mode）是 Claude Code 的 Beta 功能，允许 AI 自动执行操作而无需每次确认。这在批量处理、自动化脚本执行等场景下特别有用。
启用自动模式
方式一：CLI 标志
claude --permission-mode auto方式二：快捷键
在会话中按下 Shift+Tab 切换自动模式开关。
方式三：配置文件
在 .claude/settings.json 中设置：
{
"permissionMode": "auto"
}自动模式配置
通过 .claude/settings.json 精细控制自动模式行为：
{
"autoModeConfig": {
"maxRequestsPerTask": 50,
"maxStepsPerTask": 100,
"allowedTools": ["Read", "Edit", "Bash", "Glob", "Grep", "WebSearch"],
"blockedTools": ["DeleteFile", "RenameFile"],
"allowedPaths": ["/path/to/project/src"],
"blockedPaths": ["/path/to/project/node_modules"]
}
}| 配置项 | 说明 | 默认值 |
|---|---|---|
maxRequestsPerTask |
单任务最大请求次数 | 50 |
maxStepsPerTask |
单任务最大步骤数 | 100 |
allowedTools |
允许自动使用的工具列表 | 所有工具 |
blockedTools |
禁止自动使用的工具 | 无 |
allowedPaths |
允许自动操作的文件路径 | 项目根目录 |
blockedPaths |
禁止自动操作的文件路径 | 无 |
自动模式最佳实践
- 逐步放开权限：先使用
allowedTools限制高风险操作，确认稳定后再放开 - 设置路径白名单：避免 AI 意外修改关键配置文件
- 监控执行次数：设置合理的
maxRequestsPerTask防止无限循环
# 安全启动自动模式示例
claude --permission-mode auto --model claude-sonnet-4-20250514热特性（Hot Features）
这些是 Claude Code 最新推出的 Beta 功能，能显著提升开发效率。
Ultrareview（超强代码审查）
Ultrareview 提供比普通代码审查更深入的分析，支持任务追踪。
# 对当前分支进行超强审查
claude ultrareview
# 对指定目标进行审查
claude ultrareview src/components/
# 在会话中使用命令
/code-review ultra任务追踪：
# 启动审查并追踪任务
claude ultrareview --track
# 查看审查进度
claude ultrareview --statusUltraplan（超强规划）
Ultraplan 帮助 AI 在开始编码前进行更全面的规划。
# 在会话中使用
/ultraplan
# 示例：规划一个 API 设计
/ultraplan 设计一个用户认证系统的 REST APIChannels（频道）
Channels 允许 Claude Code 在多个会话或插件间共享上下文。
# 启用频道功能启动
claude --channels
# 指定频道名称
claude --channels my-channel频道参考配置（.claude/settings.json）：
{
"channels": {
"enabled": true,
"defaultChannel": "main",
"maxHistory": 100
}
}No Flicker Mode（无闪烁模式）
解决终端刷新时的闪烁问题，适合在性能较差的终端或远程连接中使用。
# 环境变量方式
export CLAUDE_CODE_NO_FLICKER=1
claude
# 会话中切换
/tui fullscreenDevcontainers（开发容器）
在容器化环境中使用 Claude Code，确保开发环境一致性。
// .devcontainer/devcontainer.json
{
"name": "Claude Code Dev",
"image": "mcr.microsoft.com/devcontainers/base:ubuntu-22.04",
"features": {
"ghcr.io/devcontainers/features/node:1": {}
},
"postCreateCommand": "npm install"
}Power-ups（增强功能）
Power-ups 是社区贡献的增强脚本，通过 /powerup 命令启用。
# 在会话中查看可用 Power-ups
/powerup list
# 启用特定 Power-up
/powerup enable auto-commit
# 禁用 Power-up
/powerup disable auto-commit注意事项：
- 热特性均为 Beta 版本，API 和行为可能变化
- 生产环境使用前建议充分测试
- 部分功能需要特定版本的 Claude Code 支持
组合使用示例
将 CLI 标志、自动模式和热特性结合使用，打造高效工作流：
# 开发环境启动
claude --model claude-sonnet-4-20250514 \
--permission-mode auto \
--channels \
--verbose
# 代码审查专用启动
claude ultrareview --track --verbose
# 安全模式启动（限制自动操作）
claude --permission-mode auto \
--model claude-sonnet-4-20250514配置文件完整示例（.claude/settings.json）：
{
"permissionMode": "auto",
"autoModeConfig": {
"maxRequestsPerTask": 30,
"allowedTools": ["Read", "Edit", "Bash", "Glob", "Grep"],
"blockedPaths": ["/etc", "/usr", "node_modules"]
},
"channels": {
"enabled": true
}
}通过合理组合这些进阶功能，你可以将 Claude Code 从简单的对话工具升级为强大的自动化开发助手。
10. 常见问题与延伸阅读
常见问题与延伸阅读
常见问题（FAQ）
Q1: Claude Code 无法启动或报错“API Key 无效”
原因：未正确设置 ANTHROPIC_API_KEY 环境变量，或 Key 已过期/权限不足。
解决方法：
- 检查环境变量是否已设置：
echo $ANTHROPIC_API_KEYexport ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx" - 确认 Key 在 Anthropic Console 中状态为“Active”。
- 如果使用代理，确保代理允许访问
api.anthropic.com。
Q2: 子代理（Subagent）不生效
原因：子代理文件未放置在正确路径，或文件名不符合规范。
解决方法：
- 子代理文件必须位于
.claude/agents/目录下，且文件名以.md结尾。 - 示例：
.claude/agents/my-agent.md - 文件内容需包含明确的指令，例如：
# My Agent 你是一个专门处理日志分析的助手。请分析用户提供的日志文件，提取错误信息并给出修复建议。 - 在会话中使用
/agent my-agent调用。
Q3: 命令（Command）无法识别
原因：命令文件未正确放置，或命令名称冲突。
解决方法：
- 命令文件必须位于
.claude/commands/目录下，文件名以.md结尾。 - 文件内容需包含
---分隔的元数据块，例如：--- name: test description: 运行项目测试 --- 请运行项目的测试套件，并报告结果。 - 使用
/test调用。如果命令名称与内置命令冲突，请重命名文件。
Q4: 技能（Skill）未加载
原因：技能目录结构不正确，或 SKILL.md 文件缺失。
解决方法：
- 技能目录结构必须为：
.claude/skills/<skill-name>/SKILL.md - 示例：
.claude/skills/code-review/SKILL.md - SKILL.md 文件需包含技能描述和指令。
- 在会话中使用
/skill code-review调用。
Q5: 钩子（Hook）不执行
原因：钩子脚本权限不足，或文件名不符合规范。
解决方法：
- 钩子脚本必须位于
.claude/hooks/目录下。 - 文件名必须为以下之一：
pre-commit、post-commit、pre-exec、post-exec。 - 确保脚本具有可执行权限：
chmod +x .claude/hooks/pre-commit - 脚本需以 shebang 开头，例如：
#!/bin/bash echo "Running pre-commit hook..."
Q6: MCP 服务器连接失败
原因：MCP 服务器配置错误，或服务器未启动。
解决方法：
- 检查
.mcp.json或.claude/settings.json中的 MCP 配置。 - 确保服务器地址和端口正确，例如：
{ "mcpServers": { "my-server": { "url": "http://localhost:3000" } } } - 确认服务器已启动并可访问：
curl http://localhost:3000/health
Q7: 插件（Plugin）安装失败
原因：插件包格式不正确，或依赖缺失。
解决方法：
- 插件包必须是有效的 npm 包或目录。
- 使用官方命令安装：
claude plugins install <package-name> - 如果插件有依赖，确保已安装：
npm install
Q8: 记忆（Memory）不更新
原因：CLAUDE.md 文件权限问题，或规则文件未正确配置。
解决方法：
- 确保
CLAUDE.md文件可写：chmod 644 CLAUDE.md - 检查
.claude/rules/目录下的规则文件格式是否正确。 - 使用
/memory命令手动触发记忆更新。
Q9: 检查点（Checkpoint）无法恢复
原因：检查点文件损坏，或项目目录被移动。
解决方法：
- 检查点文件存储在项目根目录的
.claude/checkpoints/下。 - 使用
/checkpoint list查看可用检查点。 - 使用
/checkpoint restore <id>恢复。 - 如果文件损坏，尝试从备份恢复。
Q10: 自动模式（Auto Mode）不工作
原因：未正确启用自动模式，或权限配置错误。
解决方法：
- 启动时使用
--permission-mode auto标志：claude --permission-mode auto - 在会话中按
Shift+Tab切换模式。 - 确保
.claude/settings.json中配置了自动模式：{ "permissionMode": "auto" }
延伸阅读
官方文档
官方技能库
- Anthropic 官方技能 — 可直接使用的技能模板。
提示工程
- 提示工程交互式教程 — 学习如何编写高效的提示。
社区资源
- Claude Code 最佳实践仓库 — 本项目的完整代码和示例。
- Boris Cherny 的推文 — Claude Code 作者的实用技巧。
高级主题
- Ultrareview — 高级代码审查功能。
- Ultraplan — 高级计划功能。
- Devcontainers — 开发容器支持。
- Channels — 多通道通信。
- No Flicker Mode — 无闪烁模式。
- Auto Mode — 自动权限模式。
- Power-ups — 增强功能。
注意事项
- 版本兼容性：确保 Claude Code 版本与文档中的功能匹配。使用
claude --version查看当前版本。 - 文件权限：钩子脚本和可执行文件需设置正确的权限。
- 路径问题：所有配置文件和目录必须位于项目根目录下。
- 调试技巧：使用
--verbose标志获取详细日志：claude --verbose - 备份：定期备份
CLAUDE.md和.claude/目录，以防数据丢失。
