作为一个在终端里泡了快十年的老开发，我平时对各类AI编程工具的态度一直比较谨慎。IDE里装个补全插件、聊天面板里问问报错意思，这些我都能接受，但真让我把核心代码逻辑交给一个“对话框”去改，总觉得不太靠谱。直到我花了一个周末认真把 Claude Code 跑起来，把几个小需求丢给它试了试，才意识到之前对“终端里的AI助手”这个定位理解得太浅了。
Claude Code 是 Anthropic 推出的命令行编程助手，直接在终端里运行，可以读你的项目文件、执行命令、修改代码，并以 Git 风格的 diff 展示改动。它的核心价值不在于“帮你写一段函数”，而在于它能围绕一个真实项目，完成“理解需求—定位代码—实施修改—运行验证”这一整条链路。这篇手册我打算按自己的使用过程来写，从装好第一个会话跑通，到日常怎么嵌入工作流，再到现在用得多了之后踩过的坑，希望能帮你少走一些弯路。
这篇文章适合两类人：一是一直在用各类 AI 编程插件，但觉得“只补全不干活”的开发者；二是已经安装了 Claude Code，但还停留在聊天式提问、没有真正让它操作过代码的朋友。我会尽量把每个步骤背后的原因也讲清楚，而不是只丢给你一堆命令。
1. 为什么一个终端工具值得我专门写篇手册
先说说我之前的典型工作流长什么样。接到一个需求后，我要花不少时间在编辑器里翻文件、跳定义、找调用关系，理清楚改动会牵扯到哪些模块，然后才开始动手。这个过程本身非常耗时，而且特别依赖你对项目的熟悉程度。如果是别人写的代码，或者是很久以前写的代码，光是“读懂”就要花掉半天。
Claude Code 之所以能改变这个流程，原因在于它不像聊天面板那样只拿到你粘贴的代码片段。它跑在项目根目录下，可以自行查看目录结构、读取文件内容、定位相关引用，甚至直接执行测试命令来验证自己的改动。换句话说，它具备了“主动探索项目”的能力，而不是被动等你投喂信息。
拿我实际测试过的一个任务举例：有次我需要给一个内部工具加一个“批量导出 CSV”的功能，放在以前我得先搞清楚现有的导出逻辑在哪个模块、数据从哪儿来、按钮加在哪个组件。这次我直接claude进入交互模式，用一句话描述了需求，它先自己扫了一遍项目结构，定位到了已有的单条导出函数，复用了一套序列化逻辑，生成了批量版本，然后跑了现有测试给我看结果。整个过程里我需要做的，只是描述需求、审核 diff、然后让它把测试跑完。
这种体验带来的效率提升是结构性的。单点补全类工具解决的是“这句话怎么写”，Claude Code 解决的则是“这个需求怎么落地”。它把从需求到代码之间的那段“理解、排查、决策”过程压缩了，这是我认为它值得被单独写一篇手册来聊的根本原因。
当然，它并不是万能的，也不是说你就可以完全放手。它更像一个执行力很强但需要你把关的协作者。你负责描述意图、审查结果、把握方向，它负责处理繁琐的文件跳转和机械修改。搞清楚这个分工，后面的所有使用技巧都围绕它展开。
2. 安装与授权，以及初跑时最容易卡住的环节
2.1 环境准备和安装命令
Claude Code 目前对 Linux、macOS 以及 Windows Subsystem for Linux 支持得比较好。我日常主力是 macOS，但也在 WSL 里跑过，整体流程几乎没有差别。安装前提是机器上有 Node.js 18 以上版本，最好顺手确认一下 npm 源是正常的。
安装命令很简单，一条 npm 全局安装：
npm install -g @anthropic-ai/claude-code装完可以用claude --version确认一下是否成功。如果提示找不到命令，多半是 npm 全局 bin 目录没加到 PATH。这时候可以执行npm bin -g拿到全局目录，再把它加到 shell 的 PATH 里。这个问题在 macOS 上尤其常见，因为 nvm 装的 Node 全局目录有时不会被自动识别。
2.2 登录、授权和第一个会话
安装完成后，在项目根目录直接敲claude，会进入一个交互式终端界面。第一次使用会引导你完成账号授权，也就是登录你订阅了 Claude 服务的账号。如果你的使用方式是 API 按量付费，也可以设置ANTHROPIC_API_KEY环境变量，让工具直接用 API Key 认证。
这里有个我第一次跑时卡住的点：授权成功后进入项目目录，Claude Code 会在首次加载时扫描整个项目结构。如果项目很大，比如 node_modules 动辄几十万个文件，它会自动忽略一些常见目录，但还是建议你自己在项目里准备好.gitignore。我见过有朋友第一次跑，终端刷屏了很久，就是在遍历文件。后来我们在项目里补上了标准的忽略规则，再进入就顺畅多了。
进入会话后，你可以直接输入自然语言指令。第一次跑通建议从一个非常小的需求开始，比如“帮我把 README 里过时的安装命令更新成现在这个”。先感受一下它是怎么定位文件、怎么提出修改方案的，再逐步加大任务复杂度。
2.3 核心操作速览
在交互模式里有几个最常用的操作，我列一下：
- 直接输入需求文字，回车发送，Claude Code 会展示它的行动计划。
- 对每次文件修改，它会给出类似 Git diff 的预览，你可以选择接收或拒绝。
/help查看内置命令列表，/status查看当前会话的上下文占用情况。Ctrl+C两次可以退出会话。- 在命令行直接
claude "你的需求"，可以不进入交互模式，一次性执行完直接退出。
这些基础操作没什么难度，但真正影响体验的是后面的高阶用法。
3. 核心工作方式：会话、Agent循环与上下文来源
3.1 会话不是聊天，而是一份工作任务记录
我第一次用的时候犯了个认知错误，把它当成像在聊天软件里追问问题那样用。后来发现 Cluade Code 的会话模型，本质上是“一个任务从开始到结束的完整记录”。你在会话里描述的每一条需求、它做的每一次修改、跑过的每一条命令，都会成为后续决策的上下文。
举个具体例子：你上午让它在会话里重构了一个工具函数，下午又在这个会话里说“把调用它的地方也改掉”，它能准确找到上午改动的位置和签名变化，因为整个历史都在会话上下文里。但如果你新开一个会话再提同样的问题，它就只能靠代码推断，可能找不到上午的改动依据。这一点决定了任务管理的方式：一个会话尽量对应一个完整的任务，而不是随手起一个会话就乱聊。
3.2 “读—改—验”的循环机制
Claude Code 的工作机制可以概括为一个持续循环：先读取相关文件理解现状，再规划需要改动的文件清单，然后动手修改，接着执行测试或语法检查验证，如果验证发现问题就再回到修改环节。这个循环是它区别于所有“对话框式AI”的关键。
为什么这个机制重要？因为它意味着它会为自己的改动负责。比如它给你改了一个函数，你不会拿到一段从未运行过的代码。它会尝试用项目里已有的测试来验证，或者至少跑一下语法检查。我在使用过程中发现，只要项目本身有测试覆盖，它改完代码之后大概率会主动说要跑哪些测试。这个行为习惯如果引导得当，能极大降低“AI改坏了代码你都不知道”的风险。
当然，验证能力取决于你项目里的测试体系。如果项目完全没有测试，它就只能做静态检查，这时候建议你在需求里主动提一句“改完后运行相关的测试文件”，或者让它自己写个最小验证脚本。
3.3 上下文从哪里来，以及如何喂好它
理解了会话机制之后，核心问题就是：它怎么知道我项目里发生了什么？有四个主要来源。
第一是CLAUDE.md文件。放在项目根目录的CLAUDE.md会被自动读取，相当于你写给这个 AI 助手的“项目说明书”。里面可以写项目结构、技术栈、代码风格约定、常用命令，这些信息会被用在每一次会话里。第二是启动时传入的额外指令文件，可以给claude命令指定参数，让它附加读取其他说明文档。第三是工作区扫描，它会主动查看目录结构、读取关键文件来理解项目。第四是会话历史。
这四个来源里，CLAUDE.md的杠杆作用最大。你不用在每次对话里重复背景信息，只要项目根目录有一份写好的说明，所有会话都会自动带上。我后面会专门讲怎么写一份高质量的CLAUDE.md，这里先提一个原则：内容要具体，不要写“代码风格良好”这种废话，要写“组件放在 src/components，业务逻辑放在 src/logic，状态管理统一用 Zustand，跑测试用 pnpm test”。
3.4 权限模式：在自动与确认之间找平衡
Claude Code 可以调用系统命令，比如执行测试、运行构建、甚至修改系统配置。这当然很方便，但也意味着它有能力在你不知情的情况下做很多事情——虽然所有操作都会以 diff 形式展示，但如果你在会话里开了自动接受模式，它就会一口气执行到底。
它提供了几种权限模式：默认模式是每个有风险的操作前请求你的确认；还有一种“自动接受文件修改并执行命令”的模式，适合你非常信任项目环境和任务边界的时候用，但我不建议新手上来就开。我自己的习惯是：日常开发用默认模式，审查每步改动；等处理一个边界明确的机械重构时，比如“统一替换某个工具函数的调用方式”，再短暂开启宽松模式，跑完立刻关掉。
4. 把 Claude Code 嵌入日常工作流的几个实用姿势
4.1 任务开始前，先写“兵粮”：一份实用的 CLAUDE.md
很多人的CLAUDE.md写得跟简历似的，堆了一堆技术栈名词，结果 Claude Code 在关键决策上还是靠猜。我的经验是，一份实用的CLAUDE.md应该是一份“任务说明书”，重点回答四个问题。
项目怎么跑起来？哪种命令是开发环境的启动方式？哪种命令是测试？代码放在哪些目录里，新增代码应该放在哪个位置？有哪些必须遵守的约定，比如某个模块不用再自己写日志、某个公共组件不允许随意改样式？发布流程里有没有容易忽略的步骤？
举个例子，某个后端服务的CLAUDE.md开头我是这么写的：
# 项目说明 # 服务入口在 cmd/server/main.go，新增 HTTP 接口时先到 internal/handler 里看同类写法 # 数据库所有变更必须通过 migrations 目录下的 SQL 文件提交，禁止直接改库 # 启动开发环境用 make dev，跑单测用 go test ./... ，提交前必须保证单测通过这样一份说明放在根目录，后面每个会话都自动带上，任务准确率会有非常明显的提升。有一次我接一个快半年没碰的项目，就是因为根目录有这份文件，我一句“按老规矩实现这个接口”，它就知道要模仿哪个目录下的哪种写法，非常省心。
4.2 “门禁模式”：需求从描述到分支到PR的完整闭环
我在团队内部推过一个做法，我们开玩笑叫“门禁模式”。核心流程是这样的：拿到一个需求后，不要在默认分支上直接干活，而是先让 Claude Code 基于当前分支开出一个新的 feature 分支，然后在这个分支里完成任务，最后让它自己跑测试、提交 commit。这个流程能跑得通，前提是你给它设定好边界，让它在特定分支里自由操作。
实际操作时，我会在会话里先手动建好分支，然后告诉它需求、指定改动范围，并明确要求“所有修改只允许在 src 目录下，不要动配置文件，完成后跑相关测试并提交 commit”。有了这些约束，它就会在分支内独立完成“实施—验证—提交”的闭环。提交信息也是按 conventional commit 格式写的，基本不需要我再修改。
有人可能会问，为什么不直接让它在主分支干活？因为一旦 AI 修改出错，你很难判断哪些改动是它做的、哪些是你自己做的。有了独立分支，随时可以 diff、revert、甚至整个分支扔掉。这是我认为目前最安全的协作方式：任务即分支，AI 在分支内闭环，你只需要审查 diff 和最后的结果。
4.3 用子代理拆分大任务，避免“贪吃蛇效应”
Claude Code 有一种中级用法，把一个大任务拆成多个子代理去处理。比如你要做一个涉及后端接口、前端页面、数据库迁移三部分的完整功能，你可以分别给三个子代理各分配一个职责，每个子代理在独立会话里完成自己的部分，最后再汇总合并。
这么做的好处在于，每个子代理的上下文都专注在自己的子任务上，不会被其他部分的信息干扰。我有一个做全栈项目的好友，他每周有一半的需求是这么完成的：他负责描述整体方案和验收标准，然后告诉 Claude Code 按模块拆分子任务，最后他来做集成测试。他说这样比让一个 AI 会话从头做到尾稳定得多，因为上下文不会越滚越复杂。
这个用法对项目结构的要求比较高，如果模块之间耦合得厉害，拆开容易，合起来难。我建议你先从边界清晰的模块入手，比如“一个独立的工具函数库”或“一个独立的定时任务服务”，不要一上来就拆那种互相依赖很重的核心业务。
4.4 指定模型与工作目录，适配不同场景
Claude Code 支持在会话内用/model切换模型。以我们日常的使用经验来看，更强大的模型适合复杂重构、交叉验证、多文件联调这类高难度任务；轻量模型则适合文档修改、简单脚本生成、模板填充这类重复劳动。这样做的实际价值除了省时间，还能显著降低成本，毕竟复杂模型按量计费的价格要高不少。
如果你想在不进入某个项目目录的情况下让它处理某个目录里的任务，可以直接用--add-dir参数指定额外的工作目录，或者启动后把目录信息写进需求里。这个功能对我的意义在于，我常在两个独立项目之间切换，不需要每次 cd 换目录再重新启动会话，一个会话就能处理两个项目边界不相关的任务。
还有一个小技巧：你可以用/compact命令压缩当前会话的上下文，把前面的历史浓缩成摘要，腾出更多的上下文窗口给新需求。目前来看，考虑到会话上下文空间有上限，大任务做到一半时这个命令是续命的关键。
5. 我踩过的坑与对应处理办法
5.1 坑一：CLAUDE.md第一天就写得太复杂
我最早写CLAUDE.md的时候，为了“全面”，把项目里所有模块的说明、编码规范、目录结构全都写了进去。结果 Claude Code 每次读取都要消耗大量上下文空间，而且有些规则之间互相矛盾，它经常会纠结该听哪一条。
后来我做了减法：第一版只保留最重要的命令和目录约定，随着使用过程中发现它反复出错，再逐步补上对应的规则。现在这份文件稳定在两屏以内。原则是：出现一个错误，才补一条规则，而不是提前把所有可能规则都写进去。
5.2 坑二：一个会话跑太长，效率断崖式下降
这是我踩过最深的一个坑。有一次我让它在同一个会话里连续改了十几个文件，改到后面它开始“遗忘”最早的需求，出现过重复修改、逻辑不一致的情况。查了会话状态才发现，上下文已经快被撑爆了，前面讨论的关键决策被挤出了有效窗口。
处理办法很简单，一个任务一个会话，任务完成就及时收尾。如果任务太大，就主动拆成多个阶段，每阶段结束时让它输出小结，下一阶段基于小结继续。我还养成了定期/compact的习惯，一旦发现它开始“答非所问”或者忘记之前的约定，就先压缩上下文再继续。
5.3 坑三：小改动交给它做，反而更慢
Claude Code 擅长的是需要理解上下文的改写，不是纯机械的小改动。比如“把这个报错提示文案改一下”“把这个变量名换一下”，这种改动自己几秒钟就完成了，让 AI 来做反而要走“扫描项目—产出diff—你审核—它改完—再验证”的完整流程，整体时间更长。
我现在的取舍标准是：改动超过三个文件、或者需要跨模块理解逻辑的任务，才交给它。改一处文案、加一行日志这种，直接手动改掉。这个取舍也符合一个朴素的道理：工具适合做复杂的事，别用它做简单的替换。
5.4 坑四：权限开太宽，AI 擅自改了不该改的东西
有一次我在宽松模式下，让它“把某个工具函数的命名从A改成B并清理相关引用”。结果它不仅改了工具函数和调用处，还顺手把几个无关文件的格式给自动格式化了一遍。diff 里其实能看到这些改动，但改动文件太多的时候，你根本不一定逐个点开。
从那之后我坚持：涉及批量替换和重构时，先明确告之“只许碰哪些目录，不许改哪些文件”，并且保持默认的逐项确认模式。AI 的执行力越强，你对边界的定义就要越清晰。
5.5 坑五：并行会话操作同一批文件，互相打架
我一度为了提效，同时开了两个会话处理同一个项目，一个改路由，一个改数据库模型。结果两个会话都按自己的想法改了同一个公共文件，合并的时候冲突惨烈，最后只能手动挑着改。
后来我规定：每个项目同一时间只允许一个会话动手改代码，多个会话只能一个负责改，另一个只做读操作（比如查代码、给方案）。如果你想并行，那就拆成完全不同的目录或模块，确保文件交集为零。
6. 用了一段时间后，我的个人体会
这套工具用了大概两个多月，最大的感受是：编程这个活儿，正在从“亲手写每一行代码”变成“定义意图、审查变更、把控方向”。这个转变对老手而言需要一段适应期，因为习惯了亲手把每个细节敲出来，突然让你放手去审核别人的产出，会有些不安。但多试几次你会发现，项目里那些真正费精力的重复劳动，是可以被可靠地外包出去的。
我特别想给新人一个建议：不要一上来就让 Claude Code 帮你写一个完整微服务，而是先挑三五个小任务，完整走一遍“描述—它扫描—它改—你审核—跑测试—合并”的流程。这个流程走顺了，你才能建立对它的信任体系，知道它在什么情况下可靠、什么情况下需要你多盯一下。
还有一个小习惯值得养成：每次它完成一个任务后，你可以多问一句“你是怎么定位到这些文件的”，让它把决策链路展开。这既是学习别人代码的捷径，也能帮你判断它是真的理解了项目，还是在瞎猜。有一次我就是通过这种方式发现它把一个重复代码段理解错了，避免了错误上线。
如果你准备认真使用 Claude Code，我的最终建议是：从一份精简的CLAUDE.md开始，从小的、边界清晰的任务开始，从默认的确认模式开始，这三点能让你的体验上一个台阶。至于那些更高级的玩法，等你和它磨合出了默契，自然就会去探索了。
