如何编写与维护规则（元规则）

如何编写与维护规则（元规则）

本仓库定位

test-spec-rule 是所有 AI 编码规则的唯一真相源（Single Source of Truth）。各编辑器、各项目都从这里「引用」，不各自维护副本。

唯一编辑处

• 只在 rules/ 下编写规则。dist/ 是脚本生成的产物，禁止手改（会被下次构建覆盖）。
• 各项目里只放「薄入口」文件（指向本仓库），不要把规则内容复制过去。

目录与编号

rules/
├── 00-global/     全局通用（所有项目）
├── 10-backend/    后端（Java）
├── 20-frontend/   前端（Vue2）
├── 30-testing/    测试
└── 90-meta/       元规则（本文件）

• 目录前缀 00/10/20... 决定加载顺序，数字小的先加载、优先级更低（被后者覆盖）。全局在前、特化在后。
• 新增类别：用下一个十位编号（如 40-xxx），不要插到已有编号中间。

单文件规则

• 一文件一主题：每个 md 只讲一件事，文件名即主题（kebab-case，如 spring-boot-service.md）。
• 文件名 = 主题英文短名，稳定，改名要同步更新引用。

文件结构模板

# <主题标题（中文）>

# 适用范围 / 技术栈基线
<说明何时适用，依赖的真实技术栈与版本>

# <规则小节>
## 要点
- 具体规则，祈使句。

Do:
<正例代码>

Don't:
<反例代码，带 ❌>

# 关联
- 见 `其他文件.md`（交叉引用）

规则编写原则

1. 具体优于抽象：写"Controller 不写业务逻辑"，不写"代码要规范"。
2. 正反例驱动：能用 Do/Don't 代码说明的，优先用代码，少用空泛说教。
3. 贴合真实技术栈：写明版本（Vue2.7、SpringBoot2.0.5、Oracle…），AI 才不会生成错版本 API。
4. 可执行可检查：规则应能转化为 checklist 项（见 00-global/code-review-checklist.md）。
5. 安全红线最高：与 00-global/security-anti-leak.md 冲突时，以安全为准。

变更流程

1. 在 rules/ 改/增规则文件。
2. 运行 scripts/build-dist.ps1 重新生成 dist/。
3. 本地校对：用目标编辑器加载 dist 产物确认无误。
4. git 提交（commit message 见 00-global/git-commit.md，type 用 docs）。
5. 通知/同步：因各项目是引用，规则更新后各项目无需改动，下次加载即生效；但需告知协作者拉取本仓库最新。

版本与历史

• 重大变更（删除/改写规则、改变行为）建议在 commit message 写明影响范围。
• 可选：在文件顶部加 > 更新：<日期> <说明> 行记录重要变更。

何时新增规则

• 同一类 AI 错误重复出现 → 沉淀为规则。
• 引入新模块/新技术栈 → 在对应角色目录加文件。
• 规则文件过长（>200 行）→ 拆分主题。