本教程面向第一次接触 Claude Code 的零基础开发者，目标是帮你在打开终端的第一分钟就建立起正确的"代理式编程"心智模型：理解它和传统代码补全工具的本质区别、读懂屏幕上正在发生的代理循环、学会提出一个能被自主执行的好需求，并亲手跑通第一个真实会话。完成本教程后，你不再把 Claude Code 当搜索引擎，而把它当成一个会读你的代码、会动手改文件、会自己跑验证的工程搭档。
cd、ls 即可）很多新手把它和 GitHub Copilot、Cursor 自动补全混为一谈，于是一上来就用错姿势。先建立这个核心区分，后面的一切才说得通。
补全工具（Copilot 式）的工作单位是"光标位置的下一行"。它嵌在 IDE 里，盯着你正在敲的字符，预测你接下来要写什么，按 Tab 就补上。它的本质是一个被动的、局部的、即时的预测器——你不敲，它不动；它看不见你光标三屏之外发生了什么。
Claude Code 的工作单位是"一个完整的目标"。它住在终端里，直接连接你的代码库，能读整个项目结构、能跨几十个文件行动、能自己运行命令看结果、能在失败后自己调整再来。它的本质是一个主动的、全局的、多步的执行体——你给它一个目标，它自己规划路线、调用工具、验证成果。
| 维度 | 补全副驾（Copilot） | 代理执行体（Claude Code） |
|---|---|---|
| 触发方式 | 你敲代码，它预测下一行 | 你描述目标，它自主推进 |
| 作用范围 | 当前光标附近 | 整个项目、跨文件 |
| 时间跨度 | 毫秒级即时 | 分钟级、可链式几十步 |
| 你的角色 | 一边写一边按 Tab | 描述目标 + 审查结果 + 随时纠偏 |
| 典型场景 | 日常补全、模板生成 | 修 bug、重构、新增功能、解释代码 |
一句话记住区别：补全工具增强你的"打字"，Claude Code 增强你的"决策与执行"。所以正确用法不是"边写边问"，而是"先想清楚要什么，再一次性交给它，然后审查"。这个思维切换，是首个会话成败的分水岭。
理解 Claude Code，只需要抓住一个模型：代理循环（agentic loop）。Anthropic 官方文档把它概括为三个不断交织的阶段：
关键在于这三阶段会反复循环，而不是走一遍就结束。官方原话是这样描述的：
"当你给 Claude 一个任务，它会经历三个阶段：收集上下文、采取行动、验证结果……一个关于代码库的问题可能只需要收集上下文；一个 bug 修复会反复经历全部三个阶段；一次重构可能涉及大量验证。Claude 根据上一步学到的东西决定下一步做什么，把几十个动作串接起来，并沿途自我纠偏。"
这就是为什么它有时快（纯问答，只收集上下文就答）、有时慢（改一行 bug，却要读文件、改文件、跑测试、发现测试挂了、再改、再跑）。慢不是卡住了，是它在循环里自我纠偏——这正是它比补全工具强大的地方。
下面这张图把循环、你的介入点、以及权限门禁画在一起，请边看边对照后面的步骤：
flowchart TD
You([你：描述一个目标]) --> Loop
subgraph Loop[agentic loop 代理循环]
G[1. 收集上下文<br/>读文件/搜索/理解]
A[2. 采取行动<br/>编辑/运行/安装]
V[3. 验证结果<br/>跑测试/对照目标]
G --> A --> V
V -->|没达目标| G
V -->|达到目标| Done([返回结果给你])
end
You -.随时可打断/纠偏.-> Loop
A -->|修改类操作| Gate{权限门禁<br/>询问/自动接受/计划/自动/绕过}
Gate -->|你批准或模式允许| A2[真正写入磁盘]
代理循环里最容易被新手忽略的一点：你始终在这个循环里。官方把这条实践列为首要原则——"It's a conversation"和"Interrupt and steer"。
具体来说，循环跑起来后你随时可以：
新手最常犯的错误是把它当单向命令执行器——丢一句话就走开等结果。正确做法是像带新人一样全程在场：给它方向、在它跑偏时及时拽回来。它自主性强，但对你的反馈响应也快。这种"放手但有监督"的状态，才是代理式编程的常态。
这部分只做最小准备，详细的安装/认证/配置在三篇延伸阅读里已讲透，这里不重复。
# 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。这是首个会话成败的核心。同样的目标，两种问法，效果天差地别。官方把高质量交互总结成几条原则，我翻译成新手可直接照做的规则：
规则一：一次给清楚完整的目标（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。
现在把前面全部串起来，做一个完整可运行的首个会话。目标：用 Python 做一个能增删查的命令行待办工具。
操作步骤：
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
把最终输出贴给我看。
预期结果（你会观察到的代理循环）：
⏺ Write(file_path: "todo.py") —— 此时权限门禁弹出，按 y 批准。它一次性写好整个脚本。⏺ Bash(command: "python todo.py add '买牛奶'")…… 它自己跑完五条命令。[ ] 1. 买牛奶
[ ] 2. 写报告
[x] 1. 买牛奶
[ ] 2. 写报告
如果输出对得上，你的首个有效会话就闭环了——你只发了一段需求，它自主完成了写代码、跑验证、回报结果的全过程。这就是代理式编程。
继续练习（加深理解）：
- 把 done 1 改成支持 delete 1（删除任务），看它怎么改、改完是否自验证。
- 故意给它一个会失败的命令（比如让它运行一个不存在的子命令），观察循环的"自我纠偏"——它会发现错误、读取脚本、修正、重跑。
常见问题与解决：
python todo.py list 给我看结果。"记住第五步规则二：主动要验证。a 选"本次会话始终允许该类操作"，或切到 Accept Edits 模式。但首个会话建议保留默认，趁机熟悉它在做什么。跑通首会话后，对照下面五条自检，把心智模型彻底固化：
--dangerously-skip-permissions 更安全的"跳过权限"方案。[!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 等场景全覆盖。