# 读懂智能体循环，跑通首个项目：Claude Code 零基础实战
## 概述
本教程面向**从未用过 Claude Code 的开发者**，目标是让你在 30 分钟内完成安装、登录，并跑通第一个真实项目。与"照着命令敲一遍"的传统入门不同，本教程的核心是帮你建立**心智模型**：Claude Code 不是一个聊天框，而是一个在终端里不断"收集上下文 → 采取行动 → 验证结果"的智能体（agent）。理解了这个循环，你就知道何时该等它自己探索、何时该打断纠偏、何时该放权、何时该收紧——这些判断能力，比记住任何一条命令都重要。学完你将能独立开始会话、完成代码改动、用对话式 Git 提交，并理解权限、上下文、会话续跑等关键概念。
## 前置条件
- **一台终端**：macOS、Linux，或 Windows 上的 WSL（强烈推荐，体验与原生 Linux 一致）。Windows 原生也支持，但建议先装 [Git for Windows](https://git-scm.com/downloads/win)，这样 Claude Code 才能用 Bash 工具。
- **一个账号**：Claude Pro / Max / Team / Enterprise 订阅，或 Claude Console（预付费额度）账号。订阅账号是首选。
- **一个项目目录**：哪怕只是一个空文件夹也行，本教程会带你从零创建一个 Flask API。
- **可选基础**：会基本的 `cd`、`ls` 命令即可，不要求精通命令行。
- **Node.js 不再是硬性要求**：2026 版 Claude Code 优先使用原生安装器，无需 Node。
## 第一部分：建立心智模型——三阶段智能体循环
在动手之前，先用 3 分钟理解 Claude Code 到底在做什么。这是本教程最值钱的部分。
当你给 Claude 一个任务（"修复登录 bug"），它不会立刻写代码，而是进入一个不断重复的循环，经历三个阶段：
1. **收集上下文（gather context）**：搜索文件、读代码、跑命令、看报错，搞清楚"现在是什么情况"。
2. **采取行动（take action）**：编辑文件、跑测试、装依赖、改配置。
3. **验证结果（verify results）**：重新跑测试、回看输出，确认改动是否真的生效。
这三个阶段相互交织，可以重复几十次。修一个 bug 的典型链路是：跑测试看到红 → 读错误 → 搜相关源文件 → 读源码 → 改代码 → 再跑测试看到绿。**每一步的产出都喂回循环，决定下一步做什么**，这就是"智能体"和"一次性问答"的本质区别。
```mermaid
flowchart LR
P([你的指令]) --> G[收集上下文
搜索/读文件/跑命令]
G --> A[采取行动
编辑/运行/装依赖]
A --> V[验证结果
跑测试/回看输出]
V -- 未完成,带新信息 --> G
V -- 完成 --> D([任务交付])
U([你:随时打断
补充/纠偏/换方向]) -.-> G
U -.-> A
U -.-> V
```
关键认知：**你也是循环的一部分**。你可以随时按 `Esc` 打断，补充上下文、否决某个方向、或让它换个思路。它高度自主，但始终对你的输入敏感。理解这一点，你就不会傻等它"瞎跑"，也不会事无巨细地微操。
循环由两样东西驱动：**模型**负责推理，**工具**负责行动。没有工具，Claude 只能输出文字；有了工具（读写文件、搜索、执行命令、联网），它才成为能干活的代理。2026 版还支持用 Skills、MCP、Hooks、子代理进一步扩展，但这些都是在核心循环之上叠加的能力，本入门篇先不展开。
## 第二部分：安装与登录
### 步骤 1：选择安装方式
2026 年官方推荐**原生安装器**，零依赖、自动后台更新：
```bash
# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash
```
```powershell
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
```
如果你习惯包管理器，也可以：
```bash
brew install --cask claude-code # macOS，注意：默认不自动更新
winget install Anthropic.ClaudeCode # Windows
```
> **Homebrew 双通道**：`claude-code` 跟稳定版（约落后一周，跳过有重大回归的版本）；`claude-code@latest` 跟最新版。手动更新用 `brew upgrade claude-code` 或 `brew upgrade claude-code@latest`。
Linux 用户还可通过 `apt`（Debian/Ubuntu）、`dnf`（Fedora/RHEL）、`apk`（Alpine）安装。npm 依然可用（`npm install -g @anthropic-ai/claude-code`），适合需要钉版本号的企业环境，但 npm 全局目录若不可写会无法自动更新，启动时会有一次性提示。
**预期结果**：安装完成后运行 `claude --version` 能打印出版本号。
### 步骤 2：健康检查
装完先跑一次自检：
```bash
claude doctor
```
`claude doctor` 会检查安装是否完整、能否联网、权限与依赖是否正常，并给出修复建议。这是排查"装了但跑不起来"的第一利器。
### 步骤 3：首次登录
在任意目录输入：
```bash
claude
```
首次启动会引导你在浏览器里完成登录。如果你用订阅账号，按提示走完 OAuth 即可；之后凭证会存在本地，**无需重复登录**。想切换账号或重新认证，在会话里输入 `/login`。支持四种账号来源：Claude 订阅、Console（首次登录会自动建一个名为 "Claude Code" 的 Workspace 用于成本汇总）、Amazon Bedrock / Google Vertex / Microsoft Foundry 等企业云，以及组织自建的 Claude apps gateway。
**常见问题**：
- **Windows 报 `The token '&&' is not a valid statement separator`**：你在 PowerShell 里却用了 CMD 语法。PowerShell 提示符有 `PS` 前缀。
- **报 `'irm' is not recognized`**：反过来，你在 CMD 里却用了 PowerShell 命令。
- **curl 报 `syntax error near unexpected token '<'` 或 403**：多半是网络代理/防火墙拦截或脚本被网关改写，去官方"安装排错"页对照错误码。
- **Alpine 上 ripgrep 缺失**：先 `apk add libgcc libstdc++ ripgrep`，再在 `settings.json` 里设 `"env": { "USE_BUILTIN_RIPGREP": "0" }`。
## 第三部分：第一个会话——让 Claude 先"看懂"项目
### 步骤 4：进入项目并启动
```bash
cd /path/to/your/project
claude
```
启动后，提示符上方会显示**版本号、当前模型、工作目录**。输入 `/help` 看全部命令，`/resume` 恢复之前的对话。此刻你已进入交互式会话。
### 步骤 5：从"提问"开始，而非"下命令"
新手最常犯的错：一上来就 "fix the bug"。更好的做法是**先让它建立上下文**，这正好对应循环的"收集"阶段。试试：
```text
这个项目是做什么的？
项目用了哪些技术栈？
主入口文件在哪？
解释一下目录结构
```
Claude 会按需读取你的文件（你**不必手动喂上下文**），用一两段话给你答案。这一步的价值在于：你既验证了它能正常工作，也为后续改动铺好了认知基础。
### 步骤 6：掌握 4 个必会会话命令
| 命令 | 作用 | 何时用 |
| --- | --- | --- |
| `/help` | 列出所有命令和技能 | 忘了有什么能用时 |
| `/model` | 切换模型（Sonnet / Opus 等） | Sonnet 够用；复杂架构决策上 Opus |
| `/context` | 查看上下文窗口被什么占用 | 对话变长、想清理时 |
| `/clear` | 清空当前对话历史 | 换主题、重置时 |
**权限模式**是另一个关键。按 `Shift+Tab` 会在三种模式间循环：默认逐次确认、自动接受（Accept）、计划模式（只规划不执行）。新手建议先用默认模式，看清楚每一步再批准，熟了再放权。
## 第四部分：第一次代码改动——在循环中协作
### 步骤 7：下一个小任务
```text
add a hello world function to the main file
```
Claude Code 会：定位文件 → 展示拟议改动 → **请求你批准** → 执行编辑。**它永远在改文件前征求许可**。你可以逐条批准，或对整个会话开启 "Accept all"。
### 步骤 8：打断、纠偏、回滚
- **打断**：看到它走偏方向，立刻 `Esc`，补充信息或换思路。这正是循环里"你"的职责。
- **回滚（checkpoint）**：Claude 在改动文件前会对受影响文件做快照，存在 `~/.claude/projects/` 下的 JSONL 记录里。改坏了可以用 rewind 恢复，让你敢于放手让它试。
**常见问题**：
- **它一直问要不要执行**：觉得烦就 `Shift+Tab` 切到 Accept 模式（仅在信任的项目里）。
- **它反复在同一个文件上改不对**：`Esc` 打断，明确告诉它"先只读不改，把 X 的逻辑讲给我听"，让它先回到"收集"阶段。
## 第五部分：对话式 Git 与会话管理
Claude Code 让 Git 操作变成自然语言：
```text
我改了哪些文件？
用一条描述性信息提交我的改动
新建一个分支叫 feature/quickstart
帮我解决合并冲突
```
会话本身也有生命周期管理：
```bash
claude -c # 继续当前目录最近一次对话
claude -r # 从历史会话列表里挑一个恢复
claude "fix build" # 一次性任务,跑完退出
claude -p "解释这个函数" # 查询模式,输出后退出,适合脚本
```
恢复（resume/`--continue`）会在**同一个会话 ID 下追加消息**；分叉（`--fork-session` 或 `/branch`）则把历史复制到一个新会话，原会话不变——适合"我想基于刚才的成果试两条不同路线"。
> **并行会话**：每个会话绑定一个目录。用 `git worktree` 给不同分支各建一个目录，就能同时开多个 Claude 会话并行干活，互不干扰。
## 实战案例：一个会话跑通 Flask 待办 API
现在把整条循环走一遍。目标是零到跑通一个带测试的 Flask 待办事项 API。
### 准备空目录
```bash
mkdir todo-api && cd todo-api
python3 -m venv .venv && source .venv/bin/activate
claude
```
### 第一轮对话：让它建项目骨架（收集 → 行动 → 验证）
```text
用 Python + Flask 建一个待办事项 REST API。
要求:
1. 支持 GET /tasks 返回所有任务
2. 支持 POST /tasks 创建任务(带 title)
3. 数据先用内存列表存
4. 用 requirements.txt 管理依赖
5. 写一个用 pytest 的测试文件
```
**预期结果**：Claude 会先（收集）确认 Python 版本、检查目录是否为空，然后（行动）创建 `app.py`、`requirements.txt`、`test_app.py`，接着（验证）自动 `pip install flask pytest` 并跑测试。你会在终端看到类似：
```text
✓ 创建 app.py
✓ 创建 requirements.txt
✓ 创建 test_app.py
$ pip install flask pytest
$ pytest
===== 2 passed in 0.4s =====
```
期间每写一个文件都请你批准——这是你观察循环的最佳时机。
### 第二轮对话：真实验证——把服务跑起来并请求
```text
启动服务,然后用 curl 验证 GET 和 POST 都能用,把结果给我看
```
**预期输出**（Claude 自己起后台进程 + 发请求）：
```text
$ python app.py & (后台启动,端口 5000)
$ curl -s localhost:5000/tasks
[]
$ curl -s -X POST localhost:5000/tasks -H "Content-Type: application/json" -d '{"title":"学完本教程"}'
{"id":1,"title":"学完本教程"}
$ curl -s localhost:5000/tasks
[{"id":1,"title":"学完本教程"}]
```
这就是一次完整的循环：收集（看代码现状）→ 行动（启动、发请求）→ 验证（确认输出符合预期）。**它替你把"我改完到底跑没跑通"这件事做实了**，这正是智能体相比补全工具的核心价值。
### 第三轮对话：加功能 + 测试驱动
```text
加一个 DELETE /tasks/ 删除任务,并先写测试再实现,跑通给我看
```
Claude 会先补一条失败的测试（红），再实现端点（绿），最后重跑全套测试确认没回归。整个过程你只需在每一步点头批准。
### 第四轮对话：写进项目记忆并提交
```text
帮我生成 CLAUDE.md,记录这个项目的运行方式(怎么装依赖、怎么跑、怎么测),然后把这些改动用一条清晰的 commit 提交
```
`CLAUDE.md` 是项目专属记忆文件，每次会话开头都会自动加载，相当于给 Claude 一份"项目说明书"。提交完成后用 `git log --oneline` 能看到一条规范的消息。
**常见问题**：
- **端口 5000 被占用**：让它改成 5001，并同步改测试里访问的地址。
- **它没自动跑测试**：明确说"改完后请运行 pytest 并把结果给我"。
- **上下文变长变慢**：`/context` 看占用，必要时 `/clear` 开新会话，重要规则写进 `CLAUDE.md`。
## 整体工作流全景
下面这张图把"安装到跑通首项目"的完整路径串起来：
```mermaid
flowchart TD
A[安装: install.sh / brew / winget] --> B[claude doctor 健康检查]
B --> C[首次 claude 登录账号]
C --> D[cd 进入项目目录]
D --> E[/claude 启动会话/]
E --> F[提问阶段: 让它先看懂项目]
F --> G[下任务: 改动/功能/修 bug]
G --> H{批准工具调用?}
H -- 是 --> I[执行 + 验证]
H -- 否 --> J[Esc 打断, 补充上下文]
J --> G
I --> K{满意?}
K -- 否 --> J
K -- 是 --> L[对话式 Git 提交]
L --> M[生成/更新 CLAUDE.md 记忆]
M --> N[claude -c / -r 续跑或收工]
```
## 常见问题 FAQ
- **每个会话彼此独立吗？** 是的，新会话是全新上下文，不继承历史对话。要跨会话保留信息，靠 `CLAUDE.md`（你手写的项目记忆）和自动记忆（Claude 自己存的学习，MEMORY.md 前 200 行或 25KB 会自动加载）。
- **它能看到我整个项目吗？** 默认看当前目录及子目录；要它读别处的文件需你授权。这也是它能跨多文件协调改动的根本原因。
- **代码会在云端跑吗？** 默认在你本机（Local）。另有 Cloud（Anthropic 托管 VM，适合卸载任务或跑你本地没有的仓库）和 Remote Control（本机执行、浏览器操控）两种环境，循环逻辑完全相同。
- **自动更新会不会打断我？** 原生安装在后台下载，下次启动 Claude Code 时生效，不打断当前会话。Homebrew/WinGet/Linux 包管理器需手动更新。
- **怕它乱删文件？** 默认逐次审批 + 改动前快照 + 可用 rewind，三重保险。新手务必先用默认权限模式。
## 延伸阅读
- **官方快速入门**：`code.claude.com/docs/en/quickstart` —— 本教程的主要骨架来源。
- **工作原理（agentic loop）**：`code.claude.com/docs/en/how-claude-code-works` —— 深入理解三阶段循环与五大工具类别。
- **最佳实践**：`code.claude.com/docs/en/best-practices` —— 如何写更好的 prompt、如何搭建项目。
- **配置与安装排错**：`code.claude.com/docs/en/setup` —— 含 `settings.json`、`claude doctor`、自动更新通道等。
- **记忆机制**：`code.claude.com/docs/en/memory` —— CLAUDE.md 与自动记忆的完整说明。
## 训练营适用性评估
- **适合类型**：开发者入门营 / AI 编程启蒙营 / 企业内部"AI 提效"培训的第一课。强调心智模型而非命令罗列，特别适合"会用 IDE 但没接触过命令行 AI 工具"的初中级开发者。
- **教学时长**：建议 **1 个半天（约 3–4 小时）**：前 30 分钟讲循环心智模型，1.5 小时跟做安装+首个会话，1 小时完成 Flask 实战案例并提交，剩余时间做权限模式对比与答疑。
- **前置作业**：学员自带笔记本，提前注册好 Claude 订阅账号，装好系统终端环境。Windows 学员建议预装 WSL + Git。
- **进阶衔接**：本篇是入口。后续可接 CLAUDE.md 项目记忆、Skills 自定义技能、MCP 外部工具接入、Hooks 自动化护栏等主题，分别对应技能树的不同分支。
- **风险点**：API/订阅成本——实战环节会真实调用模型，建议提前估算人均 token 用量；权限模式演示要强调"默认逐次审批"，避免学员误开 Accept 造成意外改动。
## 参考来源
1. [Claude Code 官方快速入门 (Quickstart)](https://code.claude.com/docs/en/quickstart) — 安装、登录、首个会话、首次改动、Git 协作的官方权威步骤，本教程主体流程来源。
2. [How Claude Code works（工作原理）](https://code.claude.com/docs/en/how-claude-code-works) — 三阶段智能体循环、五大工具类别、会话与上下文窗口机制的官方解释，心智模型部分来源。
3. [How to Install Claude Code: Complete Setup Guide (2026) — NxCode](https://www.nxcode.io/resources/news/install-claude-code-setup-guide-2026) — 2026 年第三方完整安装指南，覆盖原生安装器与 npm 两种方式、系统要求与 API key 设置，安装细节交叉验证来源。
4. [Claude Code Setup & Configuration（官方配置）](https://code.claude.com/docs/en/setup) — 原生安装器、Homebrew/WinGet/Linux 包管理器、`claude doctor`、自动更新通道与 `settings.json` 环境变量配置。
5. [Claude Code Tutorial for Beginners 2026 — Dev.to](https://dev.to/ayyazzafar/claude-code-tutorial-for-beginners-2026-from-installation-to-building-your-first-project-1lma) — 从安装到构建首个项目的第三方新手教程，提供首项目实战角度的补充参考。
> [!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 等场景全覆盖。
