## 概述 本教程面向零基础读者，目标只有一个：用最短路径把 Claude Code 装通、配好，并亲手带它造出第一个能跑、有测试、有 Git 记录的命令行项目——一个密码工具箱 `pwkit`。与传统"装完就用"教程不同，本文的核心是把 **CLAUDE.md 项目记忆文件**作为第一课：它会让你学会如何用一份"项目说明书"给 Claude 立下规矩，让它从第一次对话就懂你的技术栈、代码规范和验收标准。学完你能独立完成"安装→认证→立规矩→规划→实现→自检→提交"的完整闭环。 ## 前置条件 - 一台 macOS 13+、Windows 10 1809+ 或 Ubuntu 20.04+ 的电脑，内存 4GB 以上 - 一个 Claude 订阅账号（Pro / Max / Team / Enterprise）或 Claude Console（API 预付额度）账号 - 能联网，且身处 Anthropic 支持的国家或地区 - Python 3.10+（本教程的项目用它实现；若没有，让 Claude 帮你装） - 不需要先学终端命令——遇到不懂的，直接在 Claude 里问 ## 正文 ### 步骤 1：选对安装方式，告别 Node 依赖 Claude Code 现在有四种官方安装方式。对零基础读者，**强烈推荐原生安装（Native Install）**，因为它不依赖 Node.js，装完还会在后台自动更新，省去手动升级的烦恼。 在终端里根据系统粘贴对应命令： ```bash # 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 ``` 另外三种方式作为补充： | 方式 | 命令 | 是否自动更新 | 适用场景 | |------|------|--------------|----------| | 原生安装（推荐） | `curl … install.sh \| bash` | ✅ 后台自动 | 零基础首选 | | Homebrew | `brew install --cask claude-code` | ❌ 需手动 `brew upgrade` | 已用 brew 管软件的 Mac 用户 | | WinGet | `winget install Anthropic.ClaudeCode` | ❌ 需手动 `winget upgrade` | Windows 标准用户 | | npm | `npm install -g @anthropic-ai/claude-code` | ❌ | 已装 Node 的开发者 | **预期结果**：命令跑完后，终端输入 `claude --version` 能打印出版本号，说明安装成功。 **常见问题**： - Windows 上报 `'irm' is not recognized`：说明你在 CMD 里，应改用 CMD 那条命令；反之报 `'&&' is not a valid statement separator` 说明你在 PowerShell 里。 - `curl` 报 403 或 `syntax error near unexpected token '<'`：通常是网络代理或公司防火墙拦截，换用 npm 方式或检查代理设置即可。 - 装完找不到 `claude` 命令：原生安装会提示你把可执行文件路径加入 `PATH`，按提示复制那一行到你的 shell 配置文件（`~/.zshrc` 或 `~/.bashrc`）再 `source` 一次。 ### 步骤 2：首次登录，建立身份 在任意目录输入 `claude` 启动交互式会话，首次会自动弹出登录流程，引导你在浏览器里完成认证。支持 Pro/Max/Team/Enterprise 订阅号，也支持 Console 付费额度号，还支持 Amazon Bedrock、Google Cloud Agent Platform 等企业云通道。 登录一次后，凭据会安全保存在本地，之后无需重复登录。若要切换账号，在会话里输入 `/login` 即可。 **预期结果**：会话顶部出现版本号、当前模型、工作目录三行信息，下方是输入提示符，说明你已进入 Claude Code。 ### 步骤 3：建立项目骨架，写下 CLAUDE.md 立规矩（核心） 这是本教程最重要的一步。Claude Code 在每次启动时会自动读取项目根目录的 `CLAUDE.md`，把它作为长期记忆注入上下文。**这份文件就是你和 Claude 之间的"项目契约"**——你把技术栈、代码规范、验收标准写进去，Claude 之后每次写代码都会自觉遵守，不需要你反复叮嘱。 先建好项目目录并进入： ```bash mkdir pwkit && cd pwkit claude ``` 然后直接对 Claude 说第一句话： > 在当前目录创建一个 Python 项目骨架：`pwkit/` 放源码，`tests/` 放测试，根目录建一个 `CLAUDE.md`。CLAUDE.md 的内容我接下来口述，你照写。 接着把下面这份"规矩"口述给它（你也可以直接用编辑器手写）： ```markdown # pwkit 项目说明 ## 项目目标 命令行密码工具箱，提供「生成强密码」和「检查密码强度」两个子命令。 ## 技术栈与约束 - Python 3.10+，仅用标准库，禁止引入任何第三方依赖 - 命令行解析用 argparse - 随机数必须用 secrets 模块，禁止用 random（不安全） - 所有面向用户的输出使用中文 ## 代码规范 - 每个函数必须有类型注解和 docstring - generate(length) 默认 16 位，必须包含大写、小写、数字、符号各至少一个 - score(password) 返回 0-4 的整数评分和中文说明（很弱/较弱/中等/较强/很强） ## 验收标准（给 Claude 的自检命令） - 运行 `python -m pytest tests/` 必须 100% 通过 - 实现完成后，你必须自己跑一遍测试；若有失败，自动修复直到全绿，再结束任务 ``` **为什么这一步如此关键**：初学者最常踩的坑，是每次对话都要重新告诉 Claude"用标准库""输出中文""跑一下测试"。有了 CLAUDE.md，这些规矩被固化下来，Claude 会在后续所有会话里自动遵守。它还会被纳入上下文缓存，长期使用更省钱。 ### 步骤 4：用 Plan 模式先规划，再动手 Claude Code 的最佳实践是"先探索、再规划、再编码"。对零基础读者，最简单的做法是按 `Shift+Tab` 切到 **Plan 模式**（或输入 `/plan`）。在该模式下 Claude 只读不写，会先给你一份实施方案让你审阅。 切到 Plan 模式后输入： > 根据 CLAUDE.md，规划 pwkit 的实现：列出要创建的文件、每个文件的职责、generate 和 score 的算法思路，以及测试用例。先不要写代码。 **预期结果**：Claude 会回一份分文件、分函数的方案，并标注它会怎么满足"每类字符至少一个"和"secrets 而非 random"这两条规矩。你确认无误后，按 `Shift+Tab` 切回默认模式准备实现。 **常见问题**： - 任务很小（比如改个错别字）就不必走 Plan 模式，直接让它改即可——规划本身有开销。 - 看到方案不满意，可以直接在同一轮对话里提修改意见，让它重出。 ### 步骤 5：让 Claude 实现，并给它"自检手段" 切回默认模式后，把规划交给它执行，关键是**把验收命令一起写进同一条指令**： > 按 CLAUDE.md 实现整个 pwkit。写完后运行 `python -m pytest tests/`，若有失败就读错误、改代码、重跑，直到全部通过。最后把测试输出贴给我看。 `pwkit/__main__.py` 最终大致长这样（Claude 会按你的 CLAUDE.md 生成）： ```python import argparse import secrets import string def generate(length: int = 16) -> str: """生成包含大写、小写、数字、符号的强密码。""" pools = [string.ascii_uppercase, string.ascii_lowercase, string.digits, "!@#$%^&*"] chars = [secrets.choice(p) for p in pools] # 每类至少一个 all_chars = "".join(pools) chars += [secrets.choice(all_chars) for _ in range(length - len(pools))] secrets.SystemRandom().shuffle(chars) # 打乱顺序 return "".join(chars) def score(password: str) -> tuple[int, str]: """返回 0-4 强度评分与中文说明。""" s = 0 if len(password) >= 12: s += 1 if any(c.isupper() for c in password) and any(c.islower() for c in password): s += 1 if any(c.isdigit() for c in password): s += 1 if any(c in "!@#$%^&*" for c in password): s += 1 return s, ["很弱", "较弱", "中等", "较强", "很强"][s] def main() -> None: p = argparse.ArgumentParser(prog="pwkit", description="密码工具箱") sub = p.add_subparsers(dest="cmd", required=True) g = sub.add_parser("gen", help="生成密码"); g.add_argument("length", type=int, nargs="?", default=16) c = sub.add_parser("check", help="检查强度"); c.add_argument("password") a = p.parse_args() if a.cmd == "gen": print(generate(a.length)) elif a.cmd == "check": s, label = score(a.password); print(f"强度评分：{s}/4（{label}）") if __name__ == "__main__": main() ``` 测试文件 `tests/test_pwkit.py`： ```python from pwkit import __main__ as pw def test_generate_length(): assert len(pw.generate(20)) == 20 def test_generate_has_all_classes(): pwd = pw.generate(16) assert any(c.isupper() for c in pwd) assert any(c.islower() for c in pwd) assert any(c.isdigit() for c in pwd) def test_score_weak_and_strong(): assert pw.score("abc")[0] == 0 assert pw.score("Abcdefgh1!2")[0] == 4 ``` **预期结果**：Claude 会展示要改动的文件、请求你批准，然后落盘；接着它自动 `pytest`，把绿色通过的输出贴出来。因为它读到了 CLAUDE.md 里"失败就修到全绿"的规矩，你不必盯着。 > 给 Claude 一个能跑出"通过/失败"的检查，是区分"你得盯着它"和"你能走开"的分水岭。 ### 步骤 6：亲手验证，感受"自检闭环" 虽然 Claude 已自检，但你仍应亲自跑一次，确认它没有"看起来完成了"： ```bash python -m pwkit gen 20 # 输出一段 20 位强密码 python -m pwkit check "123" # 输出：强度评分：0/4（很弱） python -m pwkit check "Abcdefgh1!2xyz" # 输出：强度评分：4/4（很强） python -m pytest tests/ -v # 三条测试全绿 ``` ### 步骤 7：用 Git 留下第一笔记录 最后让 Claude 把成果提交进版本库，全程自然语言驱动： > 初始化 git 仓库，把所有文件加入并提交，提交信息用中文，简明描述这次实现了密码生成和强度检查功能。 **预期结果**：Claude 会创建仓库、生成合理的中文提交信息并完成首次提交。 ## 实战案例：把 pwkit 扩展成"泄露检测"工具 作为延伸练习，回到 Claude 维让它加一个 `pwkit leak ` 子命令：调用免费 Have I Been Pwned 的 Range API（k-anonymity，只传密码 SHA-1 的前 5 位，不泄露明文）检查密码是否在已知泄露库中。把这条新规矩追加进 CLAUDE.md： ```markdown ## 新增约束（leak 子命令） - 用 hashlib 算 SHA-1，只把前 5 位 hex 发给 https://api.pwnedpasswords.com/range/<前5位> - 本地比对返回结果里是否含剩余哈希后缀，输出"未泄露"或"已在 N 次泄露中出现" - 禁止把完整密码或完整哈希发到网络 ``` 因为规矩已写进 CLAUDE.md，Claude 会自动采用安全的 k-anonymity 做法，无需你额外强调。这就是 CLAUDE.md 的复利价值：**规矩写一次，长期生效**。 ## 工作流程图 ```mermaid flowchart TD A[原生安装 claude.ai/install.sh] --> B[首次浏览器登录认证] B --> C[创建项目目录并 cd 进入] C --> D[撰写 CLAUDE.md 立下项目规矩] D --> E[Shift+Tab 进入 Plan 模式规划] E --> F{方案是否满意?} F -- 否 --> E F -- 是 --> G[切回默认模式实现] G --> H[Claude 自动跑 pytest 自检] H --> I{测试全绿?} I -- 否 --> G I -- 是 --> J[你亲自验证 CLI 输出] J --> K[Git 初始化并提交] K --> L[追加新规矩扩展功能] ``` ## 延伸阅读 - **官方 Quickstart**：`code.claude.com/docs/en/quickstart` —— 八步上手的权威流程 - **Best Practices**：`code.claude.com/docs/en/best-practices` —— 上下文管理、Plan 模式、验证闭环的深入指南 - **Advanced Setup**：`code.claude.com/docs/en/setup` —— 系统要求、四种安装方式、版本管理与卸载 - **Explore the `.claude` directory**：理解项目级与全局级配置的层级关系 - **Manage sessions**：学会用 `/clear`、`/compact`、`claude -c`、`claude -r` 管理会话与上下文 ## 训练营适用性评估 - **适用类型**：零基础开发者入门营、AI 编程工具训练营第 1 天、"从 0 到 1 体验 Agent 编程"工作坊。也适合作为企业内训让传统工程师首次接触 AI 编程的破冰课。 - **教学时长**：建议 90–120 分钟。其中安装与认证 20 分钟，CLAUDE.md 概念讲解与撰写 30 分钟，Plan 模式 + 实现 + 自检 40 分钟，Git 提交与拓展练习 20 分钟。 - **学员产出**：每人带走一个可运行、有测试、有 Git 记录的密码工具 CLI，以及一份能复用到下一个项目的 CLAUDE.md 模板。 - **进阶衔接**：本课掌握 CLAUDE.md 与验证闭环后，可顺接"自定义 Skill 开发""MCP 工具开发""Hooks 自动化"等高阶主题，规矩文件与自检思想会在后续课程中反复复用。 ## 参考来源 1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — 官方八步快速上手指南，涵盖安装、登录、首次代码改动与常用命令 2. [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices) — 官方最佳实践，重点讲解上下文管理、Plan 模式四阶段与"给 Claude 验证手段"的闭环思想 3. [Advanced setup - Claude Code Docs](https://code.claude.com/docs/en/setup) — 系统要求、原生/Homebrew/WinGet/npm 四种安装方式、自动更新与卸载详解 4. [Claude Code Cheat Sheet (2.1.x)](https://computingforgeeks.com/claude-code-cheat-sheet/) — 2026 版快捷键、斜杠命令、CLI 标志速查表，Opus 4.8 默认模型 5. [Claude Code Tutorial for Beginners - Complete 2026 Guide](https://codewithmukesh.com/blog/claude-code-for-beginners/) — 第三方零基础完整教程，含 CLAUDE.md、自动记忆、Plan 模式与定价讲解 > [!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 等场景全覆盖。