Claude Code 怎么用?官方上手 7 步走完整教程

Claude Code 怎么用看官方那段「first day」教程容易越看越懵,本文按 7 个步骤把安装、登录、打开项目、批准动作、第一条 prompt、写 CLAUDE.md、收尾全部走一遍

30 秒了解:Claude Code 怎么用,到底要按什么节奏

Claude Code 怎么用这件事,新手最容易犯的错是「装好就乱说一通」。 正确的节奏是 7 步:装 → 登 → 进项目 → 第一句 prompt 让它看 → 批准它的动作 → 写一份 CLAUDE.md 让它记住 → 学会用 Shift+Tab 切模式。这套节奏跟着走,你第一天就能干出真活。

这篇是官方 first-day 教程的中文实操版。如果你还没装,先按 Claude Code 安装教程 走一遍;如果你完全不知道 Claude Code 是什么、跟 Cursor / Copilot 的区别,先看 Claude Code 是什么 再回来。

准备工作:3 个前置条件

  • Claude Code 已经装好:终端跑 claude --version 能看到版本号
  • 有一个真实项目:哪怕是个 hello world 的小仓库都行,纯净空目录练不出感觉
  • 能稳定连 anthropic.com:国内用户配好代理

下面 7 步全部在终端里完成。

第 1 步:登录你的账号

打开终端,跑:

claude

第一次启动会让你认证。在 CLI 里输入:

/login

按回车,浏览器自动弹一个 Anthropic 登录页。登完点「Authorize」回到终端,看到 Authenticated as 你的邮箱 就 OK。

几种特殊登录方式

如果你不是用订阅,而是想用 API key、AWS Bedrock 或 GCP Vertex 走云厂商:

# 用 API key(按 token 计费)
export ANTHROPIC_API_KEY=sk-ant-...
claude

# 走 AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
claude

# 走 GCP Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
claude

公司给你发的是企业账号(Claude Enterprise / Team),用法跟个人账号一样:/login 走浏览器登录,权限和用量按公司套餐走。

第 2 步:进入项目目录

退出 CLI(按 Ctrl+C 两次或者 /exit),切到你的项目根:

cd ~/projects/my-app
claude

重要:永远在项目根目录启动。 Claude Code 启动那一刻读的是当前目录,子目录、上级目录的代码它默认不看(除非你显式 @ 引用或者 /add-dir 加进来)。

进去后你会看到一个简单的提示符,等你输入。

第 3 步:先让它看,别让它写

最关键的一步——第一句话千万别是「帮我加个 xxx 功能」。先让它认识项目,再让它干活。

复制下面这段当作万能开场:

Prompt 模板

你好。这是我们这个项目的第一次 Claude Code 会话。

在动手改任何文件之前,请先:

  1. 列出项目根目录的结构(前两层就行)
  2. 找 README.md / package.json / pyproject.toml / go.mod / Cargo.toml,告诉我这是什么项目、用什么语言和框架
  3. 找 CLAUDE.md,如果有读一遍并用一句话总结你接收到的约定
  4. 跑项目的测试命令(如果你能找到 npm test / pytest / go test),告诉我现在是不是绿的

完成上面 4 件事,等我下一步指令再改任何文件。

它会按这 4 步走一遍,输出结构、技术栈摘要、测试状态。这一步的价值是:你跟 Claude Code 建立了「共同上下文」,后面任何任务它都知道这个项目的脾气。

第 4 步:批准(或拒绝)它的动作

Claude Code 想改文件、跑命令之前,默认会先弹一个确认让你 y/n

举个例子,你说「帮我修 utils.ts 里那个 typo」,它会显示:

Edit utils.ts
   42:  export function formart(date: Date) {
   42:  export function format(date: Date) {

[1] Accept   [2] Accept all in this session   [3] Reject

3 个选项:

  • [1] 单次接受:只接受这一处改动,下次还是会问
  • [2] 接受这次会话剩下的所有改动:开「auto-accept」模式,相当于全权委托,跑完才停
  • [3] 拒绝:让你写理由,Claude Code 看到理由会调整方案

用 Shift+Tab 切换 3 个权限模式

Shift+Tab 在 3 个模式之间循环:

模式行为适合
default每个动作都问你第一次干这事、不放心
acceptEdits改文件自动批准,跑命令还问已经看过 plan,让它跑
plan只看不写,只输出方案探索阶段,先想清楚

新手强烈建议从 default 模式 起步——每个改动都看一眼,培养对 AI 输出的判断力。等你跑了几十次熟了,再开 acceptEdits 加速。

第 5 步:跑你的第一条真活 prompt

热完身,开始干第一件真事。官方推荐的 5 个新手任务:

  1. 让它总结整个 codebase
  2. 找某个功能在哪儿实现
  3. 给某个函数加文档注释
  4. 修一个失败的测试
  5. 帮你写 commit message 并 stage 改动

挑一个跟你项目相关的试。比如:

Prompt 模板

帮我找一下:项目里处理用户登录的代码在哪里?

要求:

  1. 列出所有跟登录相关的文件路径
  2. 用 2-3 句话总结当前登录流程是怎么走的
  3. 指出你看到的 1-2 个可能改进的点(不用改,只指出)

不要动任何文件,只回答。

它会读相关文件、给你答案。整个过程你能看到它在读哪些文件、调用了哪些工具——这是 Claude Code 跟网页版 Claude 最大的区别。

第 6 步:跑 /init 生成 CLAUDE.md

试完一两个任务后,趁热打铁让 Claude Code 给项目写一份「持久记忆」:

/init

它会再次扫描项目、识别约定(命名、目录结构、构建命令、测试方式),输出一份草稿 CLAUDE.md 让你审。

你做的事:

  1. 通读一遍它写的草稿
  2. 删掉它猜错的、加上它不知道的——比如团队内部不成文的规矩、protected directory、commit message 格式
  3. 保存,commit 到 git(这是个团队文件,应该入版本控制)

下次任何人在这个项目里启动 Claude Code,它都会自动读这份文件,行为立刻跟项目对齐。详细写法看 CLAUDE.md 怎么写

第 7 步:会话尾声 — 学会善后

跑完一段活,养成 3 个收尾习惯:

1. /cost 看花了多少

/cost

输出当前会话用了多少 token、估算了多少钱。Pro 套餐有用量上限,Max 套餐宽松些。养成「每次干完事看一眼」的习惯,对自己的消耗有数。

2. /clear 重置上下文

/clear

清空当前对话历史,但保留 CLAUDE.md。长会话里 Claude Code 上下文越积越多容易跑偏,跑完一段活就清一次,相当于「重启对话」。

3. git commit 落盘

Claude Code 帮你写完代码,它不会自动 commit。要么手动 git add . && git commit -m "...",要么让它帮你写 commit message:

Prompt 模板

帮我看一下当前所有未 commit 的改动,按 Conventional Commits 格式写一条合适的 commit message,然后帮我 git add 并 commit。

如果改动太杂(涉及超过 3 个独立主题),先拆成多个 commit。

5 个高频玩法,第一周就该上手

玩法 1:让它先 /plan 再动手

复杂任务别直接让它干。先按 Shift+Tab 切到 plan 模式,让它输出方案:

我想把当前 REST API 改成 GraphQL。你先给我一个分步骤的 plan,不要动任何文件。

它会列 5-15 步给你看。你 OK 才切回 default / acceptEdits 让它执行——避免「跑了半小时发现方向错了」。

玩法 2:用 @ 精准喂上下文

输入 @ 触发文件引用:

帮我看 @src/components/Button.tsx 里的样式逻辑,搬到 @src/components/Card.tsx

比让它「自己找」更准、更省 token。

玩法 3:/rewind 回滚

发现 Claude Code 干歪了,按 Esc 两次或者 /rewind,能回到对话里某个 checkpoint,连同代码一起回滚。比 git reset 更细——它记得每个动作前的状态。

玩法 4:/model 切大小模型

跑常规任务用 Sonnet(快、便宜),跑大重构用 Opus(聪明、贵):

/model

会列出当前账号能用的模型让你选。养成「干活前先选合适模型」的习惯,每月省一大笔。

玩法 5:/context 看脑容量

/context

显示当前上下文窗口用了多少 token、还剩多少。看到快满了就 /compact 压缩,或者 /clear 重置。

常见的 4 个坑

现象原因解决
Claude Code 一直问你 y/n 烦死还在 default 模式Shift+Tab 切到 acceptEdits
改完代码跑测试,结果没跑它默认不会自动跑测试prompt 里明确说「改完跑 npm test 验证」
中文输出夹杂英文上下文里有英文文档在 prompt 里加一句「全部用中文回答」
跑大任务跑一半断了上下文超了 / 网络波动跑前先 /compact,或者拆成小步骤

一个完整实战:让 Claude Code 帮你写一个 README

假设你接手一个老项目,README 缺失。用这个完整流程让 Claude Code 给你写一份:

Prompt 模板

任务:给当前项目写一份高质量 README.md

要求:

  1. 先看 package.json / pyproject.toml 等元数据,识别项目用途
  2. 看 src/ 下的目录结构,识别架构
  3. 看测试目录和 CI 配置,识别开发流程
  4. 看 examples/ 或 demo/,识别使用示例
  5. 然后写 README,包含:
    • 一句话定位
    • 安装步骤(写真实可跑的命令,不要占位符)
    • 最小可用示例(5 行能跑通的代码)
    • 完整 API 概览(列主要的导出函数 / 命令)
    • 贡献指南简短一段
  6. 用中文写
  7. 写完前先输出 outline,等我说 OK 再写完整版

不要动 src/ 任何文件,只生成 README.md

跑一遍你会发现:它先按步骤探索、输出 outline、等你确认、再写完整 README、最后让你批准创建文件——整个过程节奏分明、可控。这就是 Claude Code 比「让 ChatGPT 写代码再复制粘贴」强的地方。

完整项目实战:用 Claude Code 给一个已有 Astro 静态站加深色模式

写 README 还只是「让 AI 看代码、生成文档」的轻量级活,下面这个项目是我真的在自己一个老博客上跑完的。目标:给一个已有的 Astro 静态站(10 几个页面,原本只有亮色主题)加一套深色模式——包含主题切换按钮、跟随系统、记住用户选择、所有现有页面 CSS 兼容。这种活我自己手写大概要 4-6 小时(要改十几个组件的颜色变量),用 Claude Code 跑下来 1 小时 20 分钟,全程我只批准 / 拒绝按钮,没敲一行代码。

项目目标

具体到可验证的成果:

  • 网站右上角 nav 出现一个「太阳 / 月亮」切换按钮
  • 第一次访问跟随系统主题(OS 是深色就深色)
  • 用户手动切换后,选择存到 localStorage,下次访问保持
  • 所有现有页面(首页、文章页、列表页、关于页)在深色模式下文字 / 背景 / 代码块 / 链接颜色全部协调
  • 不破坏现有的 Tailwind 4 配置和 typography 插件
  • 改完跑一遍 pnpm build 必须通过

步骤 1:准备工作(8 分钟)

先把项目状态弄干净:

cd ~/projects/my-blog
git status   # 确认 working tree 干净
git checkout -b feat/dark-mode   # 开新分支,万一搞砸了直接弃
claude

进入 Claude Code 后第一句话不要让它写代码。先按 Shift+Tab 切到 plan 模式(只看不写),然后让它认识项目:

Prompt 模板

你好。这是一个 Astro 5 + Tailwind 4 的静态博客项目。我准备给它加一套深色模式。

在动手之前,请先:

  1. 列出 src/ 下的目录结构(前两层)
  2. 找 tailwind.config.* / astro.config.* / src/styles/global.css,告诉我当前 Tailwind 是哪个大版本、有没有用 typography 插件、当前用的是哪种颜色配置方式(CSS 变量 / Tailwind 默认色板 / 自定义 theme)
  3. 列出所有 .astro 组件里直接写了颜色相关 class(比如 text-gray-900 / bg-white)的文件清单
  4. 看看现有的 Layout 是怎么组织的,主题切换按钮应该放在哪个组件里最合适

完成后等我下一步,不要改任何文件。

Claude Code 跑大约 2 分钟,输出了一份相当清晰的现状报告:Tailwind 4 + typography 插件、颜色是 Tailwind 默认色板硬编码(没用 CSS 变量)、12 个 .astro 组件里直接写了 bg-white / text-gray-900、Layout 在 src/layouts/BaseLayout.astro

步骤 2:第一次跑(25 分钟)

让 Claude Code 出一份执行 plan,还在 plan 模式:

Prompt 模板

基于你刚才识别到的现状,请输出一份「给这个站加深色模式」的详细 plan。要求:

  1. 分阶段(如:颜色变量改造 → 切换按钮 → 持久化 → 全页面适配 → 验证)
  2. 每个阶段列出要改的具体文件和大致改动
  3. 估算每个阶段大概要改多少行代码
  4. 指出 1-2 个你预判会遇到的难点(比如某个组件的颜色不好处理)
  5. 最后告诉我你建议先跑哪 2-3 个阶段、哪些可以放到后面

输出后等我确认,再切到 acceptEdits 让你执行。

Claude Code 输出了一份 5 阶段 plan:① 把 Tailwind 配置改造成支持 dark: 前缀 + class 模式;② 在 BaseLayout.astro 加一段内联 script 决定初始 theme;③ 新建 ThemeToggle.astro 组件放到 nav;④ 12 个组件批量加 dark: 变体;⑤ typography 插件单独配 dark:prose-invert。它预判的难点是 typography 插件——这个我之前自己折腾过确实是大坑,它能提前指出来说明真看了文档。

我审 plan 没问题,按 Shift+Tab 切到 acceptEdits 模式,发:

Prompt 模板

plan 看过了,按你的顺序跑前 3 个阶段(Tailwind 配置 + Layout 初始 theme script + ThemeToggle 组件)。

每个阶段做完先告诉我改了哪些文件、改了什么,让我看一眼再继续下一个阶段。

前 3 个阶段大概跑了 15 分钟,Claude Code 改了 4 个文件(tailwind 配置 + global.css + BaseLayout.astro + 新建 ThemeToggle.astro),每个改动我都批准了。中间我跑了一下 pnpm dev 看效果,切换按钮出现了,点一下页面 nav 区域确实变深色——但文章正文还是亮色的(因为还没跑阶段 ④ ⑤)。

步骤 3:处理第一次失败(22 分钟)

让 Claude Code 跑阶段 ④(12 个组件批量加 dark: 变体)的时候出了问题:它扫了一遍组件,开始批量改,但改到第 5 个组件时改错了——把 text-gray-900 改成了 text-gray-900 dark:text-white,但那个组件本身是一个「卡片标题」,深色背景下 text-white 跟周围 text-gray-300 的副标题太突兀,对比度过高刺眼。

而且阶段 ⑤ 的 typography 插件适配它漏了一个细节prose-invert 加上去了,但代码块 <pre> 的背景色还是 typography 默认的浅灰,深色模式下整个代码块像一张白纸贴在黑屏上。

打断它,发修正:

Prompt 模板

停一下,两个问题:

  1. 你批量改的 dark: 颜色映射太粗暴了。规则改一下:

    • text-gray-900 → dark:text-gray-100(不是 dark:text-white,留点呼吸空间)
    • text-gray-700 → dark:text-gray-300
    • text-gray-500 → dark:text-gray-400(保持次要文字感)
    • bg-white → dark:bg-gray-900
    • bg-gray-50 → dark:bg-gray-800
    • border-gray-200 → dark:border-gray-700 请按这套映射重新跑一遍前 5 个组件。
  2. typography 插件深色模式下代码块背景没适配。在 global.css 里加一段: .dark .prose pre { background-color: rgb(31 41 55); /* gray-800 / color: rgb(229 231 235); / gray-200 / } .dark .prose code { color: rgb(252 211 77); / amber-300,inline code 跟 pre 区分开 */ }

改完跑一下 pnpm build 确认没报错。

Claude Code 按新映射重新跑了一遍,又改了 global.css 加上 typography 深色样式,最后跑 pnpm build 通过。

步骤 4:拿到最终结果(15 分钟)

让 Claude Code 跑剩下的阶段 ⑤ 完整版(剩余 7 个组件 + 一些边边角角的 hover / focus 状态),跑完后做最终验证:

Prompt 模板

全部跑完了。请帮我做最终验证:

  1. 重新跑 pnpm build,确认 0 error 0 warning
  2. 在终端给我跑一下 grep 检查:现在 src/ 下还有没有 .astro 文件里有「text-gray-」「bg-white」「bg-gray-」但没有对应 dark: 变体的(漏网之鱼)
  3. 列出本次会话改过的所有文件清单
  4. 帮我写一条 Conventional Commits 格式的 commit message(feat: …),但先不要 commit,我自己手动 commit

Claude Code 跑了 grep 找出 2 个漏网组件(一个 footer + 一个 404 页),又补了一遍,最后输出了一份干净的改动清单和 commit 草稿。我自己 review 一遍 git diff(大概 200 行改动,挨个看了一下没问题),手动 commit、推到 GitHub、Cloudflare Pages 自动部署上线。

项目总耗时 + 成果

  • 总耗时:1 小时 20 分钟(Claude Code 实际干活约 50 分钟,我 review + 决策约 30 分钟)
  • 省下时间:vs 我自己手写改 14 个组件 + 适配 typography,至少省 3 小时
  • 改动规模:14 个文件 / 约 200 行改动 / 1 个新建组件
  • 复用价值:plan + 修正 prompt 我存到了 CLAUDE.md 里,下次给别的 Astro 站加深色模式直接抄一遍

5 个我踩过的坑(你别再踩)

下面这 5 个坑是我用 Claude Code 大概 3 个月、跑了上百次任务之后总结的,每个都让我至少一次「白干 30 分钟」。

坑 1:第一次会话上来就让它写代码

症状:你装好 Claude Code,进项目目录就直接说「帮我加一个用户登录功能」,它噼里啪啦改了一堆文件,结果——风格跟项目其他代码完全不一样,import 路径写错,用了项目根本没装的库。

原因:Claude Code 启动那一刻没有任何上下文——它不知道这个项目用什么框架、什么风格、什么命名约定。你直接让它写,它就按「通用最佳实践」写,跟你项目八字不合。

解决:第一句永远先让它看、别让它写(就是本文第 3 步的开场 prompt)。或者用下面这个「冷启动」prompt:

Prompt 模板

这是我们第一次会话。在动任何文件之前,请按顺序做这 5 件事:

  1. 列出根目录前两层结构
  2. 读 package.json / pyproject.toml / go.mod,告诉我语言 + 框架 + 主要依赖
  3. 读 CLAUDE.md(如果存在),用 3 句话总结你接收到的约定
  4. 跑测试命令(如果你能找到),告诉我测试现状
  5. 看 2-3 个核心组件 / 模块的代码,总结这个项目的「风格特点」(命名、注释密度、错误处理方式)

完成这 5 件事再等我下一步指令。不要修改任何文件。

坑 2:在 default 模式手动 y/n 几十次按麻木了,全程乱按

症状:跑一个稍微复杂的重构,Claude Code 弹出 30+ 个确认弹窗让你 y/n。前 5 个你认真看,后 25 个开始机械按 Enter,最后跑完发现有 2 处改动你根本没看清就放过了,回头 review 一脸懵。

原因:default 模式的 y/n 是设计给「不放心 / 第一次」用的,对成熟任务过于啰嗦。但很多新手怕开 acceptEdits 会失控,硬着头皮 default 跑大任务。

解决:分清楚什么任务用什么模式——

  • 探索阶段(让它读代码、出方案):plan 模式(Shift+Tab 两次)
  • 小范围修改(改 1-3 个文件):default 模式,每个都看
  • 大批量重构 + 已经审过 plan:acceptEdits 模式,让它一口气跑完,跑完用 git diff 整体 review

后两种模式的关键是先 commit 一个干净状态,万一跑歪 git reset --hard HEAD 一下就回来了。养成「acceptEdits 前先 commit」的肌肉记忆。

坑 3:让它跑大任务,跑到一半上下文炸了重新开始

症状:跑一个跨 20 个文件的重构,跑到第 13 个文件 Claude Code 突然「忘掉」前面的约定,把已经统一好的命名风格又改回旧的,或者干脆开始重复改前面已经改完的文件。

原因:上下文窗口被吃满了。你能看到 /context 显示已用 95%+ 的时候,Claude Code 实际上已经在「丢早期记忆」。

解决:跑大任务前主动规划上下文预算——

  • 任务开始前先 /context 看剩余空间
  • 估算这个任务大概要读 + 改多少文件(每个文件大概 1-3k token)
  • 如果预算不够,任务拆成 2-3 段,每段做完跑 /compact 把对话压缩,再继续下一段
  • 或者干脆用 /clear 重置(CLAUDE.md 会保留),下一段从 /clear 之后的干净状态重新开始

记住:/clear 之后让它读 CLAUDE.md 重新建立上下文,比硬撑着跑到出错强 10 倍。

坑 4:让它跑命令,结果它「跑了个寂寞」(mock 输出)

症状:你说「帮我跑一下 pnpm test 看测试过没过」,它回你「测试已通过,全部 24 个用例 green」,你高高兴兴 commit,CI 上一跑挂了 8 个测试。回头看 Claude Code 那次会话,发现它根本没真的执行命令——它「假装」跑了。

原因:Claude Code 在 default 模式下跑命令也是要请求授权的,如果你的弹窗设置或者权限模式有问题,它会「认为」没权限直接跳过,但回复给你的时候话术暧昧(「测试已通过」其实是它推测的,不是观察到的)。

解决:强制它贴出命令的实际 stdout。这条规则我建议写进 CLAUDE.md:

Prompt 模板

关于跑命令的规则:

  • 任何让你跑命令的请求,你必须真实执行(默认走 Bash 工具)
  • 执行完必须把命令的完整 stdout / stderr 原文贴回对话里给我看,不要只总结「通过 / 失败」
  • 如果你因为权限被拒绝、找不到命令、网络问题等原因没真跑,必须明说「我没能执行这条命令,原因是 X」,绝对不允许假装跑了
  • 测试 / build 类命令尤其重要——只看到「绿了」三个字我不信,必须看到测试框架的原始输出

坑 5:写完代码忘记让它跑 lint / typecheck,CI 才报错

症状:Claude Code 帮你写完一个功能,本地 build 也过了,commit 推上去 CI 红了——typecheck 报 5 个类型错误,eslint 报 12 个 warning。Claude Code 没主动跑这些检查,你也忘了让它跑。

原因:Claude Code 默认只会跑你 prompt 里明确要求的命令。它不会「自作主张」跑 lint / typecheck,除非项目 CLAUDE.md 写明了。

解决:把「写完代码必跑」清单沉到 CLAUDE.md 里。范例:

## 完成定义(DoD)
任何写代码 / 改代码的任务,「完成」必须满足:
1. 跑 `pnpm typecheck` 通过(0 error)
2. 跑 `pnpm lint` 通过(0 error,warning 可以保留但要列出来)
3. 跑 `pnpm test` 通过(如果改动涉及有测试覆盖的模块)
4. 跑 `pnpm build` 通过
跑完 4 项任意一项失败,先修复再说「完成」。不允许跳过任何一项就声明完成。

这段写进 CLAUDE.md 之后,Claude Code 每次任务收尾会自动跑这 4 个检查,CI 红灯率从我之前的 30% 降到不到 5%。

进阶 / 下一步

常见问题

Q:Claude Code 跟 Cursor 比,谁更适合新手? A:纯新手(没用过 terminal)选 Cursor,图形界面友好。有一点命令行基础(会 cd、ls、git)的人选 Claude Code,长任务能力更猛。两者不冲突,很多人两个都用。

Q:第一次用就让它改大项目可以吗? A:可以,但务必:1) 项目是干净的 git 状态(所有改动都 commit),2) 在 plan 模式先让它输出方案、你审过,3) acceptEdits 模式让它执行。万一出问题 git reset 一下就回来了。

Q:能不能离线用? A:不能。Claude Code 每个动作都要请求 Anthropic API,没网络它一句话都说不了。

Q:跟 Claude 网页版可以共享会话吗? A:不能。两个产品是分开的,记忆不互通。但 CLAUDE.md 你可以同时复制一份到 Claude 网页版的 Project 里,作为持久 context 用。

Q:会不会改坏我代码? A:会,但风险可控。3 道防线:1) 默认每个动作都问你 y/n,2) git 让你能 reset 回去,3) /rewind 能回滚到某个 checkpoint。养成「干活前 commit、干完 review、有问题 rewind」的习惯。