规约范例：一份变更

这一组四页给一份可直接照抄的实物：CampusClaw 的一次真实变更，四份文件原样列出。价值不在篇幅，而在每一句都能被检查——对照时请逐句问「这句话怎么判定」。

1这份范例的变更背景

先看清楚这次改动要交付什么，再读四份文件。

项	内容
项目	CampusClaw：浏览器 → Nginx（`web`）→ Go（`api`）→ MySQL（`db`）与 Qdrant（`qdrant`）
变更名	`2026-10-27-course-material-search`
本次交付的能力	课程资料检索：关键字、向量、混合三种检索，命中带资料出处
本轮边界	只做检索；不做跨资料综合问答，不做资料上传与解析，不引入新存储
依赖的既有约定	资料入库（`materials`）与登录会话（`auth`）的对外接口不变

对应的课程知识点：需求工程中的变更管理、基线（baseline）与增量交付。一次变更只交付一组可判定的能力，边界写在动因里，不写在代码里——执行者不必读代码就知道本轮不做哪些事。

2第一份：proposal.md

回答「为什么做」与「本次做到哪」，不写代码细节。

# 变更：course-material-search

## 为什么
学生在答疑区提出的问题，答案大多已经写在课件与资料里；现有做法只能由
助教重复回答。本次让检索先在资料里跑一遍，把命中的原文段落连同出处
一并交给模型，答案可回溯到原文。

## 本次做到哪
- 提供 /api/search：关键字、向量、混合三种检索，命中带资料出处
- 检索只在本班资料内进行；跨班资料一律按不存在处理
- 相似度低于阈值（SEARCH_VECTOR_MIN，默认 0.35）的命中不进入结果

## 本次不做
- 不做跨资料的综合问答（归入 assistant 能力）
- 不做资料上传与解析（materials 能力已有）
- 不引入新的存储，复用 db 与 qdrant

## 与既有约定的关系
依赖 materials（资料入库）与 auth（登录会话）；不修改两者的对外接口。

检查这三处：①「本次做到哪」每条都以动词开头且能单独演示；②「本次不做」至少三条——写不出「不做」清单，说明边界还没想清楚；③阈值写成了具体数字 0.35，而不是「较高的相似度」。