<!-- title: 零基础装通Claude Code造首个单词卡工具 -->

## 概述

本教程面向从未接触过命令行 AI 编程的零基础学习者，目标只有一个：在一台干净的电脑上，从安装 Claude Code、完成登录、写好配置，到亲手驱动它造出第一个能跑的项目——一个**命令行单词卡背诵工具**。学完后你将掌握 Claude Code 的安装登录、权限配置、CLAUDE.md 项目记忆、三种交互模式的区别，并具备用自然语言指挥 AI 写代码的完整心智模型。适用人群：在校学生、转行开发者、对 AI 编程好奇的非科班爱好者。

## 前置条件

| 项目 | 要求 | 说明 |
|------|------|------|
| 操作系统 | Windows / macOS / Linux 任一 | Windows 推荐 WSL2，体验更顺 |
| Node.js | 18 及以上 LTS 版本 | 安装 Claude Code 的硬性依赖 |
| 终端 | 系统自带即可 | macOS 用 Terminal，Windows 用 PowerShell 或 WSL |
| 账号 | Claude 账号（Pro/Max 订阅）或 API Key | 二选一，登录方式不同 |
| 网络 | 能访问 npm 与 claude.ai | 国内用户可配置代理或第三方中转 |
| Python | 3.8+（本教程项目用） | 验证：`python --version` |

检查 Node 是否就绪：

```bash
node --version   # 应输出 v18.x.x 或更高
npm --version
```

若没有 Node，前往 nodejs.org 下载 LTS 安装包，或用 nvm 管理：

```bash
# macOS / Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install --lts

# Windows（PowerShell，用 winget）
winget install OpenJS.NodeJS.LTS
```

---

## 正文

### 第一步：安装 Claude Code

Claude Code 官方推荐两种安装方式。**npm 全局安装**最通用，**原生安装脚本**免去 Node 依赖、自动更新更省心。二选一即可。

**方式 A：npm 全局安装（推荐新手）**

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

安装完成后验证：

```bash
claude --version
```

**预期结果**：终端打印出形如 `2.x.x` 的版本号，说明安装成功。

**方式 B：原生安装脚本（无需 Node）**

```bash
# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows（PowerShell）
irm https://claude.ai/install.ps1 | iex
```

**常见问题与解决**

- **`zsh: permission denied: claude` / `EACCES`**：npm 全局目录没有写权限。解决：改用 nvm 管理 Node，或执行 `npm config set prefix ~/.npm-global` 并把 `~/.npm-global/bin` 加入 PATH。
- **国内网络 npm 拉不下来**：换淘宝镜像 `npm config set registry https://registry.npmmirror.com`，安装完再切回官方源。
- **命令找不到**：重启终端，让 PATH 生效；仍不行，检查安装日志里提示的 bin 目录是否在 PATH 中。

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

在任意目录（建议建一个练习文件夹）启动：

```bash
mkdir ~/claude-lab && cd ~/claude-lab
claude
```

**预期结果**：第一次运行会进入交互式登录流程。

- **方式一（推荐，订阅用户）**：选择 `Claude account`，回车后终端打印一个网址和一串验证码，浏览器自动打开 claude.ai，粘贴验证码即完成 OAuth 登录。
- **方式二（API 用户）**：选择 `API key`，粘贴你在 console.anthropic.com 创建的 key；也可通过环境变量提供，避免明文留在配置里：

```bash
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"
```

登录成功后，终端会出现 `>` 提示符，进入交互式会话（REPL）。此刻你已经能和 Claude Code 对话了。

**常见问题与解决**

- **浏览器打不开验证页**：手动复制终端里的 URL 到浏览器，再输入验证码。
- **`Monthly Limit Exhausted` / 配额耗尽**：订阅套餐用量到顶，等待重置或升级套餐；用 API key 则是余额不足，去控制台充值。
- **登录后立刻报 401**：key 复制错了或带了多余空格，重新粘贴。

### 第三步：认识三种核心模式

进入会话后，先按一次 `Shift + Tab`，注意底部状态栏变化。Claude Code 有三种交互模式，新手务必分清：

| 模式 | 触发 | 行为特点 | 适用场景 |
|------|------|----------|----------|
| **默认模式** | 启动即是 | 需要执行命令/改文件时先问你授权 | 日常开发，安全可控 |
| **Plan 模式** | `Shift+Tab` 切到 "plan to accept" | 只读探索、只出方案不落地，确认后才执行 | 不确定怎么改、想先看规划 |
| **Auto-accept 模式** | `Shift+Tab` 切到 "accept edits on" | 自动接受文件编辑（命令仍可能问） | 信任度高的小步迭代 |

> 核心心法：**默认模式是新手的安全网**。它会逐条征求许可，把决定权留给你。不要一上来就开 Auto-accept 全自动，先在默认模式下观察它要做什么。

### 第四步：配置 settings.json 与权限

Claude Code 的配置分三层，优先级从低到高：用户级 < 项目级 < 本地级。

```
~/.claude/settings.json            # 用户级：所有项目生效
<项目>/.claude/settings.json       # 项目级：随仓库提交，团队共享
<项目>/.claude/settings.local.json # 本地级：不提交，个人覆盖
```

权限系统是配置的核心。用 `allow` 预批准安全命令、用 `deny` 拦截危险命令，能大幅减少反复确认。

为本次练习项目创建 `.claude/settings.json`：

```json
{
  "permissions": {
    "allow": [
      "Bash(python *)",
      "Bash(pip install *)",
      "Bash(cat *)",
      "Bash(ls *)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}
```

格式说明：`Bash(...)` 里的内容是命令前缀匹配；裸写 `Read`/`Write`/`Edit` 表示整类工具放行。`deny` 永远优先于 `allow`，是一道兜底保险。

> 也可以全程不手写文件——在会话里输入 `/permissions`，用图形界面增删规则，结果自动落盘。

**常见问题与解决**

- **每次都要确认 `python app.py`**：把它加进 `allow`，如 `Bash(python app.py)` 或更宽的 `Bash(python *)`。
- **改了配置没生效**：在会话内 `/config` 查看当前生效值；JSON 写错（多了逗号、少了引号）会被静默忽略，用 JSON 校验工具过一遍。

### 第五步：建立项目记忆 CLAUDE.md

`CLAUDE.md` 是 Claude Code 的"项目说明书"，每次会话自动加载。它越清晰，AI 越少跑偏。会话里直接输入 `/init`，它会扫描项目自动生成初稿；这里我们手写一份。

在项目根目录创建 `CLAUDE.md`：

```markdown
# 项目：命令行单词卡

## 目标
一个零依赖（仅 Python 标准库）的命令行单词卡背诵工具。

## 技术栈
- Python 3.8+，仅用标准库（json、random、argparse）
- 数据存在 words.json

## 功能
1. learn：添加生词（单词、释义、例句）
2. quiz：随机抽 5 个词测试，答对显示例句
3. list：列出全部词条

## 代码规范
- 中文注释，函数加 docstring
- 不引入第三方库
- 运行入口：python flashcard.py
```

**预期效果**：之后无论重启多少次会话，Claude Code 都"记得"这是纯标准库项目，不会自作主张塞 requests、colorama 等依赖。

---

## 实战案例：命令行单词卡工具

现在把前面四步串起来，让 Claude Code 亲手造出工具。

**第 1 步**：确认你在 `~/claude-lab` 目录，已有 `CLAUDE.md` 和 `.claude/settings.json`。

**第 2 步**：在交互会话里，切换到 **Plan 模式**（按 `Shift+Tab`），输入：

```
请按 CLAUDE.md 的规划，实现这个单词卡工具。先给我一个实现方案和数据结构设计，不要写代码。
```

Claude 会输出方案：`words.json` 的字段（word / meaning / example / box）、`flashcard.py` 的函数划分（`load_words`、`save_words`、`cmd_learn`、`cmd_quiz`、`cmd_list`、`main`）。

**第 3 步**：确认方案后切回**默认模式**，输入：

```
方案没问题，按此实现 flashcard.py 和示例 words.json。
```

Claude 会逐个创建文件，并请求执行权限（如果你配置了 `Bash(python *)`，运行阶段会很顺）。它会写出类似下面的代码（核心骨架）：

```python
import json, random, argparse, os
from pathlib import Path

DB = Path(__file__).parent / "words.json"

def load_words():
    """读取词库，不存在则返回空列表。"""
    if not DB.exists():
        return []
    return json.loads(DB.read_text(encoding="utf-8"))

def save_words(words):
    """持久化词库。"""
    DB.write_text(json.dumps(words, ensure_ascii=False, indent=2), encoding="utf-8")

def cmd_learn(args):
    """添加一个生词。"""
    words = load_words()
    words.append({"word": args.word, "meaning": args.meaning, "example": args.example or ""})
    save_words(words)
    print(f"✅ 已添加：{args.word} —— {args.meaning}")

def cmd_quiz(args):
    """随机抽测 n 个词。"""
    words = load_words()
    n = min(args.n, len(words)) if words else 0
    if n == 0:
        print("词库为空，先 learn 添加几个词吧。"); return
    score = 0
    for w in random.sample(words, n):
        ans = input(f"\n【{w['word']}】的释义是？> ")
        if ans.strip() == w["meaning"]:
            score += 1; print("✅ 正确！", f"例句：{w['example']}" if w['example'] else "")
        else:
            print(f"❌ 正确答案：{w['meaning']}")
    print(f"\n本轮得分 {score}/{n}")

def cmd_list(args):
    """列出全部词条。"""
    for i, w in enumerate(load_words(), 1):
        print(f"{i}. {w['word']} —— {w['meaning']}")

def main():
    p = argparse.ArgumentParser(description="命令行单词卡背诵工具")
    sub = p.add_subparsers(dest="cmd", required=True)
    pl = sub.add_parser("learn"); pl.add_argument("--word", required=True); pl.add_argument("--meaning", required=True); pl.add_argument("--example")
    pq = sub.add_parser("quiz"); pq.add_argument("-n", type=int, default=5)
    sub.add_parser("list")
    a = p.parse_args()
    {"learn": cmd_learn, "quiz": cmd_quiz, "list": cmd_list}[a.cmd](a)

if __name__ == "__main__":
    main()
```

**第 4 步**：让 Claude 自己跑测试。输入：

```
用 python flashcard.py learn 添加 3 个示例词，再用 quiz 抽测 3 个，确认没有报错。
```

它会自动执行命令（受你配置的权限控制），并把输出贴给你。

**第 5 步**：实际体验。在终端运行：

```bash
python flashcard.py learn --word serendipity --meaning "意外发现美好事物的能力" --example "Finding this cafe was pure serendipity."
python flashcard.py learn --word ephemeral --meaning "短暂的，转瞬即逝的"
python flashcard.py list
python flashcard.py quiz -n 2
```

**预期结果**：

```
1. serendipity —— 意外发现美好事物的能力
2. ephemeral —— 短暂的，转瞬即逝的

【ephemeral】的释义是？> 短暂的，转瞬即逝的
✅ 正确！

本轮得分 1/2
```

**常见问题与解决**

- **中文乱码（Windows）**：文件头加 `# -*- coding: utf-8 -*-`，或在 PowerShell 执行 `chcp 65001`。
- **`quiz` 输入法卡顿**：终端对中文输入支持差时，先 `learn` 英文释义的词测试流程。
- **Claude 想装第三方库美化输出**：直接回绝——`CLAUDE.md` 已声明纯标准库，提醒它"遵守 CLAUDE.md，不要加依赖"即可。
- **想加新功能（如导出 Anki 卡片）**：保持小步迭代，一次只提一个需求，先 Plan 后执行。

### 第六步：常用会话命令速查

会话内这些斜杠命令最常用，建议背下来：

| 命令 | 作用 |
|------|------|
| `/help` | 查看全部命令 |
| `/config` | 查看/修改设置 |
| `/permissions` | 管理权限白名单 |
| `/model` | 切换模型（Opus / Sonnet / Haiku） |
| `/clear` | 清空当前对话上下文 |
| `/compact` | 压缩历史，节省 token |
| `/cost` | 查看本次会话花费 |
| `/init` | 自动生成 CLAUDE.md |
| `/review` | 对当前改动做代码评审 |

---

## 工作流程

```text
flowchart TD
    A[检查 Node 18+] --> B[安装 Claude Code<br/>npm 或 原生脚本]
    B --> C[claude 首次启动<br/>OAuth/API Key 登录]
    C --> D[新建项目目录<br/>进入会话]
    D --> E[写 settings.json<br/>配置 allow/deny 权限]
    E --> F[写 CLAUDE.md<br/>项目记忆与规范]
    F --> G[Plan 模式出方案]
    G --> H{方案满意?}
    H -- 否 --> G
    H -- 是 --> I[默认模式执行<br/>逐条确认]
    I --> J[让 Claude 跑测试]
    J --> K{通过?}
    K -- 否 --> I
    K -- 是 --> L[完成单词卡工具<br/>实机体验]
    L --> M[/cost 查花费<br/>/clear 收尾]
```

整个链路体现了 Claude Code 的安全哲学：**配置在先、记忆在前、Plan 探路、默认模式把关、测试收尾**。新手按这条链路走，几乎不会出大岔子。

---

## 延伸阅读

- 官方快速上手：`code.claude.com/docs/en/quickstart`——安装登录的标准答案，永远以它为准。
- 官方权限文档：`code.claude.com/docs/en/permissions`——`allow`/`deny` 语法、四种权限模式的权威说明。
- 官方设置文档：`code.claude.com/docs/en/settings`——三层 settings.json 的合并规则与字段全集。
- Real Python《Getting Started With Claude Code》：Python 自动化视角的入门，与本教程项目互补。
- Builder.io《How to Use Claude Code》：从安装到第一个真实改动的完整录像式教程。

---

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| 适合训练营类型 | **AI 编程入门营**、**全栈/Python 启蒙营**、**大学生数字素养营**、**企业新员工 AI 提效培训** |
| 学员基础 | 零基础可上手，会用命令行更佳；不懂 Python 也能跟着跑通 |
| 预计教学时长 | **3 小时**：安装登录 40 分钟，配置与 CLAUDE.md 50 分钟，造词卡工具并调试 70 分钟，答疑 40 分钟 |
| 难度曲线 | 平缓，唯一卡点是国内网络与登录，建议讲师提前备好中转或镜像方案 |
| 进阶衔接 | 本课结束后可顺接 Skill 开发营（Round 2）、MCP 开发营（Round 3）、Agent 自动化营（Round 4） |
| 评估方式 | 学员当场跑通 `quiz` 并答对即为合格；要求 CLAUDE.md 与 settings.json 提交到 Git |

---

## 参考来源

1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — 官方安装、登录、首个会话的标准流程
2. [Configure permissions - Claude Code Docs](https://code.claude.com/docs/en/permissions) — allow/deny 权限语法与四种权限模式
3. [Claude Code settings - Claude Code Docs](https://code.claude.com/docs/en/settings) — 三层 settings.json 合并规则与字段说明
4. [Claude Code 完全指南：从安装到高级 Agent 工作流（2026 版）](https://www.promptnet.cn/2026/06/16/claude-code-complete-guide/) — 安装到 Agent 工作流的中文实战全景
5. [Claude Code 超详细完整指南（2026 版）](https://blog.csdn.net/liulin_521/article/details/155862222) — 从 0 到 1 安装登录建项目的中文手把手教程

> [!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)