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 功能」。先让它认识项目,再让它干活。
复制下面这段当作万能开场:
你好。这是我们这个项目的第一次 Claude Code 会话。
在动手改任何文件之前,请先:
- 列出项目根目录的结构(前两层就行)
- 找 README.md / package.json / pyproject.toml / go.mod / Cargo.toml,告诉我这是什么项目、用什么语言和框架
- 找 CLAUDE.md,如果有读一遍并用一句话总结你接收到的约定
- 跑项目的测试命令(如果你能找到 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 个新手任务:
- 让它总结整个 codebase
- 找某个功能在哪儿实现
- 给某个函数加文档注释
- 修一个失败的测试
- 帮你写 commit message 并 stage 改动
挑一个跟你项目相关的试。比如:
帮我找一下:项目里处理用户登录的代码在哪里?
要求:
- 列出所有跟登录相关的文件路径
- 用 2-3 句话总结当前登录流程是怎么走的
- 指出你看到的 1-2 个可能改进的点(不用改,只指出)
不要动任何文件,只回答。
它会读相关文件、给你答案。整个过程你能看到它在读哪些文件、调用了哪些工具——这是 Claude Code 跟网页版 Claude 最大的区别。
第 6 步:跑 /init 生成 CLAUDE.md
试完一两个任务后,趁热打铁让 Claude Code 给项目写一份「持久记忆」:
/init
它会再次扫描项目、识别约定(命名、目录结构、构建命令、测试方式),输出一份草稿 CLAUDE.md 让你审。
你做的事:
- 通读一遍它写的草稿
- 删掉它猜错的、加上它不知道的——比如团队内部不成文的规矩、protected directory、commit message 格式
- 保存,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:
帮我看一下当前所有未 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 给你写一份:
任务:给当前项目写一份高质量 README.md
要求:
- 先看 package.json / pyproject.toml 等元数据,识别项目用途
- 看 src/ 下的目录结构,识别架构
- 看测试目录和 CI 配置,识别开发流程
- 看 examples/ 或 demo/,识别使用示例
- 然后写 README,包含:
- 一句话定位
- 安装步骤(写真实可跑的命令,不要占位符)
- 最小可用示例(5 行能跑通的代码)
- 完整 API 概览(列主要的导出函数 / 命令)
- 贡献指南简短一段
- 用中文写
- 写完前先输出 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 模式(只看不写),然后让它认识项目:
你好。这是一个 Astro 5 + Tailwind 4 的静态博客项目。我准备给它加一套深色模式。
在动手之前,请先:
- 列出 src/ 下的目录结构(前两层)
- 找 tailwind.config.* / astro.config.* / src/styles/global.css,告诉我当前 Tailwind 是哪个大版本、有没有用 typography 插件、当前用的是哪种颜色配置方式(CSS 变量 / Tailwind 默认色板 / 自定义 theme)
- 列出所有 .astro 组件里直接写了颜色相关 class(比如 text-gray-900 / bg-white)的文件清单
- 看看现有的 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 模式:
基于你刚才识别到的现状,请输出一份「给这个站加深色模式」的详细 plan。要求:
- 分阶段(如:颜色变量改造 → 切换按钮 → 持久化 → 全页面适配 → 验证)
- 每个阶段列出要改的具体文件和大致改动
- 估算每个阶段大概要改多少行代码
- 指出 1-2 个你预判会遇到的难点(比如某个组件的颜色不好处理)
- 最后告诉我你建议先跑哪 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 模式,发:
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 默认的浅灰,深色模式下整个代码块像一张白纸贴在黑屏上。
打断它,发修正:
停一下,两个问题:
你批量改的 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 个组件。
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 状态),跑完后做最终验证:
全部跑完了。请帮我做最终验证:
- 重新跑 pnpm build,确认 0 error 0 warning
- 在终端给我跑一下 grep 检查:现在 src/ 下还有没有 .astro 文件里有「text-gray-」「bg-white」「bg-gray-」但没有对应 dark: 变体的(漏网之鱼)
- 列出本次会话改过的所有文件清单
- 帮我写一条 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:
这是我们第一次会话。在动任何文件之前,请按顺序做这 5 件事:
- 列出根目录前两层结构
- 读 package.json / pyproject.toml / go.mod,告诉我语言 + 框架 + 主要依赖
- 读 CLAUDE.md(如果存在),用 3 句话总结你接收到的约定
- 跑测试命令(如果你能找到),告诉我测试现状
- 看 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:
关于跑命令的规则:
- 任何让你跑命令的请求,你必须真实执行(默认走 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%。
进阶 / 下一步
- 命令速查表 → Claude Code 命令速查表
- 写持久记忆 → CLAUDE.md 怎么写
- 进阶 10 技巧 → Claude Code 进阶 10 技巧
- 装出问题 → Claude Code 安装教程
- 跟其他工具比 → AI 写代码完全指南
- 想用国产替代 → Kimi Code CLI 怎么用
常见问题
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」的习惯。