第一阶段：入门基础

第一阶段：入门基础 🌱

目标：能独立完成日常编码辅助任务

官方文档：Claude Code 官方文档（中文）

---

什么是 Claude Code？

Claude Code 是一个跑在命令行里的 AI 编程助手，由 Anthropic 开发。

和直接用 Claude 网页版相比，它的核心优势是：

对比项	网页版 Claude	Claude Code
访问本地文件	❌ 不能	✅ 直接读写你的项目文件
执行命令	❌ 不能	✅ 跑 npm test、git commit 等
集成开发流程	❌ 需要手动复制粘贴	✅ 在终端里，改完就能跑验证
理解整个项目	❌ 只能看你粘贴的片段	✅ 能搜索、分析整个代码库

一句话理解：网页版 Claude 是"问答助手"，Claude Code 是"坐在你旁边的 AI 程序员"，能直接操作你的项目。

---

前置知识要求

开始之前，先检查你是否具备以下基础：

# 1. Node.js 18 或以上（用来安装 Claude Code）
node --version    # 应该输出 v18.x.x 或更高

# 2. 终端基础操作
cd ~/projects     # 进入目录
ls                # 列出文件

# 3. npm 包管理工具（通常随 Node.js 一起安装）
npm --version     # 能输出版本号即可

需要懂的：

• ✅ 基础终端命令（cd、ls）
• ✅ 知道什么是"项目目录"
• ⚠️ git 基础（后面练习会用，不懂的可以先跳过相关部分）
• ❌ 不需要懂 TypeScript / Java / 任何特定语言

---

本阶段学习地图

1.1 安装与环境配置
    ↓
1.2 基础交互方式
    ↓
1.3 核心工具理解
    ↓
1.4 基础 Slash 命令
    ↓
1.5 实战练习

文件结构

# 入门基础
├── 本文件（阶段导航）
├── 安装与启动
├── 基础交互方式
├── Claude 内部工具详解
├── 基础 Slash 命令
└── 实战练习题

快速开始

# 第一步：验证安装
claude --version

# 第二步：进入交互模式
claude

# 第三步：试试最简单的操作
> 解释一下当前目录下的文件结构

阶段完成标准

• 能通过 claude 命令启动并进行对话
• 能用 @文件名 引用文件到上下文
• 知道何时使用 /compact 和 /clear
• 能让 Claude 读取、修改、创建文件
• 完成 05-practice.md 中的全部练习

---

常见问题 FAQ

Q1：启动 claude 后什么都没反应，或报错"command not found"

原因：npm 全局目录不在 PATH 里。

# 找到 npm 全局目录
npm config get prefix
# 输出类似：/Users/yourname/.npm-global

# 把 bin 目录加入 PATH（加到 ~/.zshrc 或 ~/.bash_profile）
export PATH="/Users/yourname/.npm-global/bin:$PATH"

# 重新加载配置
source ~/.zshrc

---

Q2：Claude 读了文件但回答不对，感觉"没看进去"

可能原因：

1. 文件太大（>500行），Claude 只看了一部分
2. 你的问题太模糊，Claude 不知道你关注哪里

解决方法：

# 不好的提问
> @OrderService.java 这个文件有什么问题？

# 好的提问（明确目标）
> @OrderService.java 我关注第 80-150 行的 createOrder 方法，
  这段代码有没有并发安全问题？

---

Q3：让 Claude 修改文件，但不知道它改了什么

每次修改后养成习惯，让 Claude 解释：

> 你刚才改了哪些地方？每处改动的原因是什么？

或者用 git diff 直观查看：

git diff

---

Q4：/compact 和 /clear 我该用哪个？

记住这个原则：

• 还在做同一件事，只是对话太长 → /compact（保留摘要继续）
• 要开始做完全不同的事 → /clear（干净重开）

例子：
- 正在修复一个 bug，对话到第 25 轮了 → /compact
- bug 修完了，要开始写新功能 → /clear

---

Q5：Claude 说"我没有权限读取那个文件"

原因：Claude 默认只能访问当前工作目录及其子目录。

解决方法：

# 方法一：在正确的目录下启动 claude
cd /your/project/directory
claude

# 方法二：使用绝对路径引用（但必须在工作目录范围内）
# 方法三：配置 Filesystem MCP 扩展访问范围（参考第三阶段）

---

Q6：我不确定 Claude 有没有真正执行我要求的操作

Claude 的所有工具调用都会显示在对话中。关注这些标记：

• Read → 读取了文件
• Edit / Write → 修改或创建了文件
• Bash → 执行了命令

如果你看到这些工具调用，说明 Claude 真的执行了，不只是描述。 如果只有文字描述却没有工具调用，Claude 可能只是在解释，还没有实际操作。

---

Q7：Claude 给出了修改方案，但我不想让它直接动手，想先看方案

# 在要求中加上这句话
> 先告诉我你打算怎么改，不要直接修改文件，等我确认后再动手

这是个好习惯，对应第二阶段 CLAUDE.md 的"禁止行为"配置。

1.1 安装与启动

安装

# 需要 Node.js 18+ 环境
node --version

# 全局安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 验证安装成功
claude --version

启动方式

方式一：交互模式（最常用）

claude

第一次启动后，界面是这个样子：

╭─────────────────────────────────────────────────╮
│ ✻ Welcome to Claude Code!                       │
│                                                 │
│   /help for help                                │
│   /status for account info and context window   │
╰─────────────────────────────────────────────────╯

 ✻ claude-opus-4-6  ~/projects/my-app  (main)

>

• 顶部显示欢迎信息和快捷提示
• 中间一行显示当前模型、工作目录、git 分支
• > 是输入提示符，光标停在这里等你输入

直接输入你的问题，按 Enter 发送：

> 这个项目是做什么的？

Claude 会读取你的项目文件，然后回答。回答完后，> 提示符重新出现，你可以继续提问。

退出方式：输入 exit 或按 Ctrl+C

进入后会看到提示符 >，可以直接输入任何问题或指令。

状态栏说明：

 ✻ claude-opus-4-6  ~/projects/my-app  (main)
   ↑                ↑                   ↑
   当前模型          工作目录             git 分支（非 git 目录则不显示）

右上角还有上下文用量指示，超过 70% 会变色提示你执行 /compact。

方式二：非交互模式（脚本/自动化）

非交互模式：一次性执行任务后自动退出，不停留在提示符等待下一个输入。适合脚本自动化、CI/CD 场景。

# 执行单次任务后退出
claude -p "帮我解释这段代码"
claude -p "列出当前目录下所有 TypeScript 文件"

方式三：指定工作目录

# 在指定项目目录下启动
claude --dir ~/projects/my-app

方式四：读入文件内容

# 将文件内容作为初始上下文
claude < requirements.md

认证配置

首次使用时，Claude Code 会引导你完成认证。有两种方式：

方式一：OAuth 登录（推荐，适合订阅用户）

如果你有 Claude.ai Pro 或 Team 订阅，直接运行：

claude login

会自动打开浏览器，完成 Anthropic 账号授权，无需手动填写 API Key。

适合：个人 Pro 订阅、团队 Team 订阅用户。

---

方式二：API Key（适合企业/程序化使用）

# 方法 A：环境变量（推荐，不留痕迹）
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# 永久生效：加到 ~/.zshrc 或 ~/.bash_profile
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.zshrc
source ~/.zshrc

# 方法 B：写入配置文件
# 编辑 ~/.claude/settings.json，添加：
# { "env": { "ANTHROPIC_API_KEY": "sk-ant-xxxxx" } }

API Key 获取地址：console.anthropic.com/settings/ke…

注意：Key 以 sk-ant- 开头，不要提交到 git 仓库。

常用启动参数

参数	说明	示例
--model	指定模型	claude --model claude-opus-4-6
--dir	指定工作目录	claude --dir /path/to/project
--print / -p	非交互模式，执行后退出	claude -p "解释这段代码"
--no-color	禁用颜色输出	claude --no-color
--debug	开启调试日志	claude --debug

完整启动参数列表见 reference/startup-parameters.md。

第一次在项目里使用：/init

安装完成后，进入一个项目目录，用 /init 让 Claude 自动生成 CLAUDE.md 初稿：

cd ~/projects/my-app
claude
> /init

Claude 会扫描你的项目，识别技术栈、目录结构，生成一份基础的 CLAUDE.md。你只需在此基础上补充项目特有的规范即可，省去从零写起的麻烦。

不用 /init 也完全没问题，手动写同样有效。只是 /init 能节省 10 分钟。

---

更新与卸载

# 更新到最新版本
npm update -g @anthropic-ai/claude-code

# 查看当前版本
claude --version

# 卸载
npm uninstall -g @anthropic-ai/claude-code

退出方式

# 在交互模式中退出
输入 exit 或按 Ctrl+C（连续按两次强制退出）

常见问题

Q: 提示 command not found: claude

# 检查 npm 全局目录是否在 PATH 中
npm config get prefix
# 输出类似 /Users/yourname/.npm-global

# 将 {prefix}/bin 添加到 PATH（加到 ~/.zshrc）
export PATH="$(npm config get prefix)/bin:$PATH"
source ~/.zshrc

Q: 提示认证失败

# 检查 API Key 是否正确设置
echo $ANTHROPIC_API_KEY
# 确保 Key 以 sk-ant- 开头，且没有多余的空格或引号

# 重新登录（OAuth 方式）
claude login

Q: 安装成功但启动很慢

首次启动需要初始化本地配置，之后会正常。如果每次都慢，检查网络连接是否正常（Claude Code 启动时会验证认证状态）。

Q: macOS 提示"无法验证开发者"

这是 macOS 的 Gatekeeper 提示，不影响使用：

# 在终端中运行，而非 Finder 中双击
claude
# 如果仍然报错，用 npm 安装通常不会触发此问题

1.2 基础交互方式

自然语言提问

直接描述你想要什么，无需特定语法：

> 解释一下 src/auth/middleware.ts 这个文件的作用
> 帮我找出代码中可能的内存泄漏
> 把这个函数改成 async/await 风格
> 给这段代码写单元测试

技巧：越具体越好

# 模糊（效果差）
> 修复这个 bug

# 具体（效果好）
> 修复 src/utils/date.ts 第 42 行的类型错误，
> 错误信息是：Type 'string' is not assignable to type 'Date'

技巧：告诉 Claude 你不想要什么

# 有时候"禁止做什么"比"要做什么"更重要
> 重构 formatDate 函数，但不要改变它的对外接口，
  不要修改同文件里的其他函数

> 帮我优化这段查询，不要引入新的依赖库，
  只在现有代码框架内改进

技巧：要求 Claude 先解释再动手

> 在修改代码之前，先告诉我你打算改什么，以及原因

这个习惯能帮你发现 Claude 是否理解了你的意图，避免被大量错误的修改搞乱。

文件引用 @文件名

将文件内容加入对话上下文：

# 引用单个文件
> @src/components/Button.tsx 这个组件有什么问题？

# 引用多个文件
> @src/api/user.ts @src/types/user.ts 这两个文件的类型定义对齐吗？

# 引用目录下的所有文件（谨慎使用，会消耗大量 token）
> @src/utils/ 这些工具函数有重复逻辑吗？

注意：引用大文件或整个目录会快速消耗 token，优先让 Claude 用 Grep/Glob 查找，只引用必要部分。

token 成本对比（直观感受）：

@src/services/OrderService.java（假设 500 行）
→ 直接消耗约 2000 tokens

先 Grep 找到 processOrder 在第 87 行，再精确读 80-130 行
→ 消耗约 300 tokens

节省 85%

完整的 @ 引用规则详见 @ 引用语法完整指南。

---

什么时候用 @引用，什么时候直接说？

这是新手最常困惑的问题：

你怎么做	Claude 会...	适合的场景
直接问（不用 @）	根据已有上下文回答，不主动读文件	问概念、问方法论、问通用问题
@文件名	立刻读取该文件，融入回答	你明确知道要分析哪个文件
描述让 Claude 找	Claude 用 Grep 搜索后再读	你不知道相关代码在哪里

# 场景一：你不知道代码在哪里
> 找一下项目里处理用户登录的逻辑
（Claude 会用 Grep 搜索，找到后再读相关文件）

# 场景二：你知道要看哪个文件
> @src/auth/login.ts 这段登录逻辑有没有安全问题？
（Claude 直接读这个文件分析）

# 场景三：问通用问题，不需要读代码
> JWT token 和 session 哪种方式更安全？
（不需要 @，Claude 直接用知识回答）

连续对话（上下文积累）

Claude Code 会记住对话历史，可以持续追问：

> 解释一下 UserService 类的作用
（Claude 解释了）

> 那 createUser 方法有什么潜在问题？
（Claude 基于上文继续分析）

> 帮我修复你说的那个并发问题
（Claude 实施修复）

注意上下文的边界：

• 同一会话内，Claude 记得所有历史对话
• 新会话（/clear 或重新启动）后，Claude 不记得任何之前的对话
• 上下文太长时（超过 20 轮），Claude 可能"遗忘"早期内容 → 使用 /compact

何时开新会话：

• 切换到完全不相关的任务 → /clear
• 当前任务已完成，想干净利落地开始新的 → /clear
• 对话中出现严重的前提错误（Claude 一直基于错误假设） → /clear

引用 URL（注意网络限制）

> @https://docs.anthropic.com/... 根据这个文档更新代码

公司网络限制：内网环境下外部 URL 可能无法访问，建议：

• 使用本地文档（~/Documents/cotti/）
• 使用 Chrome DevTools MCP 访问内部系统（详见 第三阶段：高级能力）
• 将文档内容复制到对话中

多行输入的所有方式

方式一：行末反斜杠（适合简单换行）

> 帮我重构这个函数，要求：\
  1. 提取重复逻辑 \
  2. 添加错误处理 \
  3. 保持原有 API 不变

方式二：双引号包裹（推荐，支持真正换行）

> "帮我重构这个函数，要求：
  1. 提取重复逻辑
  2. 添加错误处理
  3. 保持原有 API 不变"

方式三：粘贴多行内容

直接粘贴包含换行的文本，Claude Code 会自动识别：

> 分析这段错误日志：
  ERROR 2026-03-27 14:23:01 [OrderService]
  NullPointerException at OrderService.java:145
  Caused by: order is null
  Stack trace: ...

方式四：非交互模式下用 stdin 传入

# 将文件内容通过 stdin 传入（适合脚本）
cat complex-prompt.txt | claude -p

# 管道方式
echo "分析这个错误" | claude -p

方式五：heredoc（适合脚本和复杂场景）

claude -p <<'EOF'
分析以下代码的问题：
$(cat src/auth.ts)
请重点关注：
1. 类型安全
2. 错误处理
EOF

---

输入技巧总结

场景	推荐方式
分析单个文件	@文件路径 + 问题描述
跨文件分析	引用多个 @文件
搜索代码	直接说"帮我找..." Claude 会用 Grep
修改代码	描述清楚"改什么"+"改成什么样"
复杂需求	多行输入，分点列出要求
粘贴错误日志	直接粘贴，无需特殊处理
脚本批处理	claude -p < 文件名 或 heredoc
不确定代码在哪	描述功能，让 Claude 用 Grep 找
想控制改动范围	明确说"只改这个函数，不要动其他地方"

---

常见的低效用法（避免）

❌ 用 @ 引用整个 src/ 目录
   → 消耗巨量 token，效果不如先 Grep 定位

❌ "帮我看看这个项目有什么问题"
   → 太模糊，Claude 不知道关注什么

❌ 只说"不对，重新来"
   → 没有告诉 Claude 哪里不对，它会重复同样的错误

❌ Claude 改完马上关掉，不验证
   → 养成用 git diff 确认改动的习惯

1.3 核心工具详解

Claude Code 在执行任务时会调用内置工具。理解这些工具能帮你写出更精准的指令，也能更好地理解 Claude 的行为。

为什么要理解工具？

不理解工具的新手：
> 帮我找 validateToken 函数
Claude 可能反复尝试不同方式 → 多次工具调用 → 浪费 token

理解工具的人：
> 用 Grep 在 src/ 目录搜索 validateToken 函数的定义
Claude 立即用正确工具，一次找到 → 省 token，结果准确

理解工具后，你写指令会更精准，Claude 出错的概率也更低。

新手最重要的认知

Claude Code 的"手"就是这些工具——它不是魔法，每一个操作背后都是在调用工具。

当你在对话中看到类似这样的展示时，那就是 Claude 在用工具：

● Read(src/auth.ts)           ← 正在读文件
● Grep("validateToken")       ← 正在搜索代码
● Bash("npm test")            ← 正在运行命令
● Edit(src/auth.ts)           ← 正在修改文件

你可以在授权时选择"允许"或"拒绝"，完全在你的控制下。

---

工具使用频率（新手视角）

80% 场景用 Read / Grep    ← 看代码、找代码
15% 场景用 Bash           ← 跑命令、验证改动
 4% 场景用 Edit / Write   ← 改代码、创建文件
 1% 场景用 Glob / Agent   ← 找文件、复杂任务

新手只需要先理解 Read、Grep、Bash 这三个，其他遇到了再学。

---

工具一览

工具	用途	何时被调用
Read	读取文件内容	你让 Claude 看某个文件时
Grep	在文件内容中搜索	查找函数定义、引用等（最常用！）
Glob	按模式查找文件	查找特定类型的文件
Bash	执行 shell 命令	运行测试、git 操作等
Edit	精确修改文件片段	修改现有文件时（比 Write 更安全）
Write	创建/覆写文件	创建新文件时
Agent	启动子 Agent	复杂任务委派（高级阶段才需要理解）

Read 和 Edit 的区别：

• Read = 只读，不修改文件，Claude 用来"看"
• Edit = 精确替换文件中某段文字，是最常用的修改方式
• Write = 完整覆写整个文件，用于创建新文件

Read - 读取文件

你说：> 看一下 src/auth.ts 这个文件
Claude 做：Read("src/auth.ts")

你说：> 看一下那个文件的第 100-150 行
Claude 做：Read("src/auth.ts", offset=100, limit=50)

关键参数：

• offset：从第几行开始读
• limit：读多少行

技巧：对于大文件，先让 Claude Grep 定位行号，再精确读取，而不是读整个文件。

Write - 创建文件

你说：> 创建一个新的工具函数文件 src/utils/format.ts
Claude 做：Write("src/utils/format.ts", 内容...)

注意：Write 会完全覆盖文件，修改现有文件时 Claude 会优先用 Edit。

Edit - 修改文件片段

Edit 只修改文件中特定的字符串，不影响其他内容，更安全：

你说：> 把 formatDate 函数改成支持时区参数
Claude 做：Edit("src/utils/date.ts", old_string="...", new_string="...")

Bash - 执行命令

你说：> 运行一下单元测试
Claude 做：Bash("npm test")

你说：> 查看 git 状态
Claude 做：Bash("git status")

你会看到：Claude 执行命令前会显示命令内容，需要你确认（取决于权限设置）。

Grep - 搜索代码

最常被调用的工具之一：

你说：> 找一下所有使用 getUserById 的地方
Claude 做：Grep("getUserById", path="src/")

你说：> 找一下所有 TODO 注释
Claude 做：Grep("TODO", glob="**/*.ts")

Glob - 查找文件

你说：> 有哪些测试文件？
Claude 做：Glob("**/*.test.ts")

你说：> src/components 下有哪些文件？
Claude 做：Glob("src/components/**/*")

Claude Code 能做什么？不能做什么？

✅ 能做：
- 读取项目目录内的所有文件
- 修改或创建文件
- 运行终端命令（npm/git/mvn 等）
- 在整个项目中搜索代码
- 读取图片、PDF、Jupyter Notebook

❌ 不能做（除非你特别配置）：
- 访问项目目录之外的文件
- 访问数据库或生产环境
- 自动推送代码到远程（需要你确认 git push）
- 访问公司内网系统（需要配置 MCP）
- 访问外部网站（公司内网限制，需要 Chrome DevTools MCP）

---

如何查看 Claude 调用了哪些工具

对话界面中，每次工具调用都会显示出来，格式如下：

● Read(src/auth.ts)                    ← 读取了文件
⎿ 返回 150 行内容

● Grep("validateToken", path="src/")   ← 搜索了关键词
⎿ 找到 3 个匹配

● Bash("npm test")                     ← 执行了命令
⎿ 输出: All tests passed

● Edit(src/auth.ts)                    ← 修改了文件
⎿ 替换了 2 处内容

关键认知：如果 Claude 只有文字输出、没有工具调用标记，说明它在"描述"而不是"执行"。遇到这种情况，可以明确要求：> 请实际读取文件，而不是猜测。

---

理解工具调用流程

当你下达一个指令，Claude 的思考过程：

1. 理解意图：你想让我做什么？
2. 规划工具：需要用哪些工具？按什么顺序？
3. 执行工具：调用工具获取信息或修改文件
4. 验证结果：结果是否符合预期？
5. 反馈给你：总结完成了什么

实例：> 帮我重构 auth.ts 中的 validateToken 函数

Claude 内部：
1. Grep("validateToken") → 找到在第 87 行
2. Read("auth.ts", offset=80, limit=40) → 读取函数内容
3. 分析代码质量问题
4. Edit("auth.ts", ...) → 实施重构
5. 解释改动内容

---

工具调用的权限确认

不同工具的风险等级不同，Claude Code 会根据你的权限设置决定是否需要你确认：

自动执行（低风险）：Read、Grep、Glob
需要确认（中等风险）：Edit、Write、Bash
强制询问（高风险）：特定危险命令（rm -rf 等）

你看到类似 Allow this action? [y/n] 的提示时，认真看清楚 Claude 要执行的命令再决定。

权限规则可以通过 settings.json 自定义，详见第二阶段：进阶配置。

1.4 基础 Slash 命令

Slash 命令以 / 开头，是控制 Claude Code 行为的快捷方式。

完整命令列表见：Slash 命令完整参考

新手第一周只需要这 3 个

/help     # 忘记命令名时用
/compact  # 对话太长时用（超过 20 轮）
/clear    # 切换到完全不同的任务时用

其他命令遇到具体场景再学，不用一次全记。

---

必学命令

/help - 查看帮助

/help           # 列出所有可用命令
/help compact   # 查看特定命令的说明

/clear - 清空对话历史

/clear

何时使用：

• 切换到完全不相关的新任务
• 对话上下文被污染（Claude 给出错误的前提假设）
• 想从零开始一个干净的会话

注意：/clear 会清空所有历史，Claude 不再记得之前的对话。

/compact - 压缩上下文

/compact

何时使用：

• 对话超过 20 轮时（token 消耗增加）
• 上下文窗口接近上限
• 前几轮的探索性内容已经不重要了

与 /clear 的区别：

	/compact	/clear
历史保留	保留摘要	完全清空
关键信息	自动提取	丢失
适用场景	长对话瘦身	切换任务

/model - 查看/切换模型

/model                          # 查看当前使用的模型
/model claude-opus-4-6          # 切换到 Opus（最强，最贵）
/model claude-sonnet-4-6        # 切换到 Sonnet（均衡）
/model claude-haiku-4-5-20251001  # 切换到 Haiku（最快，最省）

选择策略：

• 复杂编码任务 → Opus
• 日常问答、文档 → Sonnet
• 简单格式化、翻译 → Haiku

/ide - 连接 IDE

/ide    # 连接当前已打开的 IDE（WebStorm 或 VS Code）

连接后 Claude 可以使用 IDE 的代码智能功能（跳转定义、查找引用等）。

其他实用命令

/status     # 查看当前会话状态（token 用量、MCP 连接状态等）
/cost       # 查看本次会话的费用估算
/fast       # 切换快速模式（同等模型，更快输出）
/config     # 查看或修改 Claude Code 配置

命令使用场景速查

场景	命令
对话太长了，想压缩	/compact
切换到新任务	/clear
想用更强的模型	/model claude-opus-4-6
需要 IDE 代码导航能力	/ide
查看 token 用量	/status
忘记有什么命令	/help

---

键盘快捷键（交互模式）

在 Claude Code 交互模式中，以下快捷键很常用：

快捷键	功能
↑ / ↓	浏览历史输入
Ctrl+C	中断 Claude 当前输出（不退出会话）
Ctrl+C × 2	退出会话
Tab	命令/文件路径自动补全（部分终端支持）
Ctrl+L	清屏（不影响对话历史）

---

进阶命令（用到时再看）

第二阶段以上才会用到的命令：

/commit             # 自动生成 git commit message（内置）
/compact <指令>     # 压缩时附加保留指令，如 /compact 保留所有决策

以及各种自定义 Skill 命令——这些需要单独安装，通过 /skill-name 格式触发， 封装了多步骤工作流。常见的 Skill 类型有：

Skill 类型	触发命令（示例）	一句话说明
Bug 修复	/dev-fix-bug	系统化排查 → 定位根因 → 修复 → 验证
需求实现	/dev-implement	探索代码 → 设计方案 → 实现 → 自测
代码审查	/dev-review	多维度并行审查，输出评分报告
故障诊断	/dev-diagnose	采集数据 → 根因分析 → 修复建议
提交前自查	/pre-commit-check	类型/安全/规范快速检查

具体命令名取决于你安装了哪些 Skill，完整说明见 reference/slash-commands.md， 安装方式见 phase-3-advanced/03-skills-system.md。

1.5 实战练习

完成以下练习来巩固入门知识。每个练习都有明确的目标、步骤和验证方法。

重要原则：每次 Claude 改完代码，必须自己验证，不能只看 Claude 说"完成了"就算数。

---

练习一：第一次对话

目标：熟悉基本交互流程，了解界面长什么样

步骤：

1. 打开终端，进入你的任意项目目录
2. 输入 claude 启动
3. 观察界面：顶部显示模型名和工作目录
4. 问 Claude：当前目录下有哪些文件？
5. 选择其中一个源代码文件，问：@文件名 解释一下这个文件的作用
6. 继续追问：这个文件有什么可以改进的地方？
7. 输入 exit 退出

验证：

□ Claude 成功回答了问题（不是报错）
□ 看到 Claude 显示了"Read(文件名)"的工具调用
□ Claude 的解释与你对文件的理解基本一致
□ 能正常退出

如果卡住了：

• Claude 什么都没说 → 检查是否按了 Enter
• 显示认证错误 → 检查 ANTHROPIC_API_KEY 是否设置

---

练习二：让 Claude 修改代码

目标：学会引导 Claude 精确修改代码，并学会验证结果

步骤：

1. 找一个你熟悉的函数（比如一个工具函数）
2. 先让 Claude 说明方案，不要直接动手：

   > @文件名 帮我给第 XX 行的 YY 函数添加 JSDoc 注释，说明参数含义。
     先告诉我你打算加什么内容，不要直接改文件。
   

3. 确认方案后，说"可以，开始修改"
4. Claude 修改后，检查结果

验证：

# 1. 查看改动范围（只应该改了这一个函数）
git diff

# 2. 确认代码没有语法错误
npm run lint       # 前端项目
# 或
mvn validate       # Java 项目

# 3. 确认改动只有你要求的部分，没有多改其他地方

关键习惯：git diff 是你最好的朋友——每次 Claude 改完代码，都要看一眼改了什么。

---

练习三：代码搜索

目标：学会让 Claude 在项目中搜索，理解 Grep 工具

步骤：

1. 告诉 Claude：在这个项目中找到所有调用 fetch 或 axios 的地方
2. 观察 Claude 的输出——注意是否显示了 Grep(...) 工具调用
3. 再问：这些 API 调用有统一的错误处理吗？
4. 尝试一个更精确的搜索：找一下所有带 TODO 注释的地方

验证：

# 手动验证 Claude 的搜索结果是否准确
grep -r "fetch\|axios" src/ --include="*.ts" -l

# 对比 Claude 找到的文件列表，应该一致

你应该观察到：Claude 输出结果前会显示 Grep("fetch|axios", ...) 这样的工具调用。如果没有，说明 Claude 是在"猜"而不是真的搜索。

---

练习四：使用 /compact 管理长对话

目标：掌握长对话管理，避免 token 浪费

步骤：

1. 进行一次 15 轮以上的对话（探索一个项目的代码结构）
2. 注意观察右上角或 /status 中的 token 使用量
3. 执行 /compact
4. 观察 Claude 生成的摘要内容包含哪些信息
5. 继续提问，验证 Claude 还记得关键信息

验证：

□ /compact 后 Claude 仍然知道我们在分析哪个项目
□ /compact 后 Claude 记得之前确认的结论
□ 查看 /status，token 用量明显减少

# 测试 Claude 还记得什么：
> 你还记得我们刚才分析的是哪个模块吗？主要发现了什么问题？

常见问题：/compact 后 Claude 忘记了重要信息？

• 原因：那些信息在摘要中被省略了
• 解决：在 /compact 之前说"请保留 X 信息"，或 /compact 后重新说明

---

练习五：让 Claude 写测试

目标：完成一个完整的"读代码 → 生成测试 → 运行验证"流程

步骤：

1. 选择项目中一个没有测试的工具函数（20-50 行的简单函数最合适）
2. 让 Claude 先观察项目中现有的测试怎么写的：

   > 先看一下项目里已有的测试文件是怎么写的，然后为 @src/utils/XX.ts 中的 YY 函数编写单元测试
   

3. Claude 生成测试后，运行测试

验证：

# 运行测试，确认通过
npm test               # 前端（Jest/Vitest）
npm run test -- XX.test.ts  # 只跑这一个测试文件

# 预期结果：
# ✓ YY function
#   ✓ 正常情况
#   ✓ 边界情况
# Tests: 3 passed

如果测试失败了：不要让 Claude 直接修改测试让它通过，而是：

> 测试报错了：[粘贴错误信息]
  是测试写错了，还是原函数有 bug？先分析原因。

---

练习六（新）：验证 Claude 的修改

目标：学会识别和处理 Claude 改错了的情况

背景：Claude 有时会改错，这个练习专门练习"发现错误 → 告诉 Claude → 让它修正"的流程。

步骤：

1. 让 Claude 修改一个函数，添加参数验证：

   > @src/utils/format.ts 给 formatPrice 函数添加参数验证：
     如果传入的 price 是负数，抛出 Error('价格不能为负数')
   

2. 检查 Claude 的改动：git diff
3. 如果改动看起来有问题（比如改了你没要求改的地方），明确指出：

   > 你不应该改第 XX 行，那里是我们不想动的逻辑。
     请把那里还原，只保留参数验证的改动。
   

4. 再次 git diff 确认修复

验证：

□ 最终的 git diff 只包含你期望的改动
□ 运行测试确认没有破坏已有功能
□ 学会了"Claude 改错 → 我指出 → Claude 修正"这个循环

---

进阶挑战

完成以上 6 个练习后，尝试这个综合挑战：

挑战：选择项目中一个 bug 或待改进点，完整走一遍"发现问题 → 分析 → 修复 → 验证"流程，全程只用自然语言指令控制 Claude。

执行清单：

□ 让 Claude 先解释问题根因，不要直接动手
□ 确认根因正确后，让 Claude 提出修复方案
□ 确认方案后，让 Claude 实施修复
□ 用 git diff 查看改动范围
□ 运行验证命令（lint / test）确认修复有效
□ 如果测试失败，让 Claude 分析原因并重新修复

---

推荐：5 分钟创建你的第一个 CLAUDE.md

完成练习后，建议立刻做这件事——只需 5 分钟，能省去后续大量重复解释：

在项目根目录创建 CLAUDE.md，写入：

# 项目名称

## 技术栈
- [你的框架，如 React 18 + TypeScript]
- [包管理工具，如 pnpm]

## 禁止行为
- 修改代码前必须先告诉我改什么，等我确认
- 不要引入 package.json 里没有的新依赖

## 验证命令
- 代码检查：pnpm lint
- 类型检查：pnpm type-check
- 运行测试：pnpm test

这样之后每次启动 Claude，它都会自动知道这些规范，不用你每次重复说。