Claude Code 完整使用手册 | Two Tigers Engineering

引言

Claude Code 是由 Anthropic 公司开发的 AI 驱动的代码编辑器和开发助手。它将强大的 Claude AI 模型深度集成到开发环境中，为开发者提供前所未有的智能编程体验。

与传统 IDE 的区别

传统 IDE（如 VS Code、IntelliJ IDEA）主要提供代码编辑、语法高亮、调试等基础功能，而 Claude Code 通过以下方式重新定义了开发体验：

自然语言交互：可以用中文或英文直接描述任务，无需记忆复杂的命令
智能理解：能够理解整个代码库的上下文，跨文件进行推理
自动化执行：从任务规划到代码实现，全自动完成
多工具集成：集成文件操作、命令执行、浏览器测试等全套开发工具
学习适应：随着使用，AI 会逐渐理解你的编码风格和项目需求

核心优势

效率提升：减少 70% 以上的重复编码工作
质量保证：AI 帮助发现潜在 bug 和优化机会
学习加速：实时解释代码逻辑，快速掌握新技术
跨领域能力：前端、后端、DevOps 全栈支持
安全可靠：本地化执行，代码不离开你的机器

适用场景

新项目快速原型开发
代码重构和优化
调试和问题排查
学习新技术栈
自动化脚本编写
文档生成和维护
测试用例编写

安装和配置

系统要求

操作系统：macOS、Linux、Windows（WSL2）
Node.js：v16 或更高版本（如使用 CLI 版本）
IDE：Visual Studio Code（推荐）或支持的编辑器
网络：稳定的互联网连接（访问 Anthropic API）

安装方式

方式一：VS Code 扩展（推荐）

打开 VS Code
在扩展商店搜索 “Claude Code”
点击安装
安装完成后，会在侧边栏看到 Claude Code 图标

方式二：CLI 版本

# 使用 npm 安装
npm install -g @anthropic-ai/claude-code

# 或使用 yarn
yarn global add @anthropic-ai/claude-code

# 验证安装
claude-code --version

初始化配置

首次使用需要配置 API 密钥：

访问 Anthropic Console
注册账号并登录
创建新的 API 密钥
在 Claude Code 设置中输入密钥

VS Code 配置方式：

打开设置（Cmd/Ctrl + ,）
搜索 “Claude Code”
在 “API Key” 字段粘贴你的密钥
选择模型（推荐 Claude 3.5 Sonnet）

CLI 配置方式：

# 配置 API 密钥
claude-code config set api_key YOUR_API_KEY

# 设置默认模型
claude-code config set model claude-3-5-sonnet-20241022

# 验证配置
claude-code config show

工作目录配置

Claude Code 会基于当前工作目录操作，建议在项目根目录启动：

# 进入项目目录
cd /path/to/your/project

# 启动 Claude Code（CLI 版本）
claude-code

# 或者在 VS Code 中打开项目文件夹
# 然后点击侧边栏的 Claude Code 图标

高级配置选项

{
  "claude-code.apiKey": "your-api-key",
  "claude-code.model": "claude-3-5-sonnet-20241022",
  "claude-code.maxTokens": 4096,
  "claude-code.temperature": 0.7,
  "claude-code.autoApprove": false,
  "claude-code.workspace": "/Users/yourname/projects"
}

工作模式详解

Claude Code 提供两种核心工作模式，每种模式适用于不同的开发阶段。

Plan Mode（规划模式）

适用场景：

新项目的架构设计
复杂功能的实现方案
代码重构策略制定
问题分析和诊断
需求理解和技术选型

工作流程：

用户提出任务需求
Claude Code 分析项目结构和上下文
使用探索工具（read_file、list_files、search_files）收集信息
制定详细的实现计划
与用户讨论和优化方案
用户确认后切换到 Act Mode 执行

可用的工具：

所有探索工具（read_file、list_files、search_files 等）
交互工具（ask_followup_question、plan_mode_respond）
代码定义查看（list_code_definition_names）

Act Mode（执行模式）

适用场景：

实现具体的功能代码
修改和优化现有代码
执行命令和运行测试
部署应用
调试和修复问题

工作流程：

接收明确的任务（可以是 Plan Mode 制定好的计划）
逐步执行，每个工具使用后等待确认
实时反馈执行结果
遇到问题时自动调整策略
完成后使用 attempt_completion 展示结果

可用的工具：

所有工具（包括执行类、文件操作类、浏览器操作类等）
完整的开发能力（创建、修改、删除、测试）

执行原则：

每次只使用一个工具
等待用户确认结果后再继续
遇到错误立即停止并分析
保持任务进度更新（task_progress）

模式对比

特性	Plan Mode	Act Mode
主要目标	理解和规划	实现和执行
工具范围	主要是探索工具	所有工具
交互方式	讨论式	步骤式执行
反馈机制	plan_mode_respond	工具执行结果
安全性	无修改风险	可能修改文件
适用阶段	开发前期	开发实施期

工作流最佳实践

典型开发流程：

需求理解（Plan Mode）

用户：我需要一个博客系统
Claude Code：分析需求 → 询问细节 → 制定技术方案

架构设计（Plan Mode）

Claude Code：[探索现有代码] → [设计目录结构] → [选择技术栈]

实施开发（Act Mode）

Claude Code：[创建文件] → [编写代码] → [测试验证]

迭代优化（Plan → Act）

发现问题 → Plan 分析 → Act 修复 → 重新测试

核心工具详解

Claude Code 提供了丰富的工具集，每个工具都有特定的用途和使用场景。

文件操作工具

read_file

功能：读取文件内容，用于了解现有代码或配置。

参数：

path（必需）：文件路径（相对于工作目录）
task_progress（可选）：任务进度清单

示例：

<read_file>
<path>src/main.js</path>
</read_file>

write_to_file

功能：创建新文件或完全覆盖现有文件内容。

参数：

path（必需）：目标文件路径
content（必需）：完整文件内容
task_progress（可选）：任务进度清单

重要规则：

必须提供完整的最终内容，不能截断
如果文件存在，会被完全覆盖
自动创建所需的目录
会触发编辑器的自动格式化

replace_in_file

功能：对现有文件进行精确的、局部的修改。

参数：

path（必需）：目标文件路径
diff（必需）：一个或多个 SEARCH/REPLACE 块
task_progress（可选）：任务进度清单

SEARCH/REPLACE 块格式：

------- SEARCH
[要查找的精确内容]
=======
[要替换的新内容]
+++++++ REPLACE

关键规则：

精确匹配：SEARCH 内容必须与文件中的内容完全一致
唯一性：SEARCH 块要足够唯一，只会替换第一个匹配项
简洁性：只包含需要改变的行和少量上下文
顺序性：多个 REPLACE 块按文件中出现顺序排列
完整性：必须包含完整的行，不能匹配部分行
格式正确：严格遵守标记格式（——-, =======, ++++++++ REPLACE）

项目探索工具

list_files

示例：

<list_files>
<path>src</path>
<recursive>true</recursive>
</list_files>

list_code_definition_names

列出目录顶层源代码文件中的定义（类、函数、方法等）。

示例：

<list_code_definition_names>
<path>src/components</path>
</list_code_definition_names>

search_files

使用正则表达式在目录中搜索文本模式。

参数：

path（必需）：搜索目录
regex（必需）：正则表达式模式
file_pattern（可选）：文件过滤模式（如 ‘*.js’）
task_progress（可选）：任务进度

示例：

<search_files>
<path>src</path>
<regex>function\s+(handleClick|handleSubmit)</regex>
<file_pattern>*.js</file_pattern>
</search_files>

命令执行工具

execute_command

在系统上执行 CLI 命令。

参数：

command（必需）：要执行的命令
requires_approval（必需）：是否需要用户确认（true/false）

示例：

<execute_command>
<command>npm install</command>
<requires_approval>false</requires_approval>
</execute_command>

使用提示：

优先使用复杂 CLI 命令而非创建脚本
使用非交互式标志（-y、–no-pager）
在非工作目录执行时使用 cd path && command
检查 “Actively Running Terminals” 避免重复启动服务

浏览器交互工具

browser_action

通过 Puppeteer 控制浏览器进行网页交互和测试。

参数：

action（必需）：操作类型（launch, click, type, scroll_down, scroll_up, close）
url（可选）：启动时使用的 URL
coordinate（可选）：点击坐标（x,y）
text（可选）：输入文本

示例：

# 启动浏览器
<browser_action>
<action>launch</action>
<url>http://localhost:3000</url>
</browser_action>

# 点击按钮
<browser_action>
<action>click</action>
<coordinate>450,300</coordinate>
</browser_action>

# 输入文本
<browser_action>
<action>type</action>
<text>Hello, Claude Code!</text>
</browser_action>

# 关闭浏览器
<browser_action>
<action>close</action>
</browser_action>

使用流程：

必须以 launch 开始
必须以 close 结束
每次操作等待截图和日志反馈
查看截图确定点击坐标
浏览器激活时只能使用 browser_action 工具
窗口分辨率：900x600

MCP 支持工具

use_mcp_tool

使用 MCP 服务器提供的工具。

参数：

server_name（必需）：MCP 服务器名称
tool_name（必需）：工具名称
arguments（必需）：JSON 格式的参数对象
task_progress（可选）：任务进度

access_mcp_resource

访问 MCP 服务器提供的资源。

参数：

server_name（必需）：MCP 服务器名称
uri（必需）：资源 URI
task_progress（可选）：任务进度

交互和辅助工具

ask_followup_question

向用户提问以收集完成任务所需的信息。

参数：

question（必需）：问题文本
options（可选）：2-5 个选项数组
task_progress（可选）：任务进度

attempt_completion

任务完成后向用户展示结果。

参数：

result（必需）：结果描述
command（可选）：展示结果的 CLI 命令
task_progress（必需）：完成的任务清单

plan_mode_respond

在 Plan Mode 中与用户对话。

参数：

response（必需）：响应文本
needs_more_exploration（可选）：是否需要更多探索
task_progress（可选）：任务进度

generate_explanation

生成 Git 代码差异的解释。

参数：

title（必需）：标题
from_ref（必需）：起始 Git 引用
to_ref（可选）：结束 Git 引用（默认为当前状态）

工具使用规范

参数说明

所有工具都遵循统一的参数规范：

必需参数：必须提供，否则工具无法执行
可选参数：根据需要提供，有默认值
参数类型：字符串、布尔值、数组、对象等
参数验证：系统会在执行前验证参数合法性

返回结果处理

工具执行后会返回以下信息：

执行状态：成功或失败
输出内容：工具的输出结果
错误信息：失败时的详细错误描述
建议操作：下一步应该做什么

处理原则：

等待用户确认后再继续
分析失败原因并调整策略
保留成功的中间结果
记录重要的输出信息

错误处理

常见错误类型：

参数错误：缺少必需参数、参数类型不匹配、参数值超出范围
文件错误：文件不存在、权限不足、文件被占用
命令错误：命令执行失败、依赖缺失、配置错误
网络错误：连接超时、API 限制、网络不可达

错误处理策略：

立即停止当前操作
分析错误原因
向用户报告问题
提供解决方案
等待用户指示

工具组合使用技巧

最佳实践：

顺序使用：按逻辑顺序使用工具
等待确认：每次只使用一个工具
保持上下文：相关操作保持 task_progress
避免重复：不要重复执行相同的工具
验证结果：每次工具使用后验证结果

实战案例

案例 1：创建 React 组件库

需求：创建一个可复用的 React UI 组件库，包含 Button、Input 等组件。

实施步骤：

初始化项目：mkdir react-ui-lib && npm init -y
安装依赖：npm install react react-dom
创建 Button 组件（支持多种 variant 和 size）
创建 Input 组件（支持验证和错误提示）
创建导出文件
编写使用示例

关键代码：

// Button.jsx
const Button = ({ children, onClick, variant = 'primary', size = 'medium', disabled = false }) => {
  const baseStyles = 'rounded font-semibold transition-all duration-200';
  const variants = {
    primary: 'bg-blue-500 text-white hover:bg-blue-600',
    secondary: 'bg-gray-200 text-gray-800 hover:bg-gray-300',
    danger: 'bg-red-500 text-white hover:bg-red-600'
  };
  return (
    <button onClick={onClick} disabled={disabled} className={`${baseStyles} ${variants[variant]}`}>
      {children}
    </button>
  );
};

案例 2：重构现有代码库

需求：将一个大型 JavaScript 项目重构为 TypeScript，添加类型安全。

实施步骤：

使用 list_files 和 read_file 探索项目结构
使用 search_files 找到所有导出的函数和类
创建 TypeScript 配置文件
逐个文件添加类型定义
修复类型错误
更新构建脚本

案例 3：开发和部署 Web 应用

需求：创建一个全栈 To-Do 应用（前端 React + 后端 Node.js）。

实施步骤：

Plan Mode：设计架构和技术栈
Act Mode：
- 创建前端项目（React + Vite）
- 创建后端项目（Express + MongoDB）
- 实现前端组件
- 实现后端 API
- 使用 browser_action 测试前端
- 使用 execute_command 运行测试
部署：使用 Docker 容器化部署

案例 4：调试和修复 Bug

需求：修复一个生产环境中的性能问题。

实施步骤：

使用 read_file 查看相关代码
使用 search_files 搜索可能的性能瓶颈
分析代码逻辑，找出问题
使用 replace_in_file 修复代码
使用 execute_command 运行性能测试
验证修复效果

案例 5：自动化测试和 CI/CD

需求：为项目添加完整的测试套件和 CI/CD 流程。

实施步骤：

配置测试框架（Jest、Cypress）
编写单元测试
编写集成测试
使用 E2E 测试（browser_action）
配置 GitHub Actions
实现自动化部署

最佳实践

任务分解策略

原则：将大任务分解为小而明确的步骤

示例：

❌ 错误：“创建一个完整的电商网站”
✅ 正确：“创建产品列表页面组件”

技巧：

每个步骤应该能在 2-5 个工具调用内完成
步骤之间要有清晰的依赖关系
保持任务进度更新（task_progress）

上下文管理

重要原则：

一次性传递信息：尽可能在首次描述时提供所有相关信息
使用示例：提供代码示例来说明需求
明确目标：清楚地说明你想要达到的结果

示例：

❌ 模糊："优化这个函数"
✅ 清晰："将 quickSort 函数的时间复杂度从 O(n²) 优化到 O(n log n)"

性能优化

技巧：

避免重复读取：已读取的文件内容会被记住
批量操作：使用一个 replace_in_file 包含多个 SEARCH/REPLACE 块
精确搜索：使用具体的正则表达式，避免模糊匹配
限制范围：在特定目录中搜索，而非整个项目

安全注意事项

重要提醒：

确认危险操作：删除文件、修改配置等需要显式确认
备份重要数据：在重大修改前创建备份
审查生成的代码：特别是涉及安全和权限的代码
使用版本控制：确保所有修改都在 Git 中追踪

工作流建议

推荐的开发流程：

探索阶段（Plan Mode）

list_files → read_file → search_files → 制定计划

实施阶段（Act Mode）

write_to_file/replace_in_file → execute_command → 测试验证

验证阶段

browser_action → 检查结果 → 反馈用户

完成阶段

attempt_completion → 展示结果 → 提供后续步骤

高级特性

MCP（Model Context Protocol）详解

MCP 是一个开放协议，允许 Claude Code 连接到外部服务和数据源。

MCP 的优势：

访问实时数据（天气、股票、新闻）
集成第三方服务（GitHub、GitLab、Jira）
自定义工具和资源
扩展 Claude Code 的能力

使用 MCP 服务器：

# 使用 GitHub MCP 创建 Issue
<use_mcp_tool>
<server_name>github.com/modelcontextprotocol/servers/tree/main/src/github</server_name>
<tool_name>create_issue</tool_name>
<arguments>
{
  "owner": "octocat",
  "repo": "hello-world",
  "title": "Found a bug",
  "body": "I'm having a problem with this.",
  "labels": ["bug"]
}
</arguments>
</use_mcp_tool>

自定义 MCP 服务器

创建步骤：

创建 MCP 服务器项目
定义工具和资源
实现服务器逻辑
配置 Claude Code 连接

示例服务器结构：

// server.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server({
  name: 'my-custom-server',
  version: '1.0.0'
});

// 定义工具
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'calculate',
      description: 'Perform calculations',
      inputSchema: {
        type: 'object',
        properties: {
          expression: { type: 'string' }
        }
      }
    }
  ]
}));

// 启动服务器
const transport = new StdioServerTransport();
await server.connect(transport);

工作流自动化

使用 Claude Code 自动化重复任务：

创建任务模板
使用 ask_followup_question 收集参数
执行标准化的操作序列
生成报告

示例：自动化代码审查流程

1. 搜索 TODO 注释
2. 检查代码复杂度
3. 验证测试覆盖率
4. 生成审查报告

多项目管理

策略：

工作区隔离：为每个项目使用独立的工作目录
共享配置：使用全局配置文件共享通用设置
项目特定配置：每个项目有自己的配置覆盖
快速切换：使用工作区列表快速切换项目

与其他工具集成

可集成的工具：

Git：使用 execute_command 执行 git 操作
Docker：自动化容器构建和部署
CI/CD：集成 GitHub Actions、GitLab CI
测试框架：Jest、Cypress、Playwright
数据库：MongoDB、PostgreSQL、Redis

集成示例：

# Git 集成
<execute_command>
<command>git add . && git commit -m "feat: add new feature" && git push</command>
<requires_approval>true</requires_approval>
</execute_command>

# Docker 集成
<execute_command>
<command>docker build -t myapp:latest . && docker run -p 3000:3000 myapp:latest</command>
<requires_approval>true</requires_approval>
</execute_command>

常见问题（FAQ）

安装和配置问题

Q1: 安装后找不到 Claude Code 扩展？

确保使用的是最新版本的 VS Code
检查扩展是否被禁用
尝试重新安装扩展
重启 VS Code

Q2: API 密钥如何安全存储？

VS Code: 存储在设置中，受加密保护
CLI: 存储在 ~/.config/claude-code/config.json
环境变量: 使用 ANTHROPIC_API_KEY 环境变量

使用技巧问题

Q3: 如何让 Claude Code 理解我的编码风格？

在对话中提供代码示例
明确说明你的偏好（如命名约定、代码组织）
提供 linting 配置文件
给出反馈，纠正不符合风格的地方

Q4: 如何提高 Claude Code 的理解能力？

提供清晰的上下文和背景
使用具体的例子
分步骤描述任务
保持对话连贯，避免频繁切换话题

性能问题

Q5: 响应速度慢怎么办？

检查网络连接
减少单次任务复杂度
使用更高效的工作流
考虑使用更快的 Claude 模型

Q6: Token 使用量过大？

避免重复读取大文件
使用更精确的搜索
分批次处理大任务
使用 task_progress 保持上下文

限制和注意事项

Q7: Claude Code 有什么限制？

单次工具调用需要等待用户确认
文件大小有限制（大文件可能被截断）
不能访问本地文件系统外的资源（除非使用 MCP）
需要网络连接访问 API

Q8: 可以同时处理多个项目吗？

可以，但建议一次专注于一个项目
使用多个 VS Code 工作区
每个项目使用独立的工作目录

调试问题

Q9: 如何调试 Claude Code 的问题？

查看错误信息和日志
检查工具参数是否正确
验证文件路径和权限
使用 execute_command 手动测试命令
启用调试模式（如果可用）

Q10: 代码生成不符合预期怎么办？

提供更详细的描述
给出代码示例
明确说明你的需求
使用 replace_in_file 进行精确修改
提供反馈，让 Claude Code 学习

总结和展望

核心要点回顾

Claude Code 是一个革命性的 AI 驱动开发工具，它通过以下方式改变了开发体验：

自然语言交互：用中文或英文直接描述需求
智能代码理解：深度理解代码库上下文
自动化执行：从规划到实现的全流程自动化
丰富工具集：涵盖文件操作、命令执行、浏览器测试等
可扩展性：通过 MCP 连接外部服务和数据源

关键成功因素

要有效使用 Claude Code，需要掌握以下关键点：

理解工作模式：合理使用 Plan Mode 和 Act Mode
掌握工具使用：熟悉每个工具的参数和最佳实践
有效沟通：清晰、具体地描述任务
迭代优化：通过反馈不断改进
安全意识：审查生成的代码，保护重要数据

未来发展方向

Claude Code 正在快速发展，未来的发展方向包括：

更强的代码理解能力：更深层次的代码分析和推理
更多预集成工具：内置更多常用开发工具和服务
更好的协作功能：团队协作和代码审查支持
性能优化：更快的响应速度和更低的资源消耗
更丰富的生态系统：更多 MCP 服务器和集成

学习资源

官方资源：

社区资源：

GitHub 讨论区
Discord 社区
Stack Overflow 标签
博客和教程

实践建议：

从简单任务开始，逐步提高复杂度
阅读官方文档和示例
参与社区讨论
分享你的经验和最佳实践
持续学习和探索新功能

结语

Claude Code 不仅仅是一个工具，它是开发方式的革新。通过将 AI 深度集成到开发流程中，它让开发者能够：

专注于创意：AI 处理重复性工作
提高质量：AI 帮助发现问题和优化
加速学习：AI 实时解释和指导
提升效率：AI 自动化繁琐的任务

随着技术的不断进步，Claude Code 将变得更加智能和强大。掌握它，就是掌握了未来的开发方式。

开始你的 Claude Code 之旅吧！

本文档持续更新中，如有问题或建议，欢迎反馈。

引言

与传统 IDE 的区别

核心优势

适用场景

安装和配置

系统要求

安装方式

方式一：VS Code 扩展（推荐）

方式二：CLI 版本

初始化配置

工作目录配置

高级配置选项

工作模式详解

Plan Mode（规划模式）

Act Mode（执行模式）

模式对比

工作流最佳实践

核心工具详解

文件操作工具

read_file

write_to_file

replace_in_file

项目探索工具

list_files

list_code_definition_names

search_files

命令执行工具

execute_command

浏览器交互工具

browser_action

MCP 支持工具

use_mcp_tool

access_mcp_resource

交互和辅助工具

ask_followup_question

attempt_completion

plan_mode_respond

generate_explanation

工具使用规范

参数说明

返回结果处理

错误处理

工具组合使用技巧

实战案例

案例 1：创建 React 组件库

案例 2：重构现有代码库

案例 3：开发和部署 Web 应用

案例 4：调试和修复 Bug

案例 5：自动化测试和 CI/CD

最佳实践

任务分解策略

上下文管理

性能优化

安全注意事项

工作流建议

高级特性

MCP（Model Context Protocol）详解

自定义 MCP 服务器

工作流自动化

多项目管理

与其他工具集成

常见问题（FAQ）

安装和配置问题

使用技巧问题

性能问题

限制和注意事项

调试问题

总结和展望

核心要点回顾

关键成功因素

未来发展方向

学习资源

结语

最近文章

分类

标签

友情链接

其它