# 读懂代理循环：Claude Code 零基础首个有效会话
## 概述
本教程面向**第一次接触 Claude Code 的零基础开发者**，目标是帮你在打开终端的第一分钟就建立起正确的"代理式编程"心智模型：理解它和传统代码补全工具的本质区别、读懂屏幕上正在发生的代理循环、学会提出一个能被自主执行的好需求，并亲手跑通第一个真实会话。完成本教程后，你不再把 Claude Code 当搜索引擎，而把它当成一个会读你的代码、会动手改文件、会自己跑验证的工程搭档。
## 前置条件
- 一台 macOS / Windows / Linux 计算机，能用命令行（会 `cd`、`ls` 即可）
- 已安装 Node.js 18+ 或 Homebrew（用于安装 Claude Code；具体三平台安装见延伸阅读）
- 一个能登录的 Anthropic 账号（或 Claude 订阅）
- 心态准备：**准备好把"自己敲代码"暂时换成"描述目标 + 审查结果"**
---
## 第一步：先纠正一个认知——Claude Code 不是补全副驾
很多新手把它和 GitHub Copilot、Cursor 自动补全混为一谈，于是一上来就用错姿势。先建立这个核心区分，后面的一切才说得通。
**补全工具（Copilot 式）的工作单位是"光标位置的下一行"**。它嵌在 IDE 里，盯着你正在敲的字符，预测你接下来要写什么，按 Tab 就补上。它的本质是**一个被动的、局部的、即时的预测器**——你不敲，它不动；它看不见你光标三屏之外发生了什么。
**Claude Code 的工作单位是"一个完整的目标"**。它住在终端里，直接连接你的代码库，能读整个项目结构、能跨几十个文件行动、能自己运行命令看结果、能在失败后自己调整再来。它的本质是**一个主动的、全局的、多步的执行体**——你给它一个目标，它自己规划路线、调用工具、验证成果。
| 维度 | 补全副驾（Copilot） | 代理执行体（Claude Code） |
|---|---|---|
| 触发方式 | 你敲代码，它预测下一行 | 你描述目标，它自主推进 |
| 作用范围 | 当前光标附近 | 整个项目、跨文件 |
| 时间跨度 | 毫秒级即时 | 分钟级、可链式几十步 |
| 你的角色 | 一边写一边按 Tab | 描述目标 + 审查结果 + 随时纠偏 |
| 典型场景 | 日常补全、模板生成 | 修 bug、重构、新增功能、解释代码 |
一句话记住区别：**补全工具增强你的"打字"，Claude Code 增强你的"决策与执行"**。所以正确用法不是"边写边问"，而是"先想清楚要什么，再一次性交给它，然后审查"。这个思维切换，是首个会话成败的分水岭。
## 第二步：核心心智模型——agentic loop 三阶段
理解 Claude Code，只需要抓住一个模型：**代理循环（agentic loop）**。Anthropic 官方文档把它概括为三个不断交织的阶段：
1. **收集上下文（gather context）**：先搞清楚现状——读相关文件、搜索代码库、理解依赖关系、看清要改的地方周围是什么。
2. **采取行动（take action）**：动手——编辑文件、新建文件、运行命令、安装依赖。
3. **验证结果（verify results）**：检查有没有做对——跑测试、运行程序、读自己改完的文件、对照目标复核。
关键在于**这三阶段会反复循环**，而不是走一遍就结束。官方原话是这样描述的：
> "当你给 Claude 一个任务，它会经历三个阶段：收集上下文、采取行动、验证结果……一个关于代码库的问题可能只需要收集上下文；一个 bug 修复会反复经历全部三个阶段；一次重构可能涉及大量验证。Claude 根据上一步学到的东西决定下一步做什么，把几十个动作串接起来，并沿途自我纠偏。"
这就是为什么它有时快（纯问答，只收集上下文就答）、有时慢（改一行 bug，却要读文件、改文件、跑测试、发现测试挂了、再改、再跑）。**慢不是卡住了，是它在循环里自我纠偏**——这正是它比补全工具强大的地方。
下面这张图把循环、你的介入点、以及权限门禁画在一起，请边看边对照后面的步骤：
```mermaid
flowchart TD
You([你：描述一个目标]) --> Loop
subgraph Loop[agentic loop 代理循环]
G[1. 收集上下文
读文件/搜索/理解]
A[2. 采取行动
编辑/运行/安装]
V[3. 验证结果
跑测试/对照目标]
G --> A --> V
V -->|没达目标| G
V -->|达到目标| Done([返回结果给你])
end
You -.随时可打断/纠偏.-> Loop
A -->|修改类操作| Gate{权限门禁
询问/自动接受/计划/自动/绕过}
Gate -->|你批准或模式允许| A2[真正写入磁盘]
```
## 第三步：你是 loop 的一部分——学会打断与引导
代理循环里最容易被新手忽略的一点：**你始终在这个循环里**。官方把这条实践列为首要原则——"It's a conversation"和"Interrupt and steer"。
具体来说，循环跑起来后你随时可以：
- **打断（Esc）**：发现方向跑偏，按 Esc 立刻停下，比让它跑完十步再返工省得多。
- **纠偏**：停下后输入新指令，比如"别用那个库，改用标准库"或"先只改 utils.py，别动其他文件"。
- **补充上下文**：比如"这个项目的测试框架是 pytest，不是 unittest"。
新手最常犯的错误是**把它当单向命令执行器**——丢一句话就走开等结果。正确做法是**像带新人一样全程在场**：给它方向、在它跑偏时及时拽回来。它自主性强，但**对你的反馈响应也快**。这种"放手但有监督"的状态，才是代理式编程的常态。
## 第四步：准备你的首个会话（5 分钟速通）
这部分只做最小准备，详细的安装/认证/配置在三篇延伸阅读里已讲透，这里不重复。
```bash
# 1. 安装（任选一种）
npm install -g @anthropic-ai/claude-code # 或: brew install claude-code
# 2. 进入你的项目目录（重要：Claude Code 以"当前目录"为工作边界）
mkdir my-first-project && cd my-first-project
# 3. 启动
claude
# 首次启动会让你登录认证；按提示完成即可
# 4. 进入交互后，按 Shift+Tab 可在权限模式间切换；输入 /help 看所有命令
```
**预期结果**：终端进入一个对话界面，底部有输入框，左下角显示当前权限模式。此时它已把当前目录当作你的"项目"。
**新手高频坑**：
- *在错误的目录启动*：Claude Code 只看得到当前目录及其子目录。在 home 目录启动它就"看不到"项目——**先 cd 进项目再 `claude`**。
- *启动就问无关问题*：进去先花 10 秒打个招呼验证它活着，比如"你能看到当前目录有哪些文件？"——若它列出文件，说明工作边界设对了。
## 第五步：提出一个能被代理执行的好需求
这是首个会话成败的核心。同样的目标，两种问法，效果天差地别。官方把高质量交互总结成几条原则，我翻译成新手可直接照做的规则：
**规则一：一次给清楚完整的目标（Be specific upfront）**
❌ 差需求："帮我做个待办"
✅ 好需求："用 Python 写一个命令行待办清单工具 `todo.py`，支持 `add '内容'` 增加任务、`list` 列出任务、`done 1` 标记第 1 个完成，数据存在本地 `todos.json`"
差需求缺少语言、缺少命令、缺少存储方式，Claude 只能猜，猜错你返工。好需求把语言、命令格式、存储这三件最重要的事钉死。
**规则二：给它一个可验证的锚点（Give Claude something to verify against）**
❌ "写个函数算斐波那契"
✅ "写个函数 `fib(n)` 返回第 n 个斐波那契数，并写 3 条 pytest 用例：`fib(0)==0`、`fib(1)==1`、`fib(10)==55`，最后运行 `pytest` 确保全绿"
给了具体期望值，循环的"验证"阶段就有了明确判据，它知道什么算"做对了"。
**规则三：先探索再实现（Explore before implementing）**
对已有项目，先让它"读"再让它"写"：
> "先别改代码。读一下这个项目的结构，告诉我 `main.py` 和 `utils.py` 各自做什么，再问我接下来要改哪里。"
这能让它先建立正确上下文，避免一上来乱改。
**规则四：委派目标，不要微操步骤（Delegate, don't dictate）**
❌ "打开 utils.py，在第 15 行加一个 if，然后……"（你变成人肉指挥每一步）
✅ "给 `calculate_total` 加上对负数输入的校验，负数就抛 ValueError，并更新对应的测试"（给目标，让它自己决定怎么改）
新手容易出于不安全感而微操，反而限制了它的能力。**给"做什么、做到什么标准"，不给"怎么一步步点"**。
## 第六步：读懂屏幕——工具调用、权限提示、四种模式
首个会话里，屏幕上会出现三样新东西，新手常被吓到。先看懂，就不慌了。
**① 工具调用（tool calls）**：你会看到类似 `⏺ Read(file_path: "utils.py")`、`⏺ Bash(command: "pytest")`、`⏺ Edit(...)` 这样的行。这是它在循环里"采取行动"的可视化。看到一堆工具调用**完全正常**——一个 bug 修复读几个文件、跑几次测试很常见，不是它"想太多"。
**② 权限提示（permission prompts）**：当它要做**修改类**操作（写文件、运行命令）时，会暂停问你"允许吗？"。只读操作（读文件、搜索）通常自动放行。这个提示就是上图的"权限门禁"——你的安全阀。
**③ 权限模式（用 Shift+Tab 切换）**：门禁的"严格度"可调。官方目前有四种主流模式：
| 模式 | 行为 | 适用场景 |
|---|---|---|
| **Default（逐个询问）** | 每个修改操作都暂停问你 | **新手默认就用这个** |
| **Accept Edits（自动接受编辑）** | 文件编辑自动放行，命令仍问 | 信任它的文件改动、加速 |
| **Plan Mode（计划模式）** | 只读和规划，绝不执行 | 想先看它打算怎么干再决定 |
| **Auto Mode（自动模式）** | 更安全地批量自动放行，带护栏 | 熟练后做长任务 |
> 进阶提示：还有一个 `--dangerously-skip-permissions`（俗称"YOLO 模式"）会移除**所有**护栏。Anthropic 在 2026 年 3 月推出的 **Auto Mode** 就是为了提供一个"更安全的替代品"——它在批量放行的同时保留一道权限门禁，比裸跑 YOLO 安全得多。**首个会话请不要碰这两者，老老实实用 Default。**
## 第七步：实战案例——从零跑通一个待办清单 CLI
现在把前面全部串起来，做一个**完整可运行**的首个会话。目标：用 Python 做一个能增删查的命令行待办工具。
**操作步骤：**
```bash
mkdir todo-cli && cd todo-cli
claude
```
进入会话后，**复制这段一次性发出去**（这是按第五步规则打磨过的好需求）：
```
用 Python 写一个命令行待办清单工具，文件名 todo.py，要求：
1. todo add '买牛奶' —— 增加一条任务
2. todo list —— 列出所有任务（带序号，未完成显示 [ ] 已完成显示 [x]）
3. todo done 1 —— 把第 1 条标记为完成
4. 数据持久化到同目录 todos.json
不依赖第三方库，只用标准库 json 和 sys。
写完后，自己运行这几条命令验证：
python todo.py add '买牛奶'
python todo.py add '写报告'
python todo.py list
python todo.py done 1
python todo.py list
把最终输出贴给我看。
```
**预期结果（你会观察到的代理循环）：**
1. **收集上下文**：它会发现这是个空目录，没有现成代码，直接进入新建。
2. **采取行动**：你会看到 `⏺ Write(file_path: "todo.py")` —— 此时权限门禁弹出，按 `y` 批准。它一次性写好整个脚本。
3. **验证结果**：你会看到一连串 `⏺ Bash(command: "python todo.py add '买牛奶'")`…… 它自己跑完五条命令。
4. **返回结果**：它把验证输出贴给你，你应该看到类似：
```
[ ] 1. 买牛奶
[ ] 2. 写报告
[x] 1. 买牛奶
[ ] 2. 写报告
```
如果输出对得上，**你的首个有效会话就闭环了**——你只发了一段需求，它自主完成了写代码、跑验证、回报结果的全过程。这就是代理式编程。
**继续练习（加深理解）：**
- 把 `done 1` 改成支持 `delete 1`（删除任务），看它怎么改、改完是否自验证。
- 故意给它一个会失败的命令（比如让它运行一个不存在的子命令），观察循环的"自我纠偏"——它会发现错误、读取脚本、修正、重跑。
**常见问题与解决：**
- *它写完没跑验证就交差了？* —— 你的需求里没要求它验证。回它一句："请运行 `python todo.py list` 给我看结果。"记住第五步规则二：**主动要验证**。
- *它编辑文件时反复弹权限，烦？* —— 信任后按 `a` 选"本次会话始终允许该类操作"，或切到 Accept Edits 模式。但首个会话建议保留默认，趁机熟悉它在做什么。
- *它跑到一半改错了方向？* —— 按 **Esc** 打断，重新给方向，别等它跑完。
## 第八步：新手 5 大常见误区与纠正
跑通首会话后，对照下面五条自检，把心智模型彻底固化：
1. **误区：把它当搜索引擎/聊天机器人**——只问知识不交任务。**纠正**：它最强项是"在你项目里动手"，多用"读/改/跑"，少用"百度一下"。
2. **误区：给模糊指令**——"帮我优化一下"。**纠正**：补上语言、文件、标准、验证方式（第五步四规则）。
3. **误区：不验证就收货**——它说"已完成"你就信。**纠正**：永远要它跑测试或运行程序给你看输出。
4. **误区：怕那一堆工具调用**——以为是出错了。**纠正**：工具调用是循环的正常心跳，读多了就有安全感。
5. **误区：要么全程微操、要么彻底撒手**。**纠正**：走中间路线——委派目标、放手执行、但在场监督、跑偏就 Esc。
---
## 延伸阅读
- **官方《How Claude Code works》**——agentic loop 三阶段的权威出处，读这一篇就能建立骨架。
- **官方《Permission modes》与《How we built Claude Code auto mode》（Anthropic 工程博客，2026-03）**——把"权限门禁"和 Auto Mode 的设计讲透。
- **本系列已发《终端零基础：三平台三形态装通 Claude Code》《首次认证配置：四套登录实测》**——补齐第四步跳过的安装与认证细节。
- **GitHub: helloianneo/claude-code-handbook（00-心智模型.md）**——社区整理的"从回车到回答的 7 个环节"心智地图，与本文互补。
## 训练营适用性评估
- **适用类型**：所有 Claude Code 入门类训练营的"开场第一课"；也适合作为"AI 编程通识"模块的认知铺垫。
- **预计教学时长**：**1.5–2 小时**（讲解心智模型与循环约 40 分钟，首会话实战约 60–80 分钟，误区自检与答疑约 20 分钟）。
- **学员产出验收**：每人独立跑通第七步的待办 CLI，并能用自己的话讲清"agentic loop 三阶段"与"四种权限模式的区别"。
- **前置衔接**：建议与本系列安装篇、认证篇组合成"入门三连"，本篇作为认知主线先行，安装/认证作为动手支撑紧随其后。
## 参考来源
1. [How Claude Code works — Claude Code Docs](https://code.claude.com/docs/en/how-claude-code-works) — 官方核心文档，agentic loop 三阶段（gather context / take action / verify results）、模型与工具、高效协作八原则的权威出处。
2. [How the agent loop works — Claude Code Docs](https://code.claude.com/docs/en/agent-sdk/agent-loop) — 官方对"评估→工具调用→观察→调整"执行循环的逐环节拆解，与 SDK 共用同一套机制。
3. [How we built Claude Code auto mode — Anthropic Engineering](https://www.anthropic.com/engineering/claude-code-auto-mode) — 2026 年 3 月官方工程博客，解释 Auto Mode 作为比 `--dangerously-skip-permissions` 更安全的"跳过权限"方案。
4. [Choose a permission mode — Claude Code Docs](https://code.claude.com/docs/en/permission-modes) — Default / Accept Edits / Plan / Auto 等权限模式的行为与 Shift+Tab 切换说明。
5. [Claude Code 新手教程：2026 完整入门指南 — 知乎](https://zhuanlan.zhihu.com/p/2025334640097994546) 与 [claude-code-handbook/00-心智模型.md — GitHub](https://github.com/helloianneo/claude-code-handbook/blob/main/00-%E5%BF%83%E6%99%BA%E6%A8%A1%E5%9E%8B.md) — 社区"从回车到回答的 7 个环节"心智地图，对补全工具 vs 代理工具的定位做了中文侧补充，与官方模型相互印证。
> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。
