## 概述 本教程面向**从未用过命令行 AI 编程工具**的零基础读者，带你从「装不上、不敢用」到「自己跑通第一个项目」。全程围绕一个真实可用的案例——**命令行记账本 wallet.py**（记一笔、列清单、按类别汇总，数据落地 JSON）——把 Claude Code 的安装、登录、配置、权限、迭代、提交串成一条完整工作流。学完你将能独立用自然语言指挥 AI 产出并验证代码，不再只是复制粘贴。 ## 前置条件 - 一台 macOS / Linux / Windows（含 WSL）电脑，能联网 - 一个 **Claude 订阅账号**（Pro / Max / Team / Enterprise 任一）或 **Claude Console**（API 预付费额度）账号 - 会打开「终端 / 命令提示符 / PowerShell」，会 `cd` 进入文件夹即可 - 本机装有 Python 3.8+（macOS/Linux 多数自带；Windows 建议装 Python 官网版）——仅用于跑我们的项目，**不是**装 Claude Code 的前提 > ⚠️ 重要纠正一个 2025 年的旧认知：**用 `npm install -g @anthropic-ai/claude-code` 安装已被官方标记为「废弃（deprecated）」**。现在推荐「原生安装（native install）」，它会自动带上运行时，不再强制你先装 Node.js。本教程全部采用官方推荐的新装法。 --- ## 正文：八步从零到跑通 ### 第 1 步：安装 Claude Code（原生安装，推荐） 打开终端，按你的系统**选一条**执行： **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 # Homebrew（macOS/Linux），claude-code 为稳定通道，约落后主版本一周 brew install --cask claude-code # WinGet（Windows） winget install Anthropic.ClaudeCode # Linux 包管理器 # apt / dnf / apk 也可用（Debian / Fedora / RHEL / Alpine） ``` **预期结果：** 安装完成后，终端输入下面命令能看到版本号，说明装好了： ```bash claude --version # 输出示例：2.1.199 (Claude Code) ``` > 原生安装会**在后台自动更新**，长期保持最新版；Homebrew 和 WinGet 不会自动更新，需定期 `brew upgrade claude-code` 或 `winget upgrade Anthropic.ClaudeCode`。 **常见问题：** | 报错 / 现象 | 原因 | 解决 | |---|---|---| | `'irm' is not recognized...` | 你在 CMD 里跑了 PowerShell 命令 | 看提示符：`PS C:\>` 是 PowerShell，`C:\>` 才是 CMD，换对环境 | | `The token '&&' is not valid...` | 在 PowerShell 里用了 `&&` 连接 | PowerShell 用 `;` 或分开执行，或改用 CMD | | `syntax error near unexpected token '<'` 或 403 | 网络被拦截 / curl 被代理改写 | 检查代理设置，或换网络；官方文档有专门的 Troubleshoot 安装对照表 | | 公司网络完全装不上 | 出口受限 | 让管理员配自托管 gateway，或先用 Console API 密钥方式 | ### 第 2 步：首次登录 在任意目录执行： ```bash claude ``` 第一次运行会提示登录。浏览器会打开一个认证页面，用你的 Claude 账号完成授权即可。登录后凭证会保存，**之后不再需要重复登录**。 可登录的账号类型： - **Claude Pro / Max / Team / Enterprise**（官方推荐，最省心） - **Claude Console**（API 预付费额度；首次登录会自动建一个 "Claude Code" 工作区，方便统一看花费） - **Amazon Bedrock / Google Cloud Agent Platform / Microsoft Foundry**（企业云） - 组织自托管的 **Claude apps gateway**（管理员预配 URL，走企业 SSO） **预期结果：** 登录成功后，终端出现交互式提示符 `>`，等待你输入。 想切换账号或重新认证，在会话里输入： ``` /login ``` **常见问题：** 浏览器没自动弹出？复制终端里显示的那段 URL，手动粘到浏览器打开即可。国内网络若卡在跳转，确认代理放行了 `claude.ai` 与 `statsig.anthropic.com`。 ### 第 3 步：建项目目录并初始化 Git Claude Code 最擅长在「一个项目文件夹 + Git 仓库」里干活。我们新建记账本项目： ```bash mkdir my-wallet && cd my-wallet git init ``` **为什么一定要 Git？** Claude Code 会读 Git 状态来理解「改了哪些文件」，并能在你满意时帮你生成规范的 commit。没有 Git，很多能力会打折。Windows 用户若没装 Git，建议先装 **Git for Windows**，这样 Claude Code 才能稳定使用 Bash 工具。 **预期结果：** 终端当前路径变成 `.../my-wallet`，且生成了 `.git` 隐藏目录。 ### 第 4 步：用 `/init` 生成项目记忆 CLAUDE.md 在 Claude Code 会话里输入斜杠命令： ``` /init ``` 它会扫描当前目录，生成一份 **CLAUDE.md**——这是项目的「长期记忆」，告诉 AI 这个项目用什么技术栈、遵循什么规范。首次生成后，可以用 `/memory` 继续微调。 对本项目，我们让记忆尽量精炼。你可以在生成的 `CLAUDE.md` 里保留如下要点： ```markdown # 项目：命令行记账本 wallet.py - 语言：Python 3，仅用标准库，不引第三方依赖 - 数据落地：wallet.json（UTF-8，中文不转义） - 命令风格：python wallet.py <子命令> [参数] - 编码：所有文件 UTF-8，print 输出中文 ``` **预期结果：** 目录下出现 `CLAUDE.md`，下次会话 Claude 会自动读取它，省去每次重复交代背景。 **常见问题：** `CLAUDE.md` 会不会越写越乱？会。官方在 **2026-07-09 新增了 `/checkup` 维护命令**，能审计你的配置：清理用不到的 skills / MCP / 插件以节省上下文、给根目录臃肿的 `CLAUDE.md` 做去重和拆分。定期跑一次即可。 ### 第 5 步：第一次对话——让 AI 造出记账本 现在用一句自然语言下达任务（直接粘进会话）： ``` 用 Python 写一个命令行记账本 wallet.py。功能： 1) add 金额 类别 备注 —— 记一笔，自动加当前时间 2) list —— 列出所有记录 3) summary —— 按类别汇总金额并给合计 数据存成 wallet.json（UTF-8，中文不转义）。只用标准库。写完跑几条示例命令测试给我看。 ``` **预期结果：** Claude Code 会创建 `wallet.py`，内容大致如下（它生成、你可审阅）： ```python import json, sys, os from datetime import datetime from collections import defaultdict DATA_FILE = "wallet.json" def load(): if os.path.exists(DATA_FILE): with open(DATA_FILE, encoding="utf-8") as f: return json.load(f) return [] def save(records): with open(DATA_FILE, "w", encoding="utf-8") as f: json.dump(records, f, ensure_ascii=False, indent=2) def add(amount, category, note=""): recs = load() recs.append({"date": datetime.now().strftime("%Y-%m-%d %H:%M"), "amount": float(amount), "category": category, "note": note}) save(recs) print(f"✅ 已记录：{amount} 元 -> {category}（{note}）") def lst(): for r in load(): print(f"{r['date']} {r['amount']:>8.2f} {r['category']:<6} {r['note']}") def summary(): by = defaultdict(float) for r in load(): by[r["category"]] += r["amount"] print("分类汇总：") for cat, total in sorted(by.items(), key=lambda x: -x[1]): print(f" {cat:<8} {total:>10.2f}") print(f" {'合计':<8} {sum(by.values()):>10.2f}") if __name__ == "__main__": cmd = sys.argv[1] if len(sys.argv) > 1 else "list" if cmd == "add": add(sys.argv[2], sys.argv[3], sys.argv[4] if len(sys.argv) > 4 else "") elif cmd == "list": lst() elif cmd == "summary": summary() else: print("用法: python wallet.py [add 金额 类别 备注 | list | summary]") ``` 接着它会**自己执行测试命令**并把输出贴给你： ``` $ python wallet.py add 38 午餐 公司楼下盒饭 ✅ 已记录：38 元 -> 午餐（公司楼下盒饭） $ python wallet.py add 12.5 交通 地铁 ✅ 已记录：12.5 元 -> 交通（地铁） $ python wallet.py summary 分类汇总： 午餐 38.00 交通 12.50 合计 50.50 ``` **关键点：** 当 Claude 想运行 `python wallet.py ...` 时，终端会**弹出权限确认**，问你是否允许。这是 Claude Code 的安全设计——它不会偷偷跑命令。你按 `y` 同意即可（后面会讲怎么减少这些打断）。 **常见问题：** - **它生成的代码报错怎么办？** 直接把报错原文贴回去：「`python wallet.py add` 报了 IndexError，帮我修」。Claude 会读错误、定位、改代码、再测，形成闭环。 - **它没自动测试？** 补一句「请实际运行验证一下」，它就会执行。 ### 第 6 步：迭代加功能——导出 CSV 记账本要能导出表格才实用。继续用自然语言提需求： ``` 给 wallet.py 加一个 export 命令，把所有记录导出成 expenses.csv（带表头：日期,金额,类别,备注），金额保留两位小数。 ``` **预期结果：** Claude 在原文件里追加 `export()` 分支，并跑一次导出给你看： ``` $ python wallet.py export 已导出 2 条记录到 expenses.csv ``` 打开 `expenses.csv`： ```csv 日期,金额,类别,备注 2026-07-11 14:02,38.00,午餐,公司楼下盒饭 2026-07-11 14:03,12.50,交通,地铁 ``` 这一步演示了 Claude Code 的核心价值：**它读得懂现有代码、在恰当位置增量修改、改完自测**，而不是每次从零重写。 ### 第 7 步：理解并配置权限（少被打断） 每次跑命令都要按 `y` 会烦。输入： ``` /permissions ``` 可以管理「允许 / 询问 / 拒绝」清单。对本项目，建议把安全的只读 / 运行命令放进白名单，例如允许 `python wallet.py *`、`python3 *`、`git status`、`git diff`。这些规则会写进项目的 `.claude/settings.json` 或用户级的 `~/.claude/settings.json`。 三种权限模式（按需切换）： - **默认模式**：每次执行命令 / 改文件都问你（最安全，新手起步用这个） - **Auto-accept edits**：自动接受文件编辑，但跑命令仍询问 - **Plan mode**：先只读分析、给方案，**不动手**，确认后才执行（适合大改动前） > 给新手的建议：起步用默认模式，亲手按几次 `y`，看清它在做什么；熟悉后再逐步放行白名单命令。 **常见问题：** 它提示要执行一条你不放心的命令（比如 `rm`、`git push`）？直接选拒绝，或用 `/permissions` 把危险动词挡掉。Claude Code 默认不会联网外发你的代码，但 `git push` 这类「外向」动作务必亲自确认。 ### 第 8 步：用 Git 收尾提交 确认功能 OK 后，让 Claude 帮你提交： ``` 把现在的改动提交一个规范的 commit，message 用中文，遵循「类型：简述」格式。 ``` **预期结果：** 它会先 `git add`（只加你确认的文件）、`git status` 给你看暂存内容，再提交： ``` feat: 新增命令行记账本 wallet.py，支持记一笔/列表/汇总/导出CSV ``` 提交后，`git log` 能看到这条记录。一个**可运行、可追溯、可继续迭代**的小项目就此闭环。 --- ## 实战案例回顾：wallet.py 的完整生命周期 把上面八步浓缩成一次真实开发会话： 1. **环境**：macOS，已用 `curl -fsSL https://claude.ai/install.sh | bash` 装好，`claude --version` 显示 `2.1.199`。 2. **建仓**：`mkdir my-wallet && cd my-wallet && git init`。 3. **记忆**：`/init` 生成 `CLAUDE.md`，写入「Python 标准库、UTF-8、JSON 落地」三条约束。 4. **造物**：一段自然语言 → `wallet.py` + 自动测试，看到 `✅ 已记录` 与汇总输出。 5. **扩能**：一句「加 export 导出 CSV」→ 增量代码 + 自测 + `expenses.csv`。 6. **收尾**：自然语言提交 → 规范化 commit message。 整个过程**没有手写一行代码**，但你始终掌控：审阅生成的代码、按 `y` 放行命令、看测试输出、决定何时提交。这就是「用 AI 编程」而非「被 AI 编程」。 **可继续扩展的方向**（留给读者练手）： - 加 `delete <序号>` 删除某条 - 加 `--month 2026-07` 按月过滤 - 用 `sqlite3` 标准库把 JSON 换成真正的数据库 - 加 `budget set 类别 限额` 与超支提醒 --- ## 工作流程图 ```text flowchart TD A[安装 Claude Code
原生 installer] --> B[首次登录
claude → 浏览器认证] B --> C[建项目目录 + git init] C --> D[/init 生成 CLAUDE.md
项目长期记忆] D --> E[自然语言下达任务
造 wallet.py] E --> F{Claude 请求执行命令} F -->|权限确认 y| G[运行测试
看到 ✅ 输出] F -->|拒绝| H[修正后重试] G --> I[迭代加功能
export CSV] I --> J[git add + 规范 commit] J --> K[✅ 可运行可追溯的小项目] style A fill:#e8f5e9 style K fill:#fff3e0 style F fill:#ffebee ``` --- ## 常见问题速查表 | 问题 | 一句话解法 | |---|---| | `npm install -g` 还能用吗？ | 已废弃，改用原生 installer（`curl ... claude.ai/install.sh`） | | 登录浏览器没弹？ | 复制终端里的 URL 手动打开 | | 跑命令老是要按 y？ | `/permissions` 把 `python wallet.py *` 等加白名单 | | 代码报错？ | 把报错原文贴回去，让它读错、定位、改、再测 | | `CLAUDE.md` 太乱？ | 跑新命令 `/checkup` 自动审计去重拆分 | | 安装 / 配置异常排查 | 会话里输入 `/doctor`，自动诊断并尝试修复 | | 想回到某个干净状态 | `/rewind` 把代码和对话回滚到检查点 | | 上下文太长卡顿 | `/context` 看占窗内容，`/compact` 压缩，`/clear` 开新任务保留记忆 | --- ## 延伸阅读 - **Claude Code 官方快速上手**：`https://code.claude.com/docs/en/quickstart` ——八步官方版入门，权威可信 - **命令大全（Commands）**：`https://code.claude.com/docs/en/commands` ——所有斜杠命令完整参考 - **官方 Cheatsheet**：`https://support.claude.com/en/articles/14553413` ——命令与快捷速查卡 - **GitHub 仓库**：`https://github.com/anthropics/claude-code` ——README、安装脚本、插件目录 --- ## 训练营适用性评估 - **适合类型**：「AI 编程零基础启蒙营」「大学生开发者入门营」「传统运维 / 测试转 AI 工具营」 - **预计教学时长**：**1.5～2 小时**（含动手）。讲师演示 30 分钟、学员跟做 60 分钟、答疑 30 分钟 - **难度评级**：⭐（1/5），全程有明确命令与预期输出，可逐行对照 - **交付物**：每位学员带走一个能跑的 `wallet.py` + 一个已提交的 Git 仓库，成就感强 - **后续衔接**：本营结业后，可平滑进入「Skills 开发」「MCP 服务器开发」「Agent 自动化」等进阶营 --- ## 参考来源 1. [Claude Code 官方 Quickstart](https://code.claude.com/docs/en/quickstart) — 安装、登录、首次会话的权威八步指南，含原生 installer 命令与各账号类型说明 2. [Claude Code 官方 Commands 参考](https://code.claude.com/docs/en/commands) — 全部斜杠命令（/init、/permissions、/compact、/checkup、/doctor、/rewind 等）完整语义 3. [anthropics/claude-code GitHub README](https://github.com/anthropics/claude-code) — 官方仓库，确认 npm 安装已 deprecated、原生 installer 为推荐方式、Node.js 18+ 标记 4. [Claude Code Cheat Sheet（support.claude.com）](https://support.claude.com/en/articles/14553413-claude-code-cheatsheet) — 官方命令与键盘快捷键速查 5. [explainx.ai：Claude Code Commands 完整参考（2026，含 /checkup 更新）](https://www.explainx.ai/blog/claude-code-commands-complete-reference-guide-2026) — 第三方命令详解，记录 2026-07-09 新增的 /checkup 维护命令 --- *本文由「51学通信」原创整理，站长爱卫生（微信：gprshome201101）持续输出通信与 AI 工程实战内容。* > [!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 等场景全覆盖。