1. 为什么我最终把 Claude Code 装进了日常工作流第一次听说 Claude Code 的时候我其实没太当回事。命令行里跑一个 AI 助手听起来像是极客的玩具跟提升开发效率这种正经事沾不上边。直到有一次我需要在一个十几万行的老项目里批量替换某个 API 的调用方式手动改了两百多个文件之后手指发酸我才认真去研究了一下这个工具。结果一用就回不去了——它不只是帮你写代码而是能直接读你的项目、改你的文件、跑你的命令像一个坐在你旁边的结对伙伴。这篇内容就是把我从零开始装 Claude Code、配置环境、到真正完成第一次代码修改的完整过程梳理出来。Claude Code 是 Anthropic 推出的命令行 AI 编程助手它跟你在网页上聊天的那种 AI 最大的区别在于它能直接访问你本地的文件系统能执行终端命令能理解整个项目的上下文。适合谁看如果你是会写一点代码但没接触过 AI 编程工具的开发者或者你已经用过网页版 AI 但觉得复制粘贴太麻烦那这篇就是为你准备的。如果你是完全零基础的小白也能看懂因为我会把 Git、Node.js 这些前置依赖的安装也一并讲清楚。我踩过的坑不少Node.js 版本不对导致安装失败、Git 没配好导致 Claude Code 读不到项目、CLAUDE.md 文件不知道写什么内容……这些在官方文档里往往一笔带过但对新手来说每一个都能卡你半小时。所以下面我会按环境准备 → 安装 → 配置 → 第一次改代码的顺序把每一步的意图和坑点都讲透。2. 装 Claude Code 之前先把这三个地基打牢很多人一上来就搜claude code 安装然后照着命令敲结果报一堆错。问题不在 Claude Code 本身而在于它的运行依赖没准备好。Claude Code 本质是一个跑在 Node.js 环境里的命令行工具同时它需要 Git 来做版本控制这样它改错了你还能回滚还需要一个能用的终端。这三样东西缺一不可。2.1 Node.js版本选错后面全是坑Claude Code 对 Node.js 的版本有要求官方建议Node.js 18 或更高版本。我一开始用的是系统自带的 Node.js 16安装的时候直接报错说引擎不兼容。所以第一步是确认你的 Node.js 版本。打开终端Windows 用 PowerShell 或 CMDmacOS 和 Linux 用系统终端输入node -v如果显示的是 v18.x.x 以上恭喜你可以跳过安装。如果低于 18 或者提示command not found那就需要装一个。安装 Node.js 我推荐两种方式。第一种是去 Node.js 官网下载 LTS长期支持版本的安装包Windows 下就是一个 .msi 文件双击一路下一步就行安装程序会自动把 node 和 npm 加到系统 PATH 里。第二种是用版本管理工具比如 macOS/Linux 下的 nvmWindows 下的 nvm-windows。用 nvm 的好处是你可以随时切换 Node.js 版本不会因为某个项目需要旧版本而抓狂。注意Windows 用户如果之前用安装包装过 Node.js再装 nvm-windows 可能会冲突。建议先卸载旧的 Node.js再装 nvm。装完之后验证一下node -v npm -v两个命令都能输出版本号说明 Node.js 环境就绪了。npm 是 Node.js 自带的包管理器Claude Code 就是通过 npm 安装的。2.2 Git不只是版本控制更是 Claude Code 的安全网Git 这个东西很多人觉得我一个人写代码用不上。但用 Claude Code 的时候Git 的作用被放大了——因为 AI 会直接修改你的文件万一改错了没有 Git 你就只能手动撤销。有了 Git一条git checkout .就能全部还原。Git 的安装同样简单。Windows 用户去 Git 官网下载安装包安装过程中有一个选项叫Adjusting your PATH environment建议选Git from the command line and also from 3rd-party software这样 Git 命令在任意终端都能用。macOS 用户如果装了 Homebrew直接brew install git没装 Homebrew 的话安装 Xcode Command Line Tools 也会自带 Git。Linux 用户用包管理器比如 Ubuntu 下sudo apt install git。装完之后必须配置用户名和邮箱否则 Git 不让你提交git config --global user.name 你的名字 git config --global user.email 你的邮箱这两条命令是全局配置写一次就行。验证配置git config --global --list能看到 user.name 和 user.email 就对了。我见过有人跳过这一步结果 Claude Code 帮他改完代码想提交的时候报错排查半天才发现是 Git 没配。2.3 终端选择Windows 用户别用老 CMDClaude Code 是一个交互式的命令行工具它对终端的要求比普通命令高一些。Windows 下我强烈建议用Windows Terminal或者PowerShell 7不要用老旧的 CMD。老 CMD 对 ANSI 转义字符支持不好Claude Code 的界面会显示成一堆乱码。macOS 和 Linux 用户用系统自带的终端就够如果你追求更好的体验可以装 iTerm2macOS或者 Windows TerminalWindows。这些终端支持分屏、搜索、自定义配色用起来舒服很多。3. 安装 Claude Code 的两种路径与账号准备环境准备好之后安装 Claude Code 本身其实只有一条命令的事。但这里有个分岔路你是用官方账号登录还是用 API Key两种方式各有适用场景我分别说一下。3.1 npm 全局安装一条命令搞定不管你用哪种登录方式安装命令都是一样的npm install -g anthropic-ai/claude-code-g表示全局安装这样你在任何目录下都能直接敲claude命令。安装过程会从 npm 仓库下载包速度取决于你的网络。如果卡住不动可以换一个 npm 镜像源npm config set registry https://registry.npmmirror.com装完之后验证claude --version能输出版本号就说明安装成功了。如果提示command not found大概率是 npm 的全局 bin 目录没加到 PATH 里。可以用npm config get prefix看一下全局安装路径然后把这个路径下的 bin 目录加到系统环境变量里。注意有些公司电脑有权限限制npm 全局安装会失败。这时候可以试试用npx anthropic-ai/claude-code直接运行不需要全局安装但每次都要敲这么长一串不太方便。3.2 账号登录 vs API Key怎么选安装完之后第一次运行claude会引导你登录。这里有两种方式第一种是用 Anthropic 账号登录。运行claude之后它会打开浏览器让你登录账号并授权。这种方式适合个人用户订阅制付费用起来省心。但要注意如果你用的是公司统一管理的账号可能会遇到权限限制提示你的组织禁用了某个订阅的访问。这种情况需要找管理员开通或者改用 API Key 方式。第二种是用 API Key。你需要去 Anthropic 的控制台生成一个 API Key然后设置环境变量export ANTHROPIC_API_KEY你的keyWindows 下用setx ANTHROPIC_API_KEY 你的key这种方式适合需要精细控制用量、或者团队统一管理的场景。API Key 是按 token 计费的用多少付多少。我个人的建议是如果你只是自己用先用账号登录试试简单直接。如果遇到组织限制或者想控制成本再切到 API Key。3.3 验证安装跑一个最简单的对话登录成功之后你会进入 Claude Code 的交互界面。这时候可以随便问一句比如你好帮我看看当前目录下有哪些文件。如果它能正常回复并且列出文件说明安装和配置都成功了。如果它回复说读不到文件检查一下你是不是在一个有权限的目录下运行。Claude Code 默认只能访问你启动它的那个目录及其子目录这是出于安全考虑。4. 让 Claude Code 真正读懂你的项目CLAUDE.md 与目录约定装好之后直接让 Claude Code 改代码你会发现它有时候答非所问——因为它不知道你的项目是干什么的、用了什么技术栈、有什么编码规范。这时候就需要CLAUDE.md文件出场了。4.1 CLAUDE.md 是什么为什么它比你想的重要CLAUDE.md 是 Claude Code 的项目级配置文件放在项目根目录下。每次你在这个项目里启动 Claude Code它都会自动读取这个文件的内容作为理解项目的背景知识。你可以把它理解成给 AI 写的一份项目说明书。我一开始觉得这东西可有可无直到有一次让 Claude Code 帮我加一个接口它用了一个我们项目里早就废弃的库。后来我在 CLAUDE.md 里写清楚了技术栈和禁用项它就再也没犯过这种错。一个典型的 CLAUDE.md 长这样# 项目说明 这是一个基于 React TypeScript 的前端项目使用 Vite 构建。 # 技术栈 - 框架React 18 - 语言TypeScript 5 - 构建工具Vite - 状态管理Zustand - 样式Tailwind CSS # 编码规范 - 组件使用函数式组件 Hooks - 文件名使用 kebab-case - 禁止使用 any 类型 - 所有 API 请求统一走 src/api 目录下的封装 # 常用命令 - 开发npm run dev - 构建npm run build - 测试npm run test这个文件不需要写得多复杂关键是把你项目里新人来了必须知道的信息写进去。Claude Code 每次启动都会读它相当于每次对话都带着这份背景。4.2 目录结构怎么组织Claude Code 才不迷路Claude Code 读取文件是按需的它不会一上来就把你整个项目读完。但如果你目录结构混乱它找文件就会很费劲。我建议遵循几个原则第一源码和产物分开。src 放源码dist 放构建产物node_modules 放依赖。Claude Code 默认会忽略 node_modules 和 .git 目录但如果你把源码和产物混在一起它可能会去读一些不该读的文件。第二配置文件放根目录。package.json、tsconfig.json、vite.config.ts 这些放在根目录Claude Code 一眼就能看到项目的整体配置。第三用 .gitignore 排除敏感文件。Claude Code 会尊重 .gitignore 的规则所以你的 .env 文件、密钥文件只要写进 .gitignore它就不会去读。提示如果你想让 Claude Code 忽略某些文件但不想写进 .gitignore可以在项目根目录建一个 .claudeignore 文件语法和 .gitignore 一样。4.3 第一次对话怎么问才能得到靠谱的答案跟 Claude Code 对话是有技巧的。新手最容易犯的错是问得太笼统比如帮我优化一下代码它根本不知道你要优化哪个文件、优化什么方面。好的提问应该包含三个要素位置、目标、约束。举个例子差的提问帮我改一下登录功能好的提问src/pages/Login.tsx 里的登录表单提交后没有 loading 状态用户点击后不知道有没有在请求。帮我加一个 loading 状态用现有的 Button 组件的 loading 属性。再比如你想让它理解项目读一下 src/api 目录下的文件告诉我这个项目的 API 请求是怎么封装的看一下 package.json告诉我这个项目用了哪些主要依赖Claude Code 支持多轮对话你可以先让它读文件再基于它的理解提需求。这种先对齐再动手的方式比一上来就让它改代码靠谱得多。5. 从零完成第一次代码修改一个真实的小需求前面都是准备工作现在进入正题让 Claude Code 真正帮你改一次代码。我选一个特别简单的需求保证你能跟着复现给一个函数加上参数校验和错误处理。5.1 先让 Claude Code 读代码别急着让它改假设你有一个文件utils/divide.js内容是这样的function divide(a, b) { return a / b; } module.exports divide;这个函数有个明显的问题如果 b 是 0会返回 Infinity如果传的不是数字会返回 NaN。我们要加校验。第一步启动 Claude Codecd 你的项目目录 claude然后输入读一下 utils/divide.js告诉我这个函数有什么潜在问题Claude Code 会读取文件并分析通常会指出除零、类型不匹配等问题。这一步的目的是确认它真的读到了正确的文件同时也让你自己心里有数。5.2 描述需求时把验收标准说清楚确认它读对了文件之后再提修改需求帮我修改 utils/divide.js要求 1. 如果 a 或 b 不是数字抛出 TypeError错误信息为 参数必须是数字 2. 如果 b 为 0抛出 Error错误信息为 除数不能为 0 3. 保持原有的 module.exports 导出方式 4. 不要引入任何外部依赖注意我这里把要求列成了编号列表每一条都是可验证的。Claude Code 会按照这些要求去改改完之后你可以逐条检查。它改完之后的代码大概是这样function divide(a, b) { if (typeof a ! number || typeof b ! number) { throw new TypeError(参数必须是数字); } if (b 0) { throw new Error(除数不能为 0); } return a / b; } module.exports divide;5.3 改完之后一定要做的三件事Claude Code 改完代码很多人就直接用了。我建议至少做这三件事第一让它解释改动。输入解释一下你刚才的改动它会逐条说明改了什么、为什么这么改。这既是复核也是学习。第二跑测试。如果项目有测试让它跑一下运行一下和 divide 相关的测试它会执行npm test或者你项目里配置的测试命令。如果没有测试至少手动验证一下node -e const d require(./utils/divide); console.log(d(10, 2));第三用 Git 看 diff。这是最关键的一步git diff utils/divide.jsGit 会高亮显示所有改动。你逐行看一遍确认没有多余的修改。Claude Code 有时候会顺手改一些你没让它改的地方比如调整缩进、重命名变量。这些改动不一定错但你需要知道。注意如果 Claude Code 改错了直接git checkout utils/divide.js就能还原到修改前的状态。这就是为什么我反复强调要先装 Git、先初始化仓库。5.4 提交这次修改让 Git 记录下 AI 的贡献确认改动没问题之后就可以提交了。你可以让 Claude Code 帮你生成提交信息帮我把这次修改提交写一个合适的 commit message它会执行git add和git commit提交信息大概是为 divide 函数添加参数校验和除零检查。你也可以自己写但让 AI 写的好处是它会遵循 Conventional Commits 规范如果你在 CLAUDE.md 里写了的话。提交完之后git log看一眼确认提交成功。到这里你的第一次 Claude Code 代码修改就完整走完了。6. 那些官方文档不会告诉你的坑用了一段时间之后我积累了一些官方文档里找不到的经验。这些坑不一定每个人都会遇到但遇到了真的很浪费时间。6.1 权限问题为什么它有时候读不到文件Claude Code 默认只能访问你启动它的目录。如果你在~/projects下启动它就读不到~/documents里的文件。这是安全设计不是 bug。但有时候你确实需要它访问多个目录。这时候可以在启动时指定claude --add-dir /path/to/another/dir或者在对话里明确告诉它文件的绝对路径。不过我不建议随便扩大它的访问范围尤其是包含敏感信息的目录。另一个常见的权限问题是文件系统权限。如果你在 Linux 或 macOS 下某些文件属于 root 用户Claude Code 以普通用户身份运行时就改不了。这时候要么改文件权限要么用 sudo 启动不推荐。6.2 上下文窗口项目大了怎么办Claude Code 的上下文窗口是有限的。如果你的项目特别大它不可能一次性读完所有文件。它的策略是按需读取——你提到哪个文件它读哪个。但这也意味着如果你问的问题需要跨很多文件才能回答它可能会漏掉一些。我的做法是先让它读关键文件把信息喂给它再提问。比如先读 src/api/index.ts 和 src/api/user.ts然后告诉我用户登录的请求是怎么发的这样它就会先读这两个文件再基于读到的内容回答比直接问登录请求怎么发的准确得多。6.3 它改代码的风格跟你不一样怎么办Claude Code 有它自己的代码风格偏好比如它喜欢用箭头函数、喜欢提前 return、喜欢给每个函数加 JSDoc 注释。如果你的项目风格跟它不一致改出来的代码会很突兀。解决办法就是在 CLAUDE.md 里写清楚你的风格要求。比如# 代码风格 - 使用 function 声明而不是箭头函数除非是回调 - 不要自动添加 JSDoc 注释 - 缩进用 2 个空格 - 字符串用单引号写得越具体它改出来的代码越贴合你的项目。我甚至见过有人在 CLAUDE.md 里贴了一段示例代码说就按这个风格来效果也很好。6.4 网络不稳定时的应对Claude Code 需要联网才能工作因为它要调用远端的模型。如果你的网络不稳定可能会遇到响应超时、连接中断的问题。我的经验是把大任务拆成小任务。不要一次性让它改十个文件而是一个文件一个文件地改。这样即使中途断了也不会丢失太多进度。另外重要的修改前先 commit 一次这样断了也能回到干净状态。7. 把 Claude Code 用顺手的几个进阶习惯走完第一次修改之后你算是入门了。但要用得顺手还需要养成几个习惯。这些习惯是我用了几个月之后慢慢总结出来的能显著提升效率。7.1 用 Git 分支隔离 AI 的改动我现在的习惯是每次让 Claude Code 做比较大的改动之前先开一个新分支。git checkout -b ai/refactor-divide这样 AI 的所有改动都在这个分支上不影响主分支。改完之后你可以慢慢 review满意了再合并不满意直接删分支。这比在主分支上改、改坏了再回滚要清爽得多。分支命名我习惯用ai/前缀一眼就能看出这是 AI 参与的改动。团队协作的时候这个习惯尤其重要因为别人 review 的时候会知道这是 AI 改的review 的侧重点会不一样。7.2 让 Claude Code 帮你写测试Claude Code 写测试的能力其实比写业务代码更强因为测试的逻辑相对独立不依赖太多项目上下文。我经常让它做的一件事是读一下 utils/divide.js为它写一套单元测试覆盖正常情况和所有异常情况它会生成一个测试文件通常是 Jest 或 Vitest 的格式。你检查一下测试用例是否合理然后跑一遍。如果测试通过说明你的代码逻辑没问题如果测试失败说明要么代码有 bug要么测试写得不对两种情况都值得深究。7.3 用 Claude Code 做代码审查除了写代码Claude Code 还能当代码审查员用。你可以把一段代码贴给它或者让它读某个文件然后问审查一下这个文件指出潜在的问题性能、安全、可读性、边界情况它会列出一堆问题有些是你没想到的。我经常用它来审查自己写的代码尤其是那些感觉没问题但总觉得哪里不对的地方。它指出的问题不一定都对但至少能给你一个新的视角。7.4 定期更新 Claude CodeClaude Code 更新很频繁新版本会修复 bug、增加功能、优化模型调用。我建议每隔一两周更新一次npm update -g anthropic-ai/claude-code更新之前看一眼更新日志了解有什么变化。有时候新版本会改变一些行为比如默认的模型、默认的权限策略提前知道能避免踩坑。8. 关于 Claude Code 的几个常见误解最后我想澄清几个我经常听到的误解这些误解往往来自没用过或者只用过一两次的人。误解一Claude Code 会自己乱改代码。实际上Claude Code 每次修改文件之前都会征求你的同意除非你开启了自动批准模式。它会显示要改哪个文件、改什么内容你确认了它才动手。所以控制权始终在你手里。误解二用了 Claude Code 就不需要懂代码了。恰恰相反你越懂代码越能判断它改得对不对、越能写出好的提示词、越能发现它的问题。Claude Code 是放大器不是替代品。它能让你从重复劳动中解放出来但核心的判断和决策还是得你自己做。误解三Claude Code 只能改小项目。大项目反而更能体现它的价值因为它能帮你快速理解陌生的代码、批量修改重复的模式、生成大量的样板代码。当然大项目里用它要更谨慎改动前一定要开分支、一定要 review。误解四它跟网页版 AI 差不多。差别很大。网页版你需要手动复制粘贴代码它不知道你的项目结构改完还得自己贴回去。Claude Code 直接操作文件系统能读能写能跑命令这是一个数量级的效率差异。9. 我个人的使用节奏与建议用 Claude Code 这几个月我慢慢形成了一套自己的使用节奏。分享出来供你参考但不必照搬找到适合自己的方式最重要。日常开发中我大概有 30% 的代码是 Claude Code 帮我写的主要是样板代码、测试、文档注释这些。核心的业务逻辑我还是自己写因为那需要理解业务背景和权衡取舍AI 暂时还替代不了。但即使是自己写的代码我也会让 Claude Code 审查一遍经常能发现一些低级错误。遇到陌生项目的时候Claude Code 是我的第一站。我会让它读 README、读 package.json、读主要入口文件然后给我讲一遍项目结构。这比我自己一个个文件翻要快得多。学习新技术的时候我会让 Claude Code 给我写示例代码然后逐行问它为什么这么写。这种边写边问的学习方式比看文档要直观。如果你刚开始用我的建议是从小任务开始从只读操作开始。先让它读文件、回答问题建立信任之后再让它改代码。改代码的时候从单个文件、单个函数开始不要一上来就让它重构整个模块。等你熟悉了它的行为模式再逐步扩大使用范围。还有一点很重要保持 Git 仓库干净。每次让 Claude Code 动手之前确保当前工作区没有未提交的改动。这样万一它改坏了你能干净地回滚。这个习惯能帮你避免 90% 的翻车场景。Claude Code 这个工具说到底是把你从打字这件事里解放出来让你更专注于思考。它不会让你变成更好的程序员但它能让你把时间花在更值得花的地方。至于它能帮你省多少时间取决于你怎么用它。