首页 › tutorials › 读懂智能体循环，跑通首个项目

读懂智能体循环，跑通首个项目：Claude Code 零基础实战

概述

本教程面向从未用过 Claude Code 的开发者，目标是让你在 30 分钟内完成安装、登录，并跑通第一个真实项目。与"照着命令敲一遍"的传统入门不同，本教程的核心是帮你建立心智模型：Claude Code 不是一个聊天框，而是一个在终端里不断"收集上下文 → 采取行动 → 验证结果"的智能体（agent）。理解了这个循环，你就知道何时该等它自己探索、何时该打断纠偏、何时该放权、何时该收紧——这些判断能力，比记住任何一条命令都重要。学完你将能独立开始会话、完成代码改动、用对话式 Git 提交，并理解权限、上下文、会话续跑等关键概念。

前置条件

一台终端：macOS、Linux，或 Windows 上的 WSL（强烈推荐，体验与原生 Linux 一致）。Windows 原生也支持，但建议先装 Git for Windows，这样 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"），它不会立刻写代码，而是进入一个不断重复的循环，经历三个阶段：

收集上下文（gather context）：搜索文件、读代码、跑命令、看报错，搞清楚"现在是什么情况"。
采取行动（take action）：编辑文件、跑测试、装依赖、改配置。
验证结果（verify results）：重新跑测试、回看输出，确认改动是否真的生效。

这三个阶段相互交织，可以重复几十次。修一个 bug 的典型链路是：跑测试看到红 → 读错误 → 搜相关源文件 → 读源码 → 改代码 → 再跑测试看到绿。每一步的产出都喂回循环，决定下一步做什么，这就是"智能体"和"一次性问答"的本质区别。

flowchart LR
    P([你的指令]) --> G[收集上下文<br/>搜索/读文件/跑命令]
    G --> A[采取行动<br/>编辑/运行/装依赖]
    A --> V[验证结果<br/>跑测试/回看输出]
    V -- 未完成,带新信息 --> G
    V -- 完成 --> D([任务交付])
    U([你:随时打断<br/>补充/纠偏/换方向]) -.-> G
    U -.-> A
    U -.-> V

关键认知：你也是循环的一部分。你可以随时按 Esc 打断，补充上下文、否决某个方向、或让它换个思路。它高度自主，但始终对你的输入敏感。理解这一点，你就不会傻等它"瞎跑"，也不会事无巨细地微操。

循环由两样东西驱动：模型负责推理，工具负责行动。没有工具，Claude 只能输出文字；有了工具（读写文件、搜索、执行命令、联网），它才成为能干活的代理。2026 版还支持用 Skills、MCP、Hooks、子代理进一步扩展，但这些都是在核心循环之上叠加的能力，本入门篇先不展开。

第二部分：安装与登录

步骤 1：选择安装方式

2026 年官方推荐原生安装器，零依赖、自动后台更新：

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

如果你习惯包管理器，也可以：

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：健康检查

装完先跑一次自检：

claude doctor

claude doctor 会检查安装是否完整、能否联网、权限与依赖是否正常，并给出修复建议。这是排查"装了但跑不起来"的第一利器。

步骤 3：首次登录

在任意目录输入：

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：进入项目并启动

cd /path/to/your/project
claude

启动后，提示符上方会显示版本号、当前模型、工作目录。输入 /help 看全部命令，/resume 恢复之前的对话。此刻你已进入交互式会话。

步骤 5：从"提问"开始，而非"下命令"

新手最常犯的错：一上来就 "fix the bug"。更好的做法是先让它建立上下文，这正好对应循环的"收集"阶段。试试：

这个项目是做什么的？
项目用了哪些技术栈？
主入口文件在哪？
解释一下目录结构

Claude 会按需读取你的文件（你不必手动喂上下文），用一两段话给你答案。这一步的价值在于：你既验证了它能正常工作，也为后续改动铺好了认知基础。

步骤 6：掌握 4 个必会会话命令

命令	作用	何时用
`/help`	列出所有命令和技能	忘了有什么能用时
`/model`	切换模型（Sonnet / Opus 等）	Sonnet 够用；复杂架构决策上 Opus
`/context`	查看上下文窗口被什么占用	对话变长、想清理时
`/clear`	清空当前对话历史	换主题、重置时

权限模式是另一个关键。按 Shift+Tab 会在三种模式间循环：默认逐次确认、自动接受（Accept）、计划模式（只规划不执行）。新手建议先用默认模式，看清楚每一步再批准，熟了再放权。

第四部分：第一次代码改动——在循环中协作

步骤 7：下一个小任务

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 操作变成自然语言：

我改了哪些文件？
用一条描述性信息提交我的改动
新建一个分支叫 feature/quickstart
帮我解决合并冲突

会话本身也有生命周期管理：

claude -c          # 继续当前目录最近一次对话
claude -r          # 从历史会话列表里挑一个恢复
claude "fix build" # 一次性任务,跑完退出
claude -p "解释这个函数"  # 查询模式,输出后退出,适合脚本

恢复（resume/--continue）会在同一个会话 ID 下追加消息；分叉（--fork-session 或 /branch）则把历史复制到一个新会话，原会话不变——适合"我想基于刚才的成果试两条不同路线"。

并行会话：每个会话绑定一个目录。用 git worktree 给不同分支各建一个目录，就能同时开多个 Claude 会话并行干活，互不干扰。

实战案例：一个会话跑通 Flask 待办 API

现在把整条循环走一遍。目标是零到跑通一个带测试的 Flask 待办事项 API。

准备空目录

mkdir todo-api && cd todo-api
python3 -m venv .venv && source .venv/bin/activate
claude

第一轮对话：让它建项目骨架（收集 → 行动 → 验证）

用 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 并跑测试。你会在终端看到类似：

✓ 创建 app.py
✓ 创建 requirements.txt
✓ 创建 test_app.py
$ pip install flask pytest
$ pytest
===== 2 passed in 0.4s =====

期间每写一个文件都请你批准——这是你观察循环的最佳时机。

第二轮对话：真实验证——把服务跑起来并请求

启动服务,然后用 curl 验证 GET 和 POST 都能用,把结果给我看

预期输出（Claude 自己起后台进程 + 发请求）：

$ 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":"学完本教程"}]

这就是一次完整的循环：收集（看代码现状）→ 行动（启动、发请求）→ 验证（确认输出符合预期）。它替你把"我改完到底跑没跑通"这件事做实了，这正是智能体相比补全工具的核心价值。

第三轮对话：加功能 + 测试驱动

加一个 DELETE /tasks/<id> 删除任务,并先写测试再实现,跑通给我看

Claude 会先补一条失败的测试（红），再实现端点（绿），最后重跑全套测试确认没回归。整个过程你只需在每一步点头批准。

第四轮对话：写进项目记忆并提交

帮我生成 CLAUDE.md,记录这个项目的运行方式(怎么装依赖、怎么跑、怎么测),然后把这些改动用一条清晰的 commit 提交

CLAUDE.md 是项目专属记忆文件，每次会话开头都会自动加载，相当于给 Claude 一份"项目说明书"。提交完成后用 git log --oneline 能看到一条规范的消息。

常见问题：

端口 5000 被占用：让它改成 5001，并同步改测试里访问的地址。
它没自动跑测试：明确说"改完后请运行 pytest 并把结果给我"。
上下文变长变慢：/context 看占用，必要时 /clear 开新会话，重要规则写进 CLAUDE.md。

整体工作流全景

下面这张图把"安装到跑通首项目"的完整路径串起来：

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，三重保险。新手务必先用默认权限模式。

训练营适用性评估

适合类型：开发者入门营 / AI 编程启蒙营 / 企业内部"AI 提效"培训的第一课。强调心智模型而非命令罗列，特别适合"会用 IDE 但没接触过命令行 AI 工具"的初中级开发者。
教学时长：建议 1 个半天（约 3–4 小时）：前 30 分钟讲循环心智模型，1.5 小时跟做安装+首个会话，1 小时完成 Flask 实战案例并提交，剩余时间做权限模式对比与答疑。
前置作业：学员自带笔记本，提前注册好 Claude 订阅账号，装好系统终端环境。Windows 学员建议预装 WSL + Git。
进阶衔接：本篇是入口。后续可接 CLAUDE.md 项目记忆、Skills 自定义技能、MCP 外部工具接入、Hooks 自动化护栏等主题，分别对应技能树的不同分支。
风险点：API/订阅成本——实战环节会真实调用模型，建议提前估算人均 token 用量；权限模式演示要强调"默认逐次审批"，避免学员误开 Accept 造成意外改动。

参考来源

Claude Code 官方快速入门 (Quickstart) — 安装、登录、首个会话、首次改动、Git 协作的官方权威步骤，本教程主体流程来源。
How Claude Code works（工作原理） — 三阶段智能体循环、五大工具类别、会话与上下文窗口机制的官方解释，心智模型部分来源。
How to Install Claude Code: Complete Setup Guide (2026) — NxCode — 2026 年第三方完整安装指南，覆盖原生安装器与 npm 两种方式、系统要求与 API key 设置，安装细节交叉验证来源。
Claude Code Setup & Configuration（官方配置） — 原生安装器、Homebrew/WinGet/Linux 包管理器、claude doctor、自动更新通道与 settings.json 环境变量配置。
Claude Code Tutorial for Beginners 2026 — Dev.to — 从安装到构建首个项目的第三方新手教程，提供首项目实战角度的补充参考。

[!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 等场景全覆盖。

51学通信知识星球海报-扫码加入

读懂智能体循环，跑通首个项目：Claude Code 零基础实战

概述

前置条件

第一部分：建立心智模型——三阶段智能体循环

第二部分：安装与登录

步骤 1：选择安装方式

步骤 2：健康检查

步骤 3：首次登录

第三部分：第一个会话——让 Claude 先"看懂"项目

步骤 4：进入项目并启动

步骤 5：从"提问"开始，而非"下命令"

步骤 6：掌握 4 个必会会话命令

第四部分：第一次代码改动——在循环中协作

步骤 7：下一个小任务

步骤 8：打断、纠偏、回滚

第五部分：对话式 Git 与会话管理

实战案例：一个会话跑通 Flask 待办 API

准备空目录

第一轮对话：让它建项目骨架（收集 → 行动 → 验证）

第二轮对话：真实验证——把服务跑起来并请求

第三轮对话：加功能 + 测试驱动

第四轮对话：写进项目记忆并提交

整体工作流全景

常见问题 FAQ

延伸阅读

训练营适用性评估

参考来源

📎 本分类最新文章