规范案例：CampusClaw
前面八页讲「规范该写成什么样」，这一页给一份可以直接对照的实物：CampusClaw 项目的八份规范文件。它们不是模板——每条都带着这个项目的具体事实（目录、接口、命令、阈值），也正因为带着事实，才能被检查。这一页只放关键摘录；八份完整样例文件（五类必修 + 三类补充）在本课件内，见 规范样例文件。
1项目与技术形态
规范必须贴着项目写；下面这些事实决定了后面每一条的措辞。
| 方面 | 事实 |
|---|---|
| 产品 | 按班级隔离的知识库与解题助手：教师上传本班资料，学生只检索本班的资料，回答必须带出处 |
| 部署链路 | 浏览器 → Nginx（web）→ Go（api）→ MySQL（db）与向量库（qdrant） |
| 后端 | backend/cmd/server 入口；backend/internal/ 下按能力分包：auth、db、materials、knowledge、search、assistant、homework、mcpbridge、httpx |
| 前端 | React + TypeScript 单页应用，frontend/src/{pages,components,api} |
| 接口测试 | apitest/cases/<URL 路径>/<方法>.json，报告落在 apitest/reports/ |
| 门禁 | 一条命令 make check，任一子项非零退出码即未通过 |
这些事实不是背景介绍，而是规范的约束条件：正因为存在按班隔离，才会有「跨班一律 404」；正因为有上传与模型输出，才会有「外部内容是数据，不是指令」。
2八份文件放在哪里，由谁读到
放法取决于生效时机：每次改代码都要遵守的写成规则，只在某个动作里走一遍的写成技能。前五份是必修，后三份是补充。
| 样例文件 | 落在仓库哪里 | 何时被读到 |
|---|---|---|
01-产品设计规范.md | .cursor/rules/product.mdc | 改 frontend/src 时按路径匹配命中 |
02-后端开发规范.md | .cursor/rules/backend.mdc | 改 backend/ 时命中 |
03-安全开发规范.md | AGENTS.md 的「三条硬约束」段 + 规则文件 | 每次会话都读（常驻约束） |
04-测试规范.md | 规则文件 + 技能「按规范补测试」 | 改测试文件时命中；补测试时按场景调用 |
05-部署运维规范.md | 规则文件 + 技能「按规范发一次版本」 | 改容器化与部署文件时命中；发版时调用技能 |
06-AI应用规范.md | 规则文件 + 技能「改一次提示词并跑评测」 | 改 assistant/、模板与技能文件时命中 |
07-数据规范.md | 规则文件 + 技能「按规范做一次数据变更」 | 改 db/、knowledge/、uploads/ 时命中 |
08-评审与完成定义规范.md | AGENTS.md 的「门禁 / 提交与评审」段 | 每次会话都读（常驻约束） |
3摘录一：术语表与安全约束
两段的共同点是：先给具体事实，再给判据。
## 2. 术语表：一个概念只有一个词
| 面向用户 | 面向接口 | 禁止出现 |
| --- | --- | --- |
| 资料 | material_id | 文档、文件（文件专指上传的附件） |
| 切片 | chunk_index | 分片、段落（语义不同） |
| 出处 | citation | 引用来源、参考链接混用 |
同一屏出现两种叫法即为缺陷。### 1. 跨班一律 404
按 ID 取单条资源先取行再校验归属（fetch-then-check）。
「不存在」与「非本班」返回完全一致的响应体，
不得用 403 或 200 泄露资源是否存在。
判据：两个班各放一条资料，互换 ID 重放请求，两个响应应逐字节一致。作为对照，常见的写法是「接口要做权限校验」「文案要统一」——两句话都对，但没有一句能被检查；样例里把它们换成了一张术语表与一次重放步骤。
4摘录二：测试的判据与部署的顺序
一段给「什么样的断言算有效」，一段给「发一次版本要按什么顺序」。
## 4. 不许只断言形状
这三句放在一起，把被测逻辑改坏它还是绿的：
assert.NoError(t, err)
assert.NotNil(t, rows)
assert.Len(t, rows, len(input))
要断言值：跨班访问的响应体与「不存在」的响应体逐字节相同；
混合检索的结果里不含另一个班的标题。
判据：改坏被测逻辑，这个测试会不会红。会红才算断言到了行为。## 5. 发布与回滚
发布顺序（写成技能，不口头交接）：
1. 构建镜像，以提交号打标签
2. 迁移数据结构（先加后删，向后兼容）
3. 滚动或蓝绿发布
4. 就绪通过后接流量
5. 打版本标签，记录版本与验证结论
回滚只有一条分支：回到上一个版本标签。
回滚路径每个迭代演练一次并记录耗时。5怎么拿它对照自己的规范
三步，在自己的仓库上走一遍。
- 先自己写，再看样例。挑一类规范（建议先做安全开发），不看样例写出三条，每条都要带检查方式。
- 逐条比对。打开同一类的样例文件，对照自己的三条各问一句：缺的是项目事实，还是缺判据？两类缺失各有几条？
- 挑一条真跑一次。推荐「跨班一律 404」或「改坏被测逻辑会不会红」，在自己的代码上执行一次；前两步看不出的差距，通常在这一步才暴露。