第 01 章 什么是 Claude Code

版本基准:2026-07-08 核对,Claude Code v2.1.202+,模型 Opus 4.8 / Fable 5 / Sonnet 5 / Haiku 4.5。

1.1 结论先行:它是状态化工程代理,不是聊天机器人

Claude Code(下文简称 CC)的本质是状态化工程代理(stateful engineering agent)。它不是一个被放在终端里的聊天框,而是一个能持续读文件、执行 Shell、操作 Git、调用子代理,并在多轮工具反馈中自我修正的工程闭环。

这个定位带来一个直接推论:CC 的生产力来自可执行闭环,而非更长的 prompt。聊天机器人的瓶颈是"你描述得多准",CC 的瓶颈是"验证回路闭合得多紧"。一句 运行 npm test 直到通过,只改 src/auth/ 下的代码 比一段千字需求描述更能产出可用代码,因为前者锚定了可验证的终止条件。

理解这一点后,本书其余所有章节都可以看作在回答一个问题:如何为 CC 设计更短、更硬、更可验证的闭环? 这一章先打好心智底座,讲清 CC 是什么、底层怎么运转、你应该用怎样的心智模型对待它。

1.2 CC 是什么:定位、能力与边界

与 Claude.ai 网页版、IDE 插件的差异

CC 是 Anthropic 官方的工程代理产品线之一。同一家族还有 Claude.ai 网页版与 IDE 插件,但它们的运行形态、权限边界、项目理解深度完全不同。下表是经过核对的真实差异:

维度	Claude.ai 网页版	IDE 插件(VS Code/JetBrains)	Claude Code CLI
交互方式	网页聊天,单轮问答为主	编辑器内嵌对话面板	终端 REPL,多轮状态化
文件操作	需手动上传,沙箱内只读	当前工作区读写	直接读写本地任意路径
命令执行	不支持	受限,经编辑器代理	直接执行 Shell,可带权限策略
Git 操作	不支持	间接,通过命令代理	原生支持 git add/commit/分支/PR
项目理解	单次对话,无持久记忆	部分持久(工作区)	CLAUDE.md + Memory 跨会话
自动化集成	不支持	不支持	-p headless、hooks、CI/CD

一句话归纳:网页版是问答助手,IDE 插件是编辑器外挂,CC 是工程代理。前两者让你"问得更快",CC 让你"闭环更快"。

能做什么

CC 的能力围绕五类工具展开,这些工具是它与物理世界交互的唯一通道:

1. 读写文件 — Read/Edit/Write,支持精确字符串替换与整文件创建
2. 执行 Shell — Bash,可跑测试、装依赖、调 git、起服务、管道组合
3. 操作 Git — 原生命令链,支持 Conventional Commits、分支管理、gh CLI 集成
4. 搜索代码 — Grep/Glob,正则与文件名模式,跨大仓库快速定位
5. 子代理编排 — Agent 工具派生独立上下文的子代理,并行探索或实现

这五类工具的组合构成闭环:读现状 → 推理 → 改 → 验证 → 再改。典型案例如:读 package.json 与测试入口 → 跑 npm test 看失败 → 定位文件 → 编辑 → 重跑直到通过 → git commit。

需要强调的是,这五类工具是 CC 与物理世界交互的全部通道。CC 不"知道"你的仓库状态,它只能通过 Read 看到文件内容、通过 Bash 看到命令输出、通过 Grep 看到符号命中——所有事实都来自工具返回。这意味着工程效果取决于三件事:上下文质量(它读到了什么)、动作权限(哪些工具能自动跑)、反馈强度(测试与编译器能否明确判定对错)。没有验证命令的 Agent,只是在高速生成猜测。

不能做什么(能力边界)

把 CC 当万能工程师会翻车。以下是它结构性不适合的任务,原因不是能力不足,而是架构使然:

• 精确数学计算 — LLM 是概率模型,浮点与大数运算必须经 Bash 调 python/bc
• 复杂 merge conflict 的业务判断 — 冲突涉及"哪边语义对",CC 看不到产品决策上下文
• 运行时性能分析 — 它能读静态代码,但无法 attach profiler、看不到火焰图
• 生产环境操作 — 默认无生产凭据,且即便有,也不应让概率模型直接改线上
• 加密/安全关键代码 — 侧信道、时序攻击、密钥管理需要专家审查,CC 产出必须人工复核
• 超大型耦合重构 — 跨数百文件的强一致改动,子代理并行会引入不一致,主上下文又会撑爆 token

这些边界不是缺陷,是设计取舍。CC 用"有限工具 + 状态化循环"换来了可控与可验证;它不试图取代专家判断,而是放大专家在实现与探索环节的产出。

1.3 底层架构:一图看懂状态化 REPL

CC 的运行模型可以用一张图概括。它是一个 Read-Eval-Print Loop,但每一次 "Eval" 不是求值一个表达式,而是执行一整条工具调用链:

┌─────────────────────────────────────────────────────────────┐
│                    用户输入 (User Input)                     │
└──────────────────────────┬──────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  LLM 推理:理解意图 → 选择工具 → 生成工具调用参数              │
│  (模型: Opus 4.8 / Fable 5 / Sonnet 5 / Haiku 4.5)         │
└──────────────────────────┬──────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  工具调用链(单轮可并发,无依赖的调用同时发起)                 │
│   ├─ Read(src/auth/login.ts)                                │
│   ├─ Grep("validateToken", path="src")                      │
│   └─ Bash(npm test -- auth)                                 │
└──────────────────────────┬──────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  环境返回事实:文件内容、grep 命中、命令 stdout/stderr/退出码  │
└──────────────────────────┬──────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  结果回注上下文窗口 → LLM 再次推理 → 更新计划                 │
└──────────────────────────┬──────────────────────────────────┘
                           ▼
            ┌──────────────┴──────────────┐
            ▼                             ▼
     继续下一轮工具调用            输出文本给用户(终止)
            │
            └─── 上下文窗口约 200K tokens,超限自动压缩 ───┐
                          ↑                              │
                          └──────────────────────────────┘

这张图隐含了 CC 的全部行为逻辑。理解它,就能预测 CC 在任何场景下的表现:只要能让"工具调用 → 事实回注"这条回路高速闭合,CC 就高效;一旦回路断裂(没有可执行的验证命令、文件太大读不全、依赖外部不可达服务),CC 就退化成普通聊天机器人。

这里需要解释"状态化"这个词的关键含义。普通聊天机器人每轮独立,你问一句它答一句,前后轮之间只靠你手动粘贴上下文。CC 的"状态化"指的是:同一会话内,所有工具返回的事实都累积进上下文窗口,LLM 在第 N 轮推理时能看到前 N-1 轮的全部事实。这就是为什么 CC 能"先读测试再改代码再跑验证"——它记得测试长什么样。但状态化也是双刃剑:上下文会膨胀,超限后自动压缩会丢细节,所以"把关键信息写文件"才成为铁律(见 1.5 节心智模型二)。

关键架构约束表

上图中的每个环节都有硬约束,这些约束决定了你应该怎样设计任务:

维度	实际行为	对协作的影响
上下文窗口	约 200K tokens,超限后自动摘要压缩	长会话早期细节会丢失;关键信息必须写文件,不能依赖"它记得"
单轮工具并发	同一响应中可并行发起多个无依赖工具调用	设计任务时让 CC 能并行(如"同时读这三个文件"),别串成依赖链
无守护进程	每轮由用户触发,不自主轮询	持续监控须用 /loop、hooks 或外部调度,不能指望 CC 自己盯着
工具边界	只能通过 Read/Edit/Write/Bash/Agent 等工具与世界交互	超出工具能力的需求必须 Bash 桥接(如调外部 API)
子代理隔离	Agent 子代理有独立上下文,完成后只返回摘要	适合并行探索;不适合需要精确文件:行号引用的任务,摘要会丢细节
状态化	同一会话内上下文累积,跨会话不自动继承	跨会话知识必须写入 CLAUDE.md 或 Memory,否则每次从零开始

这张表是本书最高频被引用的约束清单。后续章节讲工作流设计、上下文管理、子代理编排时,都是在围绕这张表做工程化取舍。

1.4 运行形态:四种入口,同一内核

CC 有四种运行形态,底层是同一套状态化 REPL,但交互界面与集成深度不同:

1. 终端 CLI(全平台) — claude 命令启动交互式 REPL;claude "query" 带初始 prompt 进入交互;claude -p "query" 执行后打印退出,适合脚本与 CI。这是本书主要载体,也是功能最完整的形态。三种入口里,交互式 claude 适合探索与多轮重构,claude "query" 适合把进入项目后的第一条任务直接塞进启动命令,claude -p 适合受预算和轮次限制的自动化任务(可配 --max-turns、--max-budget-usd、--allowedTools 等保护参数)。
2. VS Code 扩展 — 编辑器侧边栏内嵌 CC 面板,文件编辑与对话同屏,适合习惯在 IDE 里完成一切的开发者。
3. JetBrains 扩展 — IntelliJ/WebStorm/PyCharm 等同理,与 JetBrains 的 VCS、运行配置集成更紧。
4. Web 端(claude.ai/code) — 浏览器内访问,适合临时机器、iPad、远程办公场景,功能子集。

四种形态共享同一份 ~/.claude/ 配置目录与 CLAUDE.md 体系,因此你在终端里调好的权限策略与项目记忆,在 IDE 插件里同样生效。

选型建议:重度工程与自动化用 CLI,日常写码用 IDE 插件,临时访问用 Web 端。本书示例统一用 CLI,因为它最透明、最可脚本化,也最方便展示 CC 的真实行为。

1.5 三个心智模型:决定你用得有多好

工具用得好不好,往往不取决于工具本身,而取决于你脑子里的模型对不对。CC 有三个反直觉的心智模型,接受它们就能避开 80% 的踩坑。

心智模型一:不是聊天,是工程代理

把 CC 当聊天机器人,你会下意识写长 prompt 解释背景;把它当工程代理,你会写可验证的任务指令。

差别巨大。看两个对比例子:

# 聊天式(差)— 没有终止条件,没有约束
我们有个支付模块,最近用户反馈偶尔会重复扣款,你帮我看看是哪里的问题,
我觉得可能是并发处理有问题,但也可能是数据库事务没做好,你分析一下。

# 工程代理式(好)— 位置、现状、目标、约束、验证全齐
定位 src/payment/ 下重复扣款的根因。
现状:并发请求同一订单会触发两次 charge。
目标:同一订单 5 秒内只扣一次,重复请求返回原结果。
约束:不改支付网关 SDK,只动应用层;不引入 Redis。
验证:先写复现测试 test/payment.idempotent.test.ts,跑通后再改实现,
最后跑 npm test -- payment 全绿。

后者之所以高效,不是因为它更长,而是因为它给 CC 锚定了可执行的验证回路:先复现、再修、再验证。没有这条回路,CC 只是在高速生成猜测。

心智模型二:不是记忆,是文件

CC 有约 200K 的上下文窗口,听起来很大,但在一个中型项目里读十几个文件就接近上限。超过后自动压缩会丢失早期细节。因此有一条铁律:

关键信息必须写进文件,不能依赖 CC "记得"。

这条铁律有三个落地动作:

• 项目级约束写 CLAUDE.md — 技术栈、命令、架构红线、安全规则,每次启动自动加载
• 跨会话知识写 Memory — 业务决策原因、团队约定、历史教训,存 ~/.claude/projects/<project>/memory/
• 任务中间产物写工作文件 — 重构方案、待办清单、审查笔记写到 docs/ 或临时文件,而不是让 CC 在对话里"记着"

反例是把架构决策、API 手册、历史变更全塞进对话。一旦会话超过 40 轮,这些内容要么被压缩成模糊摘要,要么彻底丢失。让文件成为唯一可信源,对话只是工作区。

心智模型三:不是自动,是受控

CC 能自动跑测试、改代码、提交,但这不意味着它该自主决定"改哪里、怎么改、提交什么"。正确的协作模式是:

人做架构决策与关键审查,Claude 做实现探索与机械执行。

这条原则体现在三个层面:

• 架构决策归人 — 技术选型、模块边界、数据模型,这些 CC 看不到全貌的决策必须人定
• 实现探索归 Claude — 在约束内找实现路径、写样板代码、跨文件改同名符号,这些 CC 比人快
• 关键审查归人 — 安全相关、并发相关、业务语义相关的改动,CC 产出必须人工复核

落地工具是 --permission-mode:plan 模式让 CC 只读分析不动手,acceptEdits 让它在工作区内自由编辑但拦截高风险命令,default 每步都问。默认用 plan 探路,确认方案后切 acceptEdits 执行,涉及破坏性操作时回到 default。 此外,.claude/settings.json 里的 permissions.allow/ask/deny 三层策略让你能把"读操作全放行、写操作按项目放开、破坏性操作永不自动"固化成团队共享规则。权限与安全是第 04 章的主题,这里只点出原则:受控不是限制效率,而是把人类控制面从"每次按 y"升级为"一次配好策略,长期自动跑"。

这三个心智模型贯穿全书。读到任何一章,如果不确定该怎么和 CC 协作,回到这三条上对照一遍,基本能找到答案。

1.6 本书路线图:六部分导览

本书按"入门 → 工程 → 扩展 → Agent → 实战 → 产品化"六部分组织,每一部分都建立在本章的心智底座之上:

• 第一部分 入门 — 第 02 章安装与首次会话,带你跑通第一个闭环
• 第二部分 工程 — 第 03-05 章讲 CLAUDE.md、权限模型、上下文管理,把状态化 REPL 的约束变成工程纪律
• 第三部分 扩展 — 第 06-08 章讲自定义 skill、hooks、MCP,把 CC 从通用工具改造成你的专属工作流
• 第四部分 Agent — 第 09-11 章讲子代理编排、并行任务、headless 模式,从单代理走向多代理系统
• 第五部分 实战 — 第 12-15 章用四个真实场景(全栈开发、遗留重构、自动化脚本、代码审查)串起前面所有能力
• 第六部分 产品化 — 第 16-18 章讲如何把 CC 工作流沉淀成可售卖的产品,面向一人公司与超级个体方向

各章可按顺序读,也可按需跳读。但无论从哪一章开始,请确保你已经接受本章的三个心智模型——它们是后续所有内容的前提。

下一步

如果你已经理解了"状态化工程代理"这个定位与三个心智模型,可以直接去第 02 章 安装与首次会话,跑通你的第一个 CC 闭环。如果你已经装好 CC、跑通过基础用法,想直接进入工程纪律,跳到第 03 章 CLAUDE.md 与项目记忆。

本章不展开命令真实性总表(哪些 / 命令是官方内置、哪些是自定义 skill),那张表见第 06 章与附录 A。这里只给出一条原则:任何 /xxx 命令在未被你主动安装前,都不应假设它存在。例如 /bug 是反馈通道的别名,不是"自动修 Bug 模式";/search、/explain 不是默认内置命令,代码搜索靠 CC 自主调用 Grep/Glob 完成。遇到不确定的命令,以第 06 章总表与附录 A 为准。

---

上一章:总览 下一章:安装与首次会话

---

下一章:安装与订阅 | 返回目录