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 用户可以用 Homebrew：

brew install node@20

Ubuntu 用户建议用 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.md，Claude 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 user

4.5 用 Git 检查改动范围

改完之后，用 Git 确认一下它到底动了哪些文件：

git diff git status

这一步非常关键。Claude Code 有时候会顺手改一些你没要求的地方，比如格式化无关代码、调整 import 顺序。通过git diff你能清楚看到每一处改动，确认没有意外修改后再提交。

如果发现它改了不该改的地方，直接git checkout -- 文件名回滚，然后重新给它更明确的指令。

注意：养成“改完必看 diff”的习惯。这不是不信任工具，而是对自己代码负责。我见过太多人让 AI 改完直接提交，结果把调试代码、临时注释一起带上去了。

5. 常见问题排查与避坑经验

5.1 安装与认证类问题

认证类问题里最常见的是“浏览器打不开”或“回调地址粘贴后没反应”。如果你在远程服务器上操作，本地浏览器授权后拿到的回调 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 的价值不在于“替你写代码”，而在于“替你处理那些你不想手动做的琐碎改动”。它把改代码这件事从“逐行敲”变成了“描述需求 + 审核结果”，效率提升是实实在在的。但它终究是个工具，你对项目的理解、对业务的判断，才是决定改动质量的关键。把它当成一个执行力很强但需要明确指令的搭档，而不是一个能替你做所有决定的替身，这样用起来最舒服。