1. 为什么值得花时间把 Claude Code 跑起来第一次听说 Claude Code 的时候我其实没太当回事。命令行里跟 AI 聊代码我 VSCode 里插件一大堆Copilot 补全也挺顺手何必再折腾一个终端工具。直到有次接手一个祖传 Python 项目三千多行单文件函数之间靠全局变量互相勾连改一个地方崩三个地方。那天下午我抱着试试看的心态把 Claude Code 装上让它先读了一遍整个仓库然后问它“这个process_data函数被哪些地方调用了改动它会影响什么”。它没有直接甩给我一段代码而是把调用链、副作用、隐藏的全局状态依赖一条条列了出来还顺手标出了两个我根本没注意到的循环引用。那一刻我才意识到这东西跟“代码补全”完全不是一个物种。Claude Code 是 Anthropic 推出的终端级编程助手它跟普通 IDE 插件的本质区别在于它运行在你的终端里能直接读写文件、执行命令、跑测试、看 Git 状态是一个真正能“动手”的 Agent而不是只会在编辑器里给你提示的补全工具。你可以把它理解成一个坐在你旁边、手速极快、记性极好、而且从不嫌你代码烂的结对程序员。它能做的事包括但不限于读懂整个项目结构、按你的自然语言描述修改代码、自动跑测试验证改动、帮你梳理 Git 提交、生成项目文档。适合谁适合所有需要在真实项目里改代码的人——不管你是刚学 Python 的新手还是维护着几十万行遗留系统的老手只要你的工作流里有“读代码、改代码、验证代码”这三件事它就能帮上忙。这篇内容我会从零开始把安装、配置、第一次代码修改的完整链路走一遍。中间会穿插我自己踩过的坑、参数选择的理由、以及那些官方文档里不会写但实际用起来很关键的经验。目标很简单你看完之后能在一个干净的环境里把 Claude Code 跑起来并且完成一次真实的代码修改。2. 安装前的环境准备与方案选型2.1 运行环境的基本要求Claude Code 本质上是一个 Node.js 命令行工具所以第一件事是确认你的机器上有 Node.js。官方要求 Node 18 以上我实测下来 Node 20 LTS 最稳Node 22 也没问题但如果你还在用 Node 16趁早升级不然后面各种奇怪的报错会让你怀疑人生。检查 Node 版本很简单打开终端敲node -v npm -v如果显示v18.x.x以上就 OK。没有的话去 Node.js 官网下载 LTS 版本安装包Windows 用户下载.msi文件双击安装macOS 用户可以用 Homebrewbrew install node20Ubuntu 用户建议用 NodeSource 的源比系统自带的 apt 版本新很多curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs提示Windows 用户如果之前装过旧版 Node建议先卸载干净再装新版否则可能出现 npm 全局路径混乱的问题。卸载后手动删掉C:\Users\你的用户名\AppData\Roaming\npm和npm-cache两个目录。2.2 Git 不是可选项是必选项很多人会问我就改改代码不提交能不能不装 Git答案是最好装上。Claude Code 的很多核心能力依赖 Git——它需要知道哪些文件被修改过、当前在哪个分支、有没有未提交的改动。没有 Git它就像一个蒙着眼睛改代码的人改完你都不知道动了哪些地方。Git 安装各平台都简单。Windows 去官网下载安装包一路默认下一步就行注意安装选项里把“Git Bash Here”勾上后面在 Windows 上用命令行会方便很多。macOS 通常自带 Git没有的话brew install git。Ubuntu 直接sudo apt install git。装完配置一下身份这是提交代码的前提git config --global user.name 你的名字 git config --global user.email 你的邮箱验证一下git --version git config --list注意如果你在公司内网环境Git 可能已经预装了但版本很老。Claude Code 对 Git 版本没有硬性要求但建议 2.30 以上太老的版本在处理某些分支操作时会有兼容性问题。2.3 安装 Claude Code 的两种方式官方推荐用 npm 全局安装这是最省心的方式npm install -g anthropic-ai/claude-code装完之后验证claude --version能输出版本号就说明装好了。如果提示command not found大概率是 npm 全局 bin 目录没加到 PATH 里。Windows 上检查%APPDATA%\npm是否在环境变量里macOS/Linux 检查/usr/local/bin或~/.npm-global/bin。另一种方式是用 npx 直接运行不装全局npx anthropic-ai/claude-code这种方式适合临时试用但每次启动都要下载速度慢不推荐长期使用。实操心得如果你在公司电脑上没有全局安装权限可以用npm install -g anthropic-ai/claude-code --prefix ~/.local装到用户目录然后把~/.local/bin加到 PATH。这样不需要管理员权限也能用。2.4 认证与首次启动安装完成后在终端里进入你的项目目录直接敲claude第一次启动会引导你完成认证。它会打开浏览器让你登录账号并授权授权完成后终端里会显示登录成功。整个过程跟登录网页版差不多不需要手动复制什么 token。认证信息会保存在本地配置目录里macOS/Linux 在~/.claude/Windows 在%USERPROFILE%\.claude\。如果你换了账号或者想重新认证删掉这个目录里的认证文件再启动即可。注意如果你在远程服务器或者容器里跑 Claude Code浏览器打不开可以用claude login命令它会给你一个链接你在本地浏览器打开授权后把回调地址粘贴回终端。这个流程跟很多 CLI 工具的 OAuth 登录是一样的。3. 项目初始化与 CLAUDE.md 的写法3.1 第一次进入项目该做什么装好之后别急着让它改代码。先在一个你熟悉的项目里跑一次“只读模式”让它先理解项目结构。进入项目根目录启动 Claude Code然后输入类似这样的话请先阅读这个项目的整体结构告诉我主要模块的职责划分以及入口文件在哪里。不要修改任何文件。它会自动扫描目录、读取关键文件、分析依赖关系然后给你一份项目概览。这一步的价值在于你可以借此判断它是否真的“看懂”了你的项目。如果它把测试目录当成核心代码、把配置文件当成业务逻辑说明你的项目结构可能比较混乱或者需要在 CLAUDE.md 里补充说明。3.2 CLAUDE.md 到底是什么CLAUDE.md 是 Claude Code 的项目级配置文件放在项目根目录。每次启动时它会自动读取这个文件把里面的内容作为“项目背景知识”注入到对话上下文中。你可以把它理解成给新同事写的“项目入门指南”——告诉它这个项目是干什么的、代码风格是什么、有哪些约定、哪些目录不要动。这个文件不是必须的但强烈建议写。没有它Claude Code 每次都要重新摸索你的项目有了它它一上来就知道该遵守什么规则省掉大量来回沟通。3.3 一份实用的 CLAUDE.md 模板我自己的项目里CLAUDE.md 通常包含这几块内容# 项目概述 这是一个基于 FastAPI 的后端服务提供用户管理和订单处理接口。 # 技术栈 - Python 3.11 - FastAPI SQLAlchemy - PostgreSQL - pytest 做测试 # 目录结构 - app/api/ 路由层只做参数校验和响应组装 - app/services/ 业务逻辑层核心逻辑都在这里 - app/models/ 数据库模型 - tests/ 测试文件与 app 目录结构对应 # 代码规范 - 所有函数必须有类型注解 - 业务逻辑不允许写在路由层 - 数据库操作统一走 service 层 - 提交前必须跑 pytest # 禁止事项 - 不要修改 alembic/ 下的迁移文件 - 不要动 .env 和 config/ 下的配置文件 - 不要引入新的第三方依赖除非我明确要求这份文件不需要写得多漂亮关键是信息准确、规则明确。写得越具体Claude Code 的行为就越可控。实操心得CLAUDE.md 是可以迭代的。每次你发现 Claude Code 做了你不希望它做的事就把对应的规则补进去。比如它总是喜欢用print调试你就加一条“调试信息统一用 logging 模块”。用上一两周这个文件就会变成一份非常贴合你项目习惯的规则集。3.4 全局配置与项目配置的取舍除了项目级的 CLAUDE.mdClaude Code 还支持用户级的全局配置放在~/.claude/CLAUDE.md。全局配置里的规则对所有项目生效适合放一些个人偏好比如“回答用中文”、“代码注释用英文”、“不要主动格式化代码”。我的做法是全局配置只放个人风格相关的规则项目相关的规则全部放在项目级 CLAUDE.md 里。这样换项目时不会互相干扰团队协作时项目配置也能跟着仓库走。4. 完成第一次代码修改的完整实操4.1 选一个合适的“第一次”第一次修改不要挑太复杂的任务。我的建议是找一个“明确、局部、可验证”的改动。比如给某个函数加参数校验、修复一个已知的小 bug、给一个工具函数补充类型注解。这类任务边界清晰改完对错一目了然适合用来熟悉 Claude Code 的工作方式。我自己的第一次是给一个 Flask 项目里的get_user函数加空值处理。原函数大概长这样def get_user(user_id): user db.query(User).filter(User.id user_id).first() return user.name如果user是 None这里就会崩。任务很明确加一个空值判断。4.2 用自然语言描述需求在 Claude Code 里你不需要写什么特殊语法直接用中文描述就行app/services/user_service.py 里的 get_user 函数如果查不到用户会抛 AttributeError。请加上空值处理查不到时返回 None并补充对应的类型注解。改完后跑一下相关测试。注意我这段话里包含了几个关键信息文件路径、函数名、问题描述、期望行为、验证方式。信息越完整它一次做对的概率越高。4.3 观察它的执行过程Claude Code 收到指令后不会直接甩给你一段代码。它会先读文件、理解上下文然后告诉你它打算怎么改。你会看到类似这样的输出我先读取 app/services/user_service.py 了解当前实现... 找到 get_user 函数当前实现没有空值检查... 我计划做以下修改 1. 在查询后加 if user is None 判断 2. 返回类型改为 Optional[User] 3. 补充 docstring 是否继续这时候你可以确认它的方案是否符合预期。如果它理解错了直接告诉它哪里不对它会调整。确认无误后它才会真正写入文件。这个“先说明再执行”的机制很重要它给了你一个检查点避免它自作主张改一堆你没要求的东西。4.4 验证改动结果改完之后Claude Code 会自动跑你项目里的测试如果它识别到了测试命令。你也可以手动让它跑请运行 pytest tests/test_user_service.py -v它会执行命令并把结果贴出来。如果测试通过它会告诉你改动完成如果失败它会分析失败原因并尝试修复。改完的代码大概是这样from typing import Optional def get_user(user_id: int) - Optional[User]: 根据用户 ID 查询用户不存在时返回 None。 user db.query(User).filter(User.id user_id).first() if user is None: return None return user4.5 用 Git 检查改动范围改完之后用 Git 确认一下它到底动了哪些文件git diff git status这一步非常关键。Claude Code 有时候会顺手改一些你没要求的地方比如格式化无关代码、调整 import 顺序。通过git diff你能清楚看到每一处改动确认没有意外修改后再提交。如果发现它改了不该改的地方直接git checkout -- 文件名回滚然后重新给它更明确的指令。注意养成“改完必看 diff”的习惯。这不是不信任工具而是对自己代码负责。我见过太多人让 AI 改完直接提交结果把调试代码、临时注释一起带上去了。5. 常见问题排查与避坑经验5.1 安装与认证类问题问题现象可能原因解决方法claude: command not foundnpm 全局 bin 不在 PATH把 npm 全局目录加入 PATH或重开终端启动后一直卡在认证浏览器回调失败用claude login手动完成 OAuth 流程提示组织禁用了订阅访问账号权限问题确认账号类型个人版和企业版权限不同Node 版本报错Node 低于 18升级到 Node 20 LTS认证类问题里最常见的是“浏览器打不开”或“回调地址粘贴后没反应”。如果你在远程服务器上操作本地浏览器授权后拿到的回调 URL 要完整粘贴回终端不要漏掉任何参数。如果还是不行检查一下终端是否能正常访问外网。5.2 代码修改类问题它改错了文件怎么办直接git checkout回滚然后重新下指令这次把文件路径写得更明确。比如不要说“改一下用户相关的代码”而要说“只修改 app/services/user_service.py不要动其他文件”。它总是改一半就停可能是任务描述太模糊它不确定下一步该做什么。把任务拆成更小的步骤一步一步来。比如先让它“只加空值判断不要改类型注解”完成后再让它“补充类型注解”。它引入了不存在的依赖这是常见问题。它可能会用一些你项目里没装的库。解决办法是在 CLAUDE.md 里明确写“不要引入新依赖”或者在指令里加一句“只使用项目已有的库”。它改完不跑测试明确告诉它“改完后运行 pytest tests/xxx.py”。如果它不知道测试命令在 CLAUDE.md 里写上测试命令。5.3 性能与上下文管理Claude Code 处理大项目时上下文窗口是有限的。如果你的项目有几千个文件它不可能全部读一遍。这时候 CLAUDE.md 里的目录说明就很重要——它能帮你快速定位到相关文件而不是盲目扫描。另外长对话会消耗上下文。如果你发现它开始“忘事”比如忘了之前说过的规则可以开一个新会话把关键信息重新说一遍。或者用/clear命令清空当前上下文重新开始。实操心得我习惯把复杂任务拆成多个会话。比如“重构用户模块”这种大任务我会分成“先分析现状”、“再设计新结构”、“然后逐个文件改”、“最后跑测试”几个会话。每个会话聚焦一个阶段上下文干净效果比一次性说完好很多。5.4 与 IDE 的配合Claude Code 是终端工具但它不排斥 IDE。我的工作流是VSCode 开着看代码终端里跑 Claude Code 下指令。改完之后在 VSCode 里 review diff确认没问题再提交。VSCode 里也有 Claude Code 的扩展装完之后可以在编辑器里直接调用。但说实话我更喜欢终端版本因为终端里它能直接执行命令能力更完整。编辑器扩展更适合快速问答重活还是交给终端。6. 把 Claude Code 用顺手的几个进阶习惯6.1 用 Git 分支隔离 AI 改动我现在养成了一个习惯让 Claude Code 改代码之前先开一个新分支。git checkout -b ai/feature-xxx这样它的所有改动都隔离在这个分支上改坏了直接删分支主分支干干净净。改好了再合并回去。这个习惯看起来多了一步但能省掉很多“改乱了不知道怎么回滚”的麻烦。6.2 指令里带上验证条件好的指令不只是“做什么”还包括“怎么算做完了”。比如给 get_user 加空值处理要求 1. 查不到返回 None 2. 补充类型注解 Optional[User] 3. 补充 docstring 4. 跑 tests/test_user_service.py 全部通过 5. 不要修改其他文件把验收标准写清楚它就知道什么时候该停也方便你判断结果是否合格。6.3 定期更新 CLAUDE.md项目在变CLAUDE.md 也要跟着变。每次新增模块、调整目录结构、更换依赖都顺手更新一下这个文件。它就像项目的“活文档”维护得越好Claude Code 的表现就越稳定。我一般会在每个迭代结束时花五分钟过一遍 CLAUDE.md把过时的规则删掉把新踩的坑补进去。这个投入产出比非常高。6.4 不要让它碰敏感文件数据库迁移文件、生产配置、密钥文件这些一律在 CLAUDE.md 里标为禁止修改。AI 再聪明也不了解你的生产环境约束让它碰这些文件风险太大。我的做法是敏感目录直接在 CLAUDE.md 里写“禁止读取和修改”从源头上杜绝。6.5 保持人工 review最后也是最重要的一条不管 Claude Code 改得多好提交前一定要自己看一遍 diff。它的改动大多数时候是对的但它不理解你的业务背景不知道某个看似多余的判断其实是为了兼容历史数据。人工 review 是最后一道防线不能省。我在实际使用中最大的体会是Claude Code 的价值不在于“替你写代码”而在于“替你处理那些你不想手动做的琐碎改动”。它把改代码这件事从“逐行敲”变成了“描述需求 审核结果”效率提升是实实在在的。但它终究是个工具你对项目的理解、对业务的判断才是决定改动质量的关键。把它当成一个执行力很强但需要明确指令的搭档而不是一个能替你做所有决定的替身这样用起来最舒服。