Claude Code 使用指南

0030 秒速览：三句话 + 按你的处境直接选

这一节不是目录。它给你三个结论、一张"我现在该看哪节"的对照表，和一条今天就能走完的上手路径。剩下的篇幅都在解释这三句话为什么成立。

按你的处境，直接用这个

一条可执行的上手路径

01它到底是什么？（先破三个错想）

官方对它的定义只有一句：an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools——一个会读你的代码库（代码库 = 你这个项目的全部代码文件）、改文件、跑命令、并且接进你现有开发工具的"编程代理"。把它翻成人话的难点不在"编程"，而在代理这两个字。

先破三个错想

一句话版本：它是什么

它是一个跑在你终端里的编程代理。"终端"就是你敲文字命令操作电脑的那个黑框窗口（macOS 的 Terminal、Windows 的 PowerShell 都算）；如果你从没用过终端，官方专门写了一篇给新手的终端入门，本文后面每个命令都会写清楚在哪儿敲。

它和你之间是一次分工：你负责"要什么"和"这样对不对"，它负责"翻代码、动手改、跑一遍验证、把改动整理给你看"。整篇文章其实都在讲这条分工线画在哪里。

机制：它凭什么能"自己动手"

它没有魔法，靠的是三件普通的事：

• 它有一个工具箱——读文件、搜代码、改文件、执行命令、查网页之类的动作，各自是一个"工具"。它每走一步，就是挑一个工具来用。
• 它的每一步都要过一次闸——用哪个工具、为什么用，都摆在你面前（或摆给一个"审查模型"看，见 07）。这就是权限模式存在的原因。
• 它的记忆分两种——一种是你写给它的项目规矩（CLAUDE.md），一种是它自己攒的笔记（自动记忆）。两种都是"每次开新会话重新读一遍"，所以它并不是"记得你"，而是"每次都被重新告知"（见 09）。

它和 ChatGPT、Copilot 差在哪

它能碰到你项目里的哪些文件？

默认只碰你启动它时所在的那个目录，以及它下面的所有子目录。想让它在别处也动手，有两种办法：启动时加 --add-dir 路径，或者会话里敲 /add-dir 路径 临时补一个。这个默认值的用意很直白：别让它顺手改到你没打算让它碰的地方。

注意一个容易忽略的边界：官方文档明确说，从"补加进来的目录"里不会自动发现那套 .claude/ 配置（也就是权限规则、技能等）。所以补加目录只是"开了文件访问权"，不是"把它当一个新项目接进来"。

它在哪几个界面里能跑？

同一套引擎，多个门面。你在终端里配好的项目规矩、权限规则、外部工具连接，换到别的界面照样生效——因为它们读的是同一批配置文件。

官方还提供了 Chrome 扩展、Slack 集成、Remote Control（把本地会话转到另一台设备继续）等入口。记住一句就够：登录门槛按用户算，配置按目录算，所以换界面不用重配。绝大多数界面需要一份付费订阅或一个按量计费的 Console（API）账户——免费套餐不含 Claude Code。

02它到底替你省了哪一段活？

先说结论：它省掉的不是"写代码"那几分钟，而是一次改动从头到尾中间那一整段搬运和试错——找文件、对齐路径、装依赖、跑一遍、复制粘贴报错、再来一遍。

省掉的到底是哪一段

不是为了省打字，是为了省切换。每在"聊天窗口 → 编辑器 → 终端 → 浏览器"之间跳一次，你就丢一次上下文：刚才那段代码对应哪个文件、报错信息里说的是哪一行、上一次改完有没有真的跑过。它的价值就在这条链路上——把四个窗口收进一个会话，并且每一步都留下可回看的痕迹。

哪些活交给它最划算

哪些活别交给它

• 碰密钥和生产数据——不是因为它一定会做错，而是这类操作出错之后你没法"回退一下"。
• 需要多人对齐的架构决策——它能给你三个方案和各自的代价，但决定该由你们团队做。
• "你还没搞懂就让它反复重试"的活——先自己读一遍报错，往往比再试十次快。
• 你无法验证结果的活——它能给你一段你没能力判断对错的代码，那比没给更危险。

它不替你承担的那一件事

它不替你负责"这个改动对不对"。它写的每一条"我修好了"都是一个待验证的声称，不是一个已成立的结论。所以本文后面反复出现同一个动作：放行前看 diff。这不是不信任它，而是这类工具的固有分工——它有速度，你有判断。

03什么场景该用它、什么时候别用？

这一节回答一个具体的取舍：什么活值得交给它。判断标准只有一条——这件事有没有"我一眼能验的验收标准"。（该从哪个界面进，见 01 的界面表。）

一张"该不该用"的判断表

什么时候它反而不划算

• 改动只有一行，而且你比它清楚——描述给它的时间比你自己改还长。
• 涉及你必须亲身判断的取舍（比如"这个需求到底要不要做"）——它只能给你选项，不能给你立场。
• 你对结果完全没有验证能力——这类活你应该先学，而不是先外包。
• 网络不通——它的推理发生在云端，断网就用不了。它不是本地软件。

04怎么把它装到你机器上？

四条安装路线，任选一条。它们的区别只在"谁来管更新"和"你习惯用哪个包管理器"，装出来的是同一套东西。

装之前先确认三件事

• 系统：macOS 13.0 以上 / Windows 10 1809 以上（或 Windows Server 2019 以上）/ Ubuntu 20.04 以上 / Debian 10 以上 / Alpine Linux 3.19 以上。Intel 和 Apple 芯片、以及 ARM 架构都支持。
• 硬件与网络：至少 4 GB 内存，x64 或 ARM64 处理器，必须能联网——它的推理在云端完成。
• 账户：需要一份付费订阅（Pro / Max / Team / Enterprise），或者一个按量计费的 Console（API）账户。免费套餐不含 Claude Code（官方套餐对照表里 Claude Code 一栏，Free 是 No，其余都是 Yes）。

需要先装 Node.js 吗？

四条路线，任选一条

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
# Windows CMD（如果你在 CMD 里，不是 PowerShell）
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

# stable 通道：约比官方慢一周，会跳过有严重问题的版本
brew install --cask claude-code
# latest 通道：新版本第一时间就有
brew install --cask claude-code@latest

winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode   # 升级

# npm（需要 Node.js 22+，装的是原生程序，不用 sudo）
npm install -g @anthropic-ai/claude-code
# Debian / Ubuntu 用 apt（要按官方文档先配好签名仓库）
sudo apt install claude-code

装完怎么确认装对了

claude --version
# 会打印类似：2.1.269 (Claude Code)
claude doctor
# 只读的体检：检查安装、设置文件、登录状态；有问题会给出具体修复建议

--version 是"只打印版本号然后退出"的开关。本文校对时官方最新版是 2.1.269，稳定通道是 2.1.236——版本号只用来对账，不用背。

怎么升级、怎么切通道

stable 和 latest 是两条发布通道：stable 大约比官方慢一周，会跳过有严重问题的版本；latest 是第一时间拿到新功能。原生安装在设置里（敲 /config）可以切通道；brew 靠包名区分（claude-code 是 stable，claude-code@latest 是 latest）。

想让 brew / winget 这类"本来不自动更新"的安装也自动升，可以设一个环境变量 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1（环境变量就是你在终端里预先设定的一个值，程序启动时自己去读）。

登录账户

# 第一次运行 claude，它会引导你在浏览器里登录（推荐）
claude
# 或者你已经有 API Key，先设好环境变量再运行
export ANTHROPIC_API_KEY="sk-ant-..."

如果你设过 ANTHROPIC_API_KEY（Console 账户的密钥），它会跳过浏览器登录，改成问你"要不要用这个 Key"。要留意一件事：订阅套餐的额度和按量计费的 API 账单是两套独立的账，互不抵扣。

• 会话里想换账户：/login；登出：/logout。
• 不想进会话：claude auth login、claude auth status。
• 企业环境还支持 Amazon Bedrock、Google Cloud、Microsoft Foundry 这类入口，本文不展开。

装完就卡住的三个常见情况

怎么卸干净

# 原生安装：删掉命令和版本目录
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude
# 或者用包管理器卸
brew uninstall --cask claude-code        # 装的是 latest 就用 claude-code@latest
winget uninstall Anthropic.ClaudeCode
npm uninstall -g @anthropic-ai/claude-code

05最小例子：让它完成第一个任务

装好并登录之后，用一件结果看得见的小事把整条链路验证一遍。全程大概一分钟、三步。

第一步：进一个不重要的目录，启动它

先在随便哪个目录里练，别一上来就在你在意的仓库上试。复制一个小项目、或者新建一个空目录都行：

# 打开终端，进入你的练习目录
cd ~/my-test-project
# 启动交互式会话（第一次会引导你登录）
claude

cd 是"进入某个目录"的命令，~ 代表你的个人主目录。敲完 claude 后，提示符会变成它的输入框，之后你说的话就是给它的指令。

第二步：下一句"结果能验证"的指令

# 例一：让它补一行注释，并要求它总结改了什么
在 index.js 的 add 函数里补一行注释说明它的用途，然后总结你的改动
# 例二：验证它真的能读你的代码
这个项目依赖了哪些第三方库？分别用在哪里？

第一次跑通，你会看到它按顺序做四件事：读文件 → 思考 → 改文件 → 汇报。改之前它通常会停下来问你一句"要不要允许"——那个弹窗就是权限模式，见 07。你要看的是它给出的改动对照：哪一行删了、哪一行加了。

第三步（可选）：试试"无人值守"的跑法

如果你想把 Claude Code 接进脚本或流水线，用 -p 参数跑一次性任务：回答完就退出，不会停下来跟你互动。-p 是 print 的缩写。

claude -p "解释一下 package.json 里 scripts 这一段是干什么的"
# 用管道把别的命令的输出喂给它（管道符号 | 的意思是"把左边命令的输出，当作右边命令的输入"）
cat src/app.js | claude -p "指出这段代码可能抛异常的地方"

这种跑法适合自动化：一次请求、用完就退，通常也比长会话省用量。更多用法在 15。

第一次跑不顺利？对照这几条

06怎么跟它说话，它才不跑偏？

它不读心。它判断"做完了没有"的唯一依据，是你给的验收标准。同一件事，两种说法出来的结果差别巨大。

为什么差别这么大？因为它一次只消化一两个小步时，每一步都能自己验证，出错范围也小；而"加个后台"这种目标，它只能自己猜边界，猜错你还得从头解释。你的改动对照也会更好审。

一个"贴报错"的模板（照填就行）

遇到报错时别只甩一句"程序坏了"。报错信息本身就是最好的线索，把它原样贴进去：

# 目标：让用户注册接口在邮箱格式错误时返回友好提示，而不是 500。
# 报错（原样贴）：
TypeError: Cannot read properties of undefined (reading 'match')
    at validateEmail (src/api/register.js:23:14)
# 我试过：把注册请求发到 /api/register 就能复现，别的接口正常。
# 请：先讲清楚根因，给最小改动方案，我确认后再动手，改完跑相关测试。

这段话里每一行都在替它省事：目标给它验收标准，原样的报错给它文件与行号，我试过帮它排除你已经走过的弯路，请那一段规定了它的动作顺序（先说原因、再改、最后验证）。

把上下文喂准：用 @ 指名文件

在消息里写 @文件路径，等于明确告诉它"先看这个文件"。比让它自己满仓库找更准，也更省用量。

@src/components/Button.tsx 帮我把它改成用 Tailwind 实现
@src/lib/auth.ts 修复这里在 token 过期时不报错的 bug

会话里的"纠错三件套"

它给的答案你要怎么听

它汇报时常见的三类措辞，含义不同，别混：

07它会不会乱动我的东西？

它真的会跑命令、真的会改文件，所以官方给它设计了一道闸：权限模式——决定"哪些动作不用问你就能做"。默认档位是每一步都问。会话里按 Shift+Tab 循环切换，或者启动时用 claude --permission-mode 模式名 指定。

六种模式，各自放开什么

plan 模式：先出方案，你审完它再动手

涉及多个文件的大改动，先让它"只调研不动手"。三种进法：会话里按 Shift+Tab 切到 plan、单条消息用 /plan 开头、启动时加 --permission-mode plan。它调研完会给你一份方案，你在方案上选：

• 采用方案，开始改——可以顺手切到 auto，让它一口气做完。
• 不采用，继续规划——告诉它哪里不对，让它出第二版。

按 Ctrl+G 可以把方案拉进你自己的编辑器直接改文字。这是"大改之前先对齐"最省事的一个习惯。

auto 模式：让另一个模型替你把关

Pro / Max / Team 套餐的新会话默认就是 auto：大部分命令不再弹窗，改由一个独立的分类器（classifier，就是一个专门判断"这个动作危不危险"的小模型）逐条裁决。官方列出的默认拦截项包括：下载并直接执行代码（比如 curl | bash）、把敏感数据发到外部、生产环境部署与数据迁移、云端批量删除、授予权限、强制推送、以及删除本次会话开始前就已存在的文件。

注意这里有个容易误解的地方：它信任的是"会话启动那一刻"的工作目录和 git 远程仓库。会话进行中你新加的、或者改指向的远程仓库，它不信任，会按"外部"处理。

再给它立几条"铁规矩"

除了模式，你还能在 .claude/settings.json 里写具体规则。这个文件是项目的配置文件，用的是 JSON 格式（一种用花括号和引号表达数据的写法）。规则优先于模式：deny 里的东西任何模式都拦得住（包括 bypassPermissions），ask 里的东西一定弹窗问你。

// .claude/settings.json
{
  "permissions": {
    "allow": ["Bash(npm test)", "Bash(npm run lint)"],
    "ask":   ["Bash(git push *)"],
    "deny":  ["Bash(rm -rf *)", "Bash(git reset --hard)"]
  }
}

这段的意思是：跑测试和 lint 免问；git push 一律先问；rm -rf（递归强删）和 git reset --hard（丢弃未提交改动）直接禁止。会话里敲 /permissions 可以看全部规则，也能看到最近被分类器拦下的操作——如果发现是误拦，可以在那里手动重放一次并把它加进 allow。

新手推荐的起步组合

08命令那么多，我该记住哪几个？

命令分两类：在终端里敲的（启动它、给它参数），和在会话里敲的（以斜杠 / 开头）。下面把真正高频的挑出来，其余随时用 /help 看全量——命令会随版本增删，以它为准。

终端里敲：只需要这几个

会话里敲：这十几个覆盖九成场景

它下面还挂着一批子命令

按需用的启动参数

# 补加目录 / 追加系统提示词 / 预批准某些工具
claude --add-dir ../shared
claude --append-system-prompt "多用中文注释"
claude -p "…" --allowedTools "Bash(npm test)" "Read"
# 输出与会话控制
claude -p "…" --output-format json    # 输出成 JSON，方便脚本解析
claude -c --fork-session                # 继续上次，但开一个新会话 ID，不污染原记录
claude -r "2026-09-13-…"                 # 用会话 ID 精确恢复

--allowedTools（也写作 --allowed-tools）是"这些工具不用问就直接用"的白名单；如果你想限制的是"它总共能用哪些工具"，那是另一个参数 --tools。两者别搞混：一个管"要不要问"，一个管"有没有"。

几个值得记的快捷键

09怎么让它记住你的项目规矩？

它每次开新会话都是从零开始——没有"上次的记忆"。想让它不用你反复交代，靠两套机制：一份你写的项目说明书，和一份它自己攒的笔记。

先分清：你写的 vs 它自己攒的

两套都是"每次会话开始时读进上下文"，但官方特别提醒了一句：它把你的说明当上下文，不当强制配置。想要"无论如何都不许做"，得用 Hooks（见 14）。

CLAUDE.md 放哪、谁生效

CLAUDE.md 就是一个纯文本的 Markdown 文件（Markdown 是那种用 # 表示标题、- 表示列表的写作文本格式）。它放的位置决定谁能看到：

加载顺序是从宽到窄：组织 → 你 → 项目 → 本地，所以项目里的规定会出现在个人偏好之后，也就是更靠后、更具体。工作目录上层的 CLAUDE.md 在启动时就加载；子目录里的则等它真去读那个目录时才加载。

里面写什么

# 项目名：xx SaaS（Next.js + TypeScript + Prisma）
# 代码规范
- 组件用函数组件 + hooks，不用 class
- 状态管理用 Zustand，不用 Redux
- 提交前先跑：npm run lint && npm test
# 架构决策
- API 路由放 app/api/ 下
- 数据库统一走 lib/db.ts
# 绝对禁止
- 不修改 .env 文件
- commit message 用中文

判断"该不该写进去"有一个很好用的标准：同一句纠正你说了第二遍，或者代码评审抓到它本该知道的事——那就是该写下来的时候。写的时候尽量具体："用 2 空格缩进"远好过"格式写规范点"。

三个进阶能力，建议会用

• @ 导入——在 CLAUDE.md 里写 @README、@docs/api.md，就能把别的说明文件一并带进来，不用重复粘贴。
• .claude/rules/ 按路径加载——把规则拆成一个个小文件放在这个目录里。带 paths 字段的规则只在它碰到匹配的文件时才加载，比如只对 src/api/**/*.ts 生效，这样能省下大量上下文。
• /init 自动生成——让它先扫一遍项目自动产出草稿，你再补。想确认哪些文件真的被加载了，用 /context 看。

一套"进化完整"的项目配置长什么样

不用一步到位。先用 CLAUDE.md，等用得多了再逐层加，理想终态是这样：

your-project/
├── CLAUDE.md          # 项目说明书（规范 / 架构 / 绝对禁止）
├── CLAUDE.local.md    # 只属于你的补充（记得加进 .gitignore）
├── .mcp.json          # 团队共用的外部工具配置
└── .claude/           # settings.json（权限规则/钩子） · rules/（按路径生效的规则） · skills/（技能） · agents/（子代理）

自动记忆：不用你动手的那本笔记

除了你手写的文件，它还会在干活过程中把"你纠正过它的点、你的偏好"记到本机的一个目录里：~/.claude/projects/<项目>/memory/。这个目录的路径是按 git 仓库算出来的，所以同一个仓库的不同分支、子目录共用一份。它放在你本机，不上传。想浏览或关掉它，用 /memory。

关于它的三个高频疑问

10该选哪个模型、怎么不让账单失控？

模型有强弱档，也有快慢和贵贱之分。别一上来就研究型号——用官方给的别名，它会自动指向"当前那一代"的最新版本，你不需要记带日期的型号名。

四个别名，比写死型号更稳

另外还有几个：sonnet[1m] / opus[1m] 是打开百万级上下文窗口的版本，opusplan 是"规划时用 opus、执行时用 sonnet"的混合档，default 是"清掉我的选择、回到账户默认"。

切换方式：会话里敲 /model sonnet（回车表示"以后都默认"，按 s 表示只对本次生效）；启动时 claude --model sonnet；想永久改默认，敲 /config。

思考深度：让它多想还是少想

• 扩展思考——按 Option/Alt+T 开关，让它回答前先想一段。难题值得打开；日常小事打开只是更慢更贵。
• /effort 调档——可选 low / medium / high / xhigh / max。这个档位控制的是"自适应推理"的强度：模型会自己判断这一步值不值得多想，你用这个档给它定上限。普通问题用 low 或 medium 就够快够省。
• 官方也说明了：不是所有模型都支持全部档位。老一些的模型最高只到 max 或 high；如果你设了一个它不支持的档，它会自动退回"不高于你设的那个最高可用档"。

上下文窗口和自动压缩

"上下文窗口"是一次会话里它能同时记着多少内容的上限，单位是 token（可以粗略理解成"字词的碎片"，一句话大约几十到上百个）。当前主力模型都支持百万级 token——读一个中型仓库不成问题。

• 窗口快满时它会自动压缩（把前面的对话总结成更短的版本）。
• 想自己定"填到多满才自动压缩"，用 /autocompact 500k（接受 500k、1M、200000 这类写法，范围 100K 到 1M）；想恢复成"按你的模型自动调好的值"，用 /autocompact auto。
• 会话很长、用量吃紧时：/context 先看被什么占满了 → /compact 手动压缩，或者干脆 /clear 开新会话。

一张"按任务选档"的速查表

三个立刻能省下钱的动作

• 先看用量再决定——/usage 随时能看这次会话花掉多少（订阅用户看到的是套餐用量条）。
• 该清就清——长会话每一轮都会把你前面的全部上下文再算一遍，越拖越贵。做完一件事就 /clear。
• 把重复的说明挪出 CLAUDE.md——官方给的省用量建议里有一条就是"把指令从常驻上下文挪到技能里"，因为技能只在用到时才加载。官方也提到，给项目装代码智能插件、把啰嗦的操作用 Hooks 或子代理处理，都能省。

11怎么把重复流程变成一句话？

技能（Skill）是把"一段操作手册"打包成一个可以按需调用的单元。它和项目说明书的区别在于什么时候加载：说明书每次会话都读，技能只在用到时才读。所以官方给的分工是——一句事实写进 CLAUDE.md，一段多步骤流程做成技能，只对某类文件生效的规矩放进 .claude/rules/。

它自带的一些技能

登录态下直接敲 /help 会看到你这一版实际有哪些——上面这些随版本有增删。

怎么自己写一个技能

在项目里建一个目录 .claude/skills/技能名/SKILL.md，文件开头用一段固定格式的元数据写明名字和用途，正文就是步骤：

# .claude/skills/review-pr/SKILL.md
---
name: review-pr
description: 团队默认的 PR 检查清单，遇到"review 这个 PR"时使用
---
按这个顺序检查每个改动文件：
1. 有没有把密钥、路径硬编码进代码
2. 有没有处理空值与报错
3. 命名是否遵守项目的 camelCase 规范
4. 最后用 npm test 跑一遍相关用例

开头那两行被三条短横线夹住的写法是 YAML 格式的元数据（一种专门用来写配置的文本格式）。description（用途描述）很关键——它不是写给人看的说明书，而是决定"Claude 什么时候会自己想起这个技能"的触发条件，写得越具体越准。

想让团队共用，把 .claude/skills/ 提交进 Git；只想自己用，放 ~/.claude/skills/。不想手写的话，直接对它说"把上面这套审查流程做成一个技能"，它会替你建。

一个技能具体长什么样：拆开 /code-review

# 审当前还没提交的改动
/code-review
# 审出问题后顺带修掉
/code-review --fix
# 审某个 PR（编号 1234）
/code-review 1234

技能怎么被触发：两种开关

自定义技能默认属于哪一种，取决于你把用途描述写得像"给用户的指令"还是"给模型的能力说明"——技能文件里有专门的字段控制这件事，写的时候可以显式指定。另外一条实用规则：一条消息里最多可以叠加 6 个技能，比如 /skill-a /skill-b 做某事，两个技能都会加载，后面的文字当作参数传给它们。

12怎么让它同时干几件事？

有两种"并行"，别混：一种是把你手上这个会话丢到后台去跑，另一种是让它再派几个小助手分头干活。

后台任务：把整个会话丢到后台

# 丢到后台，终端立刻还给你
claude --bg "运行全部测试，把失败项整理成清单"
# 看有哪些后台会话 / 接管一个 / 停掉一个
claude agents
claude attach <会话ID>
claude stop <会话ID>

适合"编译很久""想边做别的边等"的活。会话里也可以用 /background 把当前会话直接甩到后台，终端腾出来干别的。

子代理：让它派几个"专职小助手"

子代理（Subagent）是它自己调度的小助手，各自带独立的工作说明、独立的工具清单，甚至可以指定不同的模型。你可以把分工写在一个配置文件里，它在需要时按描述派出去并行处理，主会话负责汇总。

配置文件放在 .claude/agents/ 目录下，长这样：

# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: 项目专属的安全审查员。当需要检查改动里有没有注入、越权、密钥泄露时使用
tools: Read, Grep, Glob
model: opus
---
你是本项目的安全审查员，重点检查：
1. SQL / 命令注入与越权（本项目用 Prisma，手写 SQL 拼接是红线）
2. 有没有把密钥、内网地址硬编码进代码
3. 日志里是否打印了敏感字段
只输出发现与修复建议，不要直接改代码。

• tools 这一行限制了它能用哪些工具——只管"看"，不给"写"，它就改不了代码。
• model 可以单独指定：让审查这种需要推理的活用更强的档。
• description 写得越具体，Claude 越知道"什么时候该派它出去"。

两种并行怎么选

什么时候别并行

• 任务之间会改到同一批文件——两个代理各改一半，合并起来就是一团乱。
• 你还没验证过单线程能不能做对——先跑通一遍，再谈加速。
• 结果你根本来不及看——开五个后台任务、最后只打开一个，等于白花钱。

13怎么让它连上外面的工具？

默认情况下它只能看你机器上的文件、跑你机器上的命令。想让它读 GitHub 上的工单、查数据库、更新 Jira，需要一个统一接口——这就是 MCP（Model Context Protocol，模型上下文协议）。可以把它理解成一个"插座标准"：外部工具只要按这个标准做一个"服务"，Claude Code 就能接上。

三种接法，按需要选

# 加一个远程 HTTP 服务（推荐形态）
claude mcp add --transport http notion https://mcp.notion.com/mcp
# 加一个本地 stdio 服务（跑一个本地命令来提供能力）
claude mcp add airtable -- npx -y airtable-mcp-server
# 需要密钥的，用请求头带进去
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer 你的令牌"
# 查看 / 移除
claude mcp list
claude mcp remove airtable

几个细节：默认作用范围是"用户级"（对你所有项目生效），加 --scope project 可以写进项目、随 Git 共享给团队；项目级的配置也可以直接写在 .mcp.json 这个文件里。需要登录的服务可以走网页授权：claude mcp login 名字；靠环境变量读密钥的服务，可以在 claude mcp add 时用 --env 变量=值 把值传进去（别把密钥写进会提交进 Git 的配置文件）。

还有一条容易记错的细节：配置文件里的类型字段，官方标准叫 streamable-http，Claude Code 也接受 http 这个简写——你从别的服务文档里复制的配置，一般能直接用。

接上之后，实际能做什么

它和别的东西怎么区分

14怎么让某件事"一定会发生"？

前面讲的 CLAUDE.md 和技能都是引导——它读到了、理解了就照做，偶尔也会忘。想让它必须发生，得用钩子（Hooks）：由 Claude Code 在固定时刻替你执行命令，不经过模型判断。它和权限规则的分工是——权限规则管"某条命令许不许跑"，钩子管"到了这个时刻要做什么"。

一个能直接抄的例子

配置写在 .claude/settings.json（项目级，随 Git 共享）或 ~/.claude/settings.json（个人全局）：

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command",
            "command": "npm run lint 2>&1 | head -30" }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command",
            "command": "grep -q 'rm -rf /' && exit 2 || exit 0" }
        ]
      }
    ]
  }
}

这段配置干了两件事：

• PostToolUse + matcher: "Edit|Write"——每次它改完或写完文件之后，自动跑一次代码检查（lint，就是检查代码风格和明显问题的工具），只打印前 30 行。问题当场暴露，不用等你自己想起来跑。
• PreToolUse + matcher: "Bash"——每次它要执行命令之前，先检查里面有没有 rm -rf /（把整个磁盘递归强删）。命令里的 exit 2 就是"拒绝执行"的信号，exit 0 是"放行"。

matcher（匹配器）支持用竖线连多个工具名，比如 "Edit|Write"、"Bash"。想随时看当前挂了哪些钩子，敲 /hooks。

常用事件有哪些

官方定义的事件比下面这张表多得多，但这几个是你最可能用到的：

15怎么让它在没人看着的时候干活？

用 -p 这种"问完就退"的模式，它能直接接进脚本和流水线。关键不是"能不能跑"，而是怎么把它限定在一个你事先想清楚的范围内。

三个立刻能用的组合

# 1) 让改动自己生成提交信息
git diff | claude -p "为这次改动写一个简洁的 commit message"
# 2) 定时分析日志（配合系统的定时任务工具 cron）
tail -200 app.log | claude -p "发现异常就列出来，并给修复建议"
# 3) 输出成机器能读的格式，方便脚本处理
claude -p "审查这些文件" --output-format json

在 CI 里跑，必须锁死三件事

CI（持续集成）指的是"每次提交代码，服务器自动跑一遍构建和测试"的那套流水线。把 Claude Code 放进去，你要做的是把它的活动范围锁到最小：

# 只允许它"跑测试"和"读文件"，其他一律拒绝
claude -p "运行测试套件并报告失败项" --permission-mode dontAsk \
  --allowedTools "Bash(npm test)" "Read"

一段最小可用的 GitHub Actions 配置

# .github/workflows/claude-pr-review.yml（示意：PR 一来就自动审改动）
name: claude-pr-review
on: pull_request
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 让 Claude Code 审这次改动
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          git diff origin/${{ github.event.pull_request.base.ref }}...HEAD \
            | claude -p "审查这份 PR 改动的安全问题与明显 bug，逐条给出文件与行号" \
              --permission-mode dontAsk --allowedTools "Read" "Grep"

官方还提供 GitHub Actions 和 GitLab CI/CD 的现成集成，可以直接用来做"PR 自动审查""Issue 自动归类"。除了 CI，想"定时自动跑"还有几条路：桌面 App 有定时任务、云端有 routines、会话里可以用 /loop 按间隔重复——按你的东西放在哪来选。

16四个场景，从零走一遍

下面四件事是新手最常遇到的。它们共用同一套节奏，练熟一遍，别的场景都能套。

场景 A：修一个报错

场景 B：给旧代码补测试（单元测试 = 针对单个函数写的小测试，跑一遍就知道有没有改坏）

场景 C：审查一批还没提交的改动

claude --permission-mode plan "用 /code-review 审查我现在的改动，重点看有没有安全问题和明显 bug"

让它以只读的 plan 模式跑，审完给你结论，全程不碰文件——纯审查，零风险。觉得它漏了，就追问一句"再看看数据校验那部分"。

场景 D：从零搭一个一次性小工具

这是新手最容易获得成就感的一步：让它在空目录里"从无到有造出一个能跑的东西"。

mkdir ~/csv-tool && cd ~/csv-tool
claude "这个文件夹还是空的。帮我：1) 用 Node 写一个脚本 csv-stats.js，读同目录的 data.csv，输出每列的平均值和总行数；2) 造一份 5 行的 data.csv 用来测试；3) 写一份 README 说明怎么跑。做完运行给我看结果。"

它通常会：建文件 → 造样例数据 → 执行脚本 → 把输出贴给你。你验收三点：目录结构是否合理、脚本是不是真的跑起来了、README 能不能让你照着复现一遍。

四个场景的共同套路

一条七天上手路线

每天 20 分钟，从"会启动"走到"接进日常工作"：

17最容易踩的六个坑

这些坑的共同特征是：踩之前都觉得自己不会踩。

同一件事，两种说法

最后再对照一次——这是所有坑里最常见的一个：

"修一下那个 bug"
"加个分页"
"优化一下性能"

"修复 src/api/users.ts 里 getUsers 在分页
 参数为 0 时返回空数组的 bug，改完跑测试
 并修复失败项"
"给 UserList 加前端分页，每页 20 条，
 显示页码导航，改完把界面截图给我确认"

18速查表：打印出来贴在旁边

装 / 升级

curl -fsSL https://claude.ai/install.sh | bash   # macOS / Linux / WSL（原生，自动更新）
irm https://claude.ai/install.ps1 | iex          # Windows PowerShell
brew install --cask claude-code                  # Homebrew（stable 通道）
claude update                                      # 手动升到最新
claude doctor                                       # 只读体检（排错第一步）

启动与会话

claude                          # 交互模式
claude -p "问题"                # 问完就退（脚本 / CI）
claude -c                        # 继续最近的会话（-r 恢复历史会话）
claude --permission-mode plan   # 以只读的 plan 模式启动
claude --bg "任务"               # 丢到后台

会话里最常用的

/help         全部命令        /clear       重开
/compact      压缩上下文      /context     看占用
/model        切模型          /effort      思考深度
/config       改设置          /permissions 权限规则
/memory       记忆            /init        生成 CLAUDE.md
/usage        用量            /rewind      回退到检查点
/plan         进规划模式      /diff        看改了什么
/code-review  审当前改动      /sandbox     开关命令沙箱
/autocompact  自动压缩阈值    /exit        退出（Ctrl+D）

外部工具与后台

claude mcp add --transport http 名字 https://…/mcp   # 加远程服务
claude mcp list                                        # 看已配的
claude agents                                          # 看后台会话
claude attach <会话ID>                                  # 接管后台会话

四条能直接改一改就用的指令模板

# 1) 报错 → 修复
请先说明下面这段报错的根因，再给最小改动方案；
我确认后再动手，改完跑相关测试。
[把报错原文贴在这里]
# 2) 重构 → 带验收
把 src/auth.ts 的登录逻辑拆成两个纯函数，保持对外行为不变；
用现有测试验证，最后总结改动和所有调用点。
# 3) 补测试
给 src/utils/format.js 补单元测试，覆盖 空值 / 超长文本 / 中英文混排；
沿用项目现有测试框架，全部跑通为止。
# 4) 审查
用 /code-review 审我这次的改动，重点：安全漏洞、明显的 bug、
和 CLAUDE.md 里规范不符的地方，逐条给出文件与行号。

最小安全基线（写在最后，但最重要）

• 在 CLAUDE.md 里写清"绝对禁止"清单（比如不许碰 .env——注意它不在系统的受保护路径里，得你自己立规矩）。
• 默认不碰 --dangerously-skip-permissions，只在隔离容器或虚拟机里用。
• 每次放行前看一遍 git diff 或 /diff。
• 不在会话里贴密钥、内网地址、客户数据。
• 会话越长越早 /compact 或 /clear，别硬撑到它开始"失忆"。

19术语对照表

这张表不是翻译字典。第三列回答的是"它在你实际用的时候重要在哪、什么时候会用到、最容易把它误当成什么"。

20遇到问题怎么排查？

大多数"它怎么不听话"都能一两步定位。第一件事永远是跑一次 claude doctor 看安装与配置的体检结果，然后按现象对表：

都不管用的时候：用 /bug 上报，并附上复现步骤——这是最有效的方式（/feedback 走的是同一个对话框，用来提产品建议）。

21常见问题

98参考来源与证据边界

这是一篇讲工具的文章，所以"校对到哪一天、依据哪一版"比结论本身更重要。下面每一条都标了口径。

一手来源（官方文档，逐页读取）

1. Claude Code Overview——它是什么、有哪些界面、各安装方式与自动更新行为。
2. Advanced setup——系统要求、四条安装路线、Node.js 版本要求（npm 安装自 v2.1.198 起需 Node 22+）、卸载与清理配置。
3. CLI reference——终端命令与启动参数（-p、--add-dir、--fork-session、setup-token、--autocompact 等）。
4. Commands——全部斜杠命令与内建技能，含各自的最低版本要求。
5. Choose a permission mode——六种权限模式、分类器默认拦截清单、受保护路径清单。
6. Model configuration——模型别名、各档位指向的版本、/effort 档位、自动压缩窗口。
7. Memory——CLAUDE.md 的五个位置与加载顺序、.claude/rules/ 的 paths 机制、自动记忆的存放路径。
8. Extend Claude with skills——技能的定义、加载时机、内建技能与"最多叠加 6 个"。
9. Subagents——子代理配置文件的字段（name / description / tools / model）。
10. Hooks reference——事件列表与配置结构。
11. Connect Claude Code to tools via MCP——三种接法、--transport、--scope、streamable-http 别名。
12. Manage costs——用量查看、省用量建议、企业部署的平均成本数字。
13. Models overview与官方定价页——当前模型名称（Fable 5.1 / Opus 5 / Sonnet 5 / Haiku 4.5），以及套餐对照表里"Claude Code 是否包含"一栏。
14. anthropics/claude-code——官方仓库与问题反馈入口。

本文自己做的核对

• 版本号：从 npm 官方仓库的发布记录里取 @anthropic-ai/claude-code 的标签，校对时为 latest 2.1.269、stable 2.1.236。文中出现的每一个功能都对着它自己的最低版本要求核过（例如 /autocompact 需要 v2.1.221 以上、Fable 5.1 需要 v2.1.257 以上）。
• 模型名称：以官方模型总览页为准，逐个对过 Fable 5.1 / Opus 5 / Sonnet 5 / Haiku 4.5，以及各家服务商下别名指向的版本差异（正文只写了 Anthropic 官方 API 这一列）。
• 受保护路径：逐条抄自权限模式页的清单，并据此修正了旧版的一处错误（见下）。

证据边界与时效

• 版本口径。本文校对于 Claude Code @ 2.1.269（2026-09-13）。这是个每周都在发版的工具，命令名、默认值、模型别名都可能变——这也是本文把时效标为 evolving 的原因。发现对不上时，以 /help 和官方文档为准，并跑一次 claude --version 看看自己落后了多少。
• 本文没有做的事。没有在你的机器上逐条实测每条命令；没有覆盖 Amazon Bedrock / Google Cloud / Microsoft Foundry 这些第三方入口的差异；没有展开企业级的管理策略、监控与合规配置；也没有评测各模型的真实能力差距（那需要系统性实验，不是读文档能得出的）。
• 一处刻意的"不写死"。套餐价格一律不写具体金额，只写"免费版不含、付费版包含"，因为价格随时可能调整——要用时请查官方定价页。
• 本文相对旧版更正的一处事实。旧版把 .env* 列进了"受保护路径"。官方清单里没有 .env（有的是 .envrc），而且"读取 .env 并把凭据发往对应 API"明确列在默认允许的行为里。所以这一条已经从"系统会帮你挡住"改成了"你得自己立规矩"。

99一句话总结