从零上手Claude Code实战记录

那是我第一次把终端权限交给一个 AI。它问我能不能读取整个项目目录，我犹豫了大概三十秒，然后敲了 yes。说实话，那一刻比第一次用 Copilot 紧张得多，Copilot 只是在编辑器里帮你补全一行代码，而这个东西要的是整个仓库的读写权。

这事发生在今年四月，我正准备把一个跑了两年多的 React 老项目的状态管理从 Redux 迁到 Zustand。迁移本身不复杂，但涉及四十几个文件，纯手工改至少要耗掉一个下午。朋友在微信上丢过来一句“你用 Claude Code 试试，直接让它干”，我当时的反应是，你在开玩笑。

但它确实干完了。不是完美地干完，是跌跌撞撞地、出过错、被我叫停过两次、最后交出一个我需要再花半小时修整的版本那种干完。而我付出了一个下午去学怎么跟它打交道。

这就是我想说的第一件事：Claude Code 不是那种装上就能替你干活的东西，它更像一个需要入职培训的初级同事。 那些宣传语里说的“Agent 式编程”“自主完成复杂任务”，技术上没错，但省掉了一个关键前提，你得先学会怎么训练它、约束它、看懂它什么时候在胡说八道。

一、一个被反复模糊的核心结论

市面上的“从零上手”教程，几乎都在做同一件事：把 Claude Code 包装成一个命令行里的魔法棒。定义很清晰，安装步骤很详细，第一个例子永远是用自然语言让它“整理一下下载文件夹”或者“把这些文件重新命名”。

这些场景真实吗？真实。有用吗？对第一次接触的人来说，确实挺震撼的。但问题在于，它们让你以为这就是全部，让你带着“AI 助理”的预期进去，然后在你第一次让它改生产代码的时候被现实绊一个大跟头。

我踩过的坑可以很直接地告诉你：Claude Code 最擅长的不是执行，而是理解。它最危险的地方不是能力不够，而是它在不够懂的时候，依然会自信地动手。

举一个具体的例子。第二天我让它帮我写一个 React 组件的单元测试，项目用的测试框架是 Vitest，mock 策略有些非标准写法。它没有问项目为什么这么写，而是直接按照它自己训练的“标准 Vitest 模式”生成了一套测试代码，跑倒是能跑，但把所有 mock 逻辑都绕过了，等于在测空气。当时如果没有一行行 review，我可能就把它当成“测试通过”提交了。

所以我对 Claude Code 的核心判断是：它是一个需要被事实校准的推理机器，不是一个可靠的自动化工具。 你用它的方式，决定了它到底是你的外挂大脑，还是你的技术债务制造机。

二、我是怎么入的坑：场景和动机

说说我自己的背景。我写前端七年，Copilot 用了快两年，Cursor 试过三个月然后放弃。放弃 Cursor 的主要原因不是它不好，而是它太“乖”了，它能很聪明地猜出我下一行要写什么，但从来不敢告诉我整个文件的设计有问题。它是个极好的副驾驶，但方向盘一直在我手里。

我需要的是一个能帮我做“脏活”的东西：跨文件重构、写测试覆盖、在已有代码上做变更影响分析。这些活不是一行代码补全能解决的，它需要对项目有整体理解，需要能读写多个文件，需要能在执行前告诉你它打算怎么干。

Claude Code 吸引我的就是这一点。它不是 Cursor 那种“内嵌在编辑器里的代码建议器”，而是一个独立运行在终端里的 Agent。它能用命令行操作文件系统，能跑 git 命令，能执行脚本并读取输出，然后根据结果调整下一步行动。这种感觉更像是在 Slack 里给一个远程同事分配任务，而不是在 IDE 里接受建议。

三、那些教程不会告诉你的三个反直觉事实

基于我这两个多月的实际使用，以及帮团队里另外两个同事从零搭环境的过程，总结三个很容易被忽视的点。

1. 安装环节的真正门槛不是命令行，而是心理授权

从技术上看，安装就是一行 npm install -g @anthropic-ai/claude-code 然后 claude 启动，简单到不像话。真正的门槛在于启动之后，它要求你授权访问当前工作目录。很多人在这里会卡住，因为他们突然意识到：这不是一个被沙箱隔离的网页聊天框，这是一个能直接读写你本地文件的进程。

我需要在这个环节补充一个很重要的细节：你完全不需要给它全局权限。 我的做法是专门建一个 ~/claude-projects/ 目录，每个项目用子文件夹隔开，每次只在这个目录下启动 Claude Code。这样即使它出问题，影响范围也被限制在你刻意划定的区域内。这跟给一个新同事只开特定仓库权限是一个逻辑。

2. CLAUDE.md 不是可选项，是必选项

很多教程把 CLAUDE.md 文件描述成“可以放一些项目说明”，这个表述太轻了。在我的使用经验里，这是一个没有它就会显著增加翻车概率的配置文件。

我的 CLAUDE.md 写了几件事：项目用什么技术栈、测试命令是什么、哪些目录是自动生成的不要碰、以及最重要的，“修改任何文件之前，先告诉我你的计划，等我确认再执行”。最后这条救了我不止一次。它有个习惯是推断出方案后直接动手，如果你不明确设置边界，它就会按照它的推断往下走。而它的推断，老实说，在我这个老项目上的准确率大概只有七成。

3. MCP 工具的配置难度被严重低估了

MCP 协议让 Claude Code 能连接浏览器、数据库这些外部工具，这确实是它跟普通 AI 编程工具拉开差距的能力。但配置过程对新手极不友好。我配 Brave Search 的 MCP 时卡了将近两个小时，问题出在 JSON 配置文件的一个嵌套层级写错了，而文档对这个错误的提示是一行英文 error log，没有任何指引。

我在这里的建议是：刚上手先不要碰 MCP。先把 Claude Code 在纯代码操作上的能力摸透，等你能稳定判断它在什么场景下靠谱、什么场景下会胡说之后，再去扩展它的外接能力。顺序反了，你会同时面对两个黑箱的叠加不确定性，很容易得出“这玩意根本没法用”的结论。

四、复盘两个真实项目操作，还原实际表现

以下是我在同一个 React 老项目上做过的两次尝试，一次成功，一次翻车。这两次放在一起看，能说明很多问题。

一、成功案例：批量重构文件结构

项目根目录下有个 utils/ 文件夹，塞了六十几个工具函数，完全没有分类，import 路径写得随心所欲。我给了 Claude Code 一个明确的指令：“扫描所有引用这些工具函数的文件，按功能把它们归到 utils/network/、utils/format/、utils/validation/ 三个子目录里，然后更新所有 import 路径，每移动一个文件 commit 一次。”

它执行的步骤是：先扫描所有 import 关系，再输出一个重分组方案给我确认，通过之后逐个移动文件、逐个 commit、最后跑了一遍 lint 和 build 确认没有引入错误。这个任务如果我自己干，保守估计要两个小时，它用了不到十五分钟的 AI 处理时间，加上我审核方案和看 commit diff 的时间，总计大概四十分钟。

翻车案例：写一套完整的 API 层

第二次我想让它把一个模块的 API 调用从散落在各组件里的 fetch 直接调用，封装成一个标准化的 service 层。我给的指令是：“分析 Dashboard 模块下所有 API 调用，创建 services/dashboard.ts，统一封装请求和错误处理。”

它确实是这么干的。问题出在它自己设计了一套“通用请求封装函数”，这个函数用了一种我项目里从未使用过的模式：把所有 API 方法的请求体和响应类型都放在一个联合类型里通过泛型推导。从纯技术角度看，这个设计很“聪明”，类型安全也做到了。但它完全忽略了项目里其他模块的 service 层是怎么写的，简单直接的函数导出，没有任何泛型体操。

结果就是：它写出来的代码，单看很漂亮，放进项目里格格不入。如果我当时不重写，三个月后任何一个接手这个模块的同事看到这个泛型推导逻辑，第一反应一定是怀疑我那天是不是喝多了。

关键教训：Claude Code 的代码生成能力是“上下文感知”的，但它的上下文理解有一个明确边界，它能看懂一个文件内部的逻辑，也能跨文件追踪引用关系，但它很难理解“这个团队约定俗成怎么写代码”这种隐性的规范。这种规范存在于团队成员的脑袋里，不存在于代码仓库里。而 CLAUDE.md 能部分解决这个问题，前提是你自己先把这些隐性规范写下来。

五、在 Copilot / Cursor / Claude Code 之间做选择

我现在的工具组合是这样的：

这个组合不是一成不变的。最核心的判断标准是：如果这个任务需要“理解整个项目”，就用 Claude Code；如果只需要“理解当前文件”，Copilot 更快更省心。

六、写给准备上手的人：一个经过验证的启动路径

如果你今天就想试，我建议按这个顺序走，比网上那些“第一步装第二步玩第三步就会了”的教程要实际得多：

1. 先在本地建一个隔离目录，不要在现有项目上试。随便拷几个文件过去，让 Claude Code 做几件简单的事：读文件内容、重命名、写一段说明文档。
2. 当你看到它确实能正确读写文件之后，在正式项目里加上 CLAUDE.md，至少写清楚三点：项目类型、禁止操作目录、执行前需确认的规则。
3. 前五次派任务，每次都加上同一句话：“先告诉我你的计划，不要直接动手。”等你看完计划觉得靠谱，再让它执行。
4. 在它每次改完文件后，用 git diff 逐行看变更。这个习惯至少要保持到你对自己的“AI 同事”建立足够的信任度。
5. 碰到它自信输出但明显不对的时候，不要默默修掉。直接告诉它哪里不对、为什么不对、正确的写法应该是什么样。这一步能显著提升它在这个项目里的后续表现。

最后说一下很多人关心但很少被正面回答的问题：它到底能不能省时间？

我的实际体感是：在处理“清楚但繁琐”的任务时，能省一半以上的时间；在需要深度业务判断的任务上，省不了时间，但能提高决策质量，因为它在快速穷举可能性这件事上确实比人脑快。

你可能会经历一个阶段，觉得跟它沟通的时间都够自己写完两遍了。这个阶段大概持续一周，是正常的，本质上是在建立你跟它之间的协作默契。

走过这个阶段之后，你会开始习惯性地想：这件事能不能丢给它？而答案经常是“能”。那个时候，你才算真正上手了。