零基础装通Claude Code造命令行待办管家

首页 › tutorials › 零基础装通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（长期支持版） 安装包，一路"下一步"即可。安装完成后，打开终端验证：

node --version
npm --version

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

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

1.2 一行命令安装 Claude Code

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

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

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

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

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

安装完成后验证：

claude --version

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

常见问题：

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

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

在任意目录下执行：

claude

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

2.1 登录方式

Claude Code 支持几种认证方式：

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

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

2.2 三种运行形态

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

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

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

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

3.1 建一个项目目录

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

mkdir todo-cli
cd todo-cli

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

claude

3.2 用 `/init` 生成 CLAUDE.md

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

在 Claude 的输入框里输入：

/init

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

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

# 项目：命令行待办管家（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 提速。

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

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

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 会帮你产出的核心代码（你也会在终端里看到它逐段创建）：

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 帮你跑测试命令（它会请求执行权限，你放行即可）：

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 排错心法

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

实战案例完整流程

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

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

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

工作流程图

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[完整可用项目]

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

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

训练营适用性评估

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

参考来源

Quickstart - Claude Code Docs — Anthropic 官方快速上手指南，安装与首次会话的权威步骤。
Claude Code: Complete Guide to Installation and Getting Started — 2026 年安装、桌面端与核心命令的完整图文教程。
Claude Code Commands: Complete Slash Command Reference (2026) — /init、/goal、/loop、/compact 等斜杠命令的全面解释。
Common workflows - Claude Code Docs — 官方常用工作流，含探索代码库、修复 Bug、重构与测试。
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学通信知识星球海报-扫码加入

概述