SDD + Harness 四周学习计划 · Week 1 · Day 5（认知打底第 5 课 / 全计划第 1 个实操日）
今日主题：动手写——把 Day 1–4 学到的压成一次动作，产出你本周的唯一实物交付：一份七要素完整、验收标准可量化的 spec
建议用时：90 分钟（实操日可稍多）｜ 前置：Day 3 的《Day3-七要素骨架卡.md》草稿
输出物：一份完整 spec（建议命名
Day5-spec-<你的功能名>.md）+ 一张自查清单——这份 spec 就是 Day 7 周复盘与 Day 20 端到端交付的核心原料
0. 一句话剧透
前四天你学会了「什么样的 spec 合格」和「三种方式怎么选」。今天不再讲，只写——今天结束时你要交出一份真正的 spec。
标准就一条：把这份 spec 交给一个 AI（或交给三天后的你），它应该能独立做到「不跑偏、可验收」。 如果它还做不到，说明你写的不是 spec，是又一份模糊需求。
今天没有「标准答案作业」，只有一份你自己的活物。写不好很正常，Day 7 会拿 checklist 帮你查，Day 20 还会拿它端到端交付一次。 你先写，才有的改。
1. 今日目标（学完你能做到）
- 独立产出一份七要素齐全的 spec（背景/目标/用户故事/验收标准/非目标/边界条件/验证方式一个不缺）
- 其中每条验收标准都能转成一句可自动化断言（Given-When-Then + 数字），没有任何”形容词验收”
- spec 里不混入 HOW（划掉 Redis/索引/重构/用某库……这类词）
- 能站在 AI 视角反向通读，主动补上至少 3 处它可能”自由发挥”的空白
- 完成一张自查清单并如实勾选（含没做到项——如实标注比假装全过更值钱）
今日目标 = 评估标准第 1 条（七要素完整、验收可量化）的实操版。只要求你写完，不要求你写对满分——”写得不够”在 Day 7 才有意义。
2. 学习动线（实操专用时间盒）
实操日按《研究式学习手册》4.3「实验三件套」走：预期（spec 写完长什么样）→ 观测（我真写完时哪里卡住）→ 复盘（卡住的点是什么新认知）。
| 步骤 | 内容 | 用时 |
|---|---|---|
| 1 | 选题：选定功能，写一行「目的摘要」 | 10 分钟 |
| 2 | 先列要素骨架（尽量不查讲义） | 15 分钟 |
| 3 | 逐要素填充 & 形容词翻成可测句（含 3 句小练习） | 30 分钟 |
| 4 | 清理 HOW + AI 视角反向通读补漏 | 15 分钟 |
| 5 | 自查清单 + 收尾命名存盘 | 10 分钟 |
| 观测与记录 | 边写边记「我在哪一步最卡」，写进文末 | 全程 |
卡住 ≠ 失败。研究手册说得很直白：失败的实操是最肥的研究素材。 今天最卡的地方，就是你 Day 7 复盘最该写进学习笔记的地方。
3. 动笔前：选一个”够小、够真、够可测”的功能
3.1 选题三原则
| 原则 | 说明 | 反例 |
|---|---|---|
| 够小 | 1–2 天能做完的功能，别选跨模块大需求 | “重构整个订单模块” ❌ |
| 够真 | 你手上真实要做的 / 真实遇到过的，才能写出真边界 | 随便编的”智能聊天系统” ❌ |
| 够可测 | 效果能量化（耗时/大小/成功率/覆盖率），别选纯主观体验 | “让界面更好看” ❌ |
参考候选池（若一时想不出）：登录验证码、头像上传、搜索分页、导入导出、消息已读回执、接口限流……拿你 Day 3 骨架卡里那个微需求扩写最省力。
3.2 先写一行「目的摘要」（第 0 稿，5 分钟内）
在动七要素之前，用一句话讲清你的 spec 是谁、改变什么、怎么算成功。它帮你随时拉回方向：
1
2
3
一句话摘要（模板）：
给 <角色> 增加/优化 <能力>，以便 <价值>；
成功判据（初步）：<一个可量化的"做到了"样子>。
先写”成功判据”，这是整份 spec 的北极星。 后面每一要素都要朝它收敛。
4. 写作流程六步（今天的主菜）
4.1 第一步：先列骨架，不填细节（回忆优先）
合上 Day 3 讲义，凭记忆列出七要素的标题和每个要素的一句话要点（2–3 分钟草稿）。列完再翻讲义对照补漏——这一步在训练你的提取记忆，不是在抄。
4.2 第二步：逐要素填充（按七要素顺序）
参照 Day 3 每要素的「试金石句」逐格填：
| 要素 | 填之前问自己 | 试金石（写完自查） |
|---|---|---|
| 背景 | 现状数据？代价？（给 1–2 个数字） | 删掉它还知道”非做不可”吗？ |
| 目标 | 这是结果还是动作？ | 是 outcome，不是 output |
| 用户故事 | 谁、何时、为何？2–3 条即可 | 每条能对应到至少一条验收吗？ |
| 验收标准 | 能转成自动化测试吗？ | 每个形容词都被我换成数字了吗？ |
| 非目标 | 我有没有”顺手做点啥”的念头？ | 至少 3 条明确”不做/不改/不重构” |
| 边界条件 | 空/极限/超时/并发/格式错会怎样？ | 删掉它 AI 会不会在这自由发挥？ |
| 验证方式 | 我拿什么证明？ | 每条验收都有取证手段吗？ |
4.3 第三步：把”形容词”翻成”可测句”（含 3 句小练习）
形容词是验收标准死敌（Day 3）。做个小练习，顺手把 3 句常见”模糊验收”翻成可测句，练手答案在文末附录 A：
| # | 模糊写法（形容词） | 你来翻成可测句 |
|---|---|---|
| 例 | “头像上传要快” | 已示范：>5MB 的图在 4G 下 ≤3s 完成上传并返回 URL（示例，非唯一答案） |
| 1 | “搜索要很快” | ？ |
| 2 | “错误提示要友好” | ？ |
| 3 | “系统要能撑住并发” | ？ |
翻译工具包（挑合适的用）：
- Given-When-Then：给定 <数据/前置>，当 <动作>，则 <可观测结果 + 数字>
- 给数字：阈值、上限、时间、百分比——模糊词后面一定跟一个数
- 给判定规则：什么算”通过/不通过”，白纸黑字写下来
- 若某条实在无法量化 → 说明它根本不是验收，是”感受”，删掉或降级成非目标
4.4 第四步：清扫 HOW
把 spec 里所有”技术实现词”圈出来：缓存、索引、重构、用 X 库、改表结构、拆微服务……凡是 AI 换个技术栈 spec 就变形的句子，划掉或挪走。 技术方案留给 plan.md（本周你不写 plan，只保证 spec 里干净）。
4.5 第五步：AI 视角反向通读（最值钱的一步）
把身份切换到”一个听话但爱自由发挥的 AI”：逐句问”这里没写清，我会怎么猜？” 每猜出一个空白，就补一处。最少补 3 处。
1
2
3
4
我写完之后假装是 AI 通读时，最容易自由发挥的 3 个空白：
① ______（例：'上传成功'的提示文案？我没写 → 补进验收或说明"提示不在此 spec 范围"）
② ______
③ ______
4.6 第六步：收尾
- 要素齐了没？编号规范（AC-1/AC-2…）？格式能一眼扫出七要素？
- 保存为
Day5-spec-<你的功能名>.md，放本目录。 - 写一句「交付说明」给 Day 7 的自己：我这次最没把握的是哪个要素？
5. 自查清单（写完后勾；Day 7 会复用同一张）
这一张清单就是 Day 7 周复盘要用来查你 spec 的那张。今天先自查一遍，如实勾；有 ✗ 的列出来，是 Day 7 的讨论点，不是今天的失败。
结构（六项）
- 七要素标题齐全、顺序合理、易扫读
- spec 只写 WHAT，无 HOW（可换技术栈仍成立）
- 有编号约定（如背景 B / 目标 G / 故事 US / 验收 AC）
验收（最重要）
- 每条 AC 都是 Given-When-Then + 可量化断言，零形容词
- 每条 AC 都能直接变成一句自动化测试
- 至少覆盖：主路径成功 + 一条失败路径
防漂移
- 非目标 ≥3 条
- 边界条件覆盖：空结果 / 极限数据 / 超时或失败 / 并发中的至少 3 类
- 验证方式与 AC 一一对应（能指出用哪个脚本/指标证明哪条 AC）
方向
- 我（或 AI）拿到它能讲清：做给谁、改变什么、怎么算成功
- 我”顺手的念头”都被写进非目标，没留在脑子里
诚实项（Day 7 用）
- 我最有把握的要素：；最没把握的要素：；没写出来的技术顾虑：__
6. 一份”达标样张”（示范，别照抄——用你自己的场景）
拿「用户头像上传」做示范（从 Day 3 的”优化订单查询”错开，避免你照着抄）。篇幅刻意精简，重点看”验收/边界/非目标”怎么写得可测。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
## Spec：用户头像上传（资料页）
### 1. 背景
注册用户约 1.2 万，目前无任何头像入口；评论与回复区展示默认灰头像，
运营反馈辨识度低、易误认账号。上周调研 200 人中 41% 表示"有头像入口会提高使用意愿"。
### 2. 目标
支持用户上传并保存头像，评论/资料页即时展示；单次上传 ≤5MB；
全部文件持久化保留，接口契约稳定。技术方案（存储介质/压缩库）留待 plan 阶段决定。
### 3. 用户故事
- 作为普通用户，我想上传一张头像，以便评论与资料页能显示我的样子。
- 作为老用户，我想随时更换头像，以便标识我的最新身份。
- 作为运营，我不想在无审核下看到超规/超大文件泛滥，以便控制存储与风控成本。
### 4. 验收标准
- AC-1（主路径）：Given 已登录用户选择一张 ≤5MB 的 jpg/png/webp，When 提交上传，
Then 接口 200 且返回稳定 URL，页面刷新后头像更新，全流程 ≤3s（4G 网络、样例集 50 张）。
- AC-2（成功判定）：Given 上传返回的 URL，When 访问该 URL，Then 返回图像可正常解码
且宽高不超过 1024×1024（超过则被等比压缩后落库）。
- AC-3（非法输入）：Given 文件 >5MB / 非白名单格式 / 0 字节，When 上传，
Then 返回 4xx + 明确错误码，不落任何文件。
- AC-4（鉴权）：Given 未登录用户，When 调上传接口，Then 返回 401，不执行上传。
- AC-5（回归）：Given 既有资料页用例，When 执行回归，Then 全部通过。
### 5. 非目标
- 不做 gif/动图与视频头像。
- 不做原图下载/原图查看入口。
- 不迁移存量"默认头像"方案，不改其它模块。
- 不接第三方 CDN / 不做头像内容自动审核（本期仅做格式与大小限制）。
### 6. 边界条件
- 断网/超时：上传中断时前端可重试 ≤2 次，服务端不留半截文件。
- 并发：同一账号连续快速提交时，以最后一次为准，不发生重复入库或错乱。
- 文件名冲突：存储键不与历史文件冲突，覆盖行为以"新头像替换旧头像"为准。
- 磁盘/存储异常：写入失败返回 5xx 明确错误，不静默成功。
### 7. 验证方式
- 样例集 50 张（各格式/各尺寸/超限样本各若干）跑通 AC-1/2/3，输出通过表。
- 自动化单测：AC-4（401）、文件键冲突、超时重试。
- 回归集：资料页既有用例。上线后观察 7 天上传成功率与 P95 耗时监控。
对着它检查你自己的 spec：它的”快”变成了 ≤3s+4G+样例集；”友好”变成了明确错误码；”撑住并发”变成了最后一次为准+防重复入库——每一个模糊词都被翻译成了可测条件。你的 spec 也应该能这样逐句解释。
7. 今日打卡输出
- 主产出：
Day5-spec-<你的功能名>.md（本目录）。 - 三句话交付说明（写在 spec 文末或单独一行）：
- 我选的场景是：__；它够小/够真/够可测吗（各自打勾）？
- 我全程最卡的一步是：__（对应研究手册：这是最有价值的研究素材）。
- 我最有把握 / 最没把握的要素分别是：__ / __。
- 自查清单已勾（第 5 节那张，如实标注 ✗ 项）。
全部完成 = 本周实物交付到手。Day 7 会拿同一张 checklist 复查它、并把它改写成第一篇正式学习笔记的骨架。
附录 A：形容词→可测句练习参考答案
翻译没有唯一答案，够”可转成断言”就算对。这里给的都是”把它变成一条 Given-When-Then”的思路：
- “搜索要很快” → 给定含 300 万行的订单表，当输入关键词回车并加载第 10 页，则首屏响应 ≤500ms（P95，同规格测试机）。→ 或拆成”接口 P95 ≤500ms + 前端从点击到首条结果 ≤800ms”。
- “错误提示要友好” → 当输入非法时，则返回人类可读的错误文案（错误码 + 一句话解释），且不泄露堆栈/内部信息；文案通过 i18n 键引用，长度 ≤60 字。（把”友好”翻译成”可断言的行为”：有文案、无堆栈、有码。）
- “系统要能撑住并发” → 给定 500 个并发用户同时提交上传，当持续 5 分钟，则请求失败率 ≤1%、P95 耗时 ≤5s，且无 5xx 之外的数据错误。（给并发数、时长、失败率三个数字。）
评分标准：每条答案只要包含”前置 + 动作 + 带数字的可观测结果”，就算通过；数字可以不是最终值，但必须存在，Day 7 复查时再校准量级。
本工作纸依据《SDD+Harness四周学习计划.md》Day 5 主题编制。演示样张仅示范写法与达标形态，请勿照抄；正式学习请结合真实需求完成。整理日期：2026-09-08
