样例：后端开发规范

下面是 CampusClaw 项目《后端开发规范 · CampusClaw》的原文，逐条列出，可直接照抄。

适用：backend/ 下的 Go 代码与对外接口契约
被谁读到：规则文件 .cursor/rules/backend.mdc，globs backend/**/*.go

1. 分层与依赖方向

cmd/server         入口：配置读取、路由装配
internal/auth      会话与角色
internal/db        迁移与持久层        ← 只有这一层执行 SQL
internal/materials 上传与元数据
internal/knowledge 切分与入库
internal/search    关键词 / 向量 / 混合检索
internal/assistant 解题助手编排
internal/homework  作业与提交（本周新增）
internal/mcpbridge MCP 工具桥接
internal/httpx     响应封装、错误码、请求标识中间件

依赖只能自上而下。业务层（assistant、homework）不允许出现 SQL；外部能力（模型、向量库、MCP）一律收在 search / mcpbridge 内，其他包不直接依赖。

判据：评审时问一句「这个包依赖了谁」，答案里有反向箭头即为违规。

2. 接口命名与版本

路径带版本前缀 /api/v1/；资源小写复数：/api/v1/materials、/api/v1/ask、/api/v1/sessions。
方法语义固定：列表与详情 GET，创建 POST，整体替换 PUT，局部更新 PATCH，删除 DELETE。
动作型接口用名词后缀而非动词路径：POST /api/v1/materials/{id}/reindex，不写 /api/v1/reindexMaterial。

3. 统一响应结构与错误码

成功与失败走同一套外层结构，由 internal/httpx 统一产出：

{ "code": 0, "message": "ok", "data": {}, "request_id": "01HQ..." }

错误码分区，新增必须登记：

区间	含义	HTTP 状态
1000–1099	参数与校验	400
1100–1199	未认证	401
1200–1299	未授权与跨资源	404（跨班一律 404，不用 403）
1300–1399	资源不存在	404
1400–1499	业务规则不满足	409
1500–1599	依赖不可达（向量库、模型）	503

4. 校验位置

入参的结构与范围校验在路由装配处的绑定环节完成；进入业务层的结构体一律视为已校验。业务层只做规则校验（如「已截止的作业不可提交」），返回 1400 区间错误码。

判据：把必填校验挪进业务层，看评审能否发现。

5. 幂等与并发

POST /api/v1/homework/{id}/submissions 声明为幂等：接收幂等键（idempotency key），重复请求返回首次结果。
唯一约束落在存储层（submissions(homework_id, student_id) 唯一索引），不在应用层做「先查有没有」。

6. 数据访问与迁移

SQL 只出现在 internal/db；迁移动作必须条件更新（CREATE TABLE IF NOT EXISTS、ALTER ... ADD COLUMN IF NOT EXISTS 的形式），保证可重跑。
每次迁移可回滚，并在变更说明里写回滚动作。

7. 配置外置

地址、密钥、特性开关只从 internal/config 读环境变量获得；代码里不得出现字面量与默认值。缺 SESSION_SECRET 时启动失败，不带随机值继续运行。

8. 分页、排序与筛选

列表统一用 page / page_size，默认上限 50；排序字段白名单 created_at / title；检索三种模式只允许 keyword / vector / hybrid，其余值按参数错误处理。

违反时

确认是一次性的实现偏好还是规范缺失：前者改代码，后者改本文件并在变更说明里记录改动理由。