第一章：初识 Claude Code - 从零到一的起步

欢迎来到 Claude Code 的世界。本章将引导你完成从零到一的起步过程，涵盖其核心概念、环境准备、安装配置，并带领你完成第一个交互式任务。这不仅仅是学习一个新工具，更是拥抱一种全新的编程范式。

1.1 什么是 Claude Code？- 重新定义编程范式

Claude Code 不是传统的代码补全工具或 IDE 插件，而是一个在你的终端中运行的、具备自主行动能力的 Agentic 编程助手。它的设计理念是成为你的编程伙伴，能够理解你的意图，并自主地规划和执行复杂的开发任务。

1.1.1 Agentic 编程助手：不止是代码补全

传统的 AI 编程工具通常是被动地响应你的请求，例如提供代码片段或补全当前行。Claude Code 则更进一步，它能够：

• 主动探索：分析整个代码库，理解文件结构、依赖关系和业务逻辑。
• 自主规划：将一个模糊的高级目标（如“修复支付模块的 bug”）分解为具体的、可执行的步骤。
• 执行任务：跨文件修改代码、运行测试、执行 Shell 命令、操作 Git 仓库，并与你持续沟通，请求批准关键操作。

1.1.2 核心优势：大上下文、终端原生与自主执行

Claude Code 的强大能力源于其独特的核心优势：

1.1.3 Claude Code 与 Claude 模型家族的关系

Claude Code 的强大能力由 Anthropic 顶尖的 Claude 模型家族驱动。它并非单一模型，而是根据任务的复杂性智能调用最合适的模型。

• Claude 4 Sonnet: 通常用于处理快速、直接的任务，如简单的代码生成和修改，响应速度快。
• Claude 4 Opus: 当面对需要深度思考、复杂逻辑推理和战略规划的任务时（例如，设计系统架构、修复一个深层次的 bug），Claude Code 会依赖 Opus 模型，以确保最高的输出质量和准确性。

这种多模型策略确保了你在不同场景下都能获得最佳的性能与成本效益。

1.2 环境准备与安装

在开始之前，请确保你的开发环境满足以下要求。整个安装和配置过程非常简单，通常几分钟内即可完成。

1.2.1 系统要求与环境配置

• 操作系统:
  • macOS 10.15+
  • Linux (Ubuntu 20.04+ 或其他现代发行版)
  • Windows 10/11 (新版本已适配)
• 软件依赖:
  • Node.js: v18.0 或更高版本。
  • Git: 强烈建议安装，以便 Claude Code 能够执行版本控制操作。
• 网络: 需要稳定的互联网连接以与 Anthropic API 通信。

推荐一个免费梯子：

你可以通过以下命令检查 Node.js 版本：

1

node -v

1.2.2 安装 Claude Code 以及注册 AnyRouter

我们推荐使用 NPM 进行全局安装，因为它便于版本管理。

安装完成后，运行 claude --version 来验证安装是否成功。

直接访问官网就可以了，但建议第一次通过邀请链接注册，这样就有 100 美元。

1.2.3 账户认证与 API 密钥配置（重点）

1. 首先需要确定你安装了 Node.js 和 Git for Windows。

2.管理员权限运行 Powershell，然后更改 PowerShell 的执行策略。

1

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

3. 安装 Claude Code

1

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

4. 配置环境变量

这一步你如果不熟悉命令行的，可以直接在电脑界面操作。打开系统属性 → 高级 → 环境变量。添加两个环境变量。

1
2

ANTHROPIC_AUTH_TOKEN=网站里你自己的KEY
ANTHROPIC_BASE_URL=https://anyrouter.top

5. 确保你现在处于非中国节点，一般来说梯子都会有提供一个端口

6.前往 C:\Users\用户\.claude 默认是在这个位置，新增一个 settings.json，填入如下内容：

1
2
3
4
5
6

{
  "env": {
    "HTTP_PROXY": "http://127.0.0.1:5654",
    "HTTPS_PROXY": "http://127.0.0.1:5654"
  }
}

1.3 你的第一个会话

环境配置完毕，现在让我们启动 Claude Code，并让它为我们完成第一个任务。

1.3.1 启动与交互式界面

导航到你的项目根目录，然后启动 Claude Code：

1
2
3
4
5

# 1. 进入你的项目目录
cd /path/to/your/project

# 2. 启动 Claude Code
claude

启动后，你会看到一个交互式提示符 ›，这表示 Claude Code 已经准备好接收你的指令了。

1.3.2 第一个任务：让 Claude 理解你的项目

开启一个新会话后，最佳实践是先让 Claude 了解你的项目。这有助于它在后续任务中做出更精准的决策。尝试输入你的第一个指令：

1

› what does this project do?

Claude 会扫描项目文件，分析 package.json、README.md 和主要源代码文件，然后给出一个关于项目技术栈、主要功能和文件结构的摘要。

1.3.3 执行第一个代码修改并确认

现在，让我们给它一个具体的编码任务。例如，为一个简单的 Web 服务添加一个新的 API 端点。

1. 下达指令:

   1	› 新建一个贪吃蛇的游戏内容给我玩

批准后，Claude Code 会自动修改相应的文件并保存。恭喜你，你已经成功地与 Claude Code 完成了第一次协作！在下一章中，我们将深入探索其更强大的核心功能。

第二章：核心功能与实践指南 - 完整参考

在第一章我们完成了基础安装。现在，本章将作为一份内容全面且结构整合的参考指南，严格依据官方文档并结合实践经验，深入讲解 Claude Code 的各项核心功能。我们将逐一剖析命令行（CLI）、交互模式、强大的命令系统、权限管理乃至全自动开发流程，帮助您流畅地掌握并将其融入日常工作流。

2.1 CLI 参考：完整的命令行界面

命令行界面（CLI）是所有操作的起点。它不仅用于启动会话，还提供了丰富的标志和管道集成能力，以支持自动化和高级工作流

2.1.1 核心命令

以下是 Claude Code 的所有核心命令及其功能，为您提供完整的快速参考。

常用命令示例代码块：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 1. 启动与查询
# -------------------------------------------
# 直接启动交互式会话
claude

# 启动并立即提出一个问题
claude "请解释一下这个项目的整体架构"

# 2. 非交互式打印与管道
# -------------------------------------------
# 查询后直接打印结果并退出
claude -p "重构这个函数，让它更简洁"

# 将文件内容通过管道传给 Claude 进行分析
cat ./index.html | claude -p "总结这段代码的主要功能"

# 3. 会话管理
# -------------------------------------------
# 继续最近一次的会话
claude -c

# 通过指定 ID 恢复某个特定会话，并继续提问
claude -r "session_id_abc123" "我们继续上次那个功能的开发"

2.1.2 核心标志 (Flags)

使用这些命令行标志可以进一步定制 Claude Code 的行为。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# 1. 会话与模型配置
# -------------------------------------------
# 指定本次会话使用的模型 (opus 通常更强大)
claude --model opus

# 添加额外的工作目录，让 Claude 可以访问项目外的文件
claude --add-dir ../shared-library --add-dir /etc/configs

# 启用详细日志，用于调试
claude --verbose

# 2. 非交互式打印模式相关
# -------------------------------------------
# 使用打印模式，并指定输出为 JSON 格式
claude -p "分析这个文件" --output-format json

# 限制 AI 在非交互模式下的思考轮数
claude -p "帮我规划一下重构步骤" --max-turns 3

# 接收 stream-json 格式的输入
cat data.stream.json | claude -p "总结数据" --input-format stream-json

# 3. 权限与工具控制
# -------------------------------------------
# 以“规划模式”启动，Claude 只会输出计划，不执行命令
claude --permission-mode plan

# 临时允许执行 git log 和 git diff 命令
claude --allowedTools "Bash(git log:*)" "Bash(git diff:*)"

# 临时禁止执行 rm 命令
claude --disallowedTools "Bash(rm:*)"

# (请谨慎使用) 跳过所有权限确认提示
claude --dangerously-skip-permissions

2.2 交互模式：你的高效驾驶舱

进入交互模式（REPL）后，您就处在了与 Claude 协作的主要环境中。掌握其设计精妙的交互功能是提升效率的关键。

高效输入、快捷键与 Vim 模式

Claude Code 提供程序员们喜爱的 Cli 方式进行交互式开发。但是默认的命令行终端只能接受文本，这导致，如果我们希望向大模型提交一些图片时，无法在 Claude Code 命令行中提交图片，但在 Windows 系统下适配性不高，所以我们选择了一个开源的可视化项目来对后续的 Claude 进行操作，让我们能像 Cursor 一样可视化的与大模型进行对话

对于 Vim 用户，随时输入 /vim 即可开启 Vim 模式，所有熟悉的 h/j/k/l 移动、i/a/o 插入、dd/cc 删除/修改等操作都将被支持。

内置命令、上下文与内存管理

斜杠（/）命令是交互模式的精髓。使用 /help 查看所有可用命令。其中，上下文与内存管理 至关重要：

• /clear：当您准备开始一个全新的任务时，使用此命令 清空所有历史记录和上下文。这是一个保持 AI 专注和节省成本的最佳实践。
• /add-dir <path>：当任务需要引用其他目录的文件时，使用此命令精确地将它们加入上下文。
• /compact：当对话历史变得过长，但又不想完全丢失背景时，此命令可以智能地 总结之前的对话，保留关键信息。一个高级技巧是，可以将压缩后的内容保存为自定义命令，方便后续调用。
• # (井号快捷键)：在输入内容的开头使用 #，该行文本将被 自动追加到项目的长期记忆文件 CLAUDE.md 中。这是记录项目规范、关键决策或背景信息的绝佳方式。使用 /memory 命令可以随时编辑这个文件，# 仅是他的快捷方式

权限与执行模式

Claude Code 提供了不同的执行模式，以适应不同的工作场景：

• 手动确认模式 (manual)：默认模式。Claude Code 提出的任何需要执行的命令（如文件操作、git 命令），都需要你手动输入 y 确认。
• 自动接收模式 (auto)：命令将自动执行，无需手动确认。这在您信任其操作计划时能极大提高效率，但需要配合精细的权限管理使用。
• 规划模式 (plan)：在此模式下，Claude 只会进行任务规划和思考，输出行动步骤，但 不会实际执行任何代码或命令。适合在开发初期进行头脑风暴和任务拆解

Claude Code 允许您精确控制模型在生成响应时的“思考深度”或“推理等级”，以适应不同复杂度的任务。您可以在输入框旁边的图标处切换这些模式。

• Auto (自动)：让 Claude 自己决定。这是默认选项，模型会根据问题的复杂度自动选择合适的推理等级。
• Think (基本推理)：适用于简单的、常规性的任务，提供快速的基础响应。
• 深入思考 (更深入分析)：用于需要更深入分析和推理的场景。
• Think Harder (扩展推理)：针对复杂问题，需要进行广泛、多步骤的推理。
• Ultrathink (极限计算)：为最困难的任务保留，动用最大的计算资源进行深度思考和分析，响应时间可能更长。

2.3 深入核心：内置工具、自定义命令

为了真正发挥 Claude Code 的威力，我发现不能只停留在表面提问。我需要深入理解它的核心机制：它在底层默默为我工作的 内置工具，我为自己量身打造的 自定义命令

2.3.1 解密内置工具

我必须清楚，Claude Code 本身不是一个 RAG 系统，它不会“通读”我的整个项目。它更像一个聪明的指挥官，通过调用一系列内置工具来与我的代码和系统交互。熟悉这些工具，能让我更好地向它下达指令。

以下是几个核心内置工具：

2.3.2 自定义命令

这是我最喜欢的功能之一。与其每次都费力回忆复杂的指令流，我更愿意把它们封装成简单、可复用的自定义命令，这极大地提升了我的编程效率。

创建与使用

自定义命令的本质，就是我写好的一个 Markdown (.md) 指令文件。

• 项目命令：如果这个命令和当前项目强相关，我会把它放在项目根目录的 .claude/commands/ 下，这样团队成员也能用。
• 个人命令：如果是通用的个人习惯，我就会放在用户主目录的 ~/.claude/commands/ 下，这样在我所有的项目中都能调用。

核心功能

这些命令支持动态参数 ($ARGUMENTS)、文件引用 (@file) 和执行 Shell 命令 (!command)。

我还能在文件头部通过 YAML Frontmatter 定义元数据，我们可以预览 Claude Workbench 来理解这些参数该如何配置：

下面，我用一个自己最常用的 /commit 命令作为例子，来展示它有多强大：

1. 我先创建命令文件：

1
2
3
4
5

# 这是我的个人命令，所以我放在 home 目录下
mkdir -p ~/.claude/commands

# 创建 /commit 命令文件
touch ~/.claude/commands/commit.md

2. 然后，我把精心设计的指令流写进 commit.md 文件：
这个命令文件完美地结合了 Frontmatter、Bash 命令执行 (!) 和 结构化提示。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

---
description: "根据暂存区的代码变更(git diff --staged)，自动生成一条标准的 Conventional Commit message"
argument-hint: "[可选的 JIRA ticket ID]"
allowed-tools: Bash(git diff:*)
model: sonnet
---
## 任务

你的任务是基于以下的 git diff 信息，为我撰写一条高质量的 Conventional Commit message。

## 上下文：代码变更

​``` diff
! `git diff --staged`
​```
## 输出要求
1.  严格遵循 Conventional Commits 规范 (`<type>[optional scope]: <description>`)。
2.  Commit message 必须简洁、清晰地反映代码的变更意图。
3.  如果我提供了参数 (JIRA Ticket ID: `$ARGUMENTS`)，请将其追加到 message 的末尾，格式为 `(refs: $ARGUMENTS)`。
4.  **最终只输出完整的 commit message 字符串，不要包含任何额外的解释或 Markdown 格式。**

3. 最后，在交互模式中轻松使用：
当我写完代码并 git add 之后，就可以这样调用了：

1
2
3
4
5

# 不带参数，直接生成 commit message
/commit

# 带上 JIRA Ticket ID 作为参数，参数会通过 $ARGUMENTS 传入
/commit PROJ-123

更酷的是，我的自定义命令还能调用下一节要讲的 MCP 服务，将外部知识库的能力也无缝整合进来。

2.4 高级集成：配置权限

在我看来，这一步至关重要。给 Claude Code 访问我终端的权限，就像是给了它一把我数字工作室的万能钥匙。在让它自由发挥之前，我必须先设定好明确的规则，确保它不会意外地“砸坏”任何东西。这就是权限管理不可或缺的原因。

所有权限的配置都集中在一个地方：项目根目录下的 .claude/settings.json 文件。如果你的项目里还没有这个文件，别担心，自己创建一个就行。

1. 创建并理解 settings.json 文件

这个 JSON 文件的基本结构非常简单，主要包含两个关键字段：

1
2
3
4

{
  "allowed-tools": [],
  "disallowed-tools": []
}

• allowed-tools (白名单): 只有在这里列出的工具才能被执行。如果这个列表是空的，则默认所有工具都被允许（除了被黑名单禁止的）。
• disallowed-tools (黑名单): 在这里列出的工具绝对不能被执行。黑名单的优先级高于白名单。

工具的格式是 ToolName(pattern)，其中 * 是通配符，代表“任何字符”。例如 Bash(git:*) 表示允许所有以 git: 开头的 Bash 命令。

2. 我的常用配置模板

下面是我根据不同场景总结出的几个配置模板，你可以直接复制使用或作为参考。

模板一：安全的 Git 助手

这是我最常用的配置。我希望 Claude 能帮我处理 git 操作，但绝对不能让它推送代码或删除文件。

1
2
3
4
5
6
7
8
9
10
11
12

// .claude/settings.json
{
  "allowed-tools": [
    " Bash(git:*)",  // 允许所有 git 命令
    " edit:*",       // 允许编辑文件
    " grep:*"        // 允许搜索文件内容
  ],
  "disallowed-tools": [
    " Bash(git: push*)", // ...但是明确禁止 git push
    " Bash(rm:*)"       // 明确禁止 rm 删除命令
  ]
}

模板二：专注的代码审查员

当我只想让 Claude 帮我阅读和分析代码，而不做任何修改或执行任何命令时，我会使用这个配置。

1
2
3
4
5
6
7
8
9
10
11

// .claude/settings.json
{
  "allowed-tools": [
    " glob:*",   // 允许它查找文件
    " grep:*"    // 允许它阅读文件内容
  ],
  "disallowed-tools": [
    " Bash(*)",  // 禁止所有 Bash 命令
    " edit:*"    // 禁止所有文件编辑
  ]
}

模板三：全能但谨慎的开发者

这是一个更开放的配置，允许大部分开发操作，但依然保留了对最危险命令的控制。

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// .claude/settings.json
{
  "allowed-tools": [
    " Bash(*)",        // 允许所有 Bash 命令...
    " edit:*",
    " grep:*",
    " web-search:*"
  ],
  "disallowed-tools": [
    " Bash(rm:*)",     // ...除了 rm
    " Bash(sudo:*)",   // ...除了 sudo
    " Bash(mv:*)"      // ...除了 mv
  ]
}

3. 测试你的配置

配置完成后，最重要的一步就是测试！

1. 保存你的 .claude/settings.json 文件。
2. 在终端里重新启动 claude 会话，以确保新的配置被加载。
3. 尝试一个被允许的命令，比如 让它用 git status 查看一下当前状态。它应该能顺利执行。
4. 尝试一个被禁止的命令，比如 让它用 git push 推送代码。它应该会回复一条权限错误，告诉你这个操作被禁止了。

通过这样的设置和测试，我既能享受到 Claude Code 带来的强大自动化能力，又能放心地知道我的项目和系统是安全的。

2.5 模型上下文协议 (MCP) 指南

模型上下文协议 (Model Context Protocol, MCP) 是一个开放协议，它允许 Claude Code 与外部工具、数据库及各类数据源进行交互，极大地扩展了其能力。本指南将详细介绍如何配置、管理和使用 MCP 服务器。

推荐一个可以找到大部分常见 MCP 的站点：Smithery - Model Context Protocol Registry。该站点通常会提供 Claude Code 的一键安装命令，上手极其简单。因此，本章主要讲解核心概念和使用方法。

配置与管理 MCP 服务器

您可以通过 claude mcp 系列命令来添加、列出和删除 MCP 服务器。

连接不同类型的服务器

1. 添加 Stdio 服务器 (本地命令)

   这种方式通常用于将一个本地的可执行文件作为服务器。其基本语法为 claude mcp add <name> <command> [args...]。例如，要添加一个本地服务器，并同时传入环境变量 API_KEY，可以使用以下命令：

   1	claude mcp add my-local-server -e API_KEY=123 -- /path/to/server-cli arg1

2. 添加 SSE 服务器 (服务器发送事件)

   此方式用于连接支持 Server-Sent Events 的实时通信端点。添加时需指定传输协议为 sse。例如，要添加一个需要自定义 X-API-Key 标头的 SSE 服务器，命令如下：

   1	claude mcp add --transport sse api-server https://api.example.com/mcp -e X-API-Key=your-key

3. 添加 HTTP 服务器

   当您需要连接标准的 HTTP/HTTPS 端点时，可使用此方法。例如，添加一个需要 Bearer Token 身份验证的 HTTP 服务器：

   1	claude mcp add --transport http secure-server https://api.example.com/mcp -e Authorization="Bearer your-token"

服务器管理命令

管理已配置的服务器同样非常便捷。您可以使用以下命令来列出所有服务器、获取特定服务器的详细信息或删除一个服务器：

1
2
3
4
5
6
7
8

# 列出所有已配置的服务器
claude mcp list

# 获取名为 my-local-server 的服务器的详细信息
claude mcp get my-local-server

# 删除名为 my-local-server 的服务器
claude mcp remove my-local-server

此外，在 Claude Code 的交互会话中，您可以随时输入 /mcp 命令来查看所有服务器的连接状态、进行身份验证或管理。

理解服务器作用域 (Scope)

MCP 服务器可以在三个不同的作用域级别进行配置，这决定了其可用范围和共享方式。

作用域优先级：本地 (local) > 项目 (project) > 用户 (user)。如果不同作用域中存在同名服务器，Claude Code 会优先使用范围更小的配置。

1. 本地作用域 (Local)

   此作用域用于个人私有配置，配置仅在当前项目中对您自己可用，是包含敏感凭据或进行个人开发实验的理想选择。这是默认作用域，其配置存储在项目特定的用户设置中，不会被提交到版本控制。添加时，可以省略作用域参数或显式指定：

   1 2 3 4 5

   # 默认添加到本地作用域 claude mcp add my-private-server /path/to/server # 显式指定作用域为 local claude mcp add my-private-server -s local /path/to/server

2. 项目作用域 (Project)

   此作用域用于团队共享配置，可以确保所有团队成员使用相同的 MCP 工具。配置存储在项目根目录下的 .mcp.json 文件中，建议将其检入版本控制（如 Git）。添加时需使用 -s project 参数：

   1	claude mcp add shared-server -s project /path/to/server

   这会生成或更新项目根目录下的 .mcp.json 文件，示例如下：

   1 2 3 4 5 6 7 8 9

   { "mcpServers": { "shared-server": { "command": "/path/to/server", "args": [], "env": {} } } }

   注意：出于安全考虑，首次使用项目作用域的服务器时，Claude Code 会提示您进行批准。

3. 用户作用域 (User)

   此作用域用于跨项目的个人配置。一旦配置，该服务器在您机器上的所有项目中都可用，但仅对您自己私有。它非常适用于您在多个项目中频繁使用的个人工具或服务。添加时需使用 -s user 参数：

   1	claude mcp add my-global-util -s user /path/to/utility-script

实用案例

使用 @ 引用 MCP 资源

已连接的 MCP 服务器可以暴露“资源”（如 GitHub Issue、Jira Ticket 等）。您可以像引用文件一样，使用 @ 符号来引用它们。

1
2
3
4
5

# 在提示中输入 @ 会触发自动补全，列出文件和可用的 MCP 资源
> Can you analyze the bug described in @github:issue://123 and suggest a fix?

# 也可以同时引用多个资源
> Compare the user schema in @postgres:schema://users with the documentation in @docs:file://user-model

使用 / 执行 MCP 提示

MCP 服务器还可以将其功能暴露为斜杠命令，格式通常为 /mcp__servername__promptname。

1
2
3
4
5

# 输入 / 即可发现所有可用的命令，包括来自 MCP 的命令
> /mcp__github__list_prs

# 执行带参数的命令
> /mcp__jira__create_issue "Bug in login flow" high

Windows 环境配置指南

在 Windows 环境下配置全局 MCP 服务器时，由于系统对命令行处理方式的不同，需要对启动命令进行适配。

• 核心解决方案：修改 MCP 服务器的启动命令格式。

  • 原始格式 (Linux/macOS)：

    1	{"command": "npx","args": ["@upstash/context7-mcp"]}

  • Windows 兼容格式：

    1	{"command": "cmd","args": ["/c", "npx", "@upstash/context7-mcp"]}

• 配置步骤：

  1. 安装全局 MCP 服务器包
     首先，通过 npm 将所需的 MCP 服务器包安装到全局环境。

     1 2 3 4 5 6 7 8 9 10 11 12 13 14

     # 安装 Context7 - 上下文感知服务 npm install -g @upstash/context7-mcp # 安装 Memory - 知识图谱服务 npm install -g @modelcontextprotocol/server-memory # 安装 Sequential Thinking - 思维链服务 npm install -g @modelcontextprotocol/server-sequential-thinking # 安装 Playwright - 浏览器自动化服务 npm install -g @executeautomation/playwright-mcp-server # 安装 Shrimp Task Manager - 任务管理服务 npm install -g mcp-shrimp-task-manager

     提示：安装过程可能需要几分钟，请耐心等待。

  2. 清理现有 MCP 配置 (可选)
     为了避免冲突，可以先一次性移除可能存在的旧配置。

     1	claude mcp remove context7 memory sequential-thinking playwright shrimp-task-manager

     说明：如果某个服务器不存在，命令会显示相应信息，这是正常的。

  3. 添加 Windows 兼容的全局 MCP 配置
     使用 cmd /c 格式添加服务器，并指定 --scope user 以进行全局配置。

     1 2 3 4 5 6 7 8 9 10 11 12 13 14

     # 添加 Context7 服务器 claude mcp add context7 "cmd" "/c" "npx" "@upstash/context7-mcp" --scope user # 添加 Memory 服务器 claude mcp add memory "cmd" "/c" "npx" "@modelcontextprotocol/server-memory" --scope user # 添加 Sequential Thinking 服务器 claude mcp add sequential-thinking "cmd" "/c" "npx" "@modelcontextprotocol/server-sequential-thinking" --scope user # 添加 Playwright 服务器 claude mcp add playwright "cmd" "/c" "npx" "@executeautomation/playwright-mcp-server" --scope user # 添加 Shrimp Task Manager 服务器 claude mcp add shrimp-task-manager "cmd" "/c" "npx" "mcp-shrimp-task-manager" --scope user

第三章 上下文工程入门

3.1 理解上下文工程

3.1.1 我对上下文工程的认识

我学习到的上下文工程是一种全新的方法论。它的核心思想是为 AI 编码助手系统性地构建和提供完成任务所需的全部信息。这不仅仅是下达一个命令，而是为 AI 提供一个完整的“剧本”，确保它能高质量地完成端到端的开发任务。我相信，上下文工程的效果远胜于传统的提示工程，甚至比“凭感觉编码”的传统开发方式好上百倍。

3.1.2 上下文工程与提示工程的区别

我总结了两者的关键不同之处。传统的提示工程主要关注措辞和句式技巧，即“如何提问”，信息量有限，就像给 AI 留一张便签。而上下文工程则是一种范式转变，它致力于提供完整、体系化的上下文，包含文档、代码示例、项目规则、开发模式和验证机制等，更像是为 AI 写了一整本细节详尽的剧本。

3.1.3 为什么我认为上下文工程很重要？

通过学习，我认识到上下文工程能解决很多痛点。首先，它能减少 AI 出错，因为大多数 AI 智能体的失败根源在于上下文缺失，而非模型本身不行。其次，它能确保一致性，让 AI 严格遵循我项目中的代码结构、风格和开发习惯。再者，它能够支持复杂实现，因为只有在获得完整上下文后，AI 才能处理多步骤、高复杂度的功能开发。最后，它具备自纠能力，通过内置的验证闭环机制，AI 能够自行发现并修复错误，交付更可靠的代码。

3.2 上下文工程模板入门

为了快速上手，我将遵循以下步骤使用这个模板。

3.2.1 快速开始流程

1.克隆模板仓库

1
2

git clone https://github.com/coleam00/Context-Engineering-Intro.git
cd Context-Engineering-Intro

2.设置项目规则 (CLAUDE.md)
模板已提供默认规则，可以按需编辑 CLAUDE.md 来添加我项 目的专属指南，项目提供了一些预定义的提示词，我在此基础上汉化之后并添加上了一些优化

3.添加代码示例 (examples/)
（强烈推荐）将项目中的关键代码示例放入 examples/ 文件夹中。

4.创建初始功能需求 (INITIAL.md)
编辑 INITIAL.md，写下我想要实现的功能需求。

2. 生成详细的 PRP (产品需求提示)
   在 Claude Code 等工具中运行 /generate-prp 命令来生成开发蓝图。

   1	/generate-prp INITIAL.md

3. 执行 PRP 实现功能
   运行 /execute-prp 命令，让 AI 基于蓝图开始构建功能。

   1	/execute-prp PRPs/your-feature-name.md

3.2.2 模板结构解析

理解模板中各个文件和目录的作用对于脚手架来说至关重要：

1
2
3
4
5
6
7
8
9
10

context-engineering-intro/
├── .claude/                  # Claude Code 插件的配置目录
│   ├── commands/             # 存放自定义命令（如 generate-prp, execute-prp）
│   └── settings.local.json   # 本地权限设置
├── PRPs/                     # 存放所有产品需求提示 (PRP) 的地方
│   └── templates/            # 存放 PRP 的基础模板
├── examples/                 # 存放关键代码示例的目录，非常重要！
├── CLAUDE.md                 # AI 助手的全局规则配置文件
├── INITIAL.md                # 功能需求的初始描述模板
└── README.md                 # 项目说明文件

注意：当前模板暂未深入讲解与 RAG 或外部工具的集成，这部分内容会在后续单独推出。

3.3 我的核心工作流

我的主要工作将围绕以下几个文件的创建和命令的执行展开。这个工作流分为四个核心步骤，从设定全局规则到最终实现功能。

1. 设定全局规则：CLAUDE.md

CLAUDE.md 是我与 AI 协作的“法律”，它定义了整个项目的编码标准和规范。我可以在此文件中定义项目感知能力、代码结构约束（如文件大小）、测试要求（如单元测试模式和覆盖率）、编码风格（如语言偏好）以及文档规范等。我可以根据我的项目需求，随时定制这些规则。

2. 提出初始需求与提供高质量上下文：INITIAL.md 与 examples/

这是我向 AI 提出需求的起点。为了确保 AI 能准确理解需求，编写高质量的 INITIAL.md 至关重要。

• 功能 (Feature): 描述必须明确具体。例如，不说“写一个网页爬虫”，而应具体描述为“构建一个基于 BeautifulSoup 的异步爬虫，用于抓取电商网站的产品信息，需要支持速率限制，并将结果存入 PostgreSQL 数据库。”
• 示例 (Examples) 与 examples/ 文件夹: AI 在有具体代码模式可供参考时表现会出色得多，因此 examples/ 文件夹对我项目的成功至关重要。我应该在 示例 (EXAMPLES) 部分明确指出 AI 应参考 examples/ 文件夹中的哪个文件及何种模式。我提供的示例应尽量覆盖代码结构模式（如模块如何组织）、测试用例模式（如 mock 的使用方法）、集成模式（如 API 客户端的实现方式）等。
• 文档 (Documentation) 与其他注意事项 (Other considerations): 在这里提供所有必要的参考资源和必须注意的重要细节。

3. 生成开发蓝图：/generate-prp

在 INITIAL.md 准备就绪后，我只需运行 /generate-prp INITIAL.md 命令。系统将自动生成一份极其详细的“开发蓝图”——PRP (产品需求提示)，并存放在 PRPs/ 目录下。

该命令的内部工作流包括调研（分析代码库）、文档收集（抓取 API 文档）、蓝图生成（制作详细步骤）和质量评估（确保上下文完整性），最终形成一份包含了所有上下文、实现步骤、错误处理和测试要求的完整计划。

4. 执行蓝图并构建功能：/execute-prp

当 PRP 生成并确认无误后，我便可以运行 /execute-prp PRPs/your-feature-name.md 命令，让 AI 开始构建功能。

AI 助手会遵循该命令的内部流程：首先加载上下文，然后规划任务，接着逐步实现与验证结果，并通过持续迭代修复所有问题，直至所有验收标准都达成并交付最终成果。

第四章：高级技巧与工作流 - 释放 Agentic 潜力

在前三章中，我们掌握了与 Claude Code 进行交互的基础。现在，我们将进入一个全新的领域：从“对话式编程”升级为“流程化编排”。本章将揭示如何利用 Claude Code 的 Agentic 能力，执行测试驱动开发、处理复杂重构，并将其作为自动化工作流中的一个智能“齿轮”，与你现有的工具链无缝集成。这不仅是技巧的提升，更是开发思维的革新。

4.1 测试驱动开发（TDD）新范式

测试驱动开发（TDD）的“红-绿-重构”循环是保证软件质量的经典实践。Claude Code 不仅能遵循这一流程，更能极大地加速它，将开发者从繁琐的样板代码编写中解放出来，更专注于测试逻辑与功能实现。

简单来说，这个流程的用处在于：它将一个模糊的、开放性的“创造”任务，转变成了一个有精确、客观、可验证目标的“解题”任务。

没有 TDD 的情况：

如果你直接对 AI 说：“请写一个 urlSlugify 函数。” AI 就得去 猜测 你的具体需求。它需要猜你是否想处理大写字母？是否想处理多余的空格？遇到像 & 或 ? 这样的特殊符号该怎么办？AI 会根据它的通用训练数据给出一个“大概率正确”的答案，但不一定 100% 符合你的心意。

使用 TDD 的情况：

你通过编写失败的测试，等于给了 AI 一份精确无比的需求说明书。指令不再是“请写一个 XX 函数”，而是“请编写代码，让这三个一模一样的测试用例全部通过”。AI 的任务不再是开放式创作，而是针对性地解决一个已经定义好的问题。它知道，只要代码能让 "Hello World" 变成 "hello-world"，并且能处理好空格和特殊字符那两个例子，任务就算完成。目标清晰，没有歧义。

如果没有这些测试，AI 很可能只会实现最基本的功能，忽略了这些在实际应用中非常常见的“棘手”情况。通过先定义测试，你强制 AI 去考虑和处理这些细节，最终得到的代码自然比“一蹴而就”的版本要健壮得多。

TDD 的一个核心原则是：只编写能让当前失败的测试通过的最小量代码。

AI 在这个流程下，目标不是“写一个尽善尽美的函数”，而仅仅是“让测试通过”。这意味着它不会画蛇添足，去增加那些测试用例里没有要求的功能。这使得最终产出的代码非常精炼、专注，只做它该做的事，不多也不少。

4.1.1 Red: 让 Claude 编写失败的测试

TDD 的第一步是编写一个必然失败的测试，用以精确定义新功能的需求。你可以将这个任务完全委托给 Claude。

任务：为一个尚不存在的 urlSlugify 函数编写测试。

1. 下达指令：

   1 2 3 4 5

   创建一个新的 Jest 测试文件 'utils.test.js'。在其中，为一个名为 'urlSlugify' 的函数编写一个测试套件。包含以下测试用例： 1. 一个简单的字符串: "Hello World" -> "hello-world" 2. 一个带有额外空格的字符串: " leading and trailing spaces " -> "leading-and-trailing-spaces" 3. 一个带有特殊字符的字符串: "What's the #1 issue?" -> "whats-the-1-issue" 此测试必须因函数尚不存在而初步失败。

2. 批准生成测试代码：Claude 会生成 utils.test.js 文件，并等待你的批准。
3. 运行测试并确认失败：

   1	› /run npx jest utils.test.js

   结果将如预期般失败，通常会提示 ReferenceError: urlSlugify is not defined。现在，我们有了一个清晰的目标。

4.1.2 Green: 编写代码以通过测试

有了失败的测试作为精确的“靶子”，下一步就是让 Claude 编写代码来命中它。

1. 下达实现指令：

   1	› /edit 创建一个名为“utils.js”的文件，并实现“urlSlugify”函数，以使“utils.test.js”中的所有测试都能通过。

2. 审查并批准实现：Claude 会分析失败的测试用例，并编写出能够满足所有条件的函数实现。

   1 2 3 4 5 6 7 8 9 10

   // Claude 提议在 utils.js 中创建的代码 function urlSlugify(str) { return str .trim() // 处理前后空格 .toLowerCase() // 转换为小写 .replace(/[^a-z0-9\s-]/g, '') // 移除特殊字符，保留字母、数字、空格和连字符 .replace(/\s+/g, '-'); // 将一个或多个空格替换为单个连字符 } module.exports = { urlSlugify };

3. 再次运行测试并确认通过：

   1	› /run npx jest utils.test.js

   这一次，所有的测试都应该成功通过，终端会显示绿色的 PASS 状态。

4.1.3 Refactor: 迭代与优化

通过测试后，我们进入了重构阶段。我们可以要求 Claude 在不破坏测试的前提下，对代码进行优化或增加注释。

1
2

› “urlSlugify”的实现是正确的，但请通过更清晰地链接方法来重构它，以提高可读性。
另外，请添加一个 JSDoc 注释块来解释该函数的作用。然后，重新运行测试以确保没有破坏任何内容。

4.2 Claude Code中的Agent功能

Claude Code 的 Agent 功能，是其从单一助手进化为协同团队的核心。其本质是创建和使用预先配置的、具备特定个性的 AI 子代理（Sub-Agent）。每个代理都在其独立的上下文中运作，利用专属的工具集和系统提示，来高效处理特定领域的任务。

这种模式的主要优势在于：

• 上下文保护：Agent 的独立上下文避免了对主对话的干扰，让高级目标始终保持清晰。
• 专业知识：可以为 Agent 灌输特定领域的精细指令，使其在专业任务上表现远超通用模型。
• 可重用性：一次创建，即可在不同项目中复用，并与团队共享，确保工作流程的一致性。
• 灵活权限：能为不同 Agent 分配不同的工具权限，将高风险工具的使用范围限制在可控的专家 Agent 内。

4.2.1 Agent的核心类型

根据官方文档，Agent 主要可以理解为以下两种核心类型：

1. 动态 Sub-Agent

   • 创建方式：通过 Task 工具动态创建。
   • 核心定义：一种临时的、轻量级的 Claude 实例，用于处理即时并行任务。
   • 核心特点：每个 Agent 都有独立的上下文窗口；支持最多 10 个 Agent 并行运行；输出中会以不同agent的特殊颜色标明

2. 自定义 Sub-Agent

   • 创建方式：在 .claude/agents/ 文件夹中通过 Markdown 文件预先定义。
   • 核心定义：一种持久化、可复用且预先配置好的专业化 AI 代理。
   • 核心特点：通过 Markdown 文件配置内置专业知识；高度专业化，适合重复性领域任务；可通过特定语法在项目中随时调用。

本章后续内容主要围绕功能更强大的自定义 Sub-Agent展开。

4.2.2 创建与配置Agent

创建和配置一个自定义 Agent 的过程非常直观。

1. 创建 Agent (推荐方式)
最简单的方式是使用斜杠命令，它会提供一个交互式界面来引导你完成所有步骤：

1

/agents

在该界面中，你可以选择“创建新代理”，然后定义其属性。推荐的做法是先让 Claude 生成一个基础版本，然后你再进行迭代和微调，以达到最佳效果。

2. 配置文件位置
Agent 的配置文件存储为带有 YAML frontmatter 的 Markdown 文件。根据存储位置，分为两种级别：

• 项目级 Agent：位于 .claude/agents/ 目录，仅在当前项目中可用，优先级最高。
• 用户级 Agent：位于 ~/.claude/agents/ 目录，在所有项目中都可用，优先级较低。

3. 配置文件格式
每个 Agent 的定义都遵循以下结构：

1
2
3
4
5
6
7
8
9
10

---
name: agent-name
description: A natural language description of when this subagent should be used.
tools: Read, Grep, Glob, Bash # 可选，如果省略则继承所有工具
---

这里是你的 Agent 的系统提示 (System Prompt)。

你应该在这里详细定义该 Agent 的角色、能力、解决问题的方法、
需要遵循的具体指令、最佳实践以及任何约束。

• name: 代理的唯一标识，使用小写字母和连字符。
• description: 对代理用途的自然语言描述，这是 Claude 决定是否自动调用它的关键依据。
• tools: 该代理可使用的工具列表，以逗号分隔。

4.2.3 调用与管理Agent

1. 自动委托
   Claude Code 会根据你的指令和 Agent 的 description 字段，主动地将任务委托给最合适的专家。为了鼓励这种行为，你可以在 description 中使用“主动审查代码”、“在遇到错误时使用”等引导性短语。

2. 显式调用
   你也可以在指令中通过名字直接点名某个 Agent，进行强制调用。

   1 2	› 使用 @code-reviewer 子代理检查我最近的更改 › 请 @debugger 子代理调查这个错误

3. 链接调用 (Chaining Agents)
   对于复杂的工作流，你可以将多个 Agent 的任务链接起来。

   1	› 首先使用 @spec-analyst 代理分析需求，然后让 @backend-architect 代理设计架构

4.2.4 实战范例：Agent工作流

我们预定义的自定义agent文件目录如下，这是一系列已经预定义好的agent团队，可以去我的github仓库详细了解这个项目的使用情况，在博客里我就不列举了