规约范例：任务清单

任务清单保证执行顺序不依赖执行者的记忆：骨架任务在最前，验证任务在最后。

1第四份：tasks.md

编号、可勾选，按顺序做完即完成本次改动。

# 任务清单：course-material-search
## 骨架（先做完，再谈功能）
1. [ ] internal/search 建包，只留接口定义与空实现
2. [ ] /health 增加 qdrant 连通状态字段
3. [ ] SEARCH_VECTOR_MIN 缺失即启动失败，不取默认值
4. [ ] 结构化日志字段：request_id、class_id、mode、top_k
## 检索实现
5. [ ] 关键字检索：MySQL FULLTEXT，带 class_id 过滤
6. [ ] 向量检索：Qdrant，top_k 默认 8
7. [ ] RRF 融合，k=60，按「资料 + 段落」去重
8. [ ] 阈值过滤，命中为空时填 empty_reason
## 授权与错误
9. [ ] 逐资源判定：资料不属于本班则返回 404
10. [ ] 错误码 1001 / 1101 / 1204 的映射与响应结构
## 验证
11. [ ] apitest/cases/api/search/GET.json 覆盖上述全部场景
12. [ ] make check 全绿

前四条是骨架任务：它们不涉及任何检索逻辑，却决定后面八条能否被验证——没有连通状态字段，向量库故障发生时无从判定；配置取默认值，阈值问题会静默通过。

2这份范例的四个检查点

照抄之前，先用这四条检查自己的规约。

校验命令通过。/opsx-validate 2026-10-27-course-material-search --strict 不通过就先补规约，不要先写代码。
能力与场景一一对应。四条需求各有一组场景，既没有无场景的需求，也没有无归属的场景。
数值写具体。阈值 0.35、k=60、top_k=8、字符上限 200、资料 3 份。出现「大量」「较快」「若干」的规约，等于把判定权交给了实现者。
另起一次会话照做。不带历史上下文的 Harness 会话，只拿到仓库路径与变更名，能按任务清单实现且问不出含糊之处；它问得出的地方就是规约的缺口。

对应的课程知识点：完成定义（Definition of Done）、验收测试、变更的可追溯性。四份文件的关系这样记：动因说明必要性，设计固定取舍，需求规约给出判定，任务清单保证顺序——只有第三份能判定通过与不通过。