本教程适合零基础开发者：从一台干净的开发机开始，30 分钟内完成 Claude Code 的安装、登录、项目配置，并用它从零写出一个可运行、带测试、已提交到 Git 的真实小工具——一个 Markdown 目录（TOC）生成器。学完你将掌握 Claude Code 的完整工作闭环，并具备独立用它开发任何小项目的信心。
在动手之前，请确认你的环境满足官方最低要求（来源：Claude Code 官方 Advanced setup 文档）：
| 项目 | 最低要求 |
|---|---|
| 操作系统 | macOS 13.0+ / Windows 10 1809+ 或 Windows Server 2019+ / Ubuntu 20.04+ / Debian 10+ |
| 硬件 | 4 GB+ 内存，x64 或 ARM64 处理器 |
| 网络 | 能访问 Anthropic 服务支持的国家/地区 |
| 账号 | Claude 订阅（Pro / Max / Team / Enterprise）或 Claude Console（API 预付额度），或通过 Amazon Bedrock / Google Cloud Agent Platform / Microsoft Foundry 接入 |
| 终端 | 会打开一个终端窗口即可；没用过终端可先看官方 terminal guide |
一个关键认知：Claude Code 现在的官方推荐安装方式是「原生安装（Native Install）」，不再强依赖 Node.js。 npm 仍可用，但原生安装会在后台自动更新，体验更省心。本教程以原生安装为主线。
如果你更偏爱图形界面，也可以直接下载官方桌面应用（macOS / Windows / Linux 均有），但本教程聚焦终端 CLI，因为它最通用、最适合写进训练营和自动化流程。
官方提供三种主流原生安装方式，按平台选择其一：
# 方式 A：原生安装（推荐）—— macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash
# 方式 A：原生安装 —— Windows PowerShell
irm https://claude.ai/install.ps1 | iex
# 方式 A：原生安装 —— Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
# 方式 B：Homebrew（macOS / Linux）
brew install --cask claude-code # 稳定通道，约滞后一周，跳过有重大回归的版本
brew install --cask claude-code@latest # 最新通道，新版本立即可用
# 方式 C：WinGet（Windows）
winget install Anthropic.ClaudeCode
Linux 用户还可以用发行版自带包管理器：Debian/Ubuntu 用 apt、Fedora/RHEL 用 dnf、Alpine 用 apk（官方提供签名仓库）。
安装完成后，在终端验证：
claude --version
正常会输出形如 2.1.x 的版本号。原生安装首次运行后会在后台静默更新，下次启动即生效。
The token '&&' is not a valid statement separator：说明你把 CMD 命令贴进了 PowerShell。看提示符：PS C:\> 是 PowerShell，纯 C:\> 是 CMD，两边命令不同。'irm' is not recognized：irm 是 PowerShell 专属，CMD 里要用 curl ... && install.cmd 那条。syntax error near unexpected token '<' 或 403 / curl 错误：多半是网络代理或地区限制，参考官方 Troubleshoot installation 切换镜像或代理。minimumVersion，或用环境变量 DISABLE_AUTOUPDATER（仅停后台检查）/ DISABLE_UPDATES（彻底禁更新）。在任意目录直接启动：
claude
首次启动会引导你登录。按你的账号类型选择：
/login 直接跳到 Cloud gateway 走企业 SSO。登录后想切换账号或重新认证，在会话内输入：
/login
凭证会安全存到本地，之后无需重复登录。你会看到 Claude Code 的提示符，上方显示版本、当前模型、工作目录。
/login 不会出现 Cloud gateway 选项。我们来建一个全新项目目录，作为本次实战的工作区：
mkdir mdtoc && cd mdtoc
git init
claude
进入会话后，先做两件最划算的事：
/help 看所有命令和技能。提示符上方会显示你当前的模型和工作目录（应为 .../mdtoc）。/help 会列出会话内命令清单。
/ 看全部命令与技能；Tab 补全；↑ 翻历史；Shift+Tab 循环切换权限模式。/init 配置项目记忆 CLAUDE.md（5 分钟）配置环节最容易让新手忽略、却最影响后续质量的一步，是生成项目记忆文件 CLAUDE.md。它会随每次会话自动加载，相当于给 Claude 一份"项目说明书"。
在会话里输入：
/init
Claude 会扫描项目、推断技术栈和约定，生成一份 CLAUDE.md 初稿，然后请你确认。对于这个新项目，你可以直接把它改写成下面这样精简而具体的版本：
# mdtoc — Markdown 目录生成器
## 概述
一个用 Python 编写的命令行工具：读取一个 Markdown 文件，
根据其标题层级生成可点击的目录（TOC），并写回文件顶部或输出到stdout。
## 命令
- 运行工具: python mdtoc.py README.md
- 运行测试: python -m pytest -q
- 手动验证: python mdtoc.py sample.md
## 代码风格
- Python 3.10+，类型注解必填
- 函数加 docstring，4 空格缩进
- 只用标准库，不引入第三方依赖
## 目录结构
- mdtoc.py：主程序
- tests/：单元测试
- sample.md：测试样例
项目根目录出现 CLAUDE.md。之后每次 claude 启动，Claude 都会自动读它，无需你重复交代命令和约定。
CLAUDE.md，子目录的指令会在该目录下工作时叠加生效。在会话里用自然语言下达任务，说清楚验收标准：
帮我实现 mdtoc.py：读取 Markdown 文件，把其中所有 #/##/### 标题
解析出来，生成带锚点的 Markdown 目录列表，写在文件内容最前面，
用注释 <!-- TOC --> ... <!-- /TOC --> 包裹，方便重复更新。
要求：纯标准库、带类型注解、处理标题中的特殊字符（去标点、空格转连字符）。
另外给我准备一个 sample.md 测试样例。
Claude 会：找到合适的文件 → 展示拟修改 → 请求你批准 → 落盘修改。
Claude 先展示 diff，等你确认。批准后 mdtoc.py 和 sample.md 出现在项目里。你可以让它直接跑一下自测：
跑一下 mdtoc.py 处理 sample.md，把结果给我看
Shift+Tab 切换更宽松的权限模式；但新手建议保留逐条确认，养成 review diff 的习惯。给 mdtoc.py 补单元测试，覆盖：标题解析、锚点生成、特殊字符处理、
TOC 重复更新（已有 TOC 时应替换而非追加）。然后用 pytest 跑通。
生成 tests/test_mdtoc.py，并自动执行 python -m pytest -q，输出类似：
.....
5 passed in 0.12s
python -m unittest 跑」，避免引入依赖。Claude Code 让 Git 操作变得口语化：
我改了哪些文件？
帮我建一个分支叫 feature/mdtoc
把这些改动用规范的 commit message 提交
Claude 会列出改动、建分支、生成符合规范的提交信息并提交。可继续：
看最近 5 条提交
git commit。下面是上述流程产出的一个可直接运行的最小实现，方便你对照验证：
# mdtoc.py — Markdown 目录生成器
import re
import sys
from pathlib import Path
TOC_START = "<!-- TOC -->"
TOC_END = "<!-- /TOC -->"
def slugify(text: str) -> str:
"""把标题文本转成 GitHub 风格锚点。"""
text = text.lower().strip()
text = re.sub(r"[^\w\s-]", "", text) # 去标点
text = re.sub(r"[\s_]+", "-", text) # 空格/下划线转连字符
text = re.sub(r"-+", "-", text).strip("-") # 合并多余连字符
return text
def parse_headings(content: str) -> list[tuple[int, str]]:
"""返回 [(层级, 标题文本), ...]，只认 # 开头的标题行。"""
headings: list[tuple[int, str]] = []
for line in content.splitlines():
m = re.match(r"^(#{1,6})\s+(.+?)\s*#*\s*$", line)
if m:
headings.append((len(m.group(1)), m.group(2)))
return headings
def build_toc(headings: list[tuple[int, str]]) -> str:
"""根据层级生成缩进的目录列表。"""
lines: list[str] = []
for level, title in headings:
indent = " " * (level - 1)
lines.append(f"{indent}- [{title}](#{slugify(title)})")
return "\n".join(lines)
def update_file(path: Path) -> None:
"""在文件顶部插入/替换 TOC 区块。"""
content = path.read_text(encoding="utf-8")
toc_body = build_toc(parse_headings(content))
block = f"{TOC_START}\n{toc_body}\n{TOC_END}"
pattern = re.compile(
rf"{re.escape(TOC_START)}.*?{re.escape(TOC_END)}", re.DOTALL
)
if pattern.search(content):
content = pattern.sub(block, content)
else:
content = f"{block}\n\n{content}"
path.write_text(content, encoding="utf-8")
if __name__ == "__main__":
if len(sys.argv) != 2:
print("用法: python mdtoc.py <file.md>", file=sys.stderr)
sys.exit(1)
update_file(Path(sys.argv[1]))
print(f"已更新目录: {sys.argv[1]}")
对应的最小测试 tests/test_mdtoc.py：
# tests/test_mdtoc.py
from mdtoc import slugify, parse_headings, build_toc
def test_slugify_special_chars():
assert slugify("Hello, World! C++") == "hello-world-c"
def test_parse_headings():
md = "# A\n## B\n普通文本\n### C\n"
assert parse_headings(md) == [(1, "A"), (2, "B"), (3, "C")]
def test_build_toc_indent():
toc = build_toc([(1, "A"), (2, "B")])
assert toc == "- [A](#a)\n - [B](#b)"
把这两段交给 Claude，让它「跑测试、修任何不过的用例、提交」，你就完成了一个真实的从零到提交的闭环。
flowchart TD
A[干净开发机] --> B[原生安装 curl/brew/winget]
B --> C[claude 首次登录]
C --> D[mkdir 项目 + git init]
D --> E[claude 启动会话]
E --> F["/init 生成 CLAUDE.md 配置"]
F --> G[自然语言提需求]
G --> H{Claude 展示 diff}
H -->|批准| I[落盘代码]
H -->|修改| G
I --> J[补测试 + 运行]
J --> K{测试通过?}
K -->|否| G
K -->|是| L[Git 建分支 + 提交]
L --> M[完成首个项目闭环]
/clear（清历史，换任务前必用）、/help、Ctrl+D 退出。claude（交互）、claude "任务"（一次性任务）、claude -p "查询"（问完即退）、claude -c（续最近会话）。| 维度 | 评估 |
|---|---|
| 适合训练营类型 | 企业新员工入职 AI 编程训练营、高校 AI 工具入门工作坊、开发者社区 1 日体验营 |
| 学员基础 | 会基本命令行操作即可，零 AI 经验可学 |
| 教学时长 | 讲授 30 分钟 + 动手 30 分钟，合计约 1 课时（45–60 分钟） |
| 硬件/网络要求 | 需可访问 Anthropic 服务的网络环境；每人一个 Claude 账号或共享 Console 额度 |
| 可扩展练习 | 把 mdtoc 升级为支持子目录批量处理；加 --watch 监听；发布到 PyPI |
| 风险点 | 网络/地区限制可能导致登录失败，需提前准备代理或网关方案 |
[!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 等场景全覆盖。