Claude Code 上手笔记：终端里的 AI 编程 Agent 实战指南

第一次听说 Claude Code 的时候我内心是拒绝的。当时我用 AI 编程工具已经挺顺手了网页里聊一下、把代码复制回来、贴回编辑器流程虽然烦但也能跑。直到有一次要同时改五六个文件的小需求我彻底被来回粘贴上下文搞烦了于是在终端里试了一下claude。这一试才意识到命令行才是 AI 编程最顺的位置。这篇内容就当作我的上手笔记你可以照着它一步步走哪怕只会cd和ls也能在真实项目里让 Claude Code 帮你找代码、改代码、跑测试、查报错而不是把它当成一个高级聊天框。1. 先搞清楚它和网页版聊天的本质区别一个能动手的 Agent 和只能动嘴的问答很多人第一次打开 Claude Code 之后会问这不就是个命令行版 ChatGPT 吗我打字它回话比网页版还难用。这个误解很正常因为它们看起来确实很像但底层逻辑完全不同。网页版 AI 的本质是“问答”你给我信息我给你答案而 Claude Code 的本质是“执行”它拿到你的目标后会自己决定看哪些文件、改哪些代码、跑哪条命令然后一步步把任务做完。这个差别决定了你该在什么时候用它、怎么用它。1.1 三种 AI 编程入口的定位差异我见过不少人把 AI 编程工具分成三类网页问答、IDE 插件、终端 Agent。三者各有适用场景但很多人只用了前两者就一直以为 AI 编程的体验天花板就是“生成一段代码让我粘贴”。入口上下文获取方式能做的事适合什么时候网页问答手动粘贴代码、描述需求生成代码片段、解释概念概念咨询、单文件 DemoIDE 插件依托当前打开文件、编辑器选中内容补全、改写当前文件、局部重构手写代码时的即时辅助Claude Code主动浏览项目目录、读取文件内容增删改文件、执行命令、跑测试、查日志跨多文件需求、重构、排查问题你注意最后一行里的两个词主动浏览和执行命令。这是 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 以这个身份去调用大模型。这两者的计费模式和适用场景差别很大我建议新手一开始就想清楚自己属于哪种情况身份类型计费方式适合谁注意点Claude 订阅账号订阅费固定按使用范围限制个人日常高频使用登录流程最简单不需要管理密钥API Key按 token 量计费偶尔使用、想精确控费、做自动化脚本密钥要妥善保管费用和上下文长度强相关如果你选择 API Key 方式最常见的配置方法是在 shell 环境变量里设置export ANTHROPIC_API_KEYsk-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 塞进脚本和 CIClaude 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 助手了。不是因为它短时间变得多聪明而是因为它真的住进了项目目录里替我把那些繁琐的查找、确认、修改、验证动作都做了。希望这份上手笔记也能让你少走一点弯路。