概述

本教程是 Claude Code 系列的真正起点。和"装完立刻造一个东西"的速成路线不同，我们先花十分钟建立最关键的心智模型——Agent 循环（agentic loop），搞懂 Claude Code 到底在终端里如何"思考"和"动手"，然后再去安装、登录、配置、跑通第一个真实工程。理解了循环，后面遇到权限弹窗、上下文压缩、工具选择，你都能自己解释清楚。

适用人群：从未用过 Claude Code 的开发者；装过但只会"问一句答一句"、还没体会到"代理"威力的同学；想给团队做入门培训的负责人。

学完你能：用一句话讲清 Claude Code 的工作原理；完成全平台安装与认证；写出第一份 CLAUDE.md 和 settings.json 权限规则；在 30 分钟内让 Claude Code 帮你从零交付一个可运行的小项目。

前置条件

零基础提示：如果你不懂"代理（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）、补充信息、要求换个思路。它自主，但始终对你响应。

flowchart LR
    U([你下达任务]) --> G
    subgraph Loop[Agent 循环 三阶段融合]
        G[收集上下文<br/>搜文件 读代码 跑命令] --> A[采取行动<br/>编辑 执行 安装 提交]
        A --> V[验证结果<br/>跑测试 看报错 确认]
        V -->|还有事要做| G
    end
    V -->|任务完成| D([返回最终结果])
    U -.随时打断 补充 转向.-> Loop

1.2 两个组件：模型 + 工具

官方把这个循环拆成两个支柱：

• 模型（Models）：负责推理——读懂代码、理解组件如何连接、判断该改哪里。多个模型可选：Sonnet 适合绝大多数编码任务，Opus 用于复杂的架构推理。会话中用 /model 切换，或启动时 claude --model <name> 指定。
• 工具（Tools）：负责行动。没有工具，Claude 只能回文字；有了工具，它能读你的代码、改文件、跑命令、搜网页。每一次工具调用都会把结果反馈回循环，成为下一步决策的依据。

Claude Code 自己则扮演"代理外壳（harness）"：它在模型外面套上工具、上下文管理和执行环境，把一个语言模型变成真正能干活的编码代理。

这句最重要："Claude 选择""Claude 决定"，本质是模型在推理。 理解了这一点，你才会明白为什么给它更好的上下文（更清晰的指令、更相关的文件），它就表现更好。

1.3 工具的五大类

内置工具大致分成五类，每类代表一种不同的"能动性"：

此外还有编排类工具：生成子代理（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：

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell：

irm https://claude.ai/install.ps1 | iex

Windows CMD：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

包管理器（备选）：

# 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)

常见问题与排错

Debian / Fedora / RHEL / Alpine 用户也可以用 apt、dnf、apk 安装，命令见官方文档。

三、第二步：登录认证

Claude Code 必须登录账号才能用。直接在终端启动：

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 的交互提示符，上方显示版本、当前模型、工作目录。

四、第三步：首次会话与第一条提问

打开终端，进入任意项目目录后启动：

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.md（项目指令，每次会话加载）和自动记忆 MEMORY.md（习得，前 200 行/25KB 自动加载）持久化。

flowchart TD
    Q[Claude 准备执行一个工具调用] --> P1{本地级 settings.local.json<br/>有显式 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，把"读多写少"场景里安全的命令提前放行，能极大减少弹窗：

{
  "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；只有在 Docker 容器、临时虚拟机等可丢弃环境里才用 bypassPermissions。

5.4 写第一份 CLAUDE.md

在项目根目录新建 CLAUDE.md，把"每次都要交代一遍"的背景固化下来：

# 项目说明

这是一个 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

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 按需微调）：

"""命令行待办清单工具，仅用标准库。"""
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）

完整工作流一览

把从安装到交付首项目串起来，整体路径如下：

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 — 三阶段循环、模型与工具的权威解释：https://code.claude.com/docs/en/how-claude-code-works
• 官方 Agent Loop 详解 — 消息生命周期、工具执行、上下文窗口与架构：https://code.claude.com/docs/en/agent-sdk/agent-loop
• 官方 Quickstart — 分平台安装与登录步骤：https://code.claude.com/docs/en/quickstart
• 官方 Permissions — /permissions 与 allow/deny 规则：https://code.claude.com/docs/en/permissions
• 官方 Settings — settings.json 分层与敏感文件保护：https://code.claude.com/docs/en/settings

训练营适用性评估

参考来源

1. How Claude Code works — Claude Code Docs — 官方对 Agent 循环三阶段、模型与工具双组件、访问范围的权威说明
2. How the agent loop works — Claude Code Docs — 消息生命周期、工具执行、并行调用、上下文窗口与自动压缩的实现机制
3. Quickstart — Claude Code Docs — 各平台原生安装命令、账号登录、首次会话的分步指引
4. Configure permissions — Claude Code Docs — /permissions 界面与 allow/deny 规则的官方说明
5. The Complete .claude Directory Guide for Claude Code [2026] — ComputingForGeeks — 第三方对 .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 等场景全覆盖。