名词手册
不是教材。是一张可抄的工单：名字、一句人话、以及你可以直接贴给模型的那一行。
界面怎么动
用户看得见的节奏。叫得出名字，模型就不会给你做一套「感觉不对」的交互。
- 防抖 Debounce
等动作停下来再执行。搜索框停键 300 毫秒后再请求，而不是每个字母打一次接口。
跟模型说
搜索输入防抖 300ms，停键后再请求；加载中取消上一次未完成的请求。
叫不出时 · 你会写成「打字的时候别一直转圈」，然后改五轮，模型仍可能每个按键都打接口。
- 乐观更新 Optimistic update
先改界面，再等服务器。点赞立刻变红；失败再弹回去。
跟模型说
收藏用乐观更新：点了立刻变状态，失败则回滚并提示重试，不要等接口回来才变。
叫不出时 · 每个按钮都转圈半秒。页面像在道歉。
- 骨架屏 Skeleton
内容还没到，先用灰块占住版面，避免布局跳动。
跟模型说
列表首屏用骨架屏，形状跟真实卡片一致；不要用居中大转圈。
叫不出时 · 模型给你一个会转的菊花，整页空白，加载完再「啪」一下出现。
- 模态框与抽屉 Modal / Drawer
模态框挡住整页，必须先处理；抽屉从边上滑出，背后的页面还在。
跟模型说
编辑用右侧抽屉，不要全屏模态；Esc 和点遮罩可关，焦点锁在抽屉里。
叫不出时 · 所有确认、编辑、筛选都弹正中大窗，手机上关不掉。
- 空状态 Empty state
还没有内容时的那一屏：说明为什么空，下一步按什么。
跟模型说
项目列表空状态写「还没有项目」，下面一颗按钮「新建项目」，不要只显示空白表。
叫不出时 · 用户打开应用，看见一张没字的白纸，以为坏了。
- 分页与无限滚动
分页有页码，能跳、能分享第 3 页；无限滚动一直往下，适合刷，不适合找回刚才那条。
跟模型说
管理后台用分页，每页 20 条；信息流用无限滚动，保留回到顶部。
叫不出时 · 后台表格被做成抖音式下拉，想改第 87 条时已经找不到了。
也叫 · 常和节流 Throttle 成对出现
状态怎么写
同一块界面在等、在错、在成的时候，长得不应该一样。
- 八态 Default to success
默认、悬停、焦点、按下、禁用、加载、错误、成功。少画一态，线上就缺一块。
跟模型说
每个按钮补齐默认、hover、focus-visible、active、disabled、loading、error、success，焦点环不要动画。
叫不出时 · 只有默认和悬停。键盘用户看不见焦点，提交中还能连点三次。
- 校验 Validation
失焦后再检查，不要每个字母都骂人；错误要说清错了什么、怎么改。
跟模型说
邮箱失焦后再校验；错误文案：「这不是邮箱格式，需要带 @。」不要只把框变红。
叫不出时 · 一打字就全红，用户还没写完就被打断。
- 幂等 Idempotent
同一请求做两次，结果跟做一次一样。支付、创建订单尤其要。
跟模型说
创建订单带幂等键，连点提交只生成一单；按钮提交中禁用。
叫不出时 · 网一卡，用户连点，库里两笔相同的单。
- 竞态 Race
后发的请求先回来，屏幕显示成旧结果。搜索尤其常见。
跟模型说
搜索请求要可取消；只采用最后一次输入对应的结果。
叫不出时 · 你搜「猫」再搜「猫粮」，页面先出猫粮再跳回猫。
数据放哪、谁能看
外行最容易漏的一层：不是界面，是记录和权限。
- 增删改查 CRUD
创建、读取、更新、删除。大多数「小工具」其实就是一张表的这四件事。
跟模型说
这是一个任务的 CRUD：列表、详情、新建、编辑、删除；删除要可撤销。
叫不出时 · 你会描述「能加点东西，还能改，不要了就去掉」，模型猜五张互不相干的表。
- 数据模型 Schema
有哪些对象、字段叫什么、彼此怎么连。先画这个，再画页面。
跟模型说
对象：用户、工作区、项目、任务。任务属于项目，项目属于工作区。任务有标题、状态、负责人、截止日期。
叫不出时 · 每加一个功能就多一张表，同名字段三种拼写。
- 登录态 Session / Auth
系统怎么认出你，认出之后记住多久。注册、登录、退出、忘记密码是一套，不是四个彩蛋。
跟模型说
邮箱密码登录，会话 30 天，退出清 cookie；未登录访问 /app 跳到 /login，回来时回到原地址。
叫不出时 · 模型做了注册页，忘记登录；或者登录了，刷新就丢。
- 权限与行级安全
不是「有没有登录」，是「这条记录是不是你的」。只藏按钮不够，接口也得拒。
跟模型说
用户只能读写自己工作区的项目。直接改 URL 里的 id 也不能读别人的。数据库加行级权限。
叫不出时 · 列表里看不到别人的，把地址栏数字改一下就能看见。这是真事故。
- Webhook
别人的系统在事件发生时来敲你的门：支付成功、邮件点开、仓库推送。
跟模型说
Stripe 支付成功用 webhook 写订单已付，不要只信浏览器跳回；校验签名。
叫不出时 · 用户付完钱关了页面，订单一直待支付。
- 缓存 Cache
把算过的结果先放着。快，但会脏。要说清谁失效、何时失效。
跟模型说
公开文章页缓存 60 秒；后台一点「发布」，立刻清这一页的缓存。
叫不出时 · 改了标题，网上还是旧的，你以为没保存。
产品常见块
这些不是技术黑话，是产品经理每天在用的名词。外行最常「感觉到了，叫不出」。
- 新手引导 Onboarding
第一次进来之后，怎么让人做出第一个有效动作，而不是逛一圈就走。
跟模型说
注册后三步：建工作区、邀请一位成员、创建第一条任务。可跳过，进度条可回退。
叫不出时 · 模型做五屏轮播「欢迎来到我们的宇宙」，没有一个按钮能干活。
- 付费墙 Paywall
免费能走多远，哪一步必须付钱。要写清，不要做到一半才拦。
跟模型说
免费可建 3 个项目；第 4 个弹出付费墙，文案写清升级后能做什么，关闭后留在原页。
叫不出时 · 要么永远免费，要么一进门就要信用卡，没有中间态。
- 功能开关 Feature flag
代码已经在，只对一部分人打开。出问题能立刻关上，不必回滚整站。
跟模型说
新编辑器用功能开关，默认关，内部账号打开；出 bug 只关开关，不回滚。
叫不出时 · 新功能一上全员倒霉，修要重新部署二十分钟。
- SSR / SSG / SPA
页面是服务器现拼、构建时拼好，还是到浏览器再拼。影响首屏、SEO、登录后的数据。
跟模型说
营销页 SSG；文章页 SSR 以便 SEO；登录后的 /app 用客户端渲染。
叫不出时 · 整站做成单页应用，搜索引擎只能看见「请开启 JavaScript」。
- 最小可用 MVP
能验证那一个假设的最小版本，不是「功能少一点的完整产品」。
跟模型说
第一版只做：注册、建一个项目、加任务、勾完成。不要通知、不要看板、不要积分。
叫不出时 · 你说「先简单点」，模型仍然做了设置中心、团队权限和暗色模式。
跟模型怎么说
氛围编程本身的名词。把这一层说清楚，循环会短一截。
- 提示词 Prompt
你写给模型的说明书。好的提示词像工单：对象、约束、验收，而不是心情。
跟模型说
不要写「做漂亮一点」。写「主按钮对比度 ≥ 4.5:1，不要紫色渐变，移动端 320 不横滚」。
叫不出时 · 模型只能猜你的审美，猜错了你还说不清错在哪。
- 上下文 Context
模型此刻能看见的材料：文件、报错、对话。不是「记忆」，是桌上摊开的纸。
跟模型说
只打开相关的三个文件，把报错全文贴上；不要把整个仓库塞进对话。
叫不出时 · 上下文被无关文件挤满，模型改错文件，还很有自信。
- 幻觉 Hallucination
模型把不存在的函数、库、配置说得像真的。语气越稳，越要去跑。
跟模型说
不要发明不存在的 API。先读本仓库已有的函数再调用；不确定就说不确定。
叫不出时 · 你安装了一个 npm 上根本没有的包，还怪自己网不行。
- 代理与工具调用 Agent / Tool call
模型不但说话，还会去跑命令、改文件、点浏览器。每一步都可能走偏。
跟模型说
先给计划再改文件；改完跑类型检查。不要一次改十二个文件。
叫不出时 · 代理「好心」重构了半个项目，你回不到刚才能跑的那一版。
- 差异 Diff / 拉取请求 PR
改动的对照。看 diff 比看整文件便宜，也是你当审稿人的位置。
跟模型说
这次只改登录页，PR 不要夹带格式化整个仓库。
叫不出时 · 你以为改了一行文案，实际一千行空白被重排。
- 检查器与类型错误
机器先读一遍你的代码。红字不是羞辱，是便宜的验收。
跟模型说
改完跑 lint 和 typecheck，按报错修，不要关检查来「先让它过」。
叫不出时 · 页面白屏，控制台一条红字，你只能把整段错误丢回给模型。其实那就是验收标准。