第一次听说 Claude Code 的时候，我内心是拒绝的。当时我用 AI 编程工具已经挺顺手了，网页里聊一下、把代码复制回来、贴回编辑器，流程虽然烦，但也能跑。直到有一次要同时改五六个文件的小需求，我彻底被来回粘贴上下文搞烦了，于是在终端里试了一下claude。这一试，才意识到命令行才是 AI 编程最顺的位置。这篇内容就当作我的上手笔记，你可以照着它一步步走，哪怕只会cd和ls，也能在真实项目里让 Claude Code 帮你找代码、改代码、跑测试、查报错，而不是把它当成一个高级聊天框。

1. 先搞清楚它和网页版聊天的本质区别：一个能动手的 Agent 和只能动嘴的问答

很多人第一次打开 Claude Code 之后会问：这不就是个命令行版 ChatGPT 吗？我打字它回话，比网页版还难用。这个误解很正常，因为它们看起来确实很像，但底层逻辑完全不同。网页版 AI 的本质是“问答”，你给我信息，我给你答案；而 Claude Code 的本质是“执行”，它拿到你的目标后，会自己决定看哪些文件、改哪些代码、跑哪条命令，然后一步步把任务做完。这个差别决定了你该在什么时候用它、怎么用它。

1.1 三种 AI 编程入口的定位差异

我见过不少人把 AI 编程工具分成三类：网页问答、IDE 插件、终端 Agent。三者各有适用场景，但很多人只用了前两者，就一直以为 AI 编程的体验天花板就是“生成一段代码让我粘贴”。

你注意最后一行里的两个词：主动浏览和执行命令。这是 Claude Code 和另外两种工具之间最关键的分水岭。网页问答永远只能基于你愿意贴给它的信息去判断，你少贴一个文件，它就少知道一截上下文；而你贴得太多，对话本身又会变得臃肿。Claude Code 不一样，它默认就运行在你的项目目录里，可以通过工具自己去看目录结构、读package.json、查某个函数的定义，还能直接帮你跑npm test。信息获取成本一下子从“人肉搬运”变成了“自己动手”。

1.2 它的工作循环：像一位站在你电脑前的实习生

Claude Code 的核心不是一个巨大的提示词，而是一套 Agent 循环。拆开看大概是这个流程：先确认任务，然后浏览项目相关文件，形成修改方案，调用工具执行修改，最后运行测试或命令来验证结果。如果验证失败，它会读报错信息，继续修正，直到任务完成或者你叫停。

它手里有几个非常朴素的工具：Read读文件、Edit改文件、Write新建文件、Bash执行命令、Grep搜索文本、Glob查文件路径。

很多人第一次看到它列出“将要修改哪个文件、将要运行哪条命令”时，会有点不适应，因为它有点像一位站在你电脑前的实习生，每走一步都汇报一下自己的动作。这个汇报机制不是话多，而是一种权限确认：它不会在你看不到的地方偷偷执行高危操作。建议你从一开始就习惯它的这种节奏，而不是试图跳过确认让它“全自动”。

2. 安装流程里的几个分岔路：登录方式与环境变量不要选错

安装第一步并不难，难的是环境准备和身份验证。我在几个群里看到新手的问题，十个里面有七个不是卡在安装命令，而是卡在“我明明装好了，为什么 claude 命令用不了”或者“登录方式和 API Key 到底哪个对”。这里我把容易出错的地方一次说清楚。

2.1 前置检查和安装命令

Claude Code 依赖 Node.js 环境，官方早期的版本要求 Node.js 18 及以上。安装之前先在终端检查一下自己的 Node 版本：

node -v npm -v

如果你已经装了 Node.js 但版本偏旧，建议先升级到当前 LTS 版本再继续。完全没有 Node 的话，去官网下载对应系统的安装包即可，安装完之后重新开一个终端窗口，再执行下面的命令：

npm install -g @anthropic-ai/claude-code

安装完成后，验证一下：

claude --version

只要这条命令能正常输出版本号，就说明安装没问题。如果claude提示命令不存在，多半是 npm 的全局安装目录不在系统 PATH 里。macOS/Linux 下可以直接看 npm 安装路径并把它加进 shell 配置；Windows 用户遇到这种问题，优先检查是不是没有用管理员权限打开终端。

2.2 两种身份：订阅登录和 API Key 不要选混

第一次运行claude，它会进入登录流程，这里有两类选择。一类是使用 Claude 的订阅账号直接授权登录，类似 OAuth，登录一次之后终端里就能正常使用。另一类是使用 API Key，把密钥通过环境变量配好，然后让 Claude Code 以这个身份去调用大模型。

这两者的计费模式和适用场景差别很大，我建议新手一开始就想清楚自己属于哪种情况：

如果你选择 API Key 方式，最常见的配置方法是在 shell 环境变量里设置：

export ANTHROPIC_API_KEY="sk-ant-你的密钥"

注意：不要为了省事把这个 export 写进项目里的.env文件，更不要在对话里直接把密钥发给 Claude。我在真实项目里的习惯是把它写进 shell 的配置文件，比如~/.bashrc或~/.zshrc，然后source一下。这样既不影响项目仓库的干净，也不会因为多人协作出现在代码库中。

3. 第一次实战：让它自己探索项目，再动手加一个 CSV 导出接口

安装完成后，你就站在了“从 0 到 1”的中间点：工具能跑起来，但离“上手”还差一次完整的实战。我的建议是不要第一次就在重要项目上试，先找一个你熟悉的中小型项目，按下面的流程走一遍，你就知道 Claude Code 平时到底是怎么工作的了。

3.1 进入项目后先做一次“项目体检”

很多人的第一反应是进入项目目录，直接输入“帮我加一个导出功能”。这个做法不是不行，但你会发现它给出的方案往往很泛，甚至会猜错目录结构。原因是模型虽然能看文件，但它在没有主动探索之前，对项目的了解程度并不比你多多少。

我习惯的第一步是让它先读项目，但明确告诉它“先别改代码”。比如进入项目目录后运行claude，然后输入：

先不要改代码。浏览一下当前项目的目录结构，看看 package.json 里的脚本和依赖，给我一份简短的说明：这是什么项目、核心模块在哪、测试怎么跑。

这一步有两个作用：第一，让 Claude 进入“探索模式”，把关键文件读进上下文；第二，你会看到它主动调用 Grep、Glob 这类工具去查目录，而不是凭空猜测。等它输出项目概览之后，你再让它做下一步。用了这个前置步骤之后，后面所有修改都会准确很多，基本不会出现在完全无关的文件里瞎改的情况。

在项目概览确认无误后，我会顺手做一件事：运行/init命令。它会根据当前项目结构生成一份CLAUDE.md文件，里面记录项目常用命令、代码风格、模块职责等约定。这份文件以后每次启动 Claude Code 都会自动加载，相当于给 AI 建立了一份项目说明书。如果你的项目目录里已经有人维护过CLAUDE.md，那 AI 在一开始就会对项目有更准确的把握。

3.2 从零加一个接口：我通常这样提问

下面我用一个很常见的后端场景举例：项目里已经有一个用户模块，能查用户列表，现在需要新增一个导出 CSV 的接口。假设项目结构大体上有 controller 层、service 层和路由注册文件。

我进入项目之后会这样描述任务：

这个项目已经有一个用户模块，我需要新增 GET /api/users/export 接口，把用户列表导出成 CSV。你先进入计划模式，告诉我：要改哪些文件、需要装哪些依赖、接口返回值怎么设计。等我说开始再动手。

注意这句话里有几个关键设计：先说已有模块，给 AI 一个锚点；然后明确接口路径和业务目标；再要求先进入计划模式；最后强调“等我说开始再动手”。这样做的目的是从一开始就把“规划”和“动手”分开，避免它上来就大刀阔斧乱改。

在 Claude Code 里可以用/plan进入计划模式。它会根据探索到的项目结构，给出一个改动方案，比如“在 UserController 中新增 export 方法、在 UserService 中补充导出逻辑、在路由文件中注册新路径、可能需要引入 csv 库”。你看到方案之后可以继续追问细节：“controller 里返回的是文件流还是 JSON 字符串？”“CSV 列名怎么定义？”等确认无误后，再退出计划模式，让它开始执行。

执行阶段你会看到它一个个调用工具：读 controller、读 service、修改文件、安装依赖、补测试。它会主动停下来问你是否允许运行某条安装命令。我个人对这个阶段的经验是：小改动可以放心允许，但每次它改完文件，你都至少扫一眼 diff 再放行下一步。你坐在它旁边不是仪式感，而是在给它的决策把关。

4. 权限边界就是安全线：允许什么、拒绝什么，都要先想清楚

提到“允许”，就必须展开讲讲 Claude Code 的权限模型。这是它跟网页版 AI 最大的差异点，也是新手最容易忽略、也最容易踩坑的地方。它既然能执行命令、能修改文件，那它到底什么能做什么不能做？默认规则是什么？如果你不搞懂这个，很快会陷入两个极端：要么每步都紧张地点头，要么干脆用什么跳过权限的方式裸奔。

4.1 Claude Code 默认怎么判断能不能做

Claude Code 在默认情况下是有一套保守策略的：读取文件这类只读操作，通常可以直接执行；但涉及修改文件、运行命令，它会在执行前弹出确认请求，等你选择允许还是拒绝。你可以每次单独确认，也可以针对某类命令在本会话内记住选择。

这个默认行为背后是设计者刻意留出的“人机协作空间”。如果它什么都直接做，那它就是一把高速运转的锄头，效率高但很容易挖到水管；如果它什么都要反复确认，那它又失去了 Agent 的价值。所以默认策略把“看”放开，把“动”收紧。你允许得越多，它效率越高；你限制得越严格，它越稳妥。

在会话里输入/permissions，可以查看和管理当前的授权状态。它会列出本次会话里允许过哪些工具、被拒绝过哪些操作，你也可以在这里直接编辑权限规则，不用去翻配置文件。

4.2 用配置文件固化规则

适合个人开发者的做法，是给项目写一个.claude/settings.json，把常用操作固定下来。比如项目主要是 Node.js 写测试，可以这样配置：

{ "permissions": { "allow": [ "Read", "Glob", "Grep", "Bash(npm test:*)" ], "deny": [ "Bash(git push:*)", "Bash(rm -rf:*)" ] } }

这个文件里的allow就是白名单，deny就是黑名单。命中deny的操作会直接拒绝，这是比allow更高的优先级。上面这份配置的意思是：允许读取和搜索文件、允许运行以npm test开头的命令，但禁止它推送代码、禁止递归删目录。这样既保留了它的自主性，又挡住了那些体积小但破坏力极大的操作。

我为什么会把git push放进禁止列表？因为 AI 的修改需要经过你 review 之后才能进入远程分支，这是一个基本工程纪律。Claude Code 自己也很清楚这一点，但你在配置里显式表达这个边界，会让它在执行阶段主动绕过 push 相关操作，而不是停下来问你“要不要推远程”，省掉很多无意义的打断。

4.3 别随便碰这个开关：--dangerously-skip-permissions

有些教程为了让新手少点确认，会推荐启动时加一个参数，比如--dangerously-skip-permissions。名字里已经带 “dangerously” 了，我的态度很明确：不要在真实项目里全局使用它。它适合的场景是 CI 环境里、运行完全可复现的脚本任务时，并且你对命令内容和项目状态有完全把握。日常开发中一旦全局跳过权限，AI 就有了直接改文件、直接装包、直接跑命令的全部能力，风险完全暴露。

如果你确实想要更顺畅的体验，又不想承担这个风险，正确路径是像我上面那样配置白名单。让可信任的只读操作和测试命令放行，把不可逆操作留在确认区。这样既顺畅，又不会在关键时刻失去最后一道人肉防线。

5. 进阶场景：读陌生仓库和分批重构的正确打开方式

基础工作流熟悉之后，Claude Code 真正让人上头的其实不是“加接口”这类实现需求，而是它帮你理解陌生仓库和做大范围重构的能力。这两个场景下，如果你只是简单地把任务丢给它，很容易翻车。下面是我踩过几次坑之后整理出来的用法。

5.1 让 Claude 当你的代码库讲解员

接手一个新项目或者调研一个开源仓库时，人的第一反应是从入口文件开始硬读。这个效率极低，尤其是仓库大了以后，读十几个文件可能还没理清主要链路。Claude Code 在这个场景下有天然优势：它可以快速遍历文件、搜索关键字、跟踪调用关系。

但如果你问它“这个项目是干什么的”，它会给你一份非常长的报告，信息密度低到你根本看不完。我试过更好的提示词是给它限定输出范围和时间线：

不要改代码。从入口文件开始，帮我梳理登录模块的完整调用链，说明每一层的职责。用文字描述整体流程，不要贴大段代码，控制在几百字以内。

“不要贴大段代码”“控制在几百字以内”这两个约束很重要。Claude Code 的输出默认不会像网页版那样长篇大论，但有时为了表达准确，它会忍不住贴代码片段。你明确要求它省略代码、只讲链路和职责，它会输出一份适合人类快速消费的技术摘要。拿到这份摘要之后，你再挑个别节点让它深入解释，效率远高于自己看源码。

5.2 重构的正确姿势：先计划、后小步执行

很多人让 Claude 做重构时会这样说：“帮我把这个项目的登录模块重构一下。”这句话的歧义太大了，AI 可能直接把整个模块的写法都改了，你 review 的时候根本不知道从哪里看起。我的经验是，重构任务一定要拆小，并且明确约束条件。

我一般会给出这种提示：

把 SchedulingService 里的日期比较逻辑抽成一个独立工具函数，放到 src/utils/date.ts 里，保持外部行为不变。改完先跑现有测试，再列出所有受影响的文件。不要做额外重构，不要改接口签名。

这段提示里最有价值的部分是最后两句：保持外部行为不变、不要做额外重构。Claude Code 有很强的“顺手优化”冲动，如果不禁锢它，它很可能在抽函数的同时把命名、格式、日志也一起改了。那你 review 的难度就会指数级上升。拆分小步、锁定范围、每步跑测试，才能让重构真正做到可审查、可回退。

5.3 子代理和并行研究

新版 Claude Code 里有一个 Task 工具，可以把它理解为“子代理”。主对话可以派生多个子代理，让每个子代理分别去研究一个模块、或者分别验证一个问题，然后再把结果汇总回来。

比如一个比较大的项目要梳理某个核心功能，我会这样用：让它派三个子代理，一个看前端调用链，一个看后端接口，一个看数据库相关代码，最后汇总成一个整体流程说明。这种方式在大仓库里非常省时间。但需要注意，子代理并行会明显增加 token 消耗，所以不要一上来就开五个任务，先定义一个足够清晰的拆解边界，控制在一个或两个子代理，跑通之后再加大并行度。

6. 容易被忽略的过程成本：上下文、脚本化与安全习惯

上手 Claude Code 之后，容易陷入另一种状态：只要遇到代码问题，就打开终端跟它对话。对话本身很爽，但你可能还没注意到，背后有两个容易被忽略的成本问题：一个是 token 消耗，一个是用它做自动化的边界。这两个问题不搞清楚，你可能在某次操作之后发现自己承担了不必要的开销。

6.1 上下文膨胀：钱和“记性”都是这么丢的

Claude Code 在多轮对话里，会把之前的对话历史作为上下文一遍遍发送给模型，越聊到后面，消耗越大。你让它读了十个文件，后面每轮对话重新计算时，这十个文件的内容都会占用上下文空间。结果是两个问题同时出现：费用变高、模型对最重要的信息反而可能“记不清”。

我控制上下文有几个习惯。第一，每个独立任务开一个新会话，不让上一个任务的垃圾信息污染下一次工作。第二，当会话开始明显变慢或者记忆变差时，输入/compact压缩历史，让 AI 把关键信息重新组织成更短的摘要。第三，用/cost查看当前会话的 token 花费。第四，也是很重要的一条：让它用 Grep 去搜索文件，而不是每次都 Read 整个大文件。比如一个几十 MB 的日志文件，直接读进来既不必要又烧钱，用搜索工具定位关键行才是正确姿势。

6.2 无头模式：把 Claude Code 塞进脚本和 CI

Claude Code 提供了无头模式，也就是不用进入交互界面，直接通过命令行带参数执行任务。基础用法类似这样：

claude -p "运行 test 目录下失败的用例，分析原因并给出修复建议" --output-format json

-p后面接 prompt，--output-format json让输出变成 JSON 结构，方便后续脚本处理。这种模式特别适合做成代码提交前的检查脚本、定时任务或者 CI 流水线里的一环。我见过有人把它接进提交前钩子，让它自动跑测试并提示风险，效果不错。

但这里有个很现实的坑：无头模式下，如果它执行某些命令时默认需要确认，而你没有任何权限配置，任务就会卡在那里等一个永远不来的用户输入。所以在用无头模式之前，一定要先通过.claude/settings.json把该允许的只读和测试操作放行，再在 prompt 里提示它“不要执行需要额外确认的高风险命令”。不然脚本跑起来会静默挂住。

6.3 项目里的安全习惯

我说的安全不仅指命令风险，也包括信息风险。不要在你的CLAUDE.md里写 API 密钥、内网地址、数据库密码之类的内容，因为这份文件是要被模型读取的。同样地，不要在对话里把我方的敏感配置贴给它，哪怕只是测试环境，也应该保持信息的整洁。密钥走环境变量，这是基本习惯。

另一方面，在命令行层面，我会始终保持一个原则：不可逆操作必须人工确认。git push --force、rm -rf、批量删除文件、直接操作生产环境的命令，都属于这类。即使某些命令在 mine 配置里被 deny 了，我也会在每次新建大型任务之前补一句“不要执行任何删除或强制推送类命令”。多一道提示，不费事，但能让意外概率降低一个量级。

7. 用了一段时间后，我最想告诉新手的几件事

7.1 我的工作流发生了什么变化

真正高频使用之后，我的写代码流程变成了这样：先想清楚功能边界，然后打开 Claude Code，让它读相关模块，给我计划；确认计划后让它动手，我负责看 diff 和跑测试。之前大量用于复制粘贴、上下文整理的时间基本被节省下来了。最直观的感受是，它像一个做事特别主动的实习生，不是等我把代码喂到嘴边，而是自己去项目里翻答案。

7.2 给新手的几条具体建议

第一条，每次开始新功能之前，先/clear开场新会话。不要贪恋旧上下文，拖累速度也拖累费用。第二条，早一点用/init生成CLAUDE.md，把项目约定固化进去，后面每次会话都受益。第三条，关键操作永远留在人工确认这一步，不要用跳过权限参数换一时的痛快。第四条，如果一次任务改动的文件超过五六个，中途一定要让它停下来给你看变更清单，别等它一气呵成之后才知道它动了哪些地方。

第一次在终端里打出claude的几周后，我已经很少打开之前常用的网页版 AI 助手了。不是因为它短时间变得多聪明，而是因为它真的住进了项目目录里，替我把那些繁琐的查找、确认、修改、验证动作都做了。希望这份上手笔记，也能让你少走一点弯路。