本教程带你完成 Claude Code 的第一个完整工程：从空文件夹起步，用自然语言驱动 Claude Code 写出一个能用的命令行记账本（Python，零第三方依赖）。过程中你会掌握新手最该先学的三件套——
/init生成项目骨架、CLAUDE.md给项目装"记忆"、settings.json权限配置。适合已经装好 Claude Code、但还没独立跑完一个项目的零基础开发者。
新手教程最常见的两个坑：一是只讲安装不讲"装完之后干嘛"，二是用"Hello World / 整理文件夹"这种玩具例子，跑完即弃、学不到工程闭环。
命令行记账本（expense ledger）是一个最小但完整的真实项目，它天然包含四类工程动作：
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 插件。任选其一装好、能跑通登录即可。
先看全局，再逐步落地：
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
绿色 = 项目记忆，橙色 = 权限安全，蓝色 = 自然语言驱动。这三层是新手最容易跳过、但对后续效率影响最大的部分。
打开终端，确认能正常进入交互模式：
claude --version
预期结果：打印版本号（如 2.1.x），说明 CLI 已就绪。
常见问题
command not found：说明未正确安装或不在 PATH。重跑官方安装命令，或检查 npm bin -g 是否在 PATH 中。mkdir ledger-cli && cd ledger-cli
claude
预期结果：终端进入 Claude Code 交互界面，工作目录就是 ledger-cli（一个空文件夹）。
新手务必在项目根目录启动
claude——它会把当前目录视为项目根，后续生成的CLAUDE.md和.claude/都落在这一层。
/init 生成项目骨架在交互界面直接输入斜杠命令：
/init
预期结果：Claude Code 会扫描目录（此时是空的），然后在项目根生成一个初始 CLAUDE.md，并自动加一段"项目概览"占位内容。这是官方推荐的"项目记忆"入口。
常见问题
CLAUDE.md——给项目装"记忆"CLAUDE.md 是 Claude Code 每次会话开始自动读取的项目说明文件。写得越清楚，Claude 越不需要你反复解释背景。把刚才生成的文件改成下面这样：
# 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.md写的是决策与约束（用什么、不用什么、规范是什么），而不是项目使用说明书。
.claude/settings.json——权限安全网新建 .claude/settings.json，定义 Claude 在本项目里能自动做什么、必须问你、以及绝对不能做：
{
"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 的习惯更安全。现在权限和记忆都就位，用一句人话下需求：
按 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 是否真的写了"仅标准库"。把约束钉死，再回一句"去掉所有第三方依赖，改用标准库"。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 准确十倍。
为 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 里"整数分存储"的约束）。由于 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），完成首次提交。
git log --oneline
# a1b2c3d 初始化命令行记账本
常见问题
data/ledger.json？ 你已经在 deny 或 .gitignore 排除了数据目录；如果没排，当场纠正"数据文件不要进版本库"。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 奶茶，数据自动落盘，零配置、零依赖。
CLAUDE.md，再让它写代码。 哪怕只有十行，也比空项目让它自由发挥强得多。记忆是杠杆，写一次、每次会话都受益。settings.json 分级权限，而不是全开或全关。 allow 高频安全操作、ask 危险操作、deny 不可逆操作——这套"分级闸门"是新手避免翻车的核心防线。| 现象 | 原因 | 解决 |
|---|---|---|
Claude 反复询问 python3 权限 |
未在 allow 放行 |
加 Bash(python3:*) |
| 生成的代码引入了第三方库 | CLAUDE.md 约束缺失或太弱 |
写明"仅标准库"并要求它移除依赖 |
data/ledger.json 被提交进 git |
未加 .gitignore |
排除 data/，必要时 git rm --cached |
/init 后 CLAUDE.md 内容空洞 |
空项目无代码可分析 | 正常，按步骤 3 手动填充 |
| 每次会话 Claude 忘记规范 | 没在 CLAUDE.md 写，只口头说 |
决策写进文件，文件自动加载 |
code.claude.com/docs/en/quickstart——CLI/桌面/Web 三种入口的官方起步。code.claude.com/docs/en/memory——讲清 CLAUDE.md 与命令记忆两条记忆通道。code.claude.com/docs/en/settings——settings.json 全字段与权限规则语法权威说明。claude.com/blog/using-claude-md-files——如何用 CLAUDE.md 给代码库注入持久上下文。CLAUDE.md 和 settings.json。export --month 子命令——这三个增量任务恰好对应"读改写、换存储、扩命令"三种典型工程变更，可作为营后作业。[!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 等场景全覆盖。