1. 从零到提交为什么我选择在终端里跑 Claude Code第一次听说 Claude Code 的时候我其实没太当回事。命令行里写代码、改文件、跑测试、提交 git这些事我干了快十年闭着眼都能敲。但真正让我改变看法的是某天下午一个特别琐碎的需求给一个老项目补一批单元测试文件多、逻辑散、命名还不统一。手动写一下午就没了交给 Claude Code从装好到第一个任务跑完并提交前后不到四十分钟。这篇文章就是那次实操的完整复盘。我会把 Claude Code 从安装、配置、跑第一个任务、到用 git 提交的全过程拆开讲清楚重点放在终端环境下的真实操作细节和计划模式Plan Mode怎么用这两个最容易卡住新手的环节。适合两类人看一类是刚接触 Claude Code、想快速跑通第一个任务的开发者另一类是用过但总觉得不太顺手、想搞清楚背后逻辑的老手。全文基于我自己的终端环境macOS zshWindows 和 Linux 的差异我会单独标注所有命令都可以直接抄。先说结论Claude Code 的核心价值不在于帮你写代码而在于把理解需求→拆解任务→执行→验证→提交这条链路压缩进一个终端会话里。你不需要在编辑器、浏览器、终端之间来回切所有动作都在一个窗口完成。这也是为什么我坚持在终端里用它而不是塞进某个 IDE 插件里——终端是唯一能同时容纳文件操作、命令执行和版本控制的地方。2. 装好之前环境准备与安装路径选择2.1 先确认你的终端和 Node 环境Claude Code 本质是一个跑在 Node 环境下的 CLI 工具所以第一步不是装它而是确认你的基础环境。我见过太多人卡在装完了打不开九成是 Node 版本或 PATH 的问题。打开终端先跑这两条node -v npm -vNode 版本建议18.17 以上低于这个版本会在安装阶段报奇怪的依赖错误。如果版本不够别急着用系统包管理器升级我推荐用nvmNode Version Manager来管理避免污染系统环境# macOS / Linux 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 装完重开终端然后 nvm install 20 nvm use 20Windows 用户如果用的是 PowerShellnvm 的体验一般我更推荐直接去 Node 官网下 LTS 版本的安装包装的时候勾选Add to PATH。这里有个坑Windows 上如果之前装过旧版 Node一定要先卸载干净再装新的否则 PATH 里会残留旧路径导致node -v显示的还是老版本。至于终端工具本身macOS 自带的 Terminal 够用但我更推荐 iTerm2 或者 Tabby——Tabby 的好处是跨平台、支持终端复用分屏、标签页管理跑 Claude Code 这种需要长时间交互的工具时能一边看它输出一边开另一个标签查文档效率高不少。Linux 下随便一个现代终端都行gnome-terminal、konsole 都可以。2.2 安装 Claude Code 的两种方式安装本身很简单官方推荐用 npm 全局安装npm install -g anthropic-ai/claude-code装完验证claude --version能打印出版本号就说明装好了。如果报command not found八成是 npm 全局 bin 目录没进 PATH。查一下npm config get prefix把这个路径下的bin目录加到你的 shell 配置文件里zsh 是~/.zshrcbash 是~/.bashrcexport PATH$PATH:$(npm config get prefix)/bin然后source ~/.zshrc生效。第二种方式是用官方的安装脚本适合不想折腾 npm 的人curl -fsSL https://claude.ai/install.sh | bash注意不管用哪种方式装完之后一定要新开一个终端窗口再验证。很多装好了但用不了的问题都是因为当前 shell 会话没重新加载 PATH。2.3 首次启动与认证第一次运行claude它会引导你完成认证。这个过程是交互式的跟着提示走就行。认证完成后你的凭据会存在本地配置目录里macOS 是~/.claudeLinux 和 Windows 类似后续启动不需要重复登录。这里分享一个实操心得如果你在公司网络环境下认证失败先检查是不是代理或防火墙拦截了。Claude Code 需要访问外部 API网络不通的话会在认证阶段就卡住。这种情况下去找你的网络管理员确认出口策略别自己瞎折腾。3. 计划模式Claude Code 最被低估的功能3.1 计划模式到底解决什么问题很多人用 Claude Code 的方式是直接丢一句帮我改一下这个文件然后看它噼里啪啦一顿操作。这种方式在简单任务上没问题但一旦任务涉及多个文件、多个步骤就容易失控——它可能改了你不想改的地方或者顺序搞反了。计划模式Plan Mode就是为解决这个问题设计的。开启后Claude Code 不会直接动手而是先输出一份我打算这么做的计划等你确认后再执行。这就像你带一个新同事干活先让他说说思路你觉得没问题再让他动手而不是上来就改代码。开启方式有两种启动时加参数claude --plan会话中切换输入/plan命令我个人的习惯是所有涉及三个文件以上的任务一律先开计划模式。多花三十秒看计划能省掉后面十分钟的返工。3.2 一份好的计划长什么样举个我实际跑过的例子。当时的需求是给utils/目录下所有工具函数补单元测试。我开了计划模式输入需求后Claude Code 给出的计划大致是扫描utils/目录列出所有.js文件对每个文件识别导出的函数及其签名为每个函数生成对应的测试用例覆盖正常输入、边界值、异常输入在tests/目录下创建对应的测试文件运行测试确认全部通过如果有失败回到第 3 步修正这份计划的价值在于它把补测试这个模糊需求拆成了可验证的步骤。我扫一眼就知道它理解对了没有。如果它漏了运行测试这一步我当场就能指出来而不是等它生成一堆跑不通的测试文件才发现问题。3.3 计划模式的三个使用技巧技巧一计划阶段就把约束说清楚。别等它执行到一半才说哦对了别改index.js。在计划模式下你可以直接补充第 2 步跳过index.js那个文件是入口不需要测试。它会重新生成计划。技巧二用计划模式做代码审查。我经常在计划模式下发一句读一下src/目录告诉我这个模块的依赖关系和数据流向。它不会改任何东西只输出分析结果。这比我自己一个个文件翻快多了。技巧三计划确认后执行阶段可以随时打断。如果执行到一半你发现方向不对按Esc可以中断然后重新调整。别硬着头皮等它跑完。注意计划模式不是万能的。对于帮我改个变量名这种一句话能说清的任务开计划模式反而啰嗦。判断标准很简单——如果你自己都说不清楚要改哪几个文件那就开计划模式。4. 第一个任务从需求到代码的完整实操4.1 任务背景与目录准备我选了一个真实的小项目来演示一个用 Express 写的待办事项 API代码结构如下todo-api/ ├── src/ │ ├── app.js │ ├── routes/ │ │ └── todos.js │ └── utils/ │ └── validate.js ├── tests/ ├── package.json └── .git/需求是给validate.js里的输入校验函数补测试并修复一个边界值 bug。这个任务不大不小正好能展示 Claude Code 的完整工作流。先进入项目目录cd ~/projects/todo-api claude启动后你会看到一个交互式提示符。先别急着输入需求我习惯先让它熟悉一下环境读一下这个项目的结构告诉我 src/utils/validate.js 里有哪些函数各自做什么。这一步的作用是建立上下文。Claude Code 会读取相关文件理解项目结构后续任务它就能基于这些信息工作而不是每次从零开始。4.2 用计划模式拆解任务确认它理解了项目后切换到计划模式/plan然后输入完整需求给 src/utils/validate.js 里的所有导出函数补单元测试测试文件放在 tests/validate.test.js。 要求覆盖正常输入、边界值空字符串、超长字符串、特殊字符、异常输入null、undefined、非字符串类型。 另外检查 validateEmail 函数对 ab 这种没有顶级域名的输入是否处理正确如果有 bug 就修复。它输出的计划大致如下读取src/utils/validate.js识别导出函数validateEmail、validateLength、sanitizeInput读取package.json确认测试框架这里是 Jest分析每个函数的逻辑识别边界条件检查validateEmail对ab的处理判断是否为 bug创建tests/validate.test.js编写测试用例运行npm test确认通过如果validateEmail有 bug修改src/utils/validate.js并重新运行测试我扫了一眼发现它漏了一点测试文件需要引入被测模块但项目用的是 ES Module 还是 CommonJS 它还没确认。我补充了一句注意确认项目的模块规范测试文件的引入方式要和现有代码保持一致。它更新了计划加了读取现有测试文件或 package.json 的 type 字段确认模块规范这一步。确认无误后我让它开始执行。4.3 执行过程与关键节点执行阶段Claude Code 会逐步输出它的动作。我截取几个关键节点节点一识别 bug。它读取validateEmail后输出了一段分析validateEmail当前实现是/^[^\s][^\s]$/这个正则对ab会返回 true但b不是有效的顶级域名。按照常见实践邮箱应该至少包含一个点号在 之后。建议修改为/^[^\s][^\s]\.[^\s]$/。这个判断是对的。我确认后它修改了源码。节点二生成测试。它创建了tests/validate.test.js内容结构清晰每个函数一个describe块每个边界条件一个it。我特别注意到它给sanitizeInput加了一个测试用例输入scriptalert(1)/script期望输出转义后的字符串。这个用例我没要求但它基于函数名推断出了安全相关的意图加得很合理。节点三运行测试。它执行npm test输出显示 12 个测试用例全部通过。然后它主动说了一句测试全部通过是否需要我提交这些改动4.4 验证结果与人工复核别完全信任它的全部通过。我习惯自己再跑一遍npm test -- --verbose确认每个用例都真的执行了而不是被跳过。然后git diff看一下改动git diff src/utils/validate.js确认 bug 修复只改了那一行正则没有顺手改别的东西。这一步很重要——Claude Code 有时候会顺手优化一些你没要求的地方虽然多数时候是好事但你需要知道它改了什么。5. 用 git 提交从暂存到 commit message 的规范5.1 提交前的检查清单在让 Claude Code 帮你提交之前先自己过一遍这几项git status确认改动文件列表符合预期git diff确认没有意外的调试代码console.log、注释掉的代码块确认测试全部通过确认没有大文件被误加入比如node_modules、日志文件我踩过一次坑Claude Code 生成测试时顺手在项目根目录创建了一个.claude-cache目录里面是它读取文件的缓存。这个目录不该进版本库。解决办法是在.gitignore里加一行.claude-cache/提示每次用 Claude Code 做完任务都检查一下git status里有没有多出你不认识的文件。这是最容易忽略的坑。5.2 让 Claude Code 生成 commit message确认改动没问题后可以直接让它提交把这次改动提交commit message 用 conventional commits 规范。它会执行git add和git commit并生成类似这样的 messagetest(validate): add unit tests for validation utils and fix email regex - Add tests for validateEmail, validateLength, sanitizeInput - Cover normal, boundary, and invalid inputs - Fix validateEmail to require TLD after 这个 message 质量不错类型test、范围validate、描述都齐全正文列出了具体改动。如果你团队有自己的提交规范可以在指令里说清楚比如用中文写 commit message格式是[模块] 描述。5.3 手动提交的备选方案如果你不放心让它直接提交可以只让它生成 message自己手动执行帮我生成这次改动的 commit message先不要提交。它输出 message 后你复制出来自己跑git add src/utils/validate.js tests/validate.test.js git commit -m test(validate): add unit tests and fix email regex我个人在涉及核心逻辑改动时倾向手动提交在纯新增测试或文档时让它自动提交。这个分寸你自己把握。5.4 提交后的验证提交完别急着关终端跑一下git log --oneline -3 git show --stat HEAD确认提交记录和文件变更都正确。如果发现 message 写错了还没 push 的话可以改git commit --amend -m 新的 message如果已经 push 了那就别改了重新提交一个修正 commit 更安全。6. 常见问题与排查技巧实录6.1 安装与启动类问题问题现象可能原因解决方法claude: command not foundnpm 全局 bin 不在 PATH把npm config get prefix下的 bin 加入 PATH启动后卡在认证网络不通或代理拦截检查网络出口策略确认能访问外部 APINode 版本报错版本低于 18.17用 nvm 装 Node 20Windows 下命令无响应旧版 Node 残留卸载所有 Node 后重装 LTS6.2 任务执行类问题问题它改了我没让它改的文件。这是最常见的抱怨。原因通常是你的需求描述有歧义或者它顺手优化了相关代码。解决办法开计划模式在执行前确认改动范围。如果已经改了用git checkout -- file回滚那个文件然后重新下指令明确说只改 X 文件不要动其他文件。问题测试跑不通但它说通过了。可能是它运行的测试命令和你的实际环境不一致。比如项目用pnpm test它跑了npm test。解决办法在指令里明确测试命令或者先告诉它这个项目用 pnpm。问题它读取文件时卡住或超时。大项目里文件太多它扫描目录会慢。解决办法明确告诉它只看哪个目录比如只读src/utils/下的文件。6.3 提交类问题问题commit message 不符合团队规范。在指令里把规范说清楚最好给一个示例。比如commit message 格式是类型(模块): 描述类型只能是 feat/fix/test/docs/chore描述用中文。问题误提交了大文件。如果还没 push用git reset HEAD~1撤销提交把大文件加入.gitignore重新提交。如果已经 push 了需要用git filter-repo清理历史这个操作有风险建议先备份。问题提交后发现漏了文件。补一个 commit 就行别用--amend改已经 push 的记录。如果只是漏了文件没 push可以git add后git commit --amend --no-edit。6.4 几个我踩过的坑坑一在错误的目录启动。有次我在 home 目录直接跑claude然后让它读一下项目结构它把整个 home 目录扫了一遍慢得要死。一定要先cd到项目根目录再启动。坑二让它同时做太多事。补测试 重构 更新文档 改 CI 配置这种复合需求它容易顾此失彼。拆成多个会话一个会话做一件事质量高得多。坑三忽略它的我不确定提示。有时候它会说我不确定这个函数的预期行为请确认。别跳过这句话它是在告诉你信息不足。补充上下文后它才能做对。7. 我个人的使用节奏与后续扩展跑通第一个任务后我逐渐形成了一套自己的使用节奏小改动直接下指令中等任务开计划模式大任务先让它做分析再分步执行。终端里常备两个标签页一个跑 Claude Code一个用来手动验证它的输出。这套流程跑顺之后我把它扩展到了更多场景批量重命名变量、生成 API 文档、把旧代码从回调风格迁移到 async/await、甚至用它做代码审查——让它读一个 PR 的 diff列出潜在问题。核心逻辑都是一样的先让它理解再让它计划最后让它执行每一步都留人工确认的关口。如果你刚开始用我的建议是别一上来就丢大任务。先拿一个你熟悉的小文件练手看它怎么读、怎么改、怎么提交建立信任之后再逐步放大任务规模。终端里的 Claude Code 不是魔法它更像一个执行力很强但需要清晰指令的搭档——你给它的上下文越准它还给你的结果就越靠谱。