<!-- title: 新手首项目：用Claude Code造命令行记账本 -->

> 本教程带你完成 Claude Code 的第一个**完整工程**：从空文件夹起步，用自然语言驱动 Claude Code 写出一个能用的命令行记账本（Python，零第三方依赖）。过程中你会掌握新手最该先学的三件套——`/init` 生成项目骨架、`CLAUDE.md` 给项目装"记忆"、`settings.json` 权限配置。适合**已经装好 Claude Code、但还没独立跑完一个项目**的零基础开发者。

## 一、为什么用"记账本"当第一个项目

新手教程最常见的两个坑：一是只讲安装不讲"装完之后干嘛"，二是用"Hello World / 整理文件夹"这种玩具例子，跑完即弃、学不到工程闭环。

命令行记账本（expense ledger）是一个**最小但完整**的真实项目，它天然包含四类工程动作：

- **数据建模**：每笔账目有金额、类别、日期、备注
- **持久化**：要读写本地 JSON 文件，必然触碰"文件权限"
- **命令解析**：`add / list / summary / delete` 多个子命令
- **可测试**：金额汇总、日期过滤有明确的输入输出，天然适合写单元测试

这恰好覆盖了 Claude Code 新手最需要练的核心循环：**提需求 → 看代码 → 跑起来 → 跑测试 → 提交**。

## 二、前置条件

| 项目 | 要求 | 说明 |
|------|------|------|
| Claude Code | 已安装并能 `claude` 启动 | 本教程不重复讲安装，只做一次就绪校验 |
| Python | 3.8+ | 项目只用标准库，无需 `pip install` |
| 终端 | 任意 shell（bash/zsh/PowerShell） | 命令以 bash 为例 |
| Git | 已安装 | 最后一步提交版本用到 |

> 还没安装 Claude Code？官方支持三种方式：`npm install -g @anthropic-ai/claude-code`、原生安装脚本、或 IDE 插件。任选其一装好、能跑通登录即可。

## 三、整体工作流程

先看全局，再逐步落地：

```mermaid
flowchart TD
    A[claude 就绪校验] --> B[建项目目录并进入]
    B --> C["/init 生成骨架 CLAUDE.md"]
    C --> D[手写项目 CLAUDE.md 给记忆]
    D --> E[写 .claude/settings.json 权限]
    E --> F[自然语言下需求: 造记账本]
    F --> G[Claude 实现 + 自检]
    G --> H{跑起来?}
    H -- 报错 --> I[贴报错回喂 Claude 修]
    I --> G
    H -- 正常 --> J[加单元测试]
    J --> K[git init + 首次提交]
    K --> L[完工: 可日常使用]

    style D fill:#e8f5e9
    style E fill:#fff3e0
    style F fill:#e3f2fd
```

绿色 = 项目记忆，橙色 = 权限安全，蓝色 = 自然语言驱动。这三层是新手最容易跳过、但对后续效率影响最大的部分。

## 四、分步骤实战

### 步骤 0：校验 Claude Code 就绪（1 分钟）

打开终端，确认能正常进入交互模式：

```bash
claude --version
```

**预期结果**：打印版本号（如 `2.1.x`），说明 CLI 已就绪。

**常见问题**

- *报 `command not found`*：说明未正确安装或不在 PATH。重跑官方安装命令，或检查 `npm bin -g` 是否在 PATH 中。
- *能进但提示未登录*：按提示用 Anthropic 账号或 API Key 登录一次即可。

### 步骤 1：创建项目目录并进入

```bash
mkdir ledger-cli && cd ledger-cli
claude
```

**预期结果**：终端进入 Claude Code 交互界面，工作目录就是 `ledger-cli`（一个空文件夹）。

> 新手务必在**项目根目录**启动 `claude`——它会把当前目录视为项目根，后续生成的 `CLAUDE.md` 和 `.claude/` 都落在这一层。

### 步骤 2：用 `/init` 生成项目骨架

在交互界面直接输入斜杠命令：

```
/init
```

**预期结果**：Claude Code 会扫描目录（此时是空的），然后在项目根生成一个初始 `CLAUDE.md`，并自动加一段"项目概览"占位内容。这是官方推荐的"项目记忆"入口。

**常见问题**

- *生成的 CLAUDE.md 内容很少*：空项目本来就没有代码可分析，正常现象。下一步我们会手动填充。
- *提示是否信任当前目录*：第一次在某个目录启动会问 "Do you trust this folder"，选 Yes。这是安全机制，防止在陌生目录误操作。

### 步骤 3：手写项目 `CLAUDE.md`——给项目装"记忆"

`CLAUDE.md` 是 Claude Code 每次会话开始**自动读取**的项目说明文件。写得越清楚，Claude 越不需要你反复解释背景。把刚才生成的文件改成下面这样：

```markdown
# ledger-cli —— 命令行记账本

## 项目目标
一个用 Python 标准库实现的本地记账 CLI，数据存为 JSON，零第三方依赖。

## 技术约束
- Python 3.8+，仅用标准库（json / argparse / pathlib / datetime）
- 数据文件：./data/ledger.json（不存在时自动创建）
- 入口：./ledger.py
- 测试：./test_ledger.py，用标准库 unittest，运行 `python -m pytest` 或 `python -m unittest`

## 命令规范
- add  AMOUNT CATEGORY [--note N] [--date YYYY-MM-DD]  新增一笔
- list [--category C] [--month YYYY-MM]               列出账目
- summary [--month YYYY-MM]                            按类别汇总
- delete ID                                            按 ID 删除

## 代码风格
- 函数有 docstring；金额一律用整数分存储，展示时除以 100
- 所有文件操作用 pathlib，不用 os.path 字符串拼接
```

**预期结果**：保存后，下一次发消息时 Claude 已经"知道"项目目标、技术约束和命令规范，不会自作主张引入第三方库（如 `click`、`rich`）。

**常见问题**

- *为什么不用中文写约束？* 可以中文，但关键字（命令、路径）保持英文，便于 Claude 精确匹配。
- *CLAUDE.md 该写多长？* 越精炼越好，**控制在 30 行以内**。它不是文档，而是"给 AI 的简报"，冗长反而稀释重点。

> 核心心法：`CLAUDE.md` 写的是**决策与约束**（用什么、不用什么、规范是什么），而不是项目使用说明书。

### 步骤 4：配置 `.claude/settings.json`——权限安全网

新建 `.claude/settings.json`，定义 Claude 在本项目里能自动做什么、必须问你、以及绝对不能做：

```json
{
  "permissions": {
    "allow": [
      "Read(**)",
      "Bash(python3:*)",
      "Bash(python -m unittest:*)",
      "Bash(ls:*)",
      "Edit(./ledger.py)",
      "Edit(./test_ledger.py)"
    ],
    "ask": [
      "Bash(git:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Write(./data/**)"
    ]
  }
}
```

逐层解释：

- **`allow`（自动放行）**：读文件、跑 Python、跑测试——这些是开发中高频且安全的操作，放行后不再每次弹窗，开发节奏顺滑。
- **`ask`（每次询问）**：`git` 命令默认要你确认，避免 AI 在你不知情时提交/推送。
- **`deny`（直接禁止）**：`rm -rf`、`sudo` 这种高危命令一刀切；同时禁止 Claude **直接写数据目录** `./data/**`，强制它通过程序逻辑去操作数据，防止它手贱覆盖你的记账文件。

**预期结果**：输入 `/permissions` 可在交互界面查看当前生效规则。

**常见问题**

- *权限语法 `Bash(python3:*)` 里那个 `:*` 是什么？* `:*` 是通配，表示 `python3` 开头的命令及其任意参数都匹配。`Bash(git status)`（不带 `*`）则只精确匹配这一条命令。
- *目录里还有个 `settings.local.json`？* 那是本地个人覆盖（如你自己的临时放行），加进 `.gitignore` 不提交；团队共享的规则放 `settings.json`。
- *新手要不要用 `--dangerously-skip-permissions`？* **不要**。它关掉所有安全检查，只在一次性沙箱里用。养成配 `settings.json` 的习惯更安全。

### 步骤 5：自然语言下需求，让 Claude 实现

现在权限和记忆都就位，用一句人话下需求：

```
按 CLAUDE.md 的规范，实现 ledger.py 命令行记账本。
先给我数据层和 add/list，每步实现后跑一下验证再继续。
```

**为什么这条提示好**：① 明确"按 CLAUDE.md 规范"——引用记忆；② 分两步实现，避免一次生成太多无法验证；③ 要求"每步跑一下"——让 Claude 主动用 `python3` 自检，配合刚才放行的 `Bash(python3:*)` 全程不弹窗。

**预期结果**：Claude 会先创建 `ledger.py`，实现数据读写 + `add` + `list`，并自行运行示例命令验证。你能看到它输出类似：

```
$ python3 ledger.py add 12.50 餐饮 --note 兰州拉面
✓ 新增记录 #1

$ python3 ledger.py list
ID  日期        金额    类别   备注
1   2026-06-27  12.50   餐饮   兰州拉面
```

**常见问题**

- *它擅自用了 `click`/`rich`？* 检查 `CLAUDE.md` 是否真的写了"仅标准库"。把约束钉死，再回一句"去掉所有第三方依赖，改用标准库"。
- *一次生成太多没验证？* 明确要求"先只做 add 和 list，跑通再做 summary 和 delete"，控制增量。

### 步骤 6：补充 `summary` 和 `delete`，并实战调试

继续驱动：

```
很好。现在加 summary（按类别汇总金额，支持 --month 过滤）
和 delete（按 ID 删除，删除前打印确认信息）。
做完用多笔样例数据演示一遍。
```

**预期结果**：Claude 补全两个子命令，并用样例自测：

```
$ python3 ledger.py summary --month 2026-06
类别      笔数   金额
餐饮      3      45.50
交通      2      18.00
合计      5      63.50

$ python3 ledger.py delete 2
将删除记录 #2：2026-06-27 交通 ¥6.00（地铁）
✓ 已删除
```

**调试场景**：故意制造一个边界情况，把报错喂回给 Claude——这是新手必须练的"人机协作修 bug"循环：

```
我执行 python3 ledger.py add abc 餐饮 报错了，错误是：
"could not convert string to float: 'abc'"。
请给 add 命令加金额校验，非法输入给友好提示并退出码 1。
```

**预期结果**：Claude 在金额解析处加 `try/except`，非法输入时打印 `错误：金额必须是数字，收到 'abc'` 并 `sys.exit(1)`。学会"贴报错原文回喂"是高效协作的关键——比你自己描述 bug 准确十倍。

### 步骤 7：加单元测试

```
为 ledger.py 写单元测试 test_ledger.py，用 unittest 覆盖：
- 新增记录后 list 能查到
- summary 的金额汇总正确
- 非法金额输入返回非零退出码
然后跑测试，全绿才算完。
```

因为 `Bash(python -m unittest:*)` 已在 allow 列表，Claude 跑测试不会打断你。

**预期结果**：

```
$ python3 -m unittest test_ledger.py -v
test_add_then_list ... ok
test_summary_total ... ok
test_invalid_amount ... ok
----------------------------------------------------------------------
Ran 3 tests in 0.02s

OK
```

**常见问题**

- *测试写到一半红了？* 直接把失败输出贴回去："`test_summary_total` 失败了，期望 45.50 实际 45.5，是浮点精度问题，把金额改成整数分存储。"——把根因假设也喂给它，修得更快（这一步也呼应了 `CLAUDE.md` 里"整数分存储"的约束）。

### 步骤 8：版本管理——首次提交

由于 `git` 在 `ask` 列表，Claude 会先征求你同意再执行。让它初始化仓库并提交：

```
git init，把 ledger.py、test_ledger.py、CLAUDE.md、.claude/settings.json 加入暂存并提交，
commit message 用中文简述"初始化命令行记账本"。
注意 .claude/settings.local.json 和 data/ 不要提交。
```

**预期结果**：Claude 先问是否允许执行 git 命令，确认后生成 `.gitignore`（含 `data/`、`.claude/settings.local.json`），完成首次提交。

```bash
git log --oneline
# a1b2c3d 初始化命令行记账本
```

**常见问题**

- *它想提交 `data/ledger.json`？* 你已经在 `deny` 或 `.gitignore` 排除了数据目录；如果没排，当场纠正"数据文件不要进版本库"。

## 五、最终项目结构

```mermaid
flowchart LR
    ROOT[ledger-cli/] --> ENTRY[ledger.py<br/>入口+业务逻辑]
    ROOT --> TEST[test_ledger.py<br/>单元测试]
    ROOT --> MD[CLAUDE.md<br/>项目记忆]
    ROOT --> DOT[.claude/]
    DOT --> S1[settings.json<br/>团队权限]
    DOT --> S2[settings.local.json<br/>本地覆盖·不提交]
    ROOT --> DATA[data/]
    DATA --> JSON[ledger.json<br/>运行时生成·不提交]
    ROOT --> GI[.gitignore]

    style MD fill:#e8f5e9
    style S1 fill:#fff3e0
    style DATA fill:#fce4ec
```

整个项目可一键运行：`python3 ledger.py add 9.9 饮料 --note 奶茶`，数据自动落盘，零配置、零依赖。

## 六、新手最该带走的三个习惯

1. **先写 `CLAUDE.md`，再让它写代码。** 哪怕只有十行，也比空项目让它自由发挥强得多。记忆是杠杆，写一次、每次会话都受益。
2. **用 `settings.json` 分级权限，而不是全开或全关。** `allow` 高频安全操作、`ask` 危险操作、`deny` 不可逆操作——这套"分级闸门"是新手避免翻车的核心防线。
3. **把报错原文贴回去。** 不要自己转述 bug，让 Claude 看到真实的错误信息和上下文，它能直接定位。

## 七、常见问题速查

| 现象 | 原因 | 解决 |
|------|------|------|
| Claude 反复询问 `python3` 权限 | 未在 `allow` 放行 | 加 `Bash(python3:*)` |
| 生成的代码引入了第三方库 | `CLAUDE.md` 约束缺失或太弱 | 写明"仅标准库"并要求它移除依赖 |
| `data/ledger.json` 被提交进 git | 未加 `.gitignore` | 排除 `data/`，必要时 `git rm --cached` |
| `/init` 后 CLAUDE.md 内容空洞 | 空项目无代码可分析 | 正常，按步骤 3 手动填充 |
| 每次会话 Claude 忘记规范 | 没在 `CLAUDE.md` 写，只口头说 | 决策写进文件，文件自动加载 |

## 八、延伸阅读

- **Claude Code 官方 Quickstart**：`code.claude.com/docs/en/quickstart`——CLI/桌面/Web 三种入口的官方起步。
- **Memory（记忆机制）文档**：`code.claude.com/docs/en/memory`——讲清 `CLAUDE.md` 与命令记忆两条记忆通道。
- **Settings（配置）文档**：`code.claude.com/docs/en/settings`——`settings.json` 全字段与权限规则语法权威说明。
- **Using CLAUDE.md files（官方博客）**：`claude.com/blog/using-claude-md-files`——如何用 `CLAUDE.md` 给代码库注入持久上下文。

## 九、训练营适用性评估

- **适合训练营类型**：企业新人入职训练营、AI 编程零基础启蒙营、Python 工程入门营。
- **教学时长**：约 **90–120 分钟**（含讲师演示 30 分钟 + 学员动手 60 分钟 + 答疑 30 分钟）。
- **学员产出**：每人一个可运行、可测试、已纳入版本管理的命令行记账本，附带规范的 `CLAUDE.md` 和 `settings.json`。
- **延伸练习建议**：① 增加按月导出 CSV；② 把数据层从 JSON 换成 SQLite；③ 加一个 `export --month` 子命令——这三个增量任务恰好对应"读改写、换存储、扩命令"三种典型工程变更，可作为营后作业。

## 参考来源

1. [Claude Code Quickstart — 官方文档](https://code.claude.com/docs/en/quickstart) — CLI/桌面/Web 三种入口的官方起步指南
2. [How Claude remembers your project — Memory 官方文档](https://code.claude.com/docs/en/memory) — CLAUDE.md 与命令记忆两条记忆通道机制
3. [Claude Code Settings — 官方文档](https://code.claude.com/docs/en/settings) — settings.json 全字段与权限规则语法
4. [Using CLAUDE.md files — Anthropic 官方博客](https://claude.com/blog/using-claude-md-files) — 用 CLAUDE.md 给代码库注入持久上下文
5. [The Complete Claude Code Setup Guide (2026) — Substack 技术博客](https://mlearning.substack.com/p/the-complete-claude-code-setup-guide-from-beginner-to-pro-spring-2026) — 从安装到项目配置的端到端实战
6. [The Complete .claude Directory Guide — ComputingForGeeks](https://computingforgeeks.com/claude-code-dot-claude-directory-guide/) — .claude 目录结构与 CLAUDE.md 模块化实践

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