第四篇 · 随身手册 / 第 10 章
工具箱
不用从头读，遇到问题回来查。
这一章你能查到什么
- 一句能直接照抄的话，按“开工、进行中、出问题、收尾”分组；
- 一个术语的白话解释，以及它第一次出现在第几章；
- 出现某种危险信号时，应该立刻做什么。
- 必查：13 句话术——不知道该怎么跟 AI 说时，先来这里找一句。
- 必查：危险信号清单——感觉不对时，先停下对照。
- 必查：全教程术语表——听到陌生词，按五组查。
- 可选以后再看：技能速查、常见问题、开工前自查。
13 句可以照抄的话
这是全教程唯一一份话术清单。直接复制，把 XXX 换成你的内容。 第 5、6 章讲的是这些话出现的场景，这里只保留可以照抄的版本。 想看这些话在一次完整项目里怎么串起来，回第 6 章的午饭登记实录；这里不再重复对话。
开工时
我想做 XXX（用大白话描述）。你先不要写任何代码。 请你像面试官一样，一个问题一个问题地问我，直到你完全清楚我要什么。 一次只问一个，问完等我回答。
把我们的结论整理成一份 spec.md 存下来，写清楚要做什么，以及明确不做什么。
动手之前，先告诉我怎么验证它做完了。 给我一份清单，每条都是我能亲手点一遍就能确认的，比如“点这里应该看到什么”。
现在开始做，但不要一次做完。 先只做最小的一小片——小到能立刻跑起来看到效果，但能从头贯穿到尾。 做完停下来，告诉我怎么验证，等我确认再做下一片。
进行中
我描述得不太清楚。你先问我几个问题，帮我说清楚我到底想要什么。
只看 XXX 这个文件夹里的东西，不要读别的目录。
停一下。这不是我要的。我说的 XXX 的意思是…… 请先复述一遍你理解的需求，我确认了再继续。
这个我验证过了，没问题。请帮我提交一次存档，备注写清楚这次做了什么。
出问题时
我刚才做了 XXX，出现了下面这个错误。这是完整的报错信息：
（粘贴一整屏，不要只截一行）
退回上一个存档。然后我们重新做 XXX 这一片。
我们这一轮先到这里。请写一份交接说明：做了什么、改了哪些文件、
哪些还没完成、下一步建议做什么。存成 进度.md。
请先读一下 spec.md 和 进度.md，然后告诉我你理解的现状。
先不要改任何东西，等我确认。
收尾时
你现在是代码审查员，不是开发人员。请检查 XXX，
重点看：有没有安全问题、有没有明显的 bug、有没有哪部分以后很难改。
请直接指出问题，不要先肯定我。
“你先不要写代码” —— 拦住它冲动的本能
“一次只问一个问题” —— 拦住它一口气甩你 15 个问题
“做完停下来等我确认” —— 拦住它一口气把后面几片也做了
三句话都在做同一件事：把节奏的控制权拿回你手上。
危险信号清单
看到下面任意一条，先停下来，不要继续往下推。 对照“立刻做什么”处理，再决定要不要继续。
| 信号 | 真正的问题 | 立刻做什么 |
|---|---|---|
| 它说的文件名或函数名你没见过 | 可能是它在编（幻觉） | 让它给出准确路径；给不出就让它先读真实文件 |
| “应该没问题了” | 它自己也没验证过 | 要一份能亲手点的验收清单 |
| 同一个错你说了第三次 | 你说的话被埋在桌上了 | 退回存档，写交接文档，开新会话 |
| 它一次改了 10 个文件 | 这一片切得太大了 | 退回存档，切小重做 |
| 对话已经很长了 | 快到变笨区 | 写交接文档，开新会话 |
| 它开始夸你 | 谄媚倾向出现了 | 让它“直接说问题，不要先肯定我” |
| 你完全看不懂现在的进度 | 缺一份交接文档 | 先让它写一份，再继续 |
| 你不确定能不能退回 | 太久没存档了 | 先存档，再继续 |
| 它开始忘掉你说过的要求 | 工作台满了 | 写交接文档，开新会话 |
| 改一处，坏一处 | 它记不清自己改过什么了 | 退回最近一个存档，把这一片切更小 |
| 你开始觉得“算了就这样吧” | 你也被拖进了变笨区 | 站起来走五分钟，这是最好的重启键 |
| 你不敢让它改任何东西了 | 你没有存档可以退 | 先补一次存档，再继续 |
全教程术语表
这是全教程唯一一份术语表。按“网络 / 软件结构 / 数据 / AI / 工程”五组排列， 每条只出现一次，并标出首次出现在第几章。 例子统一使用午饭登记。
网络
| 术语 | 一句话解释 | 首次出现 |
|---|---|---|
| 网络 | 两台或多台计算机互相传输数据的连接。 | 第 2 章 |
| IP 地址 | 一台计算机在网络里的门牌号，由数字组成。 | 第 2 章 |
| 域名 | 给 IP 地址起的易记名字，比如 example.com。 | 第 2 章 |
| 端口 | 同一台服务器上不同服务的门牌号。 | 第 2 章 |
| HTTP | 浏览器和服务器之间“怎么问、怎么答”的规则。 | 第 2 章 |
| HTTPS | 加了加密的 HTTP，别人截到也看不懂内容。 | 第 2 章 |
| 请求 / 响应 | 客户端发出的一次提问，和服务器返回的一次回答。 | 第 2 章 |
| 服务器 | 一直开着、等待并回应请求的计算机。 | 第 2 章 |
| 云 / 云服务器 | 别人替你维护、按需租用的服务器。 | 第 2 章 |
软件结构
| 术语 | 一句话解释 | 首次出现 |
|---|---|---|
| 前端 / 界面层 | 你看见、点得着的部分，运行在浏览器里。 | 第 3 章 |
| 后端 / 逻辑层 | 你看不见、负责判断和计算的部分，运行在服务器上。 | 第 3 章 |
| 接口 / API | 前后端约定“怎么问、怎么答”的合同。 | 第 3 章 |
| JSON | 用花括号和引号组织的数据格式，人和程序都能读。 | 第 3 章 |
| REST | 用“地址 + 动作（GET / POST / DELETE）”操作数据的一种常见接口风格。 | 第 3 章 |
| 状态码 | 服务器用数字表示结果，如 200 成功、404 找不到、500 服务器出错。 | 第 3 章 |
| 框架 / 库 | 框架规定项目怎么组织（Vue、React）；库只提供现成功能，不规定结构。 | 第 3 章 |
| 终端 / 命令行 | 用打字代替点击来操作电脑的地方。 | 第 3 章 |
| 报错 / 异常 | 程序跑不下去时给出的线索，不是失败本身。 | 第 3 章 |
| 运行时 / 依赖 / 环境 | 能读懂代码的程序、项目用到的现成零件，以及它们在你机器上的安装状态。 | 第 3 章 |
| 环境变量 / 密钥 | 程序从运行环境读取的配置；密钥是密码一类的东西，只能放服务端。 | 第 3 章 |
| 容器 / Docker | 把程序和依赖一起打包，换一台机器也能一样运行。 | 第 3 章 |
| 部署 / 运行层 | 把程序放到一直开着的机器上，让别人能访问。 | 第 3 章 |
| 横切关注点 | 鉴权、日志、Git、成本等不属于某一层、但每层都要用的能力。 | 第 3 章 |
数据
| 术语 | 一句话解释 | 首次出现 |
|---|---|---|
| 数据库 | 专门长期存放和管理数据的软件。 | 第 3 章 |
| 数据表 / 字段 / 记录 | 表是格子；字段是列；记录是其中一行。午饭登记的一行就是一条记录。 | 第 3 章 |
| SQL | 操作关系型数据库的查询语言。 | 第 3 章 |
| 索引 | 数据库的目录，让查询不用一页页翻。 | 第 3 章 |
| 事务 | 一组要么全成功、要么全回滚的写操作。 | 第 10 章 |
| 缓存 | 把常用结果临时放在更快的地方，避免每次重算或重查。 | 第 10 章 |
| 备份 | 定期留一份副本，出事时能恢复。 | 第 3 章 |
| 对象存储 | 专门存图片、PDF、附件等文件的服务，数据库里只存文件地址。 | 第 10 章 |
AI
| 术语 | 一句话解释 | 首次出现 |
|---|---|---|
| token（词元） | AI 的工作和计费单位，大致相当于一个词或一个汉字。 | 第 4 章 |
| 上下文 / 上下文窗口 | AI 的“工作台”；每次回答都要重新读一遍之前的全部内容，容量就是窗口大小。 | 第 4 章 |
| 聪明区 / 变笨区 | 同一场对话里，AI 开头清醒，聊久了会变笨，而且没有提示。 | 第 4 章 |
| 幻觉 | AI 一本正经地编出不存在的事实、文件名或函数名。 | 第 4 章 |
| 谄媚倾向 | AI 倾向于顺着你、夸你，而不是直接指出问题。 | 第 4 章 |
| agent（代理） | 能读文件、改文件、跑命令的 AI，不只是聊天。 | 第 4 章 |
| 工具调用 | agent 动手的方式；读文件、改文件、跑命令各是一个工具。 | 第 4 章 |
| 压缩 / 清空 | 两种清桌子的方式；压缩保留摘要，清空丢掉全部对话。 | 第 5 章 |
| 交接文档 | 换会话或换工具前写下的说明：做了什么、改了什么、还剩什么。 | 第 5 章 |
| 技能（斜杠命令） | 装在 AI 工具里的现成指令，在对话框敲 / 就能看到。 | 第 7 章 |
| 子代理 | 由主会话派出去、拥有独立上下文的 AI 工作者。 | 第 8 章 |
工程
| 术语 | 一句话解释 | 首次出现 |
|---|---|---|
| spec.md / 规格 | 把“做什么、为什么、明确不做什么”写下来的文件。 | 第 7 章 |
| 验收标准 | 一组你能亲手点一遍来确认“做完了”的检查项。 | 第 5 章 |
| 曳光弹 | 一条窄但完整、穿过每一层、做完就能演示的路径。 | 第 5 章 |
| 工单 / ticket | 一张自包含的小任务，大小刚好装进一个新会话。 | 第 8 章 |
| 拆票 | 把规格切成若干张工单的动作。 | 第 8 章 |
| 阻塞关系 / 前沿 | 工单被谁挡着；所有阻塞都已完成的那批工单叫“前沿”，可以并行做。 | 第 8 章 |
| 重构 / prefactoring | 重构是改结构不改行为；prefactoring 是为了后面的改动先做的那次重构。 | 第 8 章 |
| 代码审查 | 换一个干净会话，对照规格和项目规范挑错。 | 第 5 章 |
| issue tracker | 存放待办、工单和状态的地方，可以是 GitHub，也可以是本地文件。 | 第 7 章 |
| ADR | 记录“为什么做这个技术决定”的短文档。 | 第 7 章 |
| 原型 | 为了回答一个问题而写的、用完就扔的代码。 | 第 7 章 |
| 红—绿 | 先写一个会失败的测试（红），再写刚好让它通过的最少代码（绿）。 | 第 8 章 |
| Git / 仓库 / 提交 | 提交是存档；仓库是装着所有存档的文件夹。 | 第 3 章 |
本仓库 04_词典/ 有更详细的 AI 编程术语解释，可以用来补查。
进阶页的术语已经合并进本表，不再重复维护另一份。
技能速查
第 7、8 章的主干由五个技能串起来。这一节只做索引： 告诉你有哪些、什么时候用；详细档案见 进阶：技能档案。
/xxx 这种写法是技能：装在 AI 工具里的现成指令，
在对话框敲一个 / 就能看到当前能用的清单。
它们需要 Claude Code 这类支持技能的工具；普通网页聊天框可以先跳过这一节。
安装与验证步骤见 第 7 章开头，这里不重复。
主干五步
| 顺序 | 技能 | 干什么 | 能不能跳过 |
|---|---|---|---|
| 1 | /grill-with-docs |
一次一个决策地拷问你的想法，同时把讨论沉淀成文档。 | 不要跳 |
| 2 | /to-spec |
把结论整理成规格，写清做什么、明确不做什么。 | 改动小到一次会话能做完时，可以跳 |
| 3 | /to-tickets |
把规格拆成曳光弹式工单，并标出先后依赖。 | 同上，可跳 |
| 4 | /implement |
领一张工单做完，做完就停；每次从干净会话开始。 | 主干里不跳 |
| 5 | /code-review |
换干净会话，从标准与规格两个角度审这次改动。 | 不建议跳 |
第 1 步为什么不能跳，一句话：它一次代码都不写，只负责把你脑子里的模糊想法变成双方都认同的说法。 原因见 第 7 章 · 病根。
配套技能
| 技能 | 什么时候用 | 详细档案 |
|---|---|---|
/grill-me | 同样是拷问，但不产出文档；手里还没有项目目录时用。 | 档案 |
/wayfinder | 活儿大到一次会话装不下时，先铺一张路线图，找出下一步。 | 档案 |
/diagnosing-bugs | 遇到难缠的 bug 或变慢问题时，走系统的诊断循环。 | 档案 |
/triage | 事情堆积起来时，把 issue 和改动请求分级归类。 | 档案 |
/research | 要查一个具体技术问题，去读可信的一手资料并记下结论。 | 档案 |
/improve-codebase-architecture | 没新需求，但代码越来越难改时，主动扫一遍结构问题。 | 档案 |
/wizard | 把每隔几个月做一次、每次都要翻笔记的流程，变成一步步带你走的脚本。 | 档案 |
哪些要你自己敲，哪些 AI 自己会调
你自己主动敲 /
这些动作由你发起，记住名字有价值：
/grill-with-docs、/grill-me/to-spec、/to-tickets/implement、/code-review/wayfinder、/triage
AI 可能自己调用
这些是底层能力，你不需要记名字：
grilling（拷问的底层引擎）/diagnosing-bugs/research
/code-review 的统一说法
它由用户主动敲。某些工具可能在某些时点自动调用类似能力， 但不要依赖自动调用——审查这一步要由你主动发起， 而且要在一个干净的会话里做。
to-prd → to-spec；
to-plan、to-issues → to-tickets；
pathfinder、decision-mapping → wayfinder；
diagnose → diagnosing-bugs；review → code-review。
这些大多是统一说法，理解成同一个东西即可。
这套技能只管“把已经想清楚的东西准确做出来”，不管“这个想法该不该做”， 也不覆盖市场、定价和用户研究。边界见 第 7 章 · 诚实边界。
想升级成专业工具链，见 进阶：专业工具链；那一页不属于十章主线，可以跳过。
常见问题
“我完全不懂代码，用这些方法真的能做出东西吗？”
能，但有前提：你愿意去试、去点、去描述、去重来。 这套方法替换掉的是“读代码”，不是“判断”；判断这件事 AI 替不了你。
“我是不是应该先学点编程再开始？”
不需要，而且不建议。先学编程会让你花几个月在跟目标无关的事情上。 直接做一个极小的项目，遇到不懂的词就查本表，或者直接让 AI 用大白话解释。
“AI 说的技术方案我完全看不懂，怎么办？”
直接说：“用大白话解释一下，或者打个比方。” 更有效的一句是：“这个方案和另一个方案比，各自的坏处是什么？你推荐哪个？” 你不需要听懂细节，但需要听懂取舍。
“它老是理解错我的意思，是不是我表达能力有问题？”
大概率不是。更可能是你还没想清楚，而它猜了一个版本。 这就是为什么第 1 句话术要求它先问你：提问的过程，就是你想清楚的过程。
“我做的这个东西能给别人用吗？”
能跑不等于能给别人的数据用。涉及别人的账号、支付、隐私数据的， 落在“必须有人逐行看过”的格子里，纯 vibe 不行；自己用的小工具和原型可以放心练。
“为什么它总说‘你说得对’，然后什么都没改？”
谄媚倾向。它被训练成让你满意，而“你说得对”是最省事的满意方式。 应对办法是说硬一点：“不要附和我，指出我哪里说错了；如果同意，就动手改，改完告诉我改了哪些文件。”
“我要不要为了这个去学 Git？”
不用学命令行。你只需要会说两句：“帮我存一次档”和“退回上一个存档”。 概念见 第 3 章 · Git。
开工前自查
☐ 我建了独立的项目文件夹吗？
不要让它在你桌面或下载文件夹里乱来。
☐ 我第一件事建存档了吗？
要在写任何代码之前。这一步不能省。
☐ 我让它先问我了吗？
三个限定都说了吗：先别写代码、一次一问、等我回答。
☐ 我拿到验收清单了吗？
每一条都要是我能亲手点的。
☐ 第一片切得够小吗？
小到能一次做完，完整到能跑起来看到效果。
☐ 我知道什么时候该重开了吗？
对照上面的危险信号清单，任何一条出现就停下来。
三句话带走
- 遇到具体问题，先查 13 句话术；不要临场组织语言。
- 术语全教程只在这里定义一次；忘了就按五组回来查。
- 危险信号出现时，先停下、先退回存档，再决定重开还是把这一片切小。
自测：三个问题
AI 一次改了 10 个文件，你应该查哪一节、立刻做什么？
查危险信号清单：这通常说明这一片切得太大了。立刻退回存档，把任务切小重做。
spec.md 和 PRD 是什么关系？
它们指的都是“把要做什么、为什么、不做什么写下来的文档”。本教程统一叫
spec.md 或“规格”，PRD 是旧说法。
审查这一步该由谁发起？
由你主动敲。某些工具可能自动调用类似能力，但不要依赖；而且要在干净会话里审， 否则容易变成自我确认。
动手 10 分钟
做两张自己的小卡片：
- 从 13 句话术里挑 3 句，把 XXX 换成你项目的名字和文件名，抄成一张话术卡；
- 从术语表里随机挑 5 个词，不看解释，用自己的话讲一遍，再对照检查。
如果你看到 X，大概率是 Y
- 查了术语还是不懂 → 你不需要背定义。让 AI 用一个大白话类比重讲，直到你能转述。
- 照抄话术但没替换 XXX → AI 会把它当成字面内容。复制后先检查占位符。
- 危险信号出现了还在硬推 → 继续解释只会让工作台更满。先退回存档，再开新会话。
- 把技能索引当成教程 → 这一节只告诉你“有什么、什么时候用”；每一步怎么做，回第 7、8 章。