1. 为什么我最终把主力开发环境搬进了终端第一次听说 Claude Code 的时候我其实是有点抗拒的。2024 年到 2025 年那阵子AI 编程助手已经卷得不像样了——Cursor 把编辑器做成了半个 IDEWindsurf 主打心流式补全VS Code Copilot 稳坐老大哥位置Trae 又在国内圈了一波粉。我当时的想法很朴素编辑器里点一下就能补全为什么要回到黑漆漆的终端里敲命令真正让我改变主意的是一次重构任务。手上有个跑了三年的 Python 服务模块之间耦合得厉害我想把数据层抽出来。用编辑器里的 AI 助手我得一个文件一个文件地打开、选中、提问、粘贴来回切换几十次上下文还经常断。后来我试着用 Claude Code 在项目根目录跑了一条指令让它自己去找依赖关系、列出改动计划、逐个文件改。它在终端里把整个仓库当成一个整体来看那种agent 在项目里干活的感觉和编辑器里补全一行代码完全是两码事。这篇内容就是把我从零装 Claude Code、踩坑、到能独立用它完成一个完整小项目的全过程整理出来。Claude Code 是 Anthropic 推出的终端 AI 编程工具它不是一个插件而是一个跑在命令行里的智能体能读写你本地的文件、执行命令、跑测试、提交代码。适合谁看如果你已经会基本的命令行操作写过一点代码想让 AI 真正帮你做完一件事而不是补全一段代码那这篇就是给你写的。零基础也能看我会把每一步都拆开讲。需要先说明一点这类工具迭代非常快命令、参数、界面随时可能变。我下面写的都是基于我实际用下来的版本如果你照着做发现某个选项没了大概率是版本更新了思路是通用的。2. 装之前先想清楚它到底解决什么问题2.1 终端智能体和编辑器插件的本质区别很多人把 Claude Code 当成终端版的 Copilot这个理解会误导你。我用下来最大的感受是编辑器插件的工作单位是光标附近的一段代码终端智能体的工作单位是整个项目。举个具体例子。我让编辑器助手给这个函数加个错误处理它会给我一段 try/except。我让 Claude Code检查这个模块里所有网络请求统一加上超时和重试它会先读目录、找到所有相关文件、分析每个请求的写法、然后逐个改改完还会告诉你它动了哪些文件。前者是补全后者是执行任务。这个区别决定了它的使用姿势。你不能指望它帮你猜下一行写什么但你可以让它把这个需求实现出来。所以装之前先调整预期它是你的一个能读代码、能跑命令的实习生不是你的自动补全。2.2 它和 Cursor、Windsurf 这些工具怎么选我几个都用过说点实在的。Cursor 和 Windsurf 强在交互体验图形界面、diff 预览、一键接受适合边写边改的场景。Claude Code 强在自动化和批处理适合我描述一个任务你去把它做完的场景。我的实际搭配是这样的日常写新功能、调 UI我还是用编辑器做重构、写脚本、批量改配置、跑数据处理流程我切到终端用 Claude Code。两者不冲突反而互补。如果你只想装一个那就看你平时的工作是写多还是改多。2.3 装之前的环境准备清单在动手之前先把这几样确认好能省掉后面一堆报错操作系统macOS、Linux、Windows 都支持。Windows 上我建议用 WSL2原生 PowerShell 也能跑但路径和权限的坑会多一些。Node.js版本要 18 以上我实测 20 LTS 最稳。用node -v查一下低了就升级。终端系统自带的就行。想要体验好一点可以用 Tabby 这类现代终端工具分屏和字体渲染舒服很多。网络这个必须提前说。Claude Code 要连 Anthropic 的服务网络不通的话会直接报unable to connect to anthropic services或者failed to connect to api.anthropic.com。这是新手遇到最多的报错没有之一。账号需要一个能用的 Anthropic 账号订阅或者 API 额度都行。提示环境准备阶段最容易被忽略的是 Node 版本。我见过太多人卡在安装步骤最后发现是 Node 16 太老。先升级再装别省这一步。3. 从零安装三条路选适合你的那条3.1 官方推荐路径npm 全局安装这是最标准的方式也是我推荐新手走的。打开终端一条命令npm install -g anthropic-ai/claude-code装完之后验证一下claude --version能打印出版本号就说明装好了。如果报command not found八成是 npm 的全局 bin 目录没在 PATH 里。用npm config get prefix看一下路径把它加到环境变量里就行。我第一次装的时候遇到一个坑公司电脑上 npm 配了私有源装到一半卡住。后来临时切回公共源才成功。如果你也卡在下载阶段检查一下 npm 源。3.2 Ubuntu 和 Linux 上的安装细节Linux 上流程基本一样但有几个点要注意。首先是权限全局安装可能需要 sudo但我不建议直接sudo npm install -g容易把权限搞乱。更好的做法是配置 npm 的用户级全局目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH把最后一行写进~/.bashrc或~/.zshrc然后重新加载。这样以后装任何全局包都不需要 sudo也不会污染系统目录。另外 Ubuntu 上如果 Node 是 apt 装的版本往往偏旧。我建议用 nvm 管理 Node 版本装起来干净切换也方便。3.3 Windows 用户的两种选择Windows 上我强烈建议走 WSL2。原因很简单Claude Code 要执行 shell 命令WSL 里的 Linux 环境和它配合最顺。装好 WSL2 之后在里面按 Linux 的流程走一遍就行。如果你坚持用原生 WindowsPowerShell 里也能装但要注意路径分隔符和权限问题。有些命令在 PowerShell 和 bash 里行为不一样智能体执行时可能会出错。我试过一次能用但体验不如 WSL。3.4 桌面版和客户端的取舍除了命令行版Anthropic 后来也出了桌面客户端。桌面版的好处是开箱即用不用折腾 Node 环境适合完全不想碰命令行的人。但它的灵活度不如命令行版比如在项目里批量操作、配合 git worktree 做多分支并行这些还是命令行更顺手。我的建议想认真用装命令行版只想试试水桌面版够用。4. 第一次启动认证、配置和那个绕不开的连接报错4.1 登录认证的完整流程装好之后在任意目录敲claude第一次会引导你登录。它会给你一个链接在浏览器里打开、授权、把返回的码粘回终端。整个过程和大多数 CLI 工具的 OAuth 流程一样。登录成功后配置会存在本地。我建议顺手确认一下配置文件的位置后面改模型、改行为都要用到。一般在用户主目录下的隐藏目录里具体路径启动时会提示。4.2 连接失败到底怎么排查unable to connect to anthropic services这个报错我敢说每个新手都会遇到至少一次。排查顺序我总结成这样报错现象可能原因排查动作完全连不上超时网络不通先确认基础网络能访问外部服务能连但认证失败登录态过期重新走一遍登录流程提示 model route 相关错误模型配置不对检查配置文件里的模型名间歇性失败网络抖动重试或换个时间段那个doesnt look like an anthropic model: expected a gateway model route的报错通常是你手动改了配置里的模型名写了个它不认识的。改回默认值或者填官方支持的模型标识就行。注意网络问题是这类工具的头号拦路虎。如果你反复连不上先别怀疑工具本身把网络这条链路查清楚能省下大量瞎折腾的时间。4.3 基础配置项怎么调启动后可以用/config之类的命令进配置界面也能直接改配置文件。我常调的几个模型选择默认模型够用追求速度可以换更轻的追求质量换更强的。权限模式这个很关键。默认它每次要执行命令、改文件都会问你。熟练之后可以放宽但新手阶段我建议保持默认看清楚它每一步在干什么。主题和显示纯个人喜好不影响功能。配置这块我的原则是先别急着改用默认配置跑通一个完整任务再根据痛点去调。5. 核心用法把需求翻译成它能执行的指令5.1 提示词怎么写它才听得懂这是整篇最核心的部分。Claude Code 的能力上限很大程度上取决于你怎么跟它说话。我踩了无数坑之后总结出一个好指令的结构目标 范围 约束 验收标准。举个例子差的指令是帮我优化一下代码。好的指令是重构src/data目录下的数据访问层把散落在各处的 SQL 拼接统一到一个模块里保持现有函数签名不变改完确保pytest tests/test_data.py能通过。看出区别了吗后者告诉它做什么、在哪做、不能动什么、怎么算做完。它是个 agent你给的信息越完整它跑偏的概率越低。5.2 让它先规划再动手我强烈建议养成一个习惯先让它出计划你确认了再让它执行。很多任务你可以先问你打算怎么改它会列出步骤。你看一遍发现方向不对就及时纠正比它改完一堆文件你再回滚省事得多。这个习惯在重构和大范围改动时尤其重要。我有一次没看计划就让它改结果它把测试文件也一起优化了虽然没出错但 diff 大得没法 review。5.3 上下文管理别让它一次吃太多Claude Code 会把项目文件读进上下文但上下文是有窗口限制的。项目一大它不可能全读进去。所以你要学会给它划范围明确告诉它只看某个目录、某个文件或者用.gitignore类似的机制排除无关文件。我一般会在项目根目录放一个说明文件告诉它这个项目是干什么的、目录结构怎么组织、有哪些约定。它每次启动会读这个文件相当于给它一份项目地图能显著提升它找文件的准确率。5.4 权限控制哪些操作该放行哪些必须拦默认模式下它每次执行命令、写文件都会请求你确认。这个设计是对的因为 agent 能跑任意命令风险是真实存在的。我的做法是读操作放心放行读文件、列目录没风险。写操作第一次看清楚它要写什么确认没问题再放行。执行命令涉及删除、覆盖、推送的一律手动确认。网络请求谨慎尤其是会往外发数据的。熟练之后可以配置白名单把常用的安全命令放行减少打断。但白名单要慢慢加别一上来就全放开。6. 实战用它独立完成一个完整小项目6.1 项目选型和任务拆解光讲用法太虚我拿一个真实的小项目走一遍。需求是写一个命令行工具扫描指定目录下的日志文件统计各级别日志的数量输出一份汇总报告。技术栈用 Python因为依赖少、跑得快。我先在终端里建好目录初始化 git然后启动 Claude Code。第一条指令我给的是整体需求让它先出方案我要写一个 Python 命令行工具扫描指定目录下的 .log 文件 统计 ERROR、WARN、INFO 各级别的出现次数最后输出汇总。 先给我一个实现方案包括文件结构和每个文件的职责先别写代码。它返回了一个方案一个主入口文件、一个解析模块、一个统计模块还建议用 argparse 处理参数。我看了一遍觉得合理就让它开始实现。6.2 分阶段推进而不是一把梭我没有让它一次性写完所有代码而是分阶段来。第一阶段让它实现解析和统计的核心逻辑第二阶段加命令行参数第三阶段写测试。每完成一个阶段我自己跑一遍确认没问题再进下一步。这样做的好处是出问题时范围小、好定位。如果一把梭写完再跑报错了你都不知道是哪块的问题。6.3 让它自己跑测试和修 bug第三阶段我让它写单元测试。它写完测试后我直接让它跑运行测试如果有失败的自己分析原因并修复修完再跑一遍直到全绿。它跑了一遍有两个用例失败原因是它对日志格式的假设和我的测试数据不一致。它自己改了正则重跑通过了。这个过程我全程没插手只在最后 review 了 diff。这就是 agent 和补全工具最大的差别——它能形成写、跑、看结果、改的闭环。你只需要在关键节点把关。6.4 提交代码和写 commit message功能做完我让它整理提交把这次改动整理成一次提交写一个清晰的 commit message 说明新增了什么功能。它会自己git add、生成 message、提交。我一般会看一眼 message 再确认因为它有时候写得太啰嗦。整个项目从零到能跑我大概花了不到一小时其中大部分时间是我在看它的计划和 diff。如果纯手写这个工具加上测试我估计要两三个小时。7. 进阶玩法让它真正融入你的工作流7.1 配合 git worktree 做多任务并行这是我最近最喜欢的用法。git worktree 能让你在同一个仓库里开出多个工作目录每个目录对应一个分支。我可以在一个 worktree 里让 Claude Code 做重构同时在另一个 worktree 里做新功能互不干扰。具体做法是给每个 worktree 单独开一个终端窗口各自跑一个 Claude Code 实例。它们操作的是不同的目录不会打架。这个玩法适合手上同时有好几条线要推进的时候。7.2 接入其他模型和后端Claude Code 默认连 Anthropic 的服务但社区里也有人研究怎么把它接到别的模型后端上比如本地跑的模型或者第三方 API。这块我不展开讲具体配置因为涉及的东西比较杂而且各家方案差异大。思路是它本质是个客户端只要能对接上兼容的接口理论上就能换后端。想折腾的可以自己研究但要注意兼容性和稳定性。7.3 在 VS Code 里用终端版有人问能不能在 VS Code 里用 Claude Code。可以但不是在插件市场装个扩展那种用法而是在 VS Code 的集成终端里直接跑命令行版。这样你既能用编辑器的文件树和 diff 视图又能用终端智能体的能力。我有时候就这么干左边看代码右边终端里让它改。7.4 卸载和清理如果哪天不想用了卸载很简单npm uninstall -g anthropic-ai/claude-code但别忘了清理配置文件和缓存目录不然残留的登录态和配置会占地方。具体路径启动时提示过照着删就行。8. 常见问题速查和我的避坑心得8.1 高频报错速查表报错关键词大概率原因解决方向unable to connect to anthropic services网络不通检查网络链路failed to connect to api.anthropic.com同上或 DNS 问题换网络环境重试doesnt look like an anthropic model模型名配错改回默认模型标识command not found: claudePATH 没配好检查 npm 全局 bin 路径安装卡住不动npm 源问题切换 npm 源8.2 我踩过的几个真实的坑第一个坑是权限放太宽。有次我图省事把写权限全放行了结果它在一个我没注意的目录里改了个配置文件虽然没造成损失但吓了我一跳。从那以后我坚持写操作手动确认。第二个坑是上下文塞太满。有个大项目我直接在里面启动它读文件读了半天最后因为上下文超限回答质量下降。后来我学会了先cd到子目录缩小它的视野。第三个坑是过度信任它的计划。它有时候会提出一个看起来合理但实际有隐患的方案比如建议删掉某个看起来没用的模块。这种时候一定要自己判断它是助手不是决策者。8.3 让效率翻倍的几个小技巧项目根目录放说明文件告诉它项目结构和技术栈约定找文件准很多。善用先计划后执行大改动前一定先看计划。小步快跑分阶段推进每步验证别一把梭。让它写测试测试是它的验收标准也是你的安全网。定期 review diff别闭眼接受看清楚它改了什么。8.4 关于提示词的一点个人体会用了这么久我最大的体会是跟 AI 编程工具沟通本质上是在做需求管理。你需求描述得越清楚它交付得越靠谱。那些抱怨AI 写的代码不能用的人很多时候是需求本身就没想清楚。我现在写指令会刻意练习一件事把脑子里模糊的想法逼自己写成明确的、可验收的句子。这个习惯反过来也让我自己的编程思路更清晰了。这可能是用这类工具最大的意外收获。最后分享一个我最近常用的模式让它先复述一遍我的需求确认理解一致了再动手。就多这一句话能挡掉不少它理解的和我想的不一样的返工。这个技巧在需求稍微复杂一点的时候特别管用你可以试试。
