AI实战课 · 第二十章 中:Claude Code 新手使用教程

AI实战课 · 第二十章中

Claude Code 新手使用教程

从第一次只读项目到计划、改文件、跑测试、看 diff、管理会话和 VS Code 使用

文章路线图

01 先把 Claude Code 当成“会动手的同事”

02 第一次使用：只读项目，不要改文件

03 新手 Prompt 公式：目标、上下文、约束、验证

04 先探索，再计划，再实现

05 会用权限模式：default、plan、acceptEdits

06 第一次让它改文件：从小任务开始

07 Bug 修复流程：一定给复现命令

08 测试工作流：不要只让它“补测试”

09 文档工作流：让它查代码再写，不要凭空写

10 Git 工作流：先看状态，再提交

11 图片和截图：UI 问题别只靠文字描述

12 文件引用和上下文：会用 `@`、路径、日志和管道

13 管理会话：`/clear`、`/compact`、`/rewind`、`--continue`

14 VS Code 新手怎么用

15 新手常见翻车点

16 新手 7 天练习路线

上一篇我们讲了 Claude Code 怎么安装。

这一篇讲怎么用。

很多新手第一次打开 Claude Code，第一句话是：“帮我写一个项目。”这不是完全不行，但通常不是最稳的入门方式。

Claude Code 的强项是：它能读项目、找文件、提出方案、修改代码、运行命令、解释 diff、和 Git / IDE / MCP / CI 结合。你要学的不是“神提示词”，而是一个可重复的交付流程。

这篇我们按新手第一周真实会遇到的场景讲：第一次提问、第一次读项目、第一次计划、第一次改文件、第一次跑测试、第一次看 diff、第一次恢复会话。

第 01 节

01 / 先把 Claude Code 当成“会动手的同事”

Claude Code 不是普通聊天框。

普通聊天框只能回答。Claude Code 会进入你的项目目录，读取文件，运行命令，编辑文件，并在需要时请求权限。

这带来两个变化。

第一，你不能只说愿望。比如“帮我优化一下项目”太宽泛。真实同事听到也会追问：优化哪里？性能、样式、代码结构、测试覆盖率，还是包大小？

第二，你要给它验收标准。比如“修复登录报错”还不够，要告诉它如何复现、什么算修复、要跑什么检查。

官方最佳实践里有一句非常关键：给 Claude 一个能验证自己工作的方式。比如测试、构建、linter、截图对比、脚本输出。没有验证，Claude 只能在“看起来完成”时停下。

所以新手第一条原则：

不要只问“能不能做”，要让它“做完以后证明做对了”。

第 02 节

02 / 第一次使用：只读项目，不要改文件

安装后第一次进入项目，先别让 Claude 改。

在项目根目录：

claude

然后输入：

先不要修改任何文件。 请阅读当前项目，输出： 1. 项目主要做什么； 2. 技术栈是什么； 3. 主要目录和入口文件； 4. 启动、测试、构建命令； 5. 当前项目有没有 CLAUDE.md； 6. 如果要让你开始做任务，还缺哪些信息。

这条提示词的重点是“只读”。

你要先验证三件事：

- Claude 看到的是不是正确项目；

- 它能不能找到关键文件；

- 它有没有乱猜命令。

如果它把项目说得很离谱，不要往下走。先检查目录、README、package 文件、Git 状态。

第 03 节

03 / 新手 Prompt 公式：目标、上下文、约束、验证

一个稳定的 Claude Code 任务，至少有四块。

你可以复制这个模板：

目标： 修复…… 上下文： - 复现步骤：…… - 报错信息：…… - 相关文件可能是：…… - 当前分支/环境：…… 约束： - 不要新增依赖； - 不要改数据库结构； - 优先沿用已有组件和测试风格； - 修改前先说明计划。 验证： - 修改后运行…… - 如果不能运行，请说明原因； - 最后输出改动文件、验证结果、剩余风险。

这个模板看起来啰嗦，但它能大幅减少返工。

Claude 可以推断很多东西，但你越精确，它越少走弯路。

第 04 节

04 / 先探索，再计划，再实现

官方最佳实践把复杂任务分成四步：Explore、Plan、Implement、Commit。

新手可以这样理解：

第一步，探索。

让 Claude 读文件、找线索、理解现状，但不要改。

进入 plan mode。 请阅读 src/auth 相关代码，理解登录、session 和 token 刷新的流程。 不要修改文件，只总结现状和风险。

第二步，计划。

让 Claude 先提出方案。

我想修复 session 过期后登录页空白的问题。 请列出需要改哪些文件、为什么改、风险是什么、如何验证。 先不要实现。

第三步，实现。

你确认方案后再让它改。

按刚才方案实现。 要求： 1. 保持现有 API 不变； 2. 补一个最小测试； 3. 跑相关测试； 4. 如果测试失败，先分析原因再继续。

第四步，提交或整理。

请总结本次改动，给出 commit message 草稿，并列出发布前还需要人工检查的点。

如果任务很小，比如改错别字、改一个文案，不需要完整计划。计划最适合不熟悉代码、多文件修改、影响范围不确定的任务。

第 05 节

05 / 会用权限模式：default、plan、acceptEdits

新手先掌握三个模式就够。

`default`：适合日常入门。Claude 可以读文件，但编辑和命令会请求权限。你能看到它准备做什么。

`plan`：适合先探索、先做方案。Claude 读文件、跑只读命令，但不改源文件。

`acceptEdits`：适合你已经确认方向，希望它少打断地修改文件。它会自动接受工作目录内文件编辑和常见文件系统命令。

CLI 里可以按 `Shift+Tab` 切换常见模式。VS Code、Desktop、Web 里用模式选择器。

新手不要急着用 `auto` 或 `bypassPermissions`。

`auto` 是研究预览，适合你信任方向但想减少审批疲劳。`bypassPermissions` 只适合隔离容器或虚拟机。不要在自己主力电脑、真实项目、没有 git 的目录里随便开。

你要记住：权限不是阻碍效率，权限是让 Claude Code 能长期安全工作的护栏。

第 06 节

06 / 第一次让它改文件：从小任务开始

第一次修改不要选大任务。

适合新手练手的任务：

- 改 README 启动说明；

- 给一个函数补注释；

- 修一个文案；

- 补一个小测试；

- 整理一个错误提示；

- 给组件增加一个 loading 状态。

示例：

目标： 请把 README 里的本地启动说明补完整。 要求： 1. 先阅读 package.json 和现有 README； 2. 不要修改代码； 3. 只更新 README； 4. 补充 install、dev、test 三类命令； 5. 修改后总结具体改了什么。

Claude Code 默认会展示拟议改动，并请求你批准。你不要闭眼全同意。看三件事：

- 它是不是只改了 README；

- 命令是不是来自真实 package.json；

- 它有没有顺手补不存在的东西。

第一次练习的目标不是产出惊艳代码，而是建立“看它怎么动手”的肌肉记忆。

第 07 节

07 / Bug 修复流程：一定给复现命令

Claude Code 很适合修 bug，但你要给它抓手。

不要只说：

修一下登录 bug。

改成：

目标： 修复登录失败后页面空白的问题。 复现步骤： 1. 运行 npm run dev； 2. 打开 /login； 3. 输入错误密码； 4. 页面变成空白，没有错误提示。 我已经看到的报错： 粘贴浏览器 console / 终端报错。 要求： - 先定位根因； - 修改前给出方案； - 不要改登录 API； - 修复后运行相关测试； - 如果没有现成测试，请说明你建议补哪个测试。

官方 common workflows 也强调，调 bug 时要告诉 Claude 复现命令、stack trace、复现步骤，以及错误是否稳定出现。

越是具体的 bug，越适合 Claude Code。

越是“偶尔不对”“感觉卡”“用户反馈不好用”这种模糊问题，越要先让它探索和提问。

第 08 节

08 / 测试工作流：不要只让它“补测试”

“补测试”也是一个容易写坏的任务。

好的测试任务要说明行为。

请为 NotificationsService 增加测试。 重点覆盖： 1. 用户未登录时不发送通知； 2. 邮件地址为空时返回明确错误； 3. API 超时时重试一次； 4. 不要 mock 掉被测函数本身； 5. 遵循现有 test 文件风格； 6. 添加后运行相关测试。

Claude Code 会读取现有测试文件，模仿测试框架、断言风格和目录结构。

你要让它做三件事：

- 先找现有测试模式；

- 再补最小必要测试；

- 最后运行测试并修失败。

不要让它为了“测试覆盖率好看”写一堆只验证实现细节的测试。真正有价值的是行为测试和边界测试。

第 09 节

09 / 文档工作流：让它查代码再写，不要凭空写

Claude Code 也很适合写文档。

但文档最容易“写得像真的，实际上不准”。

正确提示：

目标： 更新 README 的部署说明。 要求： 1. 先阅读 package.json、Dockerfile、.env.example、现有 docs； 2. 只写代码里能确认的命令； 3. 对不确定的环境变量标注“需要确认”； 4. 不要编造部署平台； 5. 最后列出资料来源文件。

文档任务一定要求它说清楚“信息来自哪里”。

如果是对外文档，还要加一句：

涉及版本、价格、平台能力、第三方服务限制，请回到官方文档核验，不要凭记忆写。

第 10 节

10 / Git 工作流：先看状态，再提交

Claude Code 可以帮你做 Git 操作，比如查看改动、生成 commit message、创建分支、处理 merge conflict。

但新手一定要保留一个习惯：先看状态。

git status --short git diff

你也可以让 Claude 帮你解释：

请解释当前 git diff： 1. 每个文件为什么改； 2. 是否有无关改动； 3. 是否有风险； 4. 建议 commit message。 不要提交。

等你确认后再说：

请用描述性 commit message 提交这次改动。

如果要开 PR：

请创建 PR 草稿，正文包含： 1. Summary； 2. Tests； 3. Risks； 4. Screenshots（如果有 UI）。

官方 common workflows 也提到，你可以让 Claude 创建 PR，但要 review 它生成的 PR 说明，并让它突出风险和注意事项。

第 11 节

11 / 图片和截图：UI 问题别只靠文字描述

Claude Code 可以处理图片上下文。

官方 common workflows 提到几种方式：

- 拖拽图片进 Claude Code 窗口；

- 复制图片后用 Ctrl+V 粘贴到 CLI；

- 给出图片路径，比如 `/path/to/your/image.png`。

注意是 Ctrl+V，不是 macOS 的 Cmd+V。

UI 问题很适合用截图：

这是移动端页面截图。 问题：底部按钮挡住了价格说明。 请先分析可能原因，不要立刻修改。 然后给出最小 CSS 修复方案。 修复后请说明需要我如何截图复查。

如果你有设计稿截图，也可以让 Claude 对比实现：

请对比这个设计截图和当前页面实现。 只列出差异，不修改文件。 按视觉优先级排序。

UI 工作不要只靠“好看一点”。要让它对照截图、列差异、再修。

第 12 节

12 / 文件引用和上下文：会用 `@`、路径、日志和管道

官方最佳实践建议提供 rich content。

常见方式：

第一，用 `@` 引用文件。

请参考 @src/components/Button.tsx 的写法，给 @src/pages/Login.tsx 增加 loading 状态。

第二，直接给路径。

请分析 /path/to/error.log 里的最新错误。

第三，管道输入。

cat error.log | claude -p "summarize the root cause"

第四，给 URL。涉及外部 API、SDK、框架版本时，直接让它看官方文档链接。

第五，让它自己拉上下文。

请用项目内命令检查相关测试，不要只靠静态阅读。

上下文不是越多越好。你要给的是“能定位问题的上下文”，不是把整个项目复制进去。

第 13 节

13 / 管理会话：`/clear`、`/compact`、`/rewind`、`--continue`

Claude Code 的上下文会越聊越满。官方最佳实践非常强调 context window 管理。

新手要学会四个动作。

第一，`/clear`。

任务之间清空上下文。比如刚修完登录 bug，下一步要写完全无关的文案，就清掉。

/clear

第二，`/compact`。

长任务中压缩上下文。

/compact 只保留当前计划、已修改文件、测试结果和剩余风险

第三，`/rewind`。

如果 Claude 走偏，双击 Esc 或运行 `/rewind`，可以恢复 conversation、code，或只从某个点开始总结。

第四，继续会话。

claude --continue

或：

claude --resume

官方文档也提醒，checkpoint 只跟踪 Claude 的编辑，不是 Git 的替代品。你仍然要用 Git 管理真实项目。

第 14 节

14 / VS Code 新手怎么用

如果你用 VS Code，Claude Code 扩展会更直观。

官方文档说明，VS Code 扩展推荐用于 VS Code 环境，支持图形界面、inline diff、@ mention 文件、计划审查、多个会话等。

安装前确认：

- VS Code 1.98.0 或更高；

- 有 Anthropic 账号：Pro、Max、Team、Enterprise 或 Console；

- 第一次打开扩展时会浏览器登录；

- 如果想在集成终端里运行 `claude`，还要装 standalone CLI。

新手使用顺序：

1. 在 VS Code 打开项目根目录；

2. 打开 Claude Code panel；

3. 先问项目概览；

4. 用 @ mention 指定文件；

5. 让它进入计划；

6. 审计划；

7. 接受小范围修改；

8. 看 inline diff；

9. 跑测试；

10. 总结风险。

IDE 的优势是可视化 diff 和文件上下文；CLI 的优势是直接、轻量、适合脚本。两个都能用，但先把一种用顺。

第 15 节

15 / 新手常见翻车点

第一个翻车点：目录错。

你在桌面根目录运行 `claude`，然后让它找项目。它会很痛苦，你也会。

第二个翻车点：目标太大。

“帮我优化系统”不是任务。先限定一个页面、一个 bug、一个函数、一个测试。

第三个翻车点：不给验证。

如果没有测试、构建、截图、脚本输出，Claude 很容易在“看起来可以”时结束。

第四个翻车点：长会话不清理。

一个会话里聊了十个无关任务，后面质量必然下降。用 `/clear`。

第五个翻车点：过早开宽权限。

不熟悉 diff、不看命令，就开 `bypassPermissions`。这不是进阶，是把风险变大。

第六个翻车点：让它凭空写文档。

对外文档、安装教程、价格、版本、平台限制必须回官方来源核对。

第七个翻车点：不看 Git。

改完不看 diff，最后无关文件也被提交。

第 16 节

16 / 新手 7 天练习路线

第 1 天：安装和只读项目。

目标：能运行 `claude`，登录成功，进入一个项目，让它解释结构。

第 2 天：写最小 `CLAUDE.md`。

目标：把启动、测试、构建命令写清楚。

第 3 天：改一个文档。

目标：只改 README，不碰代码，跑一次人工验收。

第 4 天：修一个小 bug。

目标：给复现步骤，让 Claude 定位、计划、修改、验证。

第 5 天：补一个测试。

目标：让 Claude 先找现有测试风格，再补测试，再跑测试。

第 6 天：用 VS Code 扩展看 inline diff。

目标：学会 @ mention 文件和审计划。

第 7 天：做一次完整闭环。

目标：从 issue 描述到修改、测试、diff、commit message、PR 草稿。

7 天后你不一定“精通 Claude Code”，但你会从“会问 AI”变成“能让 AI 参与真实工作”。

下一篇我们进入深度使用。

我们会讲 CLAUDE.md 分层、settings、permission rules、MCP、skills、hooks、subagents、worktrees、GitHub Actions、non-interactive mode 和团队治理。

资料参考

Claude Code Quickstart：https://code.claude.com/docs/en/quickstart

Claude Code Best practices：https://code.claude.com/docs/en/best-practices

Claude Code Common workflows：https://code.claude.com/docs/en/common-workflows

Claude Code Permission modes：https://code.claude.com/docs/en/permission-modes

Claude Code VS Code integration：https://code.claude.com/docs/en/ide-integrations

Claude Code Memory / CLAUDE.md：https://code.claude.com/docs/en/memory

Claude Code CLI reference：https://code.claude.com/docs/en/cli-reference

Claude Code Troubleshooting：https://code.claude.com/docs/en/troubleshooting