claude code 入门指南：从安装到第一个项目

去年年底，我在重构一个运行了四年的 NestJS 后端项目时，第一次尝试让 Claude Code 帮我做全项目级的安全扫描和批量迁移，结果它直接删掉了三个关键中间件，还顺手把我写在注释里的 API 密钥一起提交到了测试分支。那次事故让我明白了一件事：Claude Code 不是一个加强版的自动补全工具，它是一把需要握对方向的全功能电锯。 而大多数“从安装到第一个项目”的教程，只教会了你如何按下开关，没告诉你为什么手会抖、血会流。

所以这篇文章不会只让你复制三行命令跑出“Hello World”。我会用我自己的踩坑经验，把 为什么用、怎么装、怎么配、怎么让它看懂你的项目、怎么跑通第一个真正有用的任务 这几个环节拆开来讲清楚。如果你已经用过 GitHub Copilot 或 Cursor、能自己在终端里装软件但还没碰过 Claude Code，这篇文章就是为你写的。

一、一个被大多数教程忽略的前提：你到底需不需要 Claude Code？

1. 它不是“又一款 AI 编程工具”

如果你已经习惯了在 VSCode 里按 Tab 接受 Copilot 的补全，或者在 Cursor 的对话框里让 AI 帮你改一个函数，你可能觉得 Claude Code 只是同样的东西换了个交互界面。但是你真正装上它并跑了两次任务之后，就会意识到它的定位完全不一样。

Claude Code 是一个命令行里的 AI 编程代理，它的默认工作单元不是“一次补全”，而是“完成一个任务”。 你可以让它“把这个目录下所有 Markdown 文件的二级标题改成疑问句形式”，它会自己去读文件、分析标题结构、改写、保存，然后再回来汇报结果。这种能力背后是几个关键差异：

这并不是说 Claude Code 比 IDE 插件更好，而是 它们适合的场景完全不同。我现在的日常组合是：日常编码用 Cursor 做实时补全，需要跨模块重构、批量操作、写自动化脚本、审查整个仓库的代码质量时，切到终端打开 Claude Code。两条腿走路，才是成年人的选择。

2. 什么情况下你会觉得物超所值

我个人用下来的感受是，有三个场景一旦遇到，你就会后悔没早点装 Claude Code：

• 遗留项目重构

面对一个没有文档、作者已离职的老项目，Claude Code 可以帮你快速梳理模块依赖关系。你只需要说一句“帮我列出所有定义了但未被实际调用的函数”，它就能从几十个文件里扫出结果。换作以前，我得手动跑 ESLint 插件再人肉过滤，一个下午就没了。

• 批量模式转换

比如团队突然决定从 CommonJS 切到 ES Module，或者要把所有 React class component 改成 function component。这种时候，我对 Claude Code 说“按项目现有的 ESLint 规则，把 src 下所有 .js 文件从 require/module.exports 改成 import/export”，它就开始默默干活，我喝杯咖啡回来看 diff，把不对劲的地方挑出来让它重改。

• CI/CD 里的代码审查助理

我们团队现在把 Claude Code 接进了 CI 流水线，专门负责自动生成 Pull Request 的摘要和潜在风险点说明。这个用法比人工写 PR 描述靠谱得多，因为它不会漏掉跨文件的副作用。

这三个场景的共同点是：你需要的不仅仅是“根据上下文猜下一步代码”，而是需要一个能理解项目全貌、并且愿意帮你执行重复劳动的 AI 代理。 如果你现在的工作里这种需求超过 30%，Claude Code 就值得花一个下午去装好、配好、跑通第一个任务。

二、装之前必须想清楚的一件事：它不是免费的

1. 安装软件不花钱，但每一次“干活”都要消耗 API 额度

几乎所有搜出来的教程都在教你 npm install 然后 claude 启动，但它们都不约而同地回避了一个关键问题：Claude Code 本身不提供免费额度，你每次让它做事，都要消耗 Anthropic API 的调用费用，或者你自己对接的第三方模型 API 的费用。

这就意味着，如果你直接用官方 An​​thropic 的 API，Claude Code 的每一次问答、每一次文件操作，背后都会产生 Token 计费。根据模型不同，价格差异很大：

我用 Claude Code 时的实际开销是这样的：一个中等规模的重构任务，比如让 AI 帮我改 50 个文件里的组件引入路径，消耗大概在 $0.3 到 $1 之间。如果你一天用它 10 次以上，月开销可能到三四十美金。但对比它省下的时间，我认为是值的。

这个成本结构决定了一个行为习惯：你不会把它当成随叫随到的自动补全，而是会学会清晰地描述任务、控制任务范围，避免无意义的重复对话。 这其实是一种使用者能力的被迫成长。

2. 怎么控制成本？

三个实操建议，都是我交了学费之后总结出来的：

• 默认用 Sonnet，只在复杂架构问题才切 Opus。Claude Code 的 settings.json 里可以单独指定模型，不要一上来就全局设为 Opus，否则第一个任务跑到一半账单就会让你血压升高。
• 任务范围要精确到路径，不要每次都“扫描整个项目”。比如改一个模块，就直接指定 src/modules/order，不要让它盲目遍历 node_modules 和 .git 文件夹。
• 善用 .claude.md 提供足够上下文，减少它“试错对话”的次数。这一点在后面的进阶篇会详细展开，但你要先有一个认知：你给它的上下文越多，它问你的次数就越少，你花的钱也就越少。

三、安装和基础配置：让它在你的机器上醒过来

1. 环境要求：Node.js 18+ 不是一句废话

我见过太多文章写“请确保已安装 Node.js 18 或以上版本”，然后就没有然后了。但是相信我，Node.js 的版本问题在你安装时至少会产生两种类型的坑：

• Windows 环境下用 nvm-windows 管理多版本，很容易装完 18 之后全局 npm 包路径依然指向旧版本，导致 npm install -g 后运行 claude 提示 command not found。
• Linux 服务器上有些发行版（如 Ubuntu 20.04）自带的 Node.js 是 12 或 14，你用 apt 直接装 18 需要加 NodeSource 源，否则一键安装后版本不对，Claude Code 会直接报错退出。

我的建议是，先跑一下 node -v 和 npm -v，确认输出是 v18.x 或 v20.x。如果你需要装 Node.js，不要直接从官网下载 .pkg 或者 .exe 无脑安装，而是先看你的系统有没有类似版本管理工具：

• macOS / Linux：推荐用 nvm
• Windows：推荐用 nvm-windows 或直接使用 fnm（跨平台，速度快）

下面是我在 Mac 上完整安装 Node.js 20 的过程，你可以直接参考：

# 如果没有 nvm，先装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

重启终端或source一下

nvm install 20

nvm use 20

node -v  # 确认输出 v20.11.0 或类似

2. 安装 Claude Code

这一步确实简单，但有两个注意事项会让你的体验完全不同。

安装命令：

npm install -g @anthropic-ai/claude-code
第一件容易踩坑的事：npm 源的问题。 如果你的网络环境访问 npm 官方仓库时断时续，安装过程中包的下载可能会卡在 50% 不动。我习惯在执行前先设置国内镜像源：

npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code

装完之后运行 claude，如果终端提示找不到命令，大概率是 npm 全局包路径没有在 PATH 里。你可以用 npm bin -g 查看全局包的实际安装位置，然后把这个路径加到你的 shell 配置文件（如 .zshrc 或 .bashrc）的 PATH 里。

3. 配置 API 密钥

装好之后，不配置 API 密钥是无法正常使用的。这一步我在三个不同的机器上操作过，整理出最稳妥的流程：

如果你直接用 Anthropic 官方 API：

export ANTHROPIC_API_KEY='sk-ant-...'
去 console.anthropic.com 登录，点击 “Get API keys”
创建新密钥，复制下来
在终端里设置环境变量（推荐，不要写死在代码里）：
为了持久化，把这行加进你的 .zshrc 或 .bashrc 文件。

如果你想接入第三方兼容接口（比如使用更便宜的国产大模型）：

Claude Code 支持修改 settings.json 来对接任何兼容 Anthropic 协议的服务。你需要创建或编辑 ~/.claude/settings.json：

{
"apiKey": "your-api-key-here",

"model": "claude-sonnet-4-20250514",

"baseURL": "https://your-proxy-endpoint.com/v1"

}

这里 baseURL 就是第三方提供商的接口地址。注意：不是所有的第三方都能完美兼容 Claude Code 的 tool use 能力，尤其 Skills 和 MCP 特性对模型的要求较高，换模型后可能会出现功能异常。 我尝试过用某个国产模型代理，结果它只能做普通对话，无法执行文件操作，相当于功能被阉割了一半。所以如果你希望完整体验，建议至少初期用官方 Sonnet 模型，等熟练之后再考虑切换。

四、让 Claude Code “看懂”你的项目：.claude.md 是你和它的共同记忆

这是整篇文章里我最想讲的部分，因为 90% 的教程在这里完全空白。它们教完安装就直接让你输入 claude 然后开始对话，仿佛这样就“跑通了第一个项目”。但实际上，没有 .claude.md 的 Claude Code，就像一个第一天入职却没收到任何交接文档的新员工，它只能靠猜，而猜的代价就是反复问答、错误推理和浪费 Token。

1. .claude.md 到底是什么？

简单说，它是你放在项目根目录下的一个 Markdown 文件，Claude Code 每次启动时都会自动读取它，把它作为整个会话的基础上下文。 你可以把它理解成“给 AI 的项目说明书”，里面写着这个项目的技术栈是什么、目录结构怎么划分、编码规范是怎样的、有哪些需要特别注意的坑。

这份文件不是一次性写完就扔的。我在我们这个后端项目里维护的 .claude.md，从第一个版本到现在已经迭代了 7 次，每次项目架构发生变化或者 Claude Code 犯了新的理解错误，我都会回头去更新它。

2. 怎么写一份能让 AI 少犯错的 .claude.md？

这里我直接给出一个真实项目的模板，它来自我们团队一个微服务电商系统，你可以根据自己的项目做调整：

# 项目概述
本项目是一个基于 NestJS 的微服务电商系统，包含订单、商品、用户、支付等 5 个核心服务。

整体采用 Monorepo 架构，使用 pnpm workspace 管理多包。

技术栈

后端框架：NestJS 10.x，语言 TypeScript 5.x

数据库：PostgreSQL 14，通过 TypeORM 连接

消息队列：RabbitMQ 3.12

缓存：Redis 7

测试框架：Jest + Supertest

代码规范：ESLint (airbnb-base) + Prettier

目录结构

apps/ : 各个微服务入口

order/ : 订单服务

product/ : 商品服务

user/ : 用户服务

libs/ : 共享库

common/ : 通用工具、拦截器、装饰器

database/ : 数据库连接和实体定义

dto/ : 数据传输对象

关键约定

所有的 API 请求参数和返回类型必须定义 DTO，不允许使用 any。

数据库实体必须放在 libs/database/src/entities 下，文件名小写加 .entity.ts。

日志统一使用 NestJS 内置 Logger，不要在代码里出现 console.log。

每次修改完代码后，必须运行 pnpm run test:unit 确保已有测试通过。

已知问题与注意事项

支付服务目前回调处理是同步的，尚未改为异步消息，相关改动需谨慎评估事务边界。

user 服务的单元测试覆盖率只有 38%，主要缺失边缘场景，重构时请帮忙补测试。

Redis 连接没有做哨兵模式，目前单节点，暂不考虑高可用。

这样一份说明书写好之后，Claude Code 在接到任务“帮我在订单服务里加一个取消订单的接口”时，就不会乱写 Express 风格的代码，也不会把实体定义放到 apps 目录下，更不会忘记写 DTO。 它还会知道应该在哪一步之后运行测试命令来检查是否改坏了已有功能。

3. 维护 .claude.md 的实践经验

我踩过的最大的坑，是 .claude.md 写成了一篇“技术文档”，而不是“给 AI 的行动指令”。早期我放了太多背景故事，比如项目历史、过往架构演进，结果 Claude Code 花了大量 Token 去阅读这些无效信息，却没有得到足够清晰的行为约束。

有效的 .claude.md 应该满足三个原则：

• 约束性强：多用“必须”、“不允许”、“统一使用”这样的词，避免模糊表述。
• 粒度适中：不要写“我们代码写得很干净”这种废话，要具体到“所有异步操作必须用 async/await，禁止使用 .then 链”。
• 与任务直接相关：如果你的任务只涉及后端代码，就不要在 .claude.md 里写前端目录结构，否则只会浪费上下文窗口。

五、第一个项目：用一次真实的重构任务跑通全流程

“第一个项目”不应该是一个 Hello World 打印，也不该是让 AI 生成一个简单的 Express 服务器，这些你靠 IDE 插件 30 秒就能完成，完全感受不到 Claude Code 的独特价值。我建议你用一个需要跨文件操作、有明确输入输出、有验证标准的任务来作为第一个实战。

下面是我带新人时常用的一个任务，你可以直接在自己项目里复刻。

1. 任务描述：统一所有日期格式处理函数

假设你的项目里有一个 src/utils/date.ts 工具函数文件，以及其他业务模块中散落着各种自制的日期格式化代码（有的用 dayjs，有的用原生 Date，有的甚至用字符串拼接）。你的目标是：把这些分散的日期处理全部统一到 date.ts 中的几个标准函数，并修改所有调用方。

听起来简单，但实际上它涉及：扫描全项目找出现有日期处理代码、分析哪些可以复用、重构复用部分、替换调用方、跑测试验证。这是一个典型的多文件重构任务，刚好能体现 Claude Code 的能力。

2. 实际操作步骤

Step 1: 启动 Claude Code 并明确任务边界

在你的项目根目录下打开终端，先不急着交任务，而是先告诉 Claude Code 你要工作在哪个范围：

cd your-project
claude

然后你会看到交互界面。输入第一段话：

> 我要重构项目中的日期处理逻辑。请在 src 目录下（不包括 node_modules 和 dist）找出所有使用了 dayjs、new Date()、或字符串操作进行日期格式化的代码，列出文件路径和函数名，以及它们各自使用的日期库或方法。

这时 Claude Code 会开始扫描文件，返回类似这样的结果：

• src/utils/date.ts: 已定义了 formatDate 和 parseDate 两个函数，使用 dayjs
• src/modules/order/order.service.ts: 第 42 行直接用 new Date().toISOString()
• src/modules/report/report.controller.ts: 第 78 行使用 dayjs 但直接从 dayjs 库导入，没有复用 date.ts
• ……

Step 2: 让 Claude Code 生成重构方案并审核

接着下达第二个指令：

> 现在请帮我制定一个重构方案：将所有日期格式化统一复用 date.ts 中的 formatDate，将时间差计算复用 date.ts 中的 getTimeDiff。请先生成修改计划，不要直接修改代码。

Claude Code 会给出一个分文件、分步骤的修改计划。这时你要做的是仔细审核这个计划，看看它有没有误解业务逻辑，这一步是不可省略的，毕竟你要为最终的代码负责。

Step 3: 执行重构并观察 diff

审核通过后，告诉它：

> 按刚才的计划执行，每修改一个文件，先展示 diff 等我确认。

这时 Claude Code 会逐一打开文件、做修改、展示 diff，你在终端里按 y 确认。这个过程很像自己在手动重构，但代码是 AI 写的，你负责审核和拍板。

Step 4: 运行测试验证

所有文件改完之后，对它说：

> 运行 pnpm run test:unit 并告诉我哪些测试失败了。

如果一切顺利，你会看到全绿通过。如果失败了，Claude Code 会分析失败原因，并提出修复方案。这个过程还可以接着交互，直到测试全部通过。

3. 这个实战任务的价值在哪里？

跑完这整个流程之后，你会真正体会到 Claude Code 和 IDE 插件最大的不同：

• 它真正在做“理解项目 → 制定方案 → 执行 → 验证”的闭环，而不是一次性补全。
• 你从“码农”切换成了“技术负责人”的角色：你负责描述目标、审查方案、做决策，AI 负责落地。
• 你开始理解上下文管理的重要性：如果第一步没有明确任务边界，Claude Code 可能会跑去扫 node_modules，浪费大量时间。

六、新手最容易犯的 5 个错误，以及怎么建立防御机制

我在自己用 Claude Code 的头两周里，把这 5 个错误犯了个遍。每一个都让我付出了额外的时间或者 API 费用，所以直接列出来，希望你能绕开。

错误 1：忘了指定工作目录，导致 AI 满天飞

Claude Code 默认的上下文是整个项目目录，但它不会自动忽略 node_modules、.git、dist 等文件夹。如果你上来就说“帮我重构所有文件”，它会真的去扫 node_modules 里的几十万个文件。结局就是超时、爆 Token、或者改了一些不该改的东西。

防御做法： 每一次任务都明确指定路径范围。比如“在 src/modules/order 下”或“仅处理 .ts 文件”。另外可以在项目根目录放一个 .claudeignore 文件（用法类似 .gitignore），在里面列出 node_modules、dist、coverage 等目录，Claude Code 会自动跳过它们。

错误 2：一次性下达太复杂的任务

我刚用的时候，觉得 AI 这么强，干脆把“重构订单模块 + 补充单元测试 + 更新文档 + 优化数据库查询”四个任务一起下达。结果 Claude Code 开始并行处理，出现了修改之间的冲突，有些文件被改了两遍，逻辑对不上，我还得多花时间修复。

防御做法： 一个会话一个主题，一个任务一个确认。 如果你想做 A、B、C 三件事，可以分成三次对话，每次完成并验证后再开始下一个。这样既能保证质量，也方便回溯哪个改动引入了问题。

错误 3：.claude.md 写成“情怀文学”而不是“指令手册”

这个前面提过，但值得单独作为一个错误点列出来。如果你的 .claude.md 里写着“本项目承载了团队三年来的技术追求”，Claude Code 只会浪费 Token 读一段毫无约束力的描述。而它真正需要的是“所有服务层函数必须返回 Promise<T>，不得使用 callback”这种硬规定。

防御做法： 请一个同事帮你读一遍 .claude.md，问他：“如果你是一个新入职的开发者，看完这份文档，你知道哪些事绝对不能做吗？” 如果他说不上来，请重写。

错误 4：忽略了 git 的保护

Claude Code 可以执行命令、修改文件，原则上它能做 git push –force。虽然概率极低，但把 AI 的可怕执行力和你的仓库权限结合到一起，本身就是一件需要敬畏的事。

防御做法：

• 始终在非主分支上使用 Claude Code 做实验性修改
• 重要修改前手动 git stash 或打 tag
• 不要让 Claude Code 直接操作远程仓库（除非你完全清楚后果）
• .gitignore 里必须加上 .claude 目录（里面有本地会话历史）

错误 5：在对话中途关闭终端了事

Claude Code 的会话是绑定在终端进程里的。如果你直接关掉终端窗口，会话不会自动保存，再次打开需要重新建立上下文，而且前一次没跑完的文件操作可能残留中间状态。

防御做法： 明确结束对话用 /exit，或者显式告诉它“这次任务结束，请保存所有更改并退出”。如果你想暂停而不是结束，可以按 Ctrl+C 优雅退出。

七、如果你想更进一步：Skills 与 MCP 的初级理解

当一个开发者熟练掌握了 .claude.md 和基础的任务协作方式之后，自然会碰到两个更高阶的概念：Skills（技能系统）和 MCP（模型上下文协议）。很多文章只提了一嘴名字，但我不希望你因为不知道它们是什么而限制了使用想象力。

1. Skills：让 Claude Code 拥有可复用的“专业能力包”

你可以把 Skills 理解为 Claude Code 的“预制能力模块”。比如你装一个 PDF Skill，Claude Code 就获得了读取和解析 PDF 文件的能力；装一个 SQL Skill，它就能连接数据库并执行受控查询。这些技能不是写死在模型里的，而是通过定义工具调用（tool_use）的方式扩展出来的。

这有什么用？举个例子：我们团队给 Claude Code 写了一个内部 Skill，用来读取公司自研的配置中心接口。这样当我们说“帮我从配置中心拉取 order-service 的所有生产配置并检查是否有过期项”时，它就不再需要我们去手动复制配置文件，而是自己通过 Skill 完成接口调用。

Skills 的配置需要写代码级定义，已经超出了入门范围，但你需要知道：Claude Code 的能力天花板，很大程度上是由 Skills 决定的。如果你发现自己经常让它做某一类特定操作，就可以考虑把这类操作封装成一个 Skill，提高后续效率。

2. MCP：AI 世界的“USB 协议”

MCP 的全称是 Model Context Protocol，它是 Anthropic 提出的一种开放标准，用来让 AI 模型和外部数据源、工具之间实现标准化通信。你可以把它想象成“AI 的 USB 接口”，只要你的数据库、文件系统、API 服务遵循 MCP 协议，Claude Code 就能即插即用地与它们交互，而不需要每次都重新写连接代码。

在实操层面，这意味着将来你可以在 Claude Code 里直接连接公司的 Confluence、Jira、GitHub Issues、数据库，只需在 settings.json 里配置相应的 MCP Server 地址即可。目前这个生态还在早期，但方向已经非常明确：它要把 Claude Code 从“终端里的编程助手”升级成“整个研发工作流的 AI 中枢”。

对于入门者，我的建议是：先不要碰 Skills 和 MCP，但要记住它们的存在。 等你能用 .claude.md 把日常工作跑顺了，再去研究它们，会事半功倍。

八、总结和你的下一步行动

写到这里，我想把整篇文章的核心逻辑收拢成一个可以被记住的判断：Claude Code 不是“写代码更快”的工具，而是“换一种方式组织和执行开发任务”的工具。 它把一部分架构决策和审查责任交还给了你这个人，同时把枯燥的执行工作外包给了 AI。

基于这个判断，我给你的行动建议也分成两条路径：

如果你只是想试试水：

• 花一个下午，按照本文第三部分到第五部分，在自己的 side project 上跑通一次重构任务
• 感受一下指令式编程和传统补全式编程的区别
• 然后用一周的时间，每天固定一个场景（比如修改注释、批量重命名、生成测试用例），观察效率变化

如果你想在生产项目中真正用起来：

• 第一件事不是装软件，而是召集团队成员一起讨论并编写第一版 .claude.md
• 制定团队使用规范：哪些操作必须人工确认、哪些可以自动执行、git 分支策略如何配合
• 从无风险的低敏感任务开始（如代码格式统一、文档生成），逐渐扩展到重构和自动化脚本

最后说一句我的私人感受：我用过几乎所有主流的 AI 编程工具，Claude Code 是第一个让我觉得“它不是在帮我打辅助，而是在代表一种新的工作模式”。这种模式对开发者的要求不是变低了，而是变高了，你不再需要用快捷键的速度来证明效率，而是需要用清晰的思维和判断力来驾驭一个比你快 100 倍的执行体。这才是 2025 年一个成熟工程师真正应该拥有的能力。