# 贡献指南

> 这个约束包的价值来自**独立复现**：越多项目各自踩到同一个坑，
> 那条规则就越该被信任、越该升级。所以欢迎贡献 —— 但请遵守质量标准。

---

## 核心理念（先读这段）

**为什么"人多"能变"厉害"**：不是投票，是**独立发现次数**。

```
1 个项目发现某规则  → 可能是这个项目写法特别
3 个项目独立发现    → 说明它命中的是普遍的人性或工具链缺陷
```

所以你的贡献**最有价值的形式**，是**你自己项目里真实踩过的坑** ——
尤其是那些"一开始以为没问题，结果被打脸"的。

**最没价值的形式**是"我觉得应该注意…"。这类**请勿提交**。

---

## 三种贡献方式

### 方式一：提交新规则（最欢迎）

适合：你在自己项目里踩了一个坑，觉得值得提醒别人。

**步骤**：

1. 在你的项目里跑一次提炼（见 `core/DISTILL.md`），把规则写进你本地的 `constraints.md`
2. 跑贡献脚本，它会自动找出**你新增的规则**（对比安装时的基线）：

   ```powershell
   # Windows
   .\agent-constraints\contribute.ps1
   ```
   ```bash
   # Linux / macOS
   ./agent-constraints/contribute.sh
   ```

3. 脚本会生成一个 `contribution-<日期>.md`，里面只含你新增的规则
4. 把它提交到本仓库（发起 PR 或直接贴 issue）

### 方式二：为一个已有规则补充来源（价值极高）

适合：你**独立踩到了**规则库里已有的某个坑。

这是**最该做的贡献** —— 它直接把那条规则的「独立发现次数 +1」，
可能触发它从 L1 升级到 L0。

**做法**：告诉维护者（或直接改）：
```
R-003 全局副作用必须带测试开关 —— 我在 XX 项目也遇到了
场景：加了 Redis 缓存后，测试之间互相读到脏数据
代价：花了 2 小时排查
```

### 方式三：证伪或修正

适合：你发现某条规则**不适用**、**有更好做法**、或者**已经过时**。

**同样重要** —— 没有证伪机制，规则库会积累越来越多的"其实没必要"的条目。

---

## 质量标准（硬性）

一条规则要被收进主库，**必须全部满足**：

- [ ] **四个字段齐全**：规则 / 触发 / 检查 / 证据（见 `templates/rule.md`）
- [ ] **「检查」可自动化**：写成命令、grep 或断言。**写"人工 review"的一律退回**
- [ ] **有真实代价**：违反它会造成时间/安全/数据损失。不是"这样更优雅"
- [ ] **真实生效过**：你自己的项目里确实因此避免了问题，或确实因此吃过亏
- [ ] **抽到了模式层**：不是"某次具体怎么改的"
  - ✗ `把 Profile.vue 第 762 行改成用 ID`
  - ✓ `展示名与标识必须分开：路由/查询/身份判断用 ID，展示才用昵称`
- [ ] **不是常识**：`要用 npm run build 构建` 这种不用提交

**常见退回原因**：

| 退回原因 | 例子 |
|---|---|
| 无法判断是否违反 | "注意代码可读性" |
| 只是风格偏好 | "变量名用驼峰"（应该交给 linter） |
| 太具体 | "这个项目的 API 路径不要硬编码" |
| 已在其他规则里 | 提交前请先搜一遍规则库 |

---

## 提交格式

用 `templates/rule.md`：

```markdown
### R-0XX 一句话规则名（动宾结构）

- **规则**：可执行的约束（做什么/不做什么）
- **触发**：
  - 场景 1
  - 场景 2
- **检查**：一条命令 / grep / 断言
- **独立发现**：1        ← 你是第一个发现就填 1
- **来源**：
  - <你的项目类型>（<日期>，<踩了什么坑>）
- **证据**：
  - 时间：
  - 经过：
  - 代价：
```

> **项目名可以匿名化** —— 写"某电商后台"就够了，不需要暴露真实项目名。

---

## 变更日志格式

每个版本条目按「**原因 / 问题 / 解决方法**」写，完整要求与反例见
[`templates/changelog-entry.md`](templates/changelog-entry.md)。

```markdown
## [x.y.z] - YYYY-MM-DD

### <用现象命名的问题概括>

**原因**：<导致问题的机制或遗漏 —— 文件、配置项、框架行为、数值>
**问题**：<造成什么后果 —— 报错原文、错误数值、对照实验、影响范围>
**解决方法**：<改了什么 —— 改哪个文件、加什么约束、补了什么测试>
```

格式由测试强制（`tests/plugin.spec.mjs` 的【变更日志】用例，从 0.25.0 起生效），
**写错了会红**，不靠记性。

> 2026-10-05 用户指出条目读起来像讲故事：
> "我感觉你再讲故事 正常应该是 因为什么原因 造成什么问题 解决方法吧"。
> 规则库 C-004（记录要沉淀成规则，不能只写故事）本来就规定了这件事，
> 但没有可执行的约束，于是又写成了叙事文。现在补上了。

---

## 维护者会怎么处理

见 [`core/MERGE.md`](core/MERGE.md)。简要说明：

1. **匹配**：你的规则是否与现有规则在描述同一个「违反场景」？
   - 相同 → 合并，该规则的独立发现次数 +1
   - 部分重合 → **抽象**出一条更上位的规则，你的和它都变成实例
2. **定级**：按独立发现次数 —— 1 次进 L2，2 次进 L1，**≥3 次进 L0**
3. **写入 + 留痕**：变更日志里会写明你的项目和这次变化

**你可能会看到自己的规则被"改写"** —— 通常是往更抽象的方向。
这不是否定，而是让它能覆盖更多场景。

---

## 不会被收录的情况

- 无法自动检查的规则（"注意…"）
- 只适用你项目特定业务的规则（→ 应该留在你项目的 L2）
- 已被工具链覆盖的（linter / formatter / CI 已经做了）
- 没有真实代价的风格偏好

**被退回不代表没价值** —— 它可能只是该留在你自己的项目里。
`core/DISTILL.md` 里也要求维护者记录「本次未收录」及原因，
所以你下次不会提同样的建议。