Think：从问题到一份 SPEC

本节目标

不急着写代码。这一节，全班要一起把整学期的产品需求写成一份 SPEC.md，并冻结为 v0.1：

• 说清这个工具给谁用、解决什么问题。
• 分清「整学期要做的」和「本次只做的」。
• 把「能保存」这类模糊说法，改写成能逐条检查的验收条件。

本节交付：一份全班共同确认的 SPEC.md v0.1，保存在项目根目录。

课前先知道：为什么要先写需求

先问自己一个问题：你上一次找不到自己的学习笔记，是什么时候？

课堂笔记、课程资料、临时想法散在聊天记录、文件夹和各种工具里——记下来了，要用的时候却找不到，更难用于复习。这个学期的项目就从这个真实问题出发：做一个「个人 AI 学习笔记本」，整学期持续迭代这一个产品。

先说问题，不急着说技术。增删改查（CRUD）不是目的，它只是第一步的实现手段。

谁在用这个工具

• 用户：学生本人，个人使用。
• 日常：记录课堂内容，随时重新查看。
• 进阶：整理重点、查询资料、辅助复习。

先想清楚「谁在什么情况下需要它」，再决定做什么功能。这个笔记本是全班共同讨论、共同使用一份完整的产品需求——不是每人各做一个不同的产品。

一份笔记的一生

一份笔记写下来之后，后面还应该能发生什么？

1. 记录：写下来，保存并重新找到。
2. 整理：提炼摘要和知识点，由人确认。
3. 查找 / 问答：找到相关资料，回答时显示依据。
4. 复习：形成要点和简单的练习任务。

这是整学期的产品主线。本次的第一步，只是把「记录」做可靠。

写 SPEC 的六条基本原则

1. 问题先于功能。 先回答为什么要做、为谁做，不从页面和按钮开始。
2. 场景先于技术。 先讲清用户怎么使用，再决定技术方案；不让 AI 替我们猜需求。
3. 完整目标与本次范围分开。 可以定义整个学期的产品愿景，但本次只实现一个可完成、可验证的闭环。
4. 明确不做什么。 登录、云同步这类没列入当前范围的内容，不因为 AI 能生成就顺手加上。
5. 需求必须可验收。 「方便」「智能」「保存成功」不是可验证标准；要改写成具体操作和可观察的结果。
6. SPEC 是协作基线，不是一次性 Prompt。 确定后保存到仓库；以后需求变了，先改 SPEC，再让 AI 改实现。

从想法到 SPEC 的六步

发现问题
  ↓
确定用户与典型场景
  ↓
明确产品目标与主要流程
  ↓
划分范围：本次 / 后续 / 不做
  ↓
写出可操作的验收条件
  ↓
检查一致性，确认并保存 SPEC 版本

每一步只回答一个关键问题：

步骤	关键问题	本模块的答案
问题	为什么做？	学习资料零散，整理和查找困难
场景	谁在什么情况下用？	学生记录、整理、查询、复习
目标	最终达到什么效果？	一套可逐步加入 AI 能力的个人学习笔记本
范围	这次做什么、不做什么？	本次只做 CRUD 与本地保存
验收	如何证明它真的有用？	新建、修改、删除后刷新，数据状态正确
确认	大家理解一致吗？	冻结 SPEC.md v0.1，作为开发依据

两个必须分清的区别

• SPEC 与 Prompt： SPEC 规定「要做什么、做到什么程度」，是较长期的要求依据；Prompt 是某一次交给 AI 的执行指令。不能用一段临时聊天代替产品要求。
• 产品级 SPEC 与本次开发任务： 可以先描述长期目标，但只能要求 AI 实现本次划定的范围。规划完整，不等于一次做完。

整学期的四个功能区，和本次只做的一小步

整学期，我们要建设四个功能区：

功能区	内容	什么时候做
F1 笔记管理	增删改查；以后增加分类和搜索	本次只做增删改查
F2 AI 整理	摘要和知识点，人确认后保存	后续
F3 资料问答	基于导入资料回答，标出处	后续
F4 复习辅助	复习任务、要点与简单练习	后续

本次范围只有一行：V0 = 新建、查看、编辑、删除 + 浏览器本地保存 + 空状态。

不做： 登录、同步、LLM API、RAG、Agent、部署。

想清楚「不做」和想清楚「做什么」同样重要——一次性做所有功能，只会让每个功能都做不可靠。

「能保存」怎样才算真的能保存

把模糊说法改写成看得见的结果：

操作	看得见的结果
新增	保存后列表出现新笔记
查看	点开能读到完整正文
修改	重新打开仍是修改后的内容
删除	确认后消失，刷新也不恢复
持久化	同一浏览器刷新 / 重开后数据仍在
空数据	首次打开有明确提示，不报错

写进 SPEC 的验收条件：

• AC01：新建一条笔记，列表出现，内容正确。
• AC02：编辑标题和正文，保存后再次打开仍为新值。
• AC03：刷新后，未删除的笔记仍然存在。
• AC04：删除后列表不显示，刷新后不会恢复。
• AC05：没有笔记时页面正常，且有可理解的提示。

先判断，再验证： 页面弹出「保存成功」，算满足持久化了吗？——不算。提示只是一个界面事件，数据是否真的写入，要刷新、必要时关掉再重新打开才算数。

本次交付：冻结 SPEC.md v0.1

把课堂讨论的结论保存为项目根目录的 SPEC.md，检查它包含：

• 产品目标
• 目标用户与使用场景
• 四个功能区（F1–F4）
• 本次 V0 开发范围（唯一编码范围）
• 验收条件 AC01–AC05
• 非目标（明确不做什么）
• 技术边界与版本规划

参考结构（以课堂讨论形成的版本为准）：

# 个人 AI 学习笔记本 — SPEC
版本：0.1

1. 产品目标
2. 目标用户与使用场景
3. 功能范围（整学期）：F1–F4
4. V0 本次开发范围：新增 / 查看 / 编辑 / 删除 / 本地保存 / 空状态
5. V0 验收条件：AC01–AC05
6. 后续模块的产品级验收目标
7. 非目标与后续候选
8. 技术边界
9. 版本规划

冻结不是永不再改：v0.1 是这一轮开发的基线。以后需求变化，先改 SPEC 再动代码——不能因为 AI 临时想到某个功能，就悄悄扩大范围。

下一节

需求写清楚了，就轮到让 AI 动手：进入 C202 · 让 AI 做出第一版。