调试与收尾
验证情况
- ✅ 已实测（Claude Code + DeepSeek）：代码审查、按审查结果修复、写 README、最终提交，页面中标注"作者实测"的内容都来自这次运行
- ⚠️ 未实测："描述 bug"和"看浏览器报错"两节的例子是为了讲解方法编写的（作者这次运行中 Agent 没有留下需要人工报告的 bug）
功能都做完了，最后还有三件事：找出并修好 bug、让 Agent 审查一遍代码、写好说明文档。
怎样向 Agent 描述 bug
用着用着发现了问题，比如"加完记录，结余算错了"。直接说"结余有 bug"，Agent 只能猜。好的 bug 描述包含四样东西：
| 要素 | 例子 |
|---|---|
| 怎么操作的 | 先添加一笔 5000 元工资，再添加一笔 32.5 元午饭 |
| 期望看到什么 | 结余显示 ¥4,967.50 |
| 实际看到什么 | 结余显示 ¥5,032.50 |
| 其他线索 | 只有支出的时候是对的，加了收入之后就不对了 |
写成一段话：
结余计算有问题。复现步骤：先添加一笔 5000 元的工资收入，再添加一笔 32.5 元的午饭支出。
期望结余显示 ¥4,967.50，实际显示 ¥5,032.50。
只有支出时结余是对的，加了收入之后就不对了。帮我找到原因并修复，
修完告诉我原因是什么。让它说出原因
最后加一句"告诉我原因是什么"。这样你能判断它是真的找到了问题，还是只是碰巧改对了；你自己也能学到东西。
看浏览器的报错信息
有些问题会在浏览器的控制台里留下错误信息，比如点按钮没反应。把这些信息交给 Agent，它能很快定位问题。
打开控制台
在出问题的页面按 F12（macOS：Command + Option + I）打开开发者工具，切换到 Console（控制台）标签页。
重现问题
再操作一次出问题的步骤（比如点一下没反应的按钮）。
复制错误信息
红色的文字就是错误信息，类似：
Uncaught TypeError: Cannot read properties of null (reading 'addEventListener')
at app.js:142:38右键点击错误信息 →「Copy message」，或者直接选中复制。
交给 Agent
点"删除"按钮没反应，浏览器控制台报错：
Uncaught TypeError: Cannot read properties of null (reading 'addEventListener')
at app.js:142:38
帮我找到原因并修复。截图不一定能用
Claude Code 和 Codex 都支持粘贴截图，但接入 DeepSeek 时可能不支持图片。所以要养成用文字描述问题、复制文字报错的习惯，这对任何模型都有效。
让 Agent 审查代码
功能做完后，让 Agent 换个角色，以"审查者"的身份把代码检查一遍，常常能发现你没注意到的问题。
/code-review/review这两个都是工具自带的代码审查功能，会检查当前的改动，列出可能的 bug 和改进建议。你也可以直接用自然语言提要求，指定审查的重点（作者实测用的就是这一段）：
请以代码审查者的身份检查整个项目，重点看：
1. 有没有可能导致数据丢失的问题
2. 用户输入特殊内容时会不会出错
3. 有没有重复、可以简化的代码
先列出问题，不要直接修改，我确认后再改。作者实测，Agent 用了约 1 分钟，列出了 10 条发现，按严重程度排好了序。下面是节选：
## 一、数据丢失风险（按严重程度排序）
1. 同时开两个标签页记账，会互相覆盖丢记录（最值得注意）
handleSubmit 和 deleteRecord 都是「读出全部记录 → 修改 → 整个写回」。如果两个标签页
同时开着：标签页 A 记一笔，标签页 B 再记一笔（写回 B 自己读到的旧数据），A 刚记的那笔
就被 B 覆盖掉了。
2. 保存到 localStorage 失败时，页面会中断且不提示
隐私模式、浏览器禁止写入或存储空间满时……你可能以为记上了其实没有。
3. localStorage 里的数据被手改坏结构时，页面会整个卡死
## 二、用户输入特殊内容
4. 金额、备注、分类的主要攻击面都守住了 ✅
5. 小瑕疵：全角数字的提示语容易让人困惑
## 三、重复、可简化代码
6. ～ 8. ……
## 顺带发现（不在三个重点里，但值得说）
9. 切到别的月份记账，记完「看不到刚记的账」
10. 连续点「上月」几千次到公元元年附近，月份会跳到 1900 年
极端情况（要连点上千次），日常用不到，我倾向不修。
我的建议：第 1、2、3 条修（数据安全相关），第 6、7 条修（顺手简化），第 8 条由你定，
第 5 条顺带改提示文字，第 9 条按你偏好选一种，第 10 条不动。你确认哪些要改，我就动手。几点值得学习的地方：
- 第 1 条"两个标签页互相覆盖"，是新手几乎想不到的问题，这就是审查的价值；
- 第 9 条超出了你给的三个重点，但它是一个实实在在影响使用的问题，它也提了出来；
- 第 10 条它自己就建议"不修"——不是每个问题都值得修。
"先列出，不要直接改"
审查时加上这句，你可以挑选哪些建议要采纳。Agent 有时会提出一些不必要的"优化"，全部照做反而会把简单的代码改复杂。
挑好之后，明确告诉它修哪几条。作者只选了和数据安全、使用体验相关的 4 条：
按你的建议修第 1、2、3、9 条（第 9 条选"记完自动切到记录所在的月份"），其他先不改。修完告诉我怎么验证。4 条修复全部完成，node 验证 8/8 通过。
怎么验证（刷新 index.html 后）：
1. 验证第 4 条（最直观）：点「‹ 上月」切到 8 月 → 随便记一笔 → 页面应自动跳回 9 月，
明细里第一条就是你刚记的
2. 验证第 1 条：开两个标签页都打开 index.html → 在标签页 A 记一笔 → 切到标签页 B，
不用刷新，明细里应该已经出现这笔
……照着验证一遍，没问题再提交。
留意过时的注释
作者检查最终代码时发现，index.html 里还留着"阶段 3 才会真正切换"这样的注释——阶段 3 早就做完了，Agent 改了功能却没有回头更新注释。这类问题不影响运行，但会误导以后读代码的人。可以在审查时加一条重点："有没有和代码不符的过时注释"。
最后检查
如果 PLAN.md 里没有安排"按检查清单验收"的阶段（作者的计划里，阶段 4 就是做这个的），让 Agent 按 beginner-web 的检查清单做最后一遍检查：
按 beginner-web 的检查清单，对整个项目做最后一遍检查，把结果逐项告诉我。然后你自己再完整地用一遍：添加几笔收入和支出、删除、切换月份、刷新页面、用手机模式看。
写 README
README 是项目的"说明书"，告诉别人（以及几个月后的你自己）这个项目是什么、怎么用。
帮我写一个 README.md：介绍小账本是什么、有哪些功能、怎么打开使用、
数据存在哪里（提醒用户清除浏览器数据会导致记录丢失）。用简体中文。作者实测生成的 README 见 examples/xiaozhangben/README.md。
最后提交：
/zh-commit$zh-commit完成！
xiaozhangben/
├── .agents/skills/beginner-web/
├── .claude/skills/beginner-web/
├── AGENTS.md
├── CLAUDE.md
├── PLAN.md ← 所有阶段都已勾选
├── README.md
├── index.html
├── style.css
└── app.js用 git log --oneline 看看你的提交记录，每一条都是一个清晰的阶段：
a9be0f8 修复：多标签页覆盖、保存失败无提示等 4 项
2c6ea80 修复：日期清空提交会存进幽灵记录
b1ae9d5 新功能：占比图与月份切换（阶段 3）
39ce5ef 新功能：实现记账闭环（阶段 2）
82ea849 新功能：小账本页面骨架（阶段 1）
6a55bf7 文档：新增小账本开发计划 PLAN.md
155fede 初始化小账本项目作者这次实测一共花了多少
从确认项目说明到最后一次提交，一共 15 步、99 轮对话，Agent 工作了约 17 分钟。按 DeepSeek 官方价格估算，总花费约 2 元（空闲时段）/ 4 元（高峰时段）。每一步的详细用量见 RUN-LOG.md。
回顾：你练到了什么
| 环节 | 方法 |
|---|---|
| 准备 | 项目级 Skill 让规范跟着项目走；AGENTS.md + CLAUDE.md 共用一份说明 |
| 规划 | 写清楚功能、验收标准、限制；Plan 模式出方案；审核后保存为 PLAN.md |
| 实现 | 一次一个阶段；每个阶段都亲手验收、看改动、提交 |
| 调试 | 描述 bug 的四要素；复制浏览器控制台的报错 |
| 收尾 | 代码审查、检查清单、README |
这套流程不只适用于小账本，任何项目都可以照这个节奏来。
继续挑战
想继续练习的话，可以给小账本加这些功能（记得先规划、再分阶段实现）：
- 预算提醒：设置每月预算，支出超过 80% 时显示提醒；
- 导出数据：把记录导出成 CSV 文件，可以用 Excel 打开；
- 编辑记录：点击一条记录可以修改它；
- 深色模式：跟随系统自动切换深色主题。
可选：把小账本发布到网上
如果你有 GitHub 账号，并且能正常访问 GitHub，可以用 GitHub Pages 免费发布这个网页，得到一个可以分享的网址。可以直接让 Agent 指导你：
我想把这个项目发布到 GitHub Pages。我有 GitHub 账号，但没用过 Git 推送。
请一步一步告诉我怎么做，每一步等我确认后再继续。注意：发布之后网页是公开的，但数据仍然只保存在每个访问者自己的浏览器里，别人看不到你的账目。
下一步：第 8 章 · 方法与技巧，把这些经验总结成通用的方法。