# Claude Code 使用指南

# Claude Code 使用指南

> 基于 Claude Code 源码深度分析，写给不会写代码但想用好 Claude Code 的你。

---

## 一、安装与配置

### 安装

Claude Code 是一个 CLI 工具，装在终端里用。

```bash
# 推荐方式
npm install -g @anthropic-ai/claude-code

# 装完检查
claude --version
```

要求：Node.js 18+、npm（或者 yarn/pnpm）。

**Windows 用户**：Claude Code 本质上跑在终端里，建议用 WSL2（Windows Subsystem for Linux），体验最好。PowerShell 也支持，但部分功能（如 Worktree）在 Linux/macOS 上更顺。

### 登录

```bash
claude login
```

两种方式：
- **Anthropic 账号**：用 OAuth 登录（需要 Pro/Max 订阅），能用语音模式等高级功能
- **API Key**：直接输入 API Key，按用量计费

### 初始配置

启动后可以用几个关键配置：

```bash
# 切模型
/model

# 切主题（暗色/亮色）
/theme

# 配置输出风格
/config
```

**输出风格（Output Style）** 可以自定义。在 `.claude/output-styles/` 目录下放一个 markdown 文件就行：

```markdown
---
name: concise
description: 简洁模式，只给关键信息
---
你的回答要简洁，不要多余解释。
```

然后通过 `/config` 切换。

### 关键环境变量

| 变量 | 作用 |
|------|------|
| `ANTHROPIC_API_KEY` | API Key（不走 OAuth 的话需要） |
| `ANTHROPIC_BASE_URL` | 自定义 API 地址 |
| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 设为 `true` 禁用后台任务 |
| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 最大输出 token 数 |
| `DISABLE_TELEMETRY` | 设为 `true` 关掉遥测 |

---

## 二、基本用法

### 启动和对话

```bash
# 进入交互模式
claude

# 直接提问（非交互）
claude "帮我看看这个项目怎么跑起来"

# 指定目录
claude --workdir /path/to/project
```

进入交互模式后，直接打字就行。Claude Code 会自己读文件、搜代码、跑命令。

### 8 个必知 Slash Command

| 命令 | 干嘛用 | 使用场景 |
|------|--------|----------|
| `/init` | 自动扫描项目，生成 CLAUDE.md | 新项目第一次用 Claude Code |
| `/model` | 切换模型 | 任务复杂用大模型，简单用小模型省钱 |
| `/config` | 打开配置面板 | 改模型、改主题、改输出风格 |
| `/cost` | 查看本次会话消耗 | 看花了多少钱 |
| `/status` | 查状态（版本、模型、连接） | 出问题时先看这个 |
| `/review` | 代码审查（需要 GitHub PR） | 有人提了 PR，让 Claude 看看 |
| `/theme` | 切暗色/亮色主题 | 护眼 |
| `/clear` | 清空对话上下文 | 对话太长、跑偏了，重开 |

**怎么用 `/init`**：

进到你的项目目录，跑 `/init`。它会自动：
1. 读你的 package.json / Cargo.toml / pyproject.toml 等，搞清楚项目结构
2. 找到构建、测试、lint 命令
3. 扫描现有的 AI 编码规则（.cursor/rules、.github/copilot-instructions.md 等）
4. 生成 `CLAUDE.md` 文件

它还会问你要不要同时设 Skills 和 Hooks。选完之后会问你项目细节，最后生成一套完整的配置文件。

### 文件操作最佳实践

Claude Code 内置了这些文件工具：

- **FileRead**：读文件
- **FileEdit**：编辑文件（精确替换，不会动到不相关的内容）
- **FileWrite**：写新文件
- **Glob**：按模式搜文件（类似 `find`）
- **Grep**：按内容搜（类似 `grep`）
- **Bash**：跑 shell 命令

**实操建议**：

1. **让 Claude 自己探索**。你不用告诉它文件在哪，直接说"帮我看看这个项目的认证逻辑怎么写的"，它会自己搜
2. **一次改一个文件**。改动涉及多文件时，Claude 会自己排序处理，但你要确认
3. **大文件要拆着看**。Claude 一次读一个文件，对大文件会分段处理，不用你操心

---

## 三、进阶技巧

### Plan Mode（规划模式）

这是 Claude Code 最重要的进阶功能。

**什么时候用**：改一个东西之前，先让 Claude 想清楚方案，你同意了再动手。

**怎么触发**：

直接说：
> "先帮我规划一下怎么加登录功能"

或者让 Claude 自己判断。源码里写了，以下情况它会自动进入 Plan Mode：
- 添加新功能（不止改一行）
- 有多种实现方式需要选
- 改动涉及多个文件
- 需要做架构决策
- 需求不明确需要先探索

**Plan Mode 里发生了什么**：
1. Claude 用 Glob/Grep/Read 探索你的代码库
2. 理解现有架构和模式
3. 设计实现方案
4. 给你看方案，你批准后再执行

**你也可以手动进 Plan Mode**：
> "进 Plan Mode"

**退出**：Claude 给你方案后，说"同意，开始做"就行。

### 子 Agent（分任务并行）

Claude Code 可以把自己拆成多个"分身"同时干活。

**怎么用**：你不需要手动触发，Claude 会在需要时自动派子 Agent。

比如你说"帮我整理这个项目的所有测试文件"，Claude 可能会：
1. 一个子 Agent 去找所有测试文件
2. 一个子 Agent 去分析测试覆盖率
3. 主 Agent 汇总结果

**源码里的关键细节**：
- 子 Agent 和主 Agent 共享上下文缓存（所以 "fork" 模式很便宜）
- 你可以在终端面板看到所有子 Agent 的运行状态
- 子 Agent 完成后会自动通知主 Agent

**你不手动操作**，但知道这个机制存在就行——它让复杂任务快很多。

### Worktree 隔离

这是个神器。你可以在一个 Git 仓库里同时开多个"工作区"，互不干扰。

**场景**：你在做功能 A，突然要修一个紧急 bug。不用 stash，直接开个 Worktree。

**怎么触发**：

```bash
# 进入 worktree 模式
# 直接跟 Claude 说：
"帮我开一个 worktree 做 bugfix"
```

**底层逻辑**（从源码看）：
- 用 `git worktree` 创建隔离的工作目录
- 每个 worktree 有独立的分支
- Claude 自动切换到新 worktree 的目录
- 完成后可以退出 worktree 回到主分支

**怎么退出**：
> "退出 worktree"

### Memory 记忆系统

Claude Code 有自己的"记忆"系统，分两层：

**1. CLAUDE.md（项目级记忆）**

放在项目根目录。每次开新会话都会自动加载。用来告诉 Claude 这个项目的基本情况。

示例：

```markdown
# CLAUDE.md

This file provides guidance to Claude Code when working with code in this repository.

## Build & Test
- 构建：`npm run build`
- 测试：`npm test`
- 单个测试：`npm test -- --grep "test name"`

## 代码风格
- 用 TypeScript，严格模式
- 组件用 PascalCase
- 优先用 async/await，不用 callback

## 常见坑
- 数据库迁移要先备份
- 别直接改 production 的 env 变量
```

**2. CLAUDE.local.md（个人级记忆）**

也在项目根目录，但加进 `.gitignore`，不提交。放你个人的偏好：

```markdown
# CLAUDE.local.md

- 我是产品经理，不太懂代码，解释的时候多说原理
- 我喜欢简洁的回答，不要啰嗦
- 测试环境 URL：http://staging.example.com
```

**3. MEMORY.md + ~/.claude/（全局记忆）**

在 `~/.claude/` 目录下放 MEMORY.md 和其他记忆文件。这些跨项目生效。

**源码关键限制**：
- MEMORY.md 最多 200 行、25KB
- 超了会自动截断并警告
- 记忆文件会按相关性自动选择加载（最多 5 个）

---

## 四、效率优化

### Prompt 怎么写

源码里对 Prompt 有明确的设计逻辑。关键是：**给足上下文，说清楚你要什么**。

**好的 Prompt**：
```
帮我在 src/auth/ 目录下实现 JWT 登录功能。
要求：
1. 登录接口 POST /api/login
2. 返回 JWT token，过期时间 24 小时
3. 密码用 bcrypt 加密
4. 写对应的单元测试
```

**差的 Prompt**：
```
帮我写个登录
```

**Prompt 黄金法则**：
- 提供文件路径，别让 Claude 瞎找
- 说清楚输入输出格式
- 列出约束条件
- 如果有多步，列出来

### 工具调用的正确姿势

Claude Code 有一套工具自动选择逻辑。你不用指定用哪个工具，但知道它在干嘛有帮助：

| 你说的话 | Claude 会用的工具 |
|----------|-------------------|
| "看看这个文件写了啥" | FileRead |
| "找一下所有 import React 的文件" | Grep |
| "跑一下测试" | Bash |
| "帮我写个新的组件" | FileWrite |
| "改一下这行的逻辑" | FileEdit |

**Tips**：
- 说"跑一下"就跑命令，不用你说"用 Bash 工具执行 xxx"
- Claude 跑的命令你可以看到，在终端里有实时输出
- 命令有超时机制，默认几分钟，超时会自动停止

### 上下文压缩

对话太长时，Claude 会自动压缩上下文（compact）。

**发生了什么**：
- 之前的对话摘要被保留
- 详细工具调用记录被清掉
- 新的对话基于摘要继续

**你也可以手动触发**：
```bash
/compact
```

**注意事项**：
- 压缩后有些细节会丢失，Claude 可能会"忘记"一些上下文
- 压缩前如果要存什么信息，先写到文件里
- 复杂任务建议压缩前先检查一下进度

### TodoWrite 任务管理

Claude Code 内置了任务清单工具。处理复杂任务时，它会自动创建 todo list。

**什么情况会触发**（源码定义）：
- 任务有 3 个以上步骤
- 你一次给了多个要求
- 任务涉及多文件改动

**你能看到的**：终端里会显示任务进度，每个任务有状态（pending / in_progress / completed）。

**你能做的**：
- 说"现在做到哪了？"——它会告诉你当前进度
- 说"跳过这个任务"——它会标记为跳过
- 说"重新开始"——它会重置 todo list

---

## 五、安全与权限

### 权限模式

Claude Code 有几个权限级别：

| 模式 | 行为 |
|------|------|
| `default` | 每次跑命令、写文件都要你确认 |
| `plan` | Plan Mode，只读探索，不执行改动 |
| `auto` | 自动批准低风险操作（仅读文件、搜代码） |

**建议**：默认用 `default`。等你熟悉了再调。

### Bash 命令安全

Claude Code 对 Bash 命令有自动安全分类：

**自动允许的**：
- 只读命令：`cat`、`ls`、`grep`、`find`、`git status`、`git log` 等
- 查看类命令不会要你确认

**需要确认的**：
- 写文件：`echo "xxx" > file`
- 修改 Git：`git commit`、`git push`
- 安装包：`npm install`、`pip install`
- 删除文件：`rm`

**绝对禁止的**（Claude 自己也知道）：
- 跳过 Git hooks：`--no-verify`、`--no-gpg-sign`
- 交互式命令：`git rebase -i`

### 怎么配置 allow/deny

在 `.claude/settings.json`（项目级）或 `~/.claude/settings.json`（全局级）配置：

```json
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "FileRead(*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *:*)"
    ]
  }
}
```

**语法**：
- `Bash(命令前缀:*)`：允许/拒绝某类命令
- `FileRead(*)`：允许读所有文件
- `FileEdit(*)`：允许编辑所有文件

---

## 六、高级功能

### MCP 集成

MCP（Model Context Protocol）让你给 Claude Code 接入外部工具。

**怎么用**：

```bash
# 添加一个 MCP 服务器
/mcp add

# 管理已有的 MCP 服务器
/mcp
```

MCP 服务器可以提供：
- 外部 API 调用（比如查数据库、查文档）
- 自定义工具
- 远程资源访问

**常见的 MCP 用法**：
- 连接 Sentry 看错误日志
- 连接 Linear/Jira 管理任务
- 连接自定义的内部工具

### 技能和插件系统

**Skills（技能）** 是 Claude Code 的扩展机制。

**内置 Skills**（从源码看）：
- `/commit`：自动分析改动，生成 commit message
- `/review`：代码审查（对接 GitHub PR）
- `/commit-push-pr`：一条龙提交、推送、创建 PR

**怎么安装插件**：

```bash
/plugin install frontend-design@claude-plugins-official
/plugin install playwright@claude-plugins-official
```

**怎么创建自定义 Skill**：

在 `.claude/skills/` 目录下建一个文件夹：

```
.claude/skills/my-skill/
  SKILL.md
```

SKILL.md 内容：

```yaml
---
name: my-skill
description: 我的自定义技能
---

## Instructions
当你需要做 xxx 时，按以下步骤执行：
1. ...
2. ...
```

然后你可以在对话里直接 `/my-skill` 调用它。

**`/init` 也能帮你建 Skill**——它会根据你的项目自动建议一些有用的 Skills。

### 语音模式

语音模式需要 Anthropic OAuth 登录（API Key 不支持）。

**怎么判断能不能用**：
- 需要 Anthropic 账号登录（不是 API Key）
- 语音走的是 claude.ai 的 voice_stream 接口
- 功能由 GrowthBook feature flag 控制（可能在逐步开放中）

**如果能用**：
```bash
/voice
```

会进入语音对话模式。

### 自定义输出风格

你可以在 `.claude/output-styles/` 目录下创建自己的输出风格文件：

```markdown
---
name: 产品经理
description: 用产品语言回答，不要代码细节
---
你是产品经理视角的助手。回答时：
1. 用业务语言，不要技术术语
2. 重点讲用户价值和业务逻辑
3. 如果必须涉及技术，用比喻解释
4. 列出关键决策点和风险
```

然后通过 `/config` 切换。

**源码里的特性**：
- `keep-coding-instructions`：设为 `true` 可以保留代码相关指令
- 支持项目级（`.claude/output-styles/`）和用户级（`~/.claude/output-styles/`）

---

## 七、常见问题与踩坑

### 1. Claude 跑的命令出错了，怎么办？

看终端输出的错误信息，直接把错误复制粘贴给 Claude：

> "报错了，错误信息是 xxx"

它会自己分析原因并修复。

### 2. 上下文太长怎么办？

用 `/compact` 压缩上下文，或者 `/clear` 清空重开。

如果任务还没完成，先把进度写到文件里（比如 TODO.md），新会话里让 Claude 读文件接着做。

### 3. Claude 改了不该改的文件？

用 git 看 diff：`git diff`，然后告诉 Claude：

> "你不该改 src/config.ts，还原它"

Claude 可以用 git 还原。

### 4. 怎么让 Claude 不每次都确认命令？

在 `.claude/settings.json` 里配置 permissions allow：

```json
{
  "permissions": {
    "allow": ["Bash(npm test:*)", "Bash(npm run lint:*)"]
  }
}
```

### 5. CLAUDE.md 该写什么？

只写"不写就会让 Claude 犯错"的信息。不要写：
- 每个文件的说明（Claude 能自己看）
- 通用编程建议（"写好注释"）
- README 里已有的内容

要写：
- 非标准的构建/测试命令
- 不同于语言默认的代码规范
- 常见坑和注意事项
- 项目特殊约定

### 6. 多个项目目录怎么管理？

Claude Code 会自动向上查找 CLAUDE.md。在 monorepo 里，可以在子目录放各自的 CLAUDE.md，Claude 在那个目录工作时会自动加载。

### 7. 子目录的项目找不到 CLAUDE.md？

不会。Claude Code 会沿目录树向上搜索 CLAUDE.md。只要在项目根目录放了就行。

### 8. 怎么省钱？

- 简单任务用小模型（`/model` 切换）
- 不需要上下文时用 `/clear` 清空
- 用 `/cost` 随时看消耗
- 非编码任务考虑直接用 Claude.ai

### 9. /init 生成的 CLAUDE.md 不满意？

直接跑 `/init` 重来。源码里写了，它会先读已有的 CLAUDE.md，提出具体改进，不会直接覆盖。

### 10. 怎么用 Hooks（自动执行的命令）？

在 `.claude/settings.json` 里配置：

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hook": "npx prettier --write $CLAUDE_FILE"
      }
    ]
  }
}
```

这样每次 Claude 写完或改完文件，会自动跑 Prettier 格式化。

**支持的事件**：
- `PostToolUse`：工具执行后触发
- `PreToolUse`：工具执行前触发
- `Stop`：每轮对话结束时触发

---

## 附录：完整工具列表

从源码 `tools.ts` 导出的所有工具：

| 工具 | 作用 |
|------|------|
| `AgentTool` | 派子 Agent |
| `BashTool` | 跑 shell 命令 |
| `FileReadTool` | 读文件 |
| `FileEditTool` | 编辑文件 |
| `FileWriteTool` | 写文件 |
| `GlobTool` | 按模式搜文件 |
| `GrepTool` | 按内容搜文件 |
| `WebFetchTool` | 抓网页内容 |
| `WebSearchTool` | 搜网页 |
| `TodoWriteTool` | 管理任务清单 |
| `NotebookEditTool` | 编辑 Jupyter Notebook |
| `LSPTool` | 语言服务器（代码补全/诊断） |
| `MCPTool` | 调用 MCP 工具 |
| `EnterPlanModeTool` | 进入规划模式 |
| `ExitPlanModeTool` | 退出规划模式 |
| `EnterWorktreeTool` | 进入 Worktree |
| `ExitWorktreeTool` | 退出 Worktree |
| `SkillTool` | 调用 Skill |
| `AskUserQuestionTool` | 向用户提问 |
| `TaskCreateTool` | 创建任务 |
| `TaskListTool` | 列出任务 |
| `TaskStopTool` | 停止任务 |
| `SendMessageTool` | 发送消息 |
| `ConfigTool` | 配置管理 |
| `BriefTool` | 简报/总结 |
| `ToolSearchTool` | 搜索可用工具 |

---

*写完于 2026 年 4 月 1 日。基于 Claude Code 源码分析，源码目录：``*