## 概述 本教程是 Claude Code 系列的真正起点。和"装完立刻造一个东西"的速成路线不同，我们先花十分钟建立最关键的心智模型——**Agent 循环（agentic loop）**，搞懂 Claude Code 到底在终端里如何"思考"和"动手"，然后再去安装、登录、配置、跑通第一个真实工程。理解了循环，后面遇到权限弹窗、上下文压缩、工具选择，你都能自己解释清楚。 **适用人群**：从未用过 Claude Code 的开发者；装过但只会"问一句答一句"、还没体会到"代理"威力的同学；想给团队做入门培训的负责人。 **学完你能**：用一句话讲清 Claude Code 的工作原理；完成全平台安装与认证；写出第一份 `CLAUDE.md` 和 `settings.json` 权限规则；在 30 分钟内让 Claude Code 帮你从零交付一个可运行的小项目。 --- ## 前置条件 | 项目 | 要求 | 说明 | |------|------|------| | 操作系统 | macOS / Linux / Windows（含 WSL，推荐 WSL2）| Windows 原生也支持，建议装 Git for Windows 以使用 Bash 工具 | | 终端 | 任意现代终端 | iTerm2、Windows Terminal、系统自带 Terminal 均可 | | Node.js | 可选 | 原生安装器不依赖 Node；若用旧版 npm 安装方式才需要 Node 18+ | | 账号 | Claude Pro / Max / Team / Enterprise，或 Console（API 预付额度），或 Bedrock / Vertex / Foundry | 任选其一即可登录 | | 网络 | 能访问 `claude.ai` | 首次登录需浏览器跳转完成 OAuth | > 零基础提示：如果你不懂"代理（agent）"和"普通聊天机器人"的区别也没关系，下一节正是为消除这个概念门槛而写的。 --- ## 一、先懂原理：Claude Code 的 Agent 循环 很多新手把 Claude Code 当成"会写代码的 ChatGPT"——你问一句，它答一段。这种理解会严重低估它。官方文档开宗明义：**Claude Code 是一个运行在你终端里的代理式助手（agentic assistant）**。它和聊天机器人的本质区别，就在于它运行着一个**循环**。 ### 1.1 循环的三阶段 当你给 Claude 一个任务，它会循环往复地走三个阶段，且这三阶段是**融合**在一起的： 1. **收集上下文（gather context）**：搜索文件、读取代码、跑命令，搞清楚现状。 2. **采取行动（take action）**：编辑文件、运行脚本、安装依赖、提交代码。 3. **验证结果（verify results）**：重新跑测试、查看报错、确认改动是否生效。 关键点在于：**下一步做什么，取决于上一步学到的东西**。它会自我纠偏，把几十个动作串成一条链。一个"修 Bug"的任务，可能意味着：跑测试 → 读报错 → 搜相关源文件 → 读源码 → 改代码 → 再跑测试，如此循环到全绿。 而且，**你也是循环的一部分**。你随时可以打断（Esc）、补充信息、要求换个思路。它自主，但始终对你响应。 ```mermaid flowchart LR U([你下达任务]) --> G subgraph Loop[Agent 循环 三阶段融合] G[收集上下文
搜文件 读代码 跑命令] --> A[采取行动
编辑 执行 安装 提交] A --> V[验证结果
跑测试 看报错 确认] V -->|还有事要做| G end V -->|任务完成| D([返回最终结果]) U -.随时打断 补充 转向.-> Loop ``` ### 1.2 两个组件：模型 + 工具 官方把这个循环拆成两个支柱： - **模型（Models）**：负责推理——读懂代码、理解组件如何连接、判断该改哪里。多个模型可选：**Sonnet 适合绝大多数编码任务**，**Opus 用于复杂的架构推理**。会话中用 `/model` 切换，或启动时 `claude --model ` 指定。 - **工具（Tools）**：负责行动。没有工具，Claude 只能回文字；有了工具，它能读你的代码、改文件、跑命令、搜网页。**每一次工具调用都会把结果反馈回循环**，成为下一步决策的依据。 Claude Code 自己则扮演"代理外壳（harness）"：它在模型外面套上工具、上下文管理和执行环境，把一个语言模型变成真正能干活的编码代理。 > 这句最重要：**"Claude 选择""Claude 决定"，本质是模型在推理。** 理解了这一点，你才会明白为什么给它更好的上下文（更清晰的指令、更相关的文件），它就表现更好。 ### 1.3 工具的五大类 内置工具大致分成五类，每类代表一种不同的"能动性"： | 类别 | 能做什么 | |------|----------| | 文件操作 | 读文件、编辑代码、新建文件、重命名重组 | | 搜索 | 按模式找文件、用正则搜内容、探索代码库 | | 执行 | 跑 shell 命令、启动服务器、跑测试、用 git | | 网络 | 搜网页、抓文档、查错误信息 | | 代码智能 | 看类型错误、跳定义、查引用（需代码智能插件）| 此外还有编排类工具：生成子代理（subagent）、向你提问等。记住一个直觉：**工具 = 代理的手和眼**。 ### 1.4 它能访问什么 当你在某个目录里敲下 `claude`，Claude Code 就获得了对该范围资源的访问权： - **你的项目**：当前目录及子目录的文件（经你许可也能访问别处）。 - **你的终端**：任何你能在命令行做的事——构建工具、git、包管理器、系统工具、脚本。你能做的，它也能做。 - **你的 git 状态**：当前分支、未提交改动、近期提交历史。 - **你的 CLAUDE.md**：存放项目专属指令、约定、上下文的 Markdown 文件，**每次会话都会加载**。 - **自动记忆（Auto memory）**：工作时自动保存的习得，如项目模式和你的偏好。`MEMORY.md` 的前 200 行或 25KB（取先到者）会在每次会话开始时加载。 - **你配置的扩展**：MCP 服务器、skills、子代理、Chrome 扩展等。 > 概念门槛就在这里：正因为"你能做的它也能做"，所以**权限管理是入门必修课**。第五节会专门讲。 到这里，你已经比 80% 的新手更懂 Claude Code 了。下面正式动手。 --- ## 二、第一步：安装 Claude Code 官方强烈推荐**原生安装（Native Install）**，它会**后台自动更新**，省心。打开终端，按你的系统选一条命令： **macOS / Linux / WSL：** ```bash curl -fsSL https://claude.ai/install.sh | bash ``` **Windows PowerShell：** ```powershell irm https://claude.ai/install.ps1 | iex ``` **Windows CMD：** ```cmd curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd ``` **包管理器（备选）：** ```bash # macOS Homebrew（不自动更新，需手动 brew upgrade） brew install --cask claude-code # 稳定通道，约落后一周 brew install --cask claude-code@latest # 最新通道 # Windows WinGet（不自动更新） winget install Anthropic.ClaudeCode ``` > Homebrew 有两个 cask：`claude-code` 走稳定通道（通常落后约一周，跳过有重大回归的版本）；`claude-code@latest` 走最新通道，新版本一发就有。 **预期结果**：命令跑完后，终端输入 `claude --version` 能打印出版本号，例如： ``` 1.0.x (Claude Code) ``` ### 常见问题与排错 | 报错 | 原因与解决 | |------|------------| | `The token '&&' is not a valid statement separator` | 你在 PowerShell 里却用了 CMD 语法。PowerShell 提示符是 `PS C:\`，CMD 是 `C:\`。 | | `'irm' is not recognized` | 反过来——你在 CMD 里却用了 PowerShell 的 `irm`。 | | `syntax error near unexpected token '<'`、403 或其他 curl 错误 | 通常是网络代理/防火墙拦截，或被重定向到 HTML。挂代理重试，或查阅官方 Troubleshoot 页匹配修复方案。 | | Windows 上没有 Git for Windows | 建议装上，这样 Claude Code 才能使用 Bash 工具；否则它会退而用 PowerShell 作为 shell。WSL 不需要 Git for Windows。 | Debian / Fedora / RHEL / Alpine 用户也可以用 `apt`、`dnf`、`apk` 安装，命令见官方文档。 --- ## 三、第二步：登录认证 Claude Code 必须登录账号才能用。直接在终端启动： ```bash claude ``` 首次使用会引导你在浏览器里完成认证。支持的账号类型： - **Claude Pro / Max / Team / Enterprise（推荐）**：订阅制，适合个人与团队。 - **Claude Console（API）**：预付额度，按 token 计费；首次登录会在 Console 里自动创建一个 "Claude Code" 工作区用于集中成本追踪。 - **企业云**：Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry。 - **自托管网关**：若你的组织运行了 Claude apps gateway，管理员会预配好 URL，`/login` 会直接打开云网关页面，用企业 SSO 登录。 登录后凭据会安全存储在系统里，**之后无需重复登录**。要切换账号或重新认证，在运行中的会话里输入： ``` /login ``` > 预期结果：登录成功后回到终端，看到 Claude Code 的交互提示符，上方显示版本、当前模型、工作目录。 --- ## 四、第三步：首次会话与第一条提问 打开终端，进入任意项目目录后启动： ```bash cd /path/to/your/project claude ``` 你会看到提示符上方显示版本、模型、工作目录。输入 `/help` 看全部命令，`/resume` 继续之前的对话。 ### 第一条提问：让循环"只收集上下文" 最稳妥的破冰方式不是"帮我写个系统"，而是先让它**用循环的第一阶段读懂你的代码**： ``` > what does this project do? ``` Claude 会自主调度工具：用 Glob 找入口文件、用 Read 读 `README`/`package.json`/`pom.xml`、必要时用 Grep 搜关键字，然后给你一份总结。你会**亲眼看到循环在跑**——左边的工具调用流就是证据。 继续追问更具体的问题，观察它如何调整工具策略： ``` > what technologies does this project use? > where is the main entry point? > explain the folder structure ``` 甚至可以问它自己的能力： ``` > what can Claude Code do? > how do I create custom skills in Claude Code? ``` > 体会要点：同样是"读代码"，问"这个项目干嘛的"和问"`src/auth/login.ts` 里 token 怎么校验的"，它会用完全不同的工具组合。**你的问题越具体，上下文越精准，循环越高效。** 这是贯穿后续所有进阶用法的第一原则。 --- ## 五、第四步：配置体系入门（权限 + 记忆） 很多新手卡在两件事上：一是**频繁的权限弹窗**很烦，二是**每次都要重新交代项目背景**。这两件事正是配置体系要解决的。 ### 5.1 配置文件的三层结构 Claude Code 的配置是**分层的**，从外到内优先级递增（更内层的覆盖更外层）： | 层级 | 路径 | 用途 | 是否进版本库 | |------|------|------|--------------| | 用户级 | `~/.claude/settings.json` | 对你所有项目生效的偏好 | 否（在 home） | | 项目级 | `/.claude/settings.json` | 团队共享的规则、权限 | **是**（建议提交） | | 本地级 | `/.claude/settings.local.json` | 你个人的、不共享的覆盖 | 否（加进 .gitignore）| 记忆则通过 `CLAUDE.md`（项目指令，每次会话加载）和自动记忆 `MEMORY.md`（习得，前 200 行/25KB 自动加载）持久化。 ```mermaid flowchart TD Q[Claude 准备执行一个工具调用] --> P1{本地级 settings.local.json
有显式 allow/deny?} P1 -->|有 deny| BLOCK[拒绝执行] P1 -->|有 allow| RUN[直接执行] P1 -->|无| P2{项目级 settings.json} P2 -->|有 deny| BLOCK P2 -->|有 allow| RUN P2 -->|无| P3{用户级 settings.json} P3 -->|有 deny| BLOCK P3 -->|有 allow| RUN P3 -->|无| MODE{当前权限模式?} MODE -->|default| ASK[弹窗问你 yes/no] MODE -->|acceptEdits| AUTO_EDIT[自动放行编辑类] MODE -->|bypassPermissions / yolo| RUN ``` ### 5.2 写第一份权限规则 在项目根目录新建 `.claude/settings.json`，把"读多写少"场景里安全的命令提前放行，能极大减少弹窗： ```json { "permissions": { "allow": [ "Bash(npm test:*)", "Bash(npm run lint:*)", "Bash(git status)", "Bash(git diff:*)", "Bash(git log:*)", "Read(**/*)" ], "deny": [ "Read(**/.env*)", "Read(**/secrets/**)", "Bash(rm -rf:*)", "Bash(git push:*)" ] } } ``` **规则格式**：`工具名(参数模式)`，支持通配符 `*`。`deny` 永远优先于 `allow`，是安全底线。 > 实用习惯：当弹窗出现时选 **"always allow"**，对应规则会自动写进本地 settings——但你应定期把它**手工沉淀到项目级 settings.json**，让团队共享。 在会话里输入 `/permissions` 可以图形化查看和管理所有规则。 ### 5.3 四种权限模式 会话中按 `Shift+Tab` 可在模式间循环，或在配置里指定： | 模式 | 行为 | 适用 | |------|------|------| | `default` | 每个有副作用的工具调用都问你 | 新手起步、陌生代码库 | | `acceptEdits` | 自动放行文件编辑，命令仍问 | 信任的重构批量改 | | `plan` | 只规划不动手，先出方案再执行 | 复杂任务先对齐 | | `bypassPermissions`（俗称 yolo）| 全自动不问 | **危险**，仅在隔离环境/沙箱里用 | > 安全建议：入门阶段保持 `default`；只有在 Docker 容器、临时虚拟机等**可丢弃环境**里才用 `bypassPermissions`。 ### 5.4 写第一份 CLAUDE.md 在项目根目录新建 `CLAUDE.md`，把"每次都要交代一遍"的背景固化下来： ```markdown # 项目说明 这是一个 Python 命令行待办清单工具（todo.py）。 ## 技术栈 - Python 3.10+ - 仅用标准库，不引入第三方依赖 ## 约定 - 所有提交信息用中文 - 函数必须有 docstring - 改完代码必须跑 `python -m pytest` 验证 - 不要自动 git commit，等用户确认 ``` 这一份文件，每次会话自动加载，相当于给 Claude 一份"入职手册"。从此你不用每次重复说"用中文""别提交"。 --- ## 六、实战案例：让 Claude Code 交付第一个真实项目 理论够了，现在用一整轮**真实的 Agent 循环**交付一个可运行项目：一个 Python 待办清单 CLI（`todo.py`）。目标功能： - `python todo.py add "买菜"` —— 添加任务（持久化到 `tasks.json`） - `python todo.py list` —— 列出全部任务 - `python todo.py done 1` —— 把第 1 个任务标记完成 - `python todo.py rm 1` —— 删除第 1 个任务 ### 步骤 1：准备目录与 CLAUDE.md ```bash mkdir -p ~/projects/todo-cli && cd ~/projects/todo-cli claude ``` 把上一节的 `CLAUDE.md` 内容贴进文件（Claude Code 也会在 `/init` 时帮你生成雏形，可输入 `/init`）。 ### 步骤 2：下达一个具体任务 在会话里输入（注意有多具体——给了功能清单、文件名、数据格式）： ``` > 帮我创建 todo.py，实现一个命令行待办清单： - add "内容"：添加任务，存到同目录 tasks.json - list：列出所有任务，带编号、状态、内容 - done <编号>：标记完成 - rm <编号>：删除任务 每个函数写 docstring，完成后跑 `python todo.py add 测试` 和 `python todo.py list` 自检。 ``` ### 步骤 3：观察循环，必要时打断 你会看到 Claude 走完三阶段：先用 Write 创建 `todo.py`（行动），再用 Bash 跑 `python todo.py add 测试`（验证），读 `tasks.json` 确认（收集上下文），再跑 `list`（验证）。**这就是第一章的循环在你眼前真实上演。** 生成的 `todo.py` 核心结构大致如下（你可让 Claude 按需微调）： ```python """命令行待办清单工具，仅用标准库。""" import json import sys from pathlib import Path DATA_FILE = Path(__file__).parent / "tasks.json" def load_tasks(): """读取 tasks.json，文件不存在则返回空列表。""" if DATA_FILE.exists(): return json.loads(DATA_FILE.read_text(encoding="utf-8")) return [] def save_tasks(tasks): """把任务列表写回 tasks.json。""" DATA_FILE.write_text( json.dumps(tasks, ensure_ascii=False, indent=2), encoding="utf-8" ) def add(content): """新增一条待办，状态默认未完成。""" tasks = load_tasks() tasks.append({"content": content, "done": False}) save_tasks(tasks) print(f"已添加：{content}") def list_tasks(): """列出全部任务，含编号与状态。""" tasks = load_tasks() if not tasks: print("（空）") return for i, t in enumerate(tasks, 1): flag = "x" if t["done"] else " " print(f"{i}. [{flag}] {t['content']}") def toggle_done(num): """把第 num 个任务标记为完成。""" tasks = load_tasks() tasks[num - 1]["done"] = True save_tasks(tasks) print(f"已完成第 {num} 项") def remove(num): """删除第 num 个任务。""" tasks = load_tasks() removed = tasks.pop(num - 1) save_tasks(tasks) print(f"已删除：{removed['content']}") def main(): cmd = sys.argv[1] if len(sys.argv) > 1 else "list" if cmd == "add": add(sys.argv[2]) elif cmd == "list": list_tasks() elif cmd == "done": toggle_done(int(sys.argv[2])) elif cmd == "rm": remove(int(sys.argv[2])) else: print("用法: todo.py [add|list|done|rm] [参数]") if __name__ == "__main__": main() ``` ### 步骤 4：继续用循环加功能（验证你已掌握） 再下一句任务，体验"小步迭代"： ``` > 给 todo.py 加一个 clear 命令，清空所有已完成任务；改完跑自检。 ``` 观察它如何：读现有 `todo.py`（上下文）→ 编辑加函数与分支（行动）→ 跑命令自检（验证）。如果它忘了加进 `main()` 的分支，你打断（Esc）并提示："记得在 main() 里加 clear 分支。"——这就是第一章说的"你也是循环的一部分"。 ### 预期结果 ``` $ python todo.py add 买菜 已添加：买菜 $ python todo.py add 写周报 已添加：写周报 $ python todo.py list 1. [ ] 买菜 2. [ ] 写周报 $ python todo.py done 1 已完成第 1 项 $ python todo.py list 1. [x] 买菜 2. [ ] 写周报 ``` 到这里，你已经**亲手驱动了一轮完整的 Agent 循环**，从收集上下文到行动到验证，全部跑通。 --- ## 常见问题与排错（FAQ） | 问题 | 解决 | |------|------| | 跑着跑着 Claude 说"上下文已满/正在压缩" | 循环累积了太多工具输出。用 `/clear` 开新会话，或 `/compact` 手动压缩；长任务拆成子任务，必要时让子代理分担（见后续进阶教程）。| | 每次都要重复交代背景 | 没写 `CLAUDE.md`。在项目根目录建一份（见 5.4），下次自动加载。| | 弹窗太多太烦 | 把安全命令写进 `.claude/settings.json` 的 `allow`；或切到 `acceptEdits` 模式（`Shift+Tab`）。| | Claude 改完没跑测试 | 在 `CLAUDE.md` 里写死约定"改完必须跑 xxx"，它会遵守。| | 想换更强模型推理架构问题 | 会话内 `/model` 切到 Opus；日常用 Sonnet 即可。| | 误删了文件想回退 | 用 `/rewind` 或 checkpoint 回退；入门养成"重要改动前让它先开 git 分支"的习惯。| --- ## 完整工作流一览 把从安装到交付首项目串起来，整体路径如下： ```mermaid flowchart TD A[原生安装 claude.ai/install.sh] --> B[claude 首次登录认证] B --> C[cd 进入项目目录 启动 claude] C --> D[写 CLAUDE.md 与 settings.json 权限] D --> E[下达具体任务] E --> F{Agent 循环} F --> F1[收集上下文] F --> F2[采取行动] F --> F3[验证结果] F3 -->|未完成| F1 F3 -->|完成| G[查看产出 跑自检] G -->|需调整| E G -->|满意| H[交付首项目] ``` --- ## 延伸阅读 - **官方 How Claude Code works** — 三阶段循环、模型与工具的权威解释： - **官方 Agent Loop 详解** — 消息生命周期、工具执行、上下文窗口与架构： - **官方 Quickstart** — 分平台安装与登录步骤： - **官方 Permissions** — `/permissions` 与 allow/deny 规则： - **官方 Settings** — `settings.json` 分层与敏感文件保护： --- ## 训练营适用性评估 | 维度 | 评估 | |------|------| | 适合的训练营类型 | 全栈/后端/DevOps/AI 应用开发的**入门第一课**；企业新人入职技术培训；高校编程实践导论 | | 学员基础要求 | 会用命令行、有任意一门语言基础；零 AI 工具经验亦可 | | 预计教学时长 | **1.5–2 小时**（讲解 30 分钟 + 安装登录 20 分钟 + 配置与首项目实操 60 分钟）| | 建议课后作业 | 学员各自用 Claude Code 交付一个不同主题的 CLI 小工具（如记账、单词卡、单位换算），并提交自己的 `CLAUDE.md` 与 `settings.json` | | 与后续课程衔接 | 本课为后续 Skills 开发、MCP 服务器、子代理与自动化、上下文管理与性能优化打下**概念地基**——尤其是"循环 + 工具 + 权限"三件套的理解 | --- ## 参考来源 1. [How Claude Code works — Claude Code Docs](https://code.claude.com/docs/en/how-claude-code-works) — 官方对 Agent 循环三阶段、模型与工具双组件、访问范围的权威说明 2. [How the agent loop works — Claude Code Docs](https://code.claude.com/docs/en/agent-sdk/agent-loop) — 消息生命周期、工具执行、并行调用、上下文窗口与自动压缩的实现机制 3. [Quickstart — Claude Code Docs](https://code.claude.com/docs/en/quickstart) — 各平台原生安装命令、账号登录、首次会话的分步指引 4. [Configure permissions — Claude Code Docs](https://code.claude.com/docs/en/permissions) — `/permissions` 界面与 allow/deny 规则的官方说明 5. [The Complete .claude Directory Guide for Claude Code [2026] — ComputingForGeeks](https://computingforgeeks.com/claude-code-dot-claude-directory-guide/) — 第三方对 `.claude` 目录结构、CLAUDE.md 与分层配置的实践补充 > [!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 等场景全覆盖。