Claude Code 使用指南

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

一、安装与配置

安装

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

# 推荐方式
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 上更顺。

初始配置

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

# 切模型
/model

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

# 配置输出风格
/config

输出风格（Output Style） 可以自定义。在 .claude/output-styles/ 目录下放一个 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` 关掉遥测

二、基本用法

启动和对话

# 进入交互模式
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。它会自动：

读你的 package.json / Cargo.toml / pyproject.toml 等，搞清楚项目结构
找到构建、测试、lint 命令
扫描现有的 AI 编码规则（.cursor/rules、.github/copilot-instructions.md 等）
生成 CLAUDE.md 文件

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

文件操作最佳实践

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

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

实操建议：

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

三、进阶技巧

Plan Mode（规划模式）

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

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

怎么触发：

直接说：

"先帮我规划一下怎么加登录功能"

或者让 Claude 自己判断。源码里写了，以下情况它会自动进入 Plan Mode：

添加新功能（不止改一行）
有多种实现方式需要选
改动涉及多个文件
需要做架构决策
需求不明确需要先探索

Plan Mode 里发生了什么：

Claude 用 Glob/Grep/Read 探索你的代码库
理解现有架构和模式
设计实现方案
给你看方案，你批准后再执行

你也可以手动进 Plan Mode：

"进 Plan Mode"

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

子 Agent（分任务并行）

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

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

比如你说"帮我整理这个项目的所有测试文件"，Claude 可能会：

一个子 Agent 去找所有测试文件
一个子 Agent 去分析测试覆盖率
主 Agent 汇总结果

源码里的关键细节：

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

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

Worktree 隔离

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

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

怎么触发：

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

底层逻辑（从源码看）：

用 git worktree 创建隔离的工作目录
每个 worktree 有独立的分支
Claude 自动切换到新 worktree 的目录
完成后可以退出 worktree 回到主分支

怎么退出：

"退出 worktree"

Memory 记忆系统

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

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

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

示例：

# 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，不提交。放你个人的偏好：

# 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）。

发生了什么：

之前的对话摘要被保留
详细工具调用记录被清掉
新的对话基于摘要继续

你也可以手动触发：

/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（全局级）配置：

{
  "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 接入外部工具。

怎么用：

# 添加一个 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

怎么安装插件：

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

怎么创建自定义 Skill：

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

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

SKILL.md 内容：

---
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 控制（可能在逐步开放中）

如果能用：

/voice

会进入语音对话模式。

自定义输出风格

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

---
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：

{
  "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 里配置：

{
  "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 源码分析，源码目录：``