<!-- title: 零基础装通Claude Code造命令行待办管家 -->

## 概述

本教程面向零基础读者，目标只有一个：从一台"什么都没装"的电脑起步，在 30 分钟内装通 Claude Code，并用对话的方式让它帮你写出一个**真正能用的命令行待办事项管理器（TODO CLI）**。你不需要会写代码——你需要学会的是"如何把需求讲清楚"。本教程覆盖安装、登录、CLAUDE.md 配置、Plan 模式、斜杠命令、权限确认，以及第一个完整项目的开发、测试与排错全流程。学完后你不仅能用上这个待办管家，更掌握了用 AI 编程的通用方法论。

## 前置条件

- **一台联网电脑**：Windows / macOS / Linux 任一系统均可。
- **Node.js 运行时**：版本 18 或更高（用于安装 Claude Code 本体）。
- **一个 Anthropic 账号**：用于登录认证；也可使用支持的第三方提供商。
- **一个终端**：Windows 用 PowerShell 或 Git Bash，macOS/Linux 用自带的 Terminal。
- **会的基本操作**：打开终端、`cd` 切换目录、复制粘贴命令。不需要任何编程经验。

---

## 第一步：安装 Node.js 与 Claude Code

### 1.1 安装 Node.js

Claude Code 是一个用 Node.js 写的命令行程序，所以要先装 Node.js 运行时。打开浏览器访问 nodejs.org，下载 **LTS（长期支持版）** 安装包，一路"下一步"即可。安装完成后，打开终端验证：

```bash
node --version
npm --version
```

预期输出类似 `v20.11.0` 和 `10.2.4`，只要第一个数字 ≥ 18 即可。

如果 `node` 命令找不到，多半是环境变量没生效，重启终端或重启电脑即可解决。

### 1.2 一行命令安装 Claude Code

Node 自带的包管理器 npm 可以全局安装 Claude Code。在终端执行：

```bash
npm install -g @anthropic-ai/claude-code
```

这条命令会从 npm 官方仓库下载 Claude Code 及其依赖，并注册到系统全局命令 `claude`。安装耗时约 1–2 分钟，取决于网速。

**国内网络加速（可选）**：如果下载卡住，可以先切换 npm 镜像源：

```bash
npm config set registry https://registry.npmmirror.com
```

安装完成后验证：

```bash
claude --version
```

预期输出一个版本号（如 `2.1.x`），说明安装成功。

**常见问题：**

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| `EACCES` 权限错误 | 全局目录无写权限 | macOS/Linux 前面加 `sudo`，或改用 nvm 管理 Node |
| 下载超时 | 网络问题 | 切换 npmmirror 镜像，或开代理 |
| `claude: command not found` | 全局 bin 路径不在 PATH | 用 `npm bin -g` 查路径，加入 PATH |

---

## 第二步：首次启动与登录认证

在任意目录下执行：

```bash
claude
```

第一次运行会进入**交互式登录流程**。你会看到终端里出现一个引导界面，提示你按回车在浏览器中打开 Anthropic 登录页。

### 2.1 登录方式

Claude Code 支持几种认证方式：

1. **Anthropic 账号（推荐新手）**：用浏览器跳转完成 OAuth 授权，自动回填令牌，最省事。
2. **API Key**：适合已有 API 余额的开发者，通过环境变量 `ANTHROPIC_API_KEY` 配置。
3. **第三方提供商**：如部分云厂商提供的兼容端点，通过 `--provider` 等参数指定。

新手选第 1 种即可。浏览器里登录你的 Anthropic 账号、点击"Authorize"，回到终端就会看到欢迎信息，光标停在一个输入框处——这就是你和 Claude 对话的地方。

### 2.2 三种运行形态

Claude Code 不止能在终端跑。了解全貌有助于后续选择：

- **交互式 REPL**：输入 `claude` 进入，一问一答持续对话，最常用。
- **一次性查询模式**：`claude "你的问题"`，跑完即退出，适合脚本。
- **桌面应用 / IDE 插件**：提供图形界面，VS Code 等编辑器有官方扩展。

本教程全程使用交互式 REPL。

---

## 第三步：理解 CLAUDE.md 与项目初始化

### 3.1 建一个项目目录

先为待办管家建一个干净的工作目录，并进去：

```bash
mkdir todo-cli
cd todo-cli
```

在这个目录里再次启动 Claude Code（如果已经开着，可以 `Ctrl+C` 退出后重启，确保它在正确目录）：

```bash
claude
```

### 3.2 用 `/init` 生成 CLAUDE.md

`CLAUDE.md` 是 Claude Code 的"项目说明书"——它会被自动读取并注入到每次对话的上下文里。里面有项目的技术栈、编码规范、目录结构、注意事项等。写好它，等于给 AI 装上了"项目记忆"。

在 Claude 的输入框里输入：

```
/init
```

`/init` 会扫描当前目录、理解项目（这里是空目录），然后生成一份 `CLAUDE.md` 草稿。因为是新项目，它会问你几个问题，比如用什么语言、做什么用途。

对于我们的待办管家，你可以让它生成后，再手动补充关键约定。一个适合本项目的 `CLAUDE.md` 示例：

```markdown
# 项目：命令行待办管家（todo-cli）

## 技术栈
- 语言：Python 3.10+
- 无第三方依赖，仅用标准库
- 数据存储：本地 JSON 文件 todos.json

## 编码规范
- 函数必须有中文 docstring
- 变量与函数名用英文 snake_case
- 每个函数尽量短小，单一职责

## 功能约定
- 支持 add / list / done / delete / clear 五个命令
- list 默认按优先级和创建时间排序
- 输出用颜色区分状态：未完成、已完成
```

`CLAUDE.md` 可以放在三个层级，优先级从高到低：

- **项目级**：`./CLAUDE.md`（或子目录的），只对当前项目生效。
- **用户级**：`~/.claude/CLAUDE.md`，对你所有项目生效（比如你个人的回复语言偏好）。
- **企业级**：系统管理的策略文件。

新手记住"项目根目录放一个 `CLAUDE.md`"就够了。

### 3.3 让 AI 帮你完善 CLAUDE.md

你不用手敲整份文件。直接跟 Claude 说：

> "帮我生成一份适合 Python 命令行待办管家的 CLAUDE.md，技术栈只用标准库，数据存 JSON，函数要中文注释。"

它会读你的需求、写文件，并问你确认。这正是 Claude Code 的核心用法：**你描述目标，它动手实现，你审核确认。**

---

## 第四步：认识核心交互——斜杠命令、Plan 模式、权限

在动手写代码前，掌握三个能让你效率翻倍的能力。

### 4.1 斜杠命令（Slash Commands）

以 `/` 开头的是 Claude Code 的内置快捷指令。最常用的几个：

| 命令 | 作用 |
|------|------|
| `/init` | 初始化项目，生成 CLAUDE.md |
| `/clear` | 清空当前对话上下文，开始新任务 |
| `/compact` | 压缩历史对话，节省上下文额度 |
| `/review` | 对当前改动做代码评审 |
| `/help` | 查看所有可用命令 |

这些命令让你不必记住复杂参数，输入 `/` 就能看到候选列表。

### 4.2 Plan 模式（计划模式）

这是新手最该养成的习惯。**让 Claude 先想、再动手。**

在输入框里，你可以切换到 Plan 模式（通常通过快捷键或输入特定命令切换，提示符会变化）。在 Plan 模式下，Claude **只读不写**——它会探索代码库、设计方案、列出步骤，但不会真的创建或修改任何文件。

为什么重要？因为它防止 AI 在你还没想清楚时，就哗啦啦改了一堆文件。你先看它的计划，觉得合理了再批准执行。

> 💡 心法：复杂任务永远先进入 Plan 模式审计划，简单任务可直接让它做。

### 4.3 权限确认（Permission）

Claude Code 默认不会"乱来"。当它要**写文件、执行命令、访问网络**时，会先弹窗请你确认。你会看到类似这样的提示：

```
Claude wants to write to todo.py
  ⎿  [y] Yes  [n] No  [a] Always allow for this directory
```

- 选 `y` 只允许这一次。
- 选 `a` 允许以后在这个目录里自动执行同类操作（减少打扰）。

新手建议**保持默认的逐次确认**，看清它要做什么再放行，这是建立信任的过程。熟练后再用 `a` 提速。

---

## 第五步：第一个项目——命令行待办管家

现在进入正题。我们要做一个这样的工具：

```bash
python todo.py add "写周报"              # 添加一条待办
python todo.py list                      # 列出所有待办
python todo.py done 2                    # 把第2条标记为完成
python todo.py delete 3                  # 删除第3条
python todo.py clear                     # 清空已完成
```

### 5.1 用"好需求"启动开发

在 Claude 输入框里，把需求讲清楚（这是你最该练的技能）。可以这样写：

> 我要做一个命令行待办管家 todo.py。请先进入 Plan 模式，给我一个实现方案。要求：
> 1. 用 Python 标准库，不装第三方包；
> 2. 数据存在当前目录的 todos.json；
> 3. 命令有 add / list / done / delete / clear；
> 4. list 输出要带颜色，未完成红色、已完成绿色；
> 5. 每条待办有 id、标题、优先级（high/normal/low）、是否完成、创建时间。

Claude 会先给出计划：文件结构、数据格式、各函数职责。你审阅后输入"同意，开始实现"，它就开始写代码。

### 5.2 预期结果：todo.py

下面是 Claude 会帮你产出的核心代码（你也会在终端里看到它逐段创建）：

```python
import json
import os
from datetime import datetime

DATA_FILE = "todos.json"

# 颜色码（ANSI）
RED = "\033[91m"
GREEN = "\033[92m"
YELLOW = "\033[93m"
RESET = "\033[0m"

PRIORITY_ORDER = {"high": 0, "normal": 1, "low": 2}


def load_todos():
    """从 JSON 文件读取待办列表，文件不存在则返回空列表。"""
    if not os.path.exists(DATA_FILE):
        return []
    with open(DATA_FILE, "r", encoding="utf-8") as f:
        return json.load(f)


def save_todos(todos):
    """把待办列表写回 JSON 文件。"""
    with open(DATA_FILE, "w", encoding="utf-8") as f:
        json.dump(todos, f, ensure_ascii=False, indent=2)


def add_todo(title, priority="normal"):
    """新增一条待办，自动分配递增 id 并记录创建时间。"""
    todos = load_todos()
    new_id = (todos[-1]["id"] + 1) if todos else 1
    todos.append({
        "id": new_id,
        "title": title,
        "priority": priority,
        "done": False,
        "created": datetime.now().strftime("%Y-%m-%d %H:%M"),
    })
    save_todos(todos)
    print(f"{GREEN}已添加 #{new_id}：{title}{RESET}")


def list_todos():
    """列出所有待办，按优先级与创建时间排序，未完成在前。"""
    todos = load_todos()
    if not todos:
        print("（暂无待办）")
        return
    todos.sort(key=lambda t: (t["done"], PRIORITY_ORDER.get(t["priority"], 1)))
    for t in todos:
        status = f"{GREEN}✓{RESET}" if t["done"] else f"{RED}○{RESET}"
        color = GREEN if t["done"] else YELLOW
        print(f"[{t['id']:>2}] {status} {color}{t['title']}{RESET} ({t['priority']})")
```

完整版还会包含 `done_todo`、`delete_todo`、`clear_done` 和命令行参数解析（用 `argparse`）。你不必一次写完——让 Claude 分批实现，每完成一个命令就测一个。

### 5.3 跑起来验证

让 Claude 帮你跑测试命令（它会请求执行权限，你放行即可）：

```bash
python todo.py add "写周报" --priority high
python todo.py add "买咖啡" --priority low
python todo.py list
python todo.py done 2
python todo.py list
```

预期输出（带颜色）：

```
已添加 #1：写周报
已添加 #2：买咖啡
[ 1] ○ 写周报 (high)
[ 2] ○ 买咖啡 (low)
已标记 #2 完成
[ 1] ○ 写周报 (high)
[ 2] ✓ 买咖啡 (low)
```

### 5.4 常见问题与解决

| 现象 | 排查方向 |
|------|----------|
| Windows 下颜色码显示成 `[91m` 乱码 | 终端不支持 ANSI，加一行 `os.system("")` 或换用 Windows Terminal |
| `todos.json` 中文变 `\uXXXX` | 写文件时 `ensure_ascii=False`（上面代码已加） |
| `done 2` 报错找不到 id | 列表展示的 id 与存储 id 不一致，检查排序是否影响了取值 |
| 报错找不到命令 | 没把命令分发到对应函数，检查 `argparse` 子命令是否注册完整 |

---

## 第六步：迭代增强、测试与排错

第一个版本能跑只是起点。Claude Code 的强项在于**持续迭代**。你可以继续这样对话：

> 给 todo.py 加一个 `find 关键词` 命令，按标题模糊搜索待办；再帮我写一个 test_todo.py，用标准库 unittest 测试 add/list/done/clear 四个功能。

Claude 会新增 `find` 功能、生成测试文件，并请求运行测试。你会看到类似输出：

```
.....
----------------------------------------------------------------------
Ran 5 tests in 0.01s

OK
```

如果某个测试失败，把失败信息贴回对话，Claude 会自动定位、修复、重跑。这种"**让 AI 跑测试 → 贴报错 → AI 修复**"的闭环，是高效开发的核心节奏。

### 6.1 排错心法

1. **报错原样贴给 Claude**，比你自己描述准确得多。
2. **一次只改一个地方**，改完先测再继续。
3. **上下文太长时用 `/clear`**，避免历史干扰。
4. **想偷懒提速**：把读操作（`list`、`find`）设为 `a` 自动允许，写操作（`delete`、`clear`）保持确认。

---

## 实战案例完整流程

把前面串起来，完整跑一遍待办管家的开发闭环：

1. `mkdir todo-cli && cd todo-cli`
2. `claude` 启动
3. `/init` 生成 CLAUDE.md，补充项目约定
4. 进入 Plan 模式，提交需求，审核实现计划
5. 批准执行，Claude 创建 `todo.py`
6. 放行命令权限，跑 `add/list/done` 验证
7. 让 Claude 加 `find` 命令和 `test_todo.py`
8. 跑测试，贴报错让 Claude 修复
9. `/clear` 收尾，或继续加新功能

这是一个**最小但完整**的 AI 编程工作流——需求 → 计划 → 实现 → 测试 → 修复 → 迭代。

---

## 工作流程图

```mermaid
flowchart TD
    A[装 Node.js + Claude Code] --> B[claude 启动并登录]
    B --> C[建项目目录]
    C --> D["/init 生成 CLAUDE.md"]
    D --> E[进入 Plan 模式写需求]
    E --> F{审核计划}
    F -- 不满意 --> E
    F -- 满意 --> G[Claude 创建 todo.py]
    G --> H[放行权限 跑命令验证]
    H --> I{功能正常?}
    I -- 否 --> J[贴报错给 Claude 修复]
    J --> H
    I -- 是 --> K[迭代新功能+写测试]
    K --> L[完整可用项目]
```

整个开发过程的控制流，从安装到产出，一图掌握：

```mermaid
flowchart LR
    subgraph 准备
      P1[安装]
      P2[登录]
      P3[配置 CLAUDE.md]
    end
    subgraph 开发
      D1[Plan 计划]
      D2[编码]
      D3[权限确认]
    end
    subgraph 闭环
      T1[运行测试]
      T2[贴报错]
      T3[自动修复]
    end
    P1 --> P2 --> P3 --> D1 --> D2 --> D3 --> T1 --> T2 --> T3 --> T1
```

---

## 延伸阅读

- **官方快速上手**：code.claude.com/docs/en/quickstart —— Anthropic 官方 Quickstart，权威起点。
- **常用工作流**：code.claude.com/docs/en/common-workflows —— 探索代码库、修 Bug、重构、测试等日常操作。
- **斜杠命令全集**：code.claude.com/docs/en/commands —— 所有内置命令的官方说明。
- **社区速查表**：computingforgeeks.com/claude-code-cheat-sheet —— v2.1.x 速查，含 CLI flags 与快捷键。

下一步建议：把待办管家用 Git 纳入版本管理（`git init`），体验"让 Claude 帮你写 commit message"；或尝试给项目接入一个 MCP 服务器，让它能直接读写你的日历。

---

## 训练营适用性评估

- **适合的训练营类型**：AI 编程入门营、产品经理/运营的"无代码上手 AI"工作坊、大学生技能启蒙营、企业内部数字化提效培训。门槛极低，不要求学员有编程背景。
- **预计教学时长**：2–2.5 小时。其中安装与登录约 30 分钟，CLAUDE.md 与核心交互讲解约 30 分钟，待办管家项目开发约 60–90 分钟。
- **教学价值**：本教程不是"教写代码"，而是"教如何用自然语言驱动 AI 产出可用代码"。学员收获的是一个可运行的工具 + 一套可复用的 AI 协作方法论（需求描述、Plan 审核、权限管理、测试闭环），后者可迁移到任何后续项目。
- **分组建议**：2 人一组，一人负责提需求、一人负责审计划与确认权限，效果最佳。
- **延伸练习**：让学员把待办管家改成"个人记账本"或"读书清单"，复用本教程的工作流独立完成。

---

## 参考来源

1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — Anthropic 官方快速上手指南，安装与首次会话的权威步骤。
2. [Claude Code: Complete Guide to Installation and Getting Started](https://neurohive.io/en/guides/claude-code-getting-started-guide/) — 2026 年安装、桌面端与核心命令的完整图文教程。
3. [Claude Code Commands: Complete Slash Command Reference (2026)](https://www.explainx.ai/blog/claude-code-commands-complete-reference-guide-2026) — `/init`、`/goal`、`/loop`、`/compact` 等斜杠命令的全面解释。
4. [Common workflows - Claude Code Docs](https://code.claude.com/docs/en/common-workflows) — 官方常用工作流，含探索代码库、修复 Bug、重构与测试。
5. [Claude Code Cheat Sheet](https://computingforgeeks.com/claude-code-cheat-sheet/) — v2.1.x 速查表，覆盖默认模型、后台 Agent、斜杠命令与 CLI flags。

> [!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 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)