1. 为什么值得花一个下午把 Claude Code 跑通我第一次接触 Claude Code 的时候心态其实挺随意的——命令行里敲个claude问两句改个 bug能有多难结果真上手才发现从安装、认证、项目初始化到第一次让它动我的代码中间踩的坑比我想象的多得多。尤其是让它改代码这一步很多人卡在权限确认、Git 状态、CLAUDE.md 配置这几个环节上最后误以为这工具不好用其实是流程没走对。这篇东西就是把我自己从零到跑通第一次代码修改的完整路径写下来。核心关键词就几个Claude Code、安装、代码修改、Git、CLAUDE.md。它解决的核心问题是——让一个命令行里的 AI 助手安全、可控地读你的项目、改你的文件、跑你的命令而你全程知道它在干什么。适合谁看适合已经会基本命令行操作、装过 Node.js、用过 Git但还没把 Claude Code 真正用起来的开发者。如果你连 Git 都没装过别急我在第 2 节会把前置环境一起带上。我先把结论摆前面Claude Code 的本质是一个跑在终端里的 agent它不是一个聊天窗口而是一个能读文件、写文件、执行 shell 命令的操作员。理解这一点你后面所有的配置思路都会顺——你要做的不是教它写代码而是给它划好边界让它在边界内自己干活。这个认知差是新手和老手最大的分水岭。2. 装之前先把地基打好环境与依赖清单2.1 Node.js 与 npm 的版本要求Claude Code 是通过 npm 分发的所以 Node.js 是硬依赖。我实测下来Node 18 是底线Node 20 LTS 最稳。Node 16 及以下会直接报错别浪费时间试。装 Node 的方式我推荐两种官网下载 LTS 安装包一路下一步最省心用 nvmmacOS/Linux或 nvm-windows 管理多版本方便以后切版本。装完验证一下node -v npm -v两条命令都能输出版本号说明环境通了。这里有个小坑Windows 上如果之前装过旧版 NodePATH 里可能残留旧路径导致node -v显示的版本和你以为的不一样。遇到这种情况去环境变量里把旧路径删掉重开终端。2.2 Git 不是可选项是必选项很多人以为 Git 只是用来提交代码的跟 Claude Code 没关系。错。Claude Code 大量依赖 Git 来做变更追踪和安全回滚——它改了什么文件、改了哪几行靠的就是 Git 的 diff。如果你在一个没有 Git 初始化的目录里让它改代码它会一直提醒你当前不是 Git 仓库而且你也没法一键撤销它的改动。Git 安装Windows# 官网下载 Git for Windows安装时保持默认即可 # 安装完成后验证 git --versionmacOS 一般自带或者brew install git。Linux 用包管理器装就行。装完必须配置身份否则第一次提交会报错git config --global user.name 你的名字 git config --global user.email 你的邮箱注意这里的邮箱建议和你代码托管平台用的一致不然提交记录会显示成未知作者后面排查问题很麻烦。2.3 一个干净的测试项目我强烈建议不要一上来就在你正在维护的生产项目里试 Claude Code。新建一个空目录git init随便放几个文件用它来练手。等你能熟练控制它的行为了再放到真实项目里。这个习惯能帮你省下至少一次它把我文件改乱了的惊吓。mkdir claude-demo cd claude-demo git init echo # demo README.md git add . git commit -m init到这里地基就打好了。Node、Git、一个干净的 Git 仓库三样齐活。3. 安装 Claude Code三种方式与各自的坑3.1 全局 npm 安装最主流这是官方推荐、也是我用得最多的方式npm install -g anthropic-ai/claude-code装完输入claude看能不能起来。如果提示command not found八成是 npm 全局 bin 目录没进 PATH。查一下npm config get prefix把这个路径下的binWindows 是根目录加到系统 PATH 里重开终端即可。这个坑在 Windows 上尤其常见因为 npm 全局目录默认不在 PATH 里。3.2 项目内本地安装如果你不想污染全局环境可以在项目里装npm install anthropic-ai/claude-code --save-dev npx claude好处是版本跟着项目走团队协作时大家用的版本一致。坏处是每个项目都要装一遍占空间。我个人在正式项目里更倾向这种方式因为版本可控这件事在团队里太重要了。3.3 版本升级与降级Claude Code 迭代很快有时候新版反而有 bug。升级npm update -g anthropic-ai/claude-code想锁死某个版本npm install -g anthropic-ai/claude-code1.x.x实操心得升级前先记下当前版本号claude --version万一新版出问题能立刻回退。我吃过一次亏新版改了权限确认的交互逻辑我一时没适应差点误操作。3.4 首次启动与认证第一次运行claude它会引导你完成认证。整个过程是交互式的跟着提示走就行。认证信息会存在本地配置目录里之后不用重复登录。如果中途认证失败最常见的原因是网络环境不稳定或者浏览器回调没成功重试一次通常就好。认证成功后你会看到一个交互式界面可以直接输入自然语言指令。到这一步安装就算完成了。4. 第一次对话先让它读别急着让它写4.1 用只读任务建立信任新手最容易犯的错就是一上来就说帮我把这个功能实现了。正确做法是先让它做只读任务观察它的理解能力。比如帮我梳理一下这个项目的目录结构说明每个主要文件的作用它会去读文件、给你一份总结。这个过程你能看出两件事一是它读文件的范围对不对二是它的理解准不准。如果连目录都读错说明你的项目结构或者配置有问题先解决这个。4.2 理解它的工作循环Claude Code 的工作方式是一个循环理解任务 → 读取相关文件 → 提出方案 → 请求执行权限 → 执行 → 反馈结果。关键在请求执行权限这一步。它每次要改文件或跑命令都会先问你。你可以选择允许一次、允许这个会话、或者拒绝。这个设计是它的安全底线。我见过有人嫌麻烦把所有权限都设成自动允许结果它跑了一条rm命令把临时文件删了——虽然没造成大损失但吓出一身汗。权限确认不要关这是保命的。4.3 第一次代码修改的完整流程假设我们有个简单的 Python 文件calc.pydef add(a, b): return a b def divide(a, b): return a / b我们让它加一个除法除零保护。指令可以这样写calc.py 里的 divide 函数没有处理除数为 0 的情况帮我加上保护除数为 0 时返回 None并补一个简单的测试接下来会发生什么它读取calc.py确认当前实现它提出修改方案展示 diff它请求你确认是否写入你确认后它修改文件它可能还会问要不要跑测试。整个过程你能看到每一处改动。这就是可控的含义——你不是把代码交给它而是和它一起改代码。改完后用 Git 看一眼git diff确认改动符合预期再决定提交还是回滚。这一步千万别省。5. CLAUDE.md让 AI 记住你的项目规矩5.1 CLAUDE.md 到底是什么CLAUDE.md是 Claude Code 的项目级配置文件放在项目根目录。它会在每次会话开始时被自动读取相当于给 AI 的一份项目说明书。你可以在这里写项目用什么技术栈、代码风格要求、目录约定、常用命令、禁止事项等等。为什么它重要因为没有它你每次都要重复解释一遍项目背景有了它AI 一进来就知道规矩省下大量沟通成本。5.2 一份实用的 CLAUDE.md 模板# 项目说明 ## 技术栈 - Python 3.11 - 依赖管理用 pip requirements.txt - 测试框架 pytest ## 代码规范 - 遵循 PEP 8 - 函数必须有 docstring - 禁止使用 print 调试用 logging ## 常用命令 - 跑测试pytest - 格式化black . ## 禁止事项 - 不要修改 migrations 目录下的文件 - 不要直接改 requirements.txt先问我这份文件不用写得多漂亮关键是把你踩过的坑写进去。比如你被某个目录的自动生成文件坑过就明确写不要动这个目录。5.3 分层配置全局与项目级Claude Code 支持多层配置用户级全局和项目级。全局的放你个人的通用偏好项目级的放这个项目特有的规矩。项目级优先级更高。我一般全局只放回答用中文改动前先展示 diff这类通用要求项目相关的全部放项目里的 CLAUDE.md。注意CLAUDE.md 会被提交到 Git 仓库团队共享。所以别在里面写敏感信息比如密钥、内部地址。这个坑我见过有人踩把测试环境的账号密码写进去了提交后才发现。6. 权限、安全与 Git 的配合使用6.1 权限模式的选择Claude Code 有几种权限模式从严格到宽松。我的建议是默认用最严格的只在明确知道自己在干什么时才放宽。严格模式下每次写文件、跑命令都要确认虽然点得多但安全。宽松模式适合你已经完全信任当前任务、且项目有 Git 兜底的情况。6.2 用 Git 做安全网这是我最想强调的一点在让 Claude Code 改代码之前确保工作区是干净的。git status如果显示有未提交的改动先提交或者 stash。这样万一 AI 改乱了一条命令就能回滚git checkout -- .或者更精细地回滚单个文件git checkout -- calc.py我自己的习惯是每让 AI 完成一个独立的小任务就提交一次。这样历史清晰出问题也好定位。别攒一大堆改动一起提交那样回滚粒度太粗。6.3 敏感文件与目录的排除有些文件你绝对不想让 AI 碰比如.env、密钥文件、生产配置。可以在项目里配置忽略规则或者在 CLAUDE.md 里明确写禁止读取和修改 .env。双保险更稳妥。7. 常见问题与排查速查表7.1 安装与启动类问题现象可能原因解决办法claude: command not foundnpm 全局 bin 不在 PATH把npm config get prefix的路径加进 PATH启动报 Node 版本错误Node 版本过低升级到 Node 18推荐 20 LTS认证一直失败网络或回调问题重试检查浏览器是否拦截了回调安装卡住不动npm 源慢换国内镜像源后重装7.2 使用过程中的典型问题问题一它读不到我的文件。通常是工作目录不对。Claude Code 是以你启动它的目录为根的如果你在父目录启动它看不到子目录里的细节。解决方法是cd到项目根目录再启动。问题二它改完代码后测试跑不过。先别急着怪它用git diff看改动很多时候是它改对了但你的测试本身有问题或者它漏改了关联文件。把报错信息贴给它让它继续修通常两三轮就能收敛。问题三它反复问同样的问题。说明 CLAUDE.md 没写好或者你的指令太模糊。把项目约定补进 CLAUDE.md指令尽量具体到文件和函数。问题四改动范围超出预期。这是权限没控好。检查是不是开了自动允许或者指令里说了顺便优化一下这种模糊要求。指令越具体它越不会乱来。7.3 我的独家避坑清单永远在 Git 干净的状态下开始任务一次只让它做一件事别把五个需求塞进一条指令改动后必看 diff别闭眼确认CLAUDE.md 里写清楚禁止事项比写要做什么更重要遇到它理解偏差别骂它把上下文补全它就能纠正。8. 从能用到好用的几个进阶习惯跑通第一次修改只是起点。真正让 Claude Code 发挥价值的是把它嵌进你的日常工作流。我自己的做法是把重复性任务比如写测试、补类型注解、重构小函数交给它把需要判断力的任务架构设计、复杂业务逻辑留给自己。它是个执行力很强的助手但不是决策者。另外善用它的解释能力。遇到不熟悉的代码直接让它讲一遍比你自己啃快得多。我经常用它来快速理解接手的老项目效果很好。最后说个细节Claude Code 的会话是有上下文的长会话会消耗更多资源也容易让它记混。所以一个任务做完开新会话保持上下文干净。这个习惯能让它的表现稳定很多。我在实际使用中最大的体会是把它当成一个需要明确指令、需要边界约束、但执行力极强的初级工程师。你给它的信息越清晰、约束越明确它的产出就越靠谱。反过来模糊的指令加宽松的权限就是灾难的开始。这个平衡点得你自己在实操里慢慢找。