> 本教程适合零基础开发者：从一台干净的开发机开始，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，因为它最通用、最适合写进训练营和自动化流程。 ## 二、安装 Claude Code（5 分钟） ### 操作说明 官方提供三种主流原生安装方式，按平台选择其一： ```bash # 方式 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 ``` ```bash # 方式 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`（官方提供签名仓库）。 ### 预期结果 安装完成后，在终端验证： ```bash claude --version ``` 正常会输出形如 `2.1.x` 的版本号。原生安装首次运行后会在后台静默更新，下次启动即生效。 ### 常见问题 - **PowerShell 报 `The token '&&' is not a valid statement separator`**：说明你把 CMD 命令贴进了 PowerShell。看提示符：`PS C:\>` 是 PowerShell，纯 `C:\>` 是 CMD，两边命令不同。 - **CMD 报 `'irm' is not recognized`**：`irm` 是 PowerShell 专属，CMD 里要用 `curl ... && install.cmd` 那条。 - **报 `syntax error near unexpected token '<'` 或 403 / curl 错误**：多半是网络代理或地区限制，参考官方 *Troubleshoot installation* 切换镜像或代理。 - **Windows 上想让 Claude Code 用 Bash 工具**：安装 *Git for Windows*；没装的话它会退回用 PowerShell 当 shell。WSL 环境无需额外装 Git。 - **想固定版本/关闭自动更新**：可在配置里设 `minimumVersion`，或用环境变量 `DISABLE_AUTOUPDATER`（仅停后台检查）/ `DISABLE_UPDATES`（彻底禁更新）。 ### 三、登录认证（3 分钟） #### 操作说明 在任意目录直接启动： ```bash claude ``` 首次启动会引导你登录。按你的账号类型选择： - **Claude Pro / Max / Team / Enterprise（推荐）**：在浏览器里完成认证即可。 - **Claude Console（API 预付额度）**：首次登录会自动在 Console 里建一个名为 "Claude Code" 的工作区，方便集中看账单。 - **企业云**：Amazon Bedrock / Google Cloud Agent Platform / Microsoft Foundry。 - **自建网关**：管理员预先配好网关 URL，`/login` 直接跳到 Cloud gateway 走企业 SSO。 登录后想切换账号或重新认证，在会话内输入： ``` /login ``` #### 预期结果 凭证会安全存到本地，之后无需重复登录。你会看到 Claude Code 的提示符，上方显示版本、当前模型、工作目录。 #### 常见问题 - **公司用网关登录**：让管理员先配网关 URL，否则 `/login` 不会出现 Cloud gateway 选项。 - **额度/计费疑问**：订阅用户走套餐额度；Console 用户走预付额度，可在 Console 的 "Claude Code" 工作区看用量。 ## 四、创建项目并启动首个会话（5 分钟） ### 操作说明 我们来建一个全新项目目录，作为本次实战的工作区： ```bash mkdir mdtoc && cd mdtoc git init claude ``` 进入会话后，先做两件最划算的事： 1. 输入 `/help` 看所有命令和技能。 2. 让 Claude 先"看懂"空项目，再动手。 ### 预期结果 提示符上方会显示你当前的模型和工作目录（应为 `.../mdtoc`）。`/help` 会列出会话内命令清单。 ### 常见问题 - **不知道怎么提问**：像跟同事说话一样自然描述目标即可，比如「分析一下这个项目结构」「这个项目用了哪些技术」。Claude 会按需读文件，不用手动喂上下文。 - **快捷键记不住**：敲 `/` 看全部命令与技能；`Tab` 补全；`↑` 翻历史；`Shift+Tab` 循环切换权限模式。 ## 五、用 `/init` 配置项目记忆 CLAUDE.md（5 分钟） 配置环节最容易让新手忽略、却最影响后续质量的一步，是生成项目记忆文件 `CLAUDE.md`。它会随每次会话自动加载，相当于给 Claude 一份"项目说明书"。 ### 操作说明 在会话里输入： ``` /init ``` Claude 会扫描项目、推断技术栈和约定，生成一份 `CLAUDE.md` 初稿，然后请你确认。对于这个新项目，你可以直接把它改写成下面这样精简而具体的版本： ```markdown # 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 该写多少**：少而精。最关键的三块是「构建/测试/运行命令」「代码风格」「目录结构」。模糊的指令（如"写好一点"）效果差，具体的（如"pytest -q"）效果好。 - **子项目要不要单独写**：可以。Claude Code 支持目录层级的 `CLAUDE.md`，子目录的指令会在该目录下工作时叠加生效。 ## 六、第一个需求：让 Claude 写代码（5 分钟） ### 操作说明 在会话里用自然语言下达任务，**说清楚验收标准**： ``` 帮我实现 mdtoc.py：读取 Markdown 文件，把其中所有 #/##/### 标题 解析出来，生成带锚点的 Markdown 目录列表，写在文件内容最前面， 用注释 ... 包裹，方便重复更新。 要求：纯标准库、带类型注解、处理标题中的特殊字符（去标点、空格转连字符）。 另外给我准备一个 sample.md 测试样例。 ``` Claude 会：找到合适的文件 → 展示拟修改 → 请求你批准 → 落盘修改。 ### 预期结果 Claude 先展示 diff，等你确认。批准后 `mdtoc.py` 和 `sample.md` 出现在项目里。你可以让它直接跑一下自测： ``` 跑一下 mdtoc.py 处理 sample.md，把结果给我看 ``` ### 常见问题 - **改得不对怎么办**：直接说「不对，xxx 那里要 yyy」，Claude 会基于上下文重做，不必从头描述。 - **嫌每次确认麻烦**：可在本会话开 "Accept all" 模式，或用 `Shift+Tab` 切换更宽松的权限模式；但新手建议保留逐条确认，养成 review diff 的习惯。 - **提示词怎么写更好**：具体胜过抽象。与其「修 bug」，不如「修用户在表单为空时点提交会白屏的那个 bug」。 ## 七、写测试并运行（2 分钟） ### 操作说明 ``` 给 mdtoc.py 补单元测试，覆盖：标题解析、锚点生成、特殊字符处理、 TOC 重复更新（已有 TOC 时应替换而非追加）。然后用 pytest 跑通。 ``` ### 预期结果 生成 `tests/test_mdtoc.py`，并自动执行 `python -m pytest -q`，输出类似： ``` ..... 5 passed in 0.12s ``` ### 常见问题 - **测试失败**：把失败输出原样贴回会话，让 Claude 自己定位修复——这是它最擅长的闭环之一。 - **没有 pytest**：让它「用标准库 unittest 写测试，`python -m unittest` 跑」，避免引入依赖。 ## 八、用 Git 收尾（5 分钟） ### 操作说明 Claude Code 让 Git 操作变得口语化： ``` 我改了哪些文件？ 帮我建一个分支叫 feature/mdtoc 把这些改动用规范的 commit message 提交 ``` ### 预期结果 Claude 会列出改动、建分支、生成符合规范的提交信息并提交。可继续： ``` 看最近 5 条提交 ``` ### 常见问题 - **不想让它自动提交**：可以；默认它会在执行前展示并征求确认。也可让它只生成 commit message，由你自己 `git commit`。 - **遇到合并冲突**：直接说「帮我解决合并冲突」，它会读冲突标记并给出处理方案。 ## 九、实战案例：完整的 mdtoc.py 下面是上述流程产出的一个可直接运行的最小实现，方便你对照验证： ```python # mdtoc.py — Markdown 目录生成器 import re import sys from pathlib import Path TOC_START = "" TOC_END = "" 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=sys.stderr) sys.exit(1) update_file(Path(sys.argv[1])) print(f"已更新目录: {sys.argv[1]}") ``` 对应的最小测试 `tests/test_mdtoc.py`： ```python # 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，让它「跑测试、修任何不过的用例、提交」，你就完成了一个真实的从零到提交的闭环。 ## 十、整体工作流程图 ```mermaid 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[完成首个项目闭环] ``` ## 十一、给新手的 6 条心法 1. **先让它理解，再让它动手。** 改代码前先问「分析一下这个项目的数据库 schema / 目录结构」，效果远好于直接「实现 xxx」。 2. **拆步骤。** 复杂任务拆成「1. 建表 2. 写接口 3. 写页面」分轮做，每轮可验证。 3. **具体胜过模糊。** 「修复登录后白屏的 bug」优于「修 bug」。 4. **CLAUDE.md 是杠杆。** 把命令和约定固化进去，省下无数次重复说明。 5. **常用会话命令记三个**：`/clear`（清历史，换任务前必用）、`/help`、`Ctrl+D` 退出。 6. **常用 shell 命令记四个**：`claude`（交互）、`claude "任务"`（一次性任务）、`claude -p "查询"`（问完即退）、`claude -c`（续最近会话）。 ## 十二、延伸阅读 - **官方 Quickstart**：8 步上手 walkthrough，本文步骤对其做了中文化与项目化扩展。 - **官方 Advanced setup**：系统要求、包管理器安装、版本固定、卸载、二进制签名校验等进阶细节。 - **Best practices**：提示词与项目设置的最佳实践，进阶必读。 - **Common workflows**：重构、写测试、改文档、代码审查等常见任务的 step-by-step。 ## 十三、训练营适用性评估 | 维度 | 评估 | |------|------| | 适合训练营类型 | 企业新员工入职 AI 编程训练营、高校 AI 工具入门工作坊、开发者社区 1 日体验营 | | 学员基础 | 会基本命令行操作即可，零 AI 经验可学 | | 教学时长 | 讲授 30 分钟 + 动手 30 分钟，合计约 1 课时（45–60 分钟） | | 硬件/网络要求 | 需可访问 Anthropic 服务的网络环境；每人一个 Claude 账号或共享 Console 额度 | | 可扩展练习 | 把 mdtoc 升级为支持子目录批量处理；加 `--watch` 监听；发布到 PyPI | | 风险点 | 网络/地区限制可能导致登录失败，需提前准备代理或网关方案 | ## 参考来源 1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — 官方入门 8 步指南，覆盖安装、登录、首个会话、首次改动与 Git 操作。 2. [Advanced setup - Claude Code Docs](https://code.claude.com/docs/en/setup) — 官方系统要求、多平台原生安装、包管理器安装、版本管理与卸载。 3. [Getting Started with Claude Code in 2026: Setup to First Commit](https://septimlabs.com/blog/getting-started-with-claude-code-2026) — 2026 年实战 5 步上手，覆盖认证到首次提交。 4. [Claude Code Tutorial for Beginners 2026: From Installation to Building Your First Project](https://dev.to/ayyazzafar/claude-code-tutorial-for-beginners-2026-from-installation-to-building-your-first-project-1lma) — 面向零基础、从安装到首个项目的完整教程。 5. [How to Use Claude Code (Beginner Guide) - builder.io](https://www.builder.io/blog/how-to-use-claude-code) — 强调"避免模糊提问、拿到平庸结果"的新手避坑指南。 > [!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 等场景全覆盖。