@routerhub/agent-rules 1.5.185 → 1.5.186
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.base.md +39 -0
- package/package.json +1 -1
- package/rules/global.md +39 -0
package/AGENTS.base.md
CHANGED
|
@@ -47,6 +47,45 @@
|
|
|
47
47
|
- ⚠️ **部署完成的定义 = 脚本执行完 → 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。
|
|
48
48
|
- ⚠️ **「部署可用」≠「功能已验证」**：部署自动化到位只保证环境就绪、功能直接可操作；功能是否正确，仍需按既有验证铁律用真实数据验证，两者不冲突。
|
|
49
49
|
|
|
50
|
+
## ⚠️ 上线前准备清单（AI 写代码时自动登记「代码里体现不了的上线准备」）
|
|
51
|
+
|
|
52
|
+
「可部署性自包含铁律」要求所有上线准备内嵌部署脚本、上线只跑脚本零人工补操作。但**并非所有上线准备都能写进代码/部署脚本**——新建定时任务（cron / Cloud Scheduler / Job）并安排首次触发、只能在云平台控制台手动操作、跨仓库的部署顺序依赖、需先通知下游团队等，代码与脚本天然覆盖不到。这类准备不登记，上线必漏。**本规则把登记动作交给写代码的 AI 自动完成：规则随发版分发到各仓库后，AI 每次写需求/改代码都会自查是否引入此类准备并当场登记——不需要仓库预置任何文件、不需要任何人拷贝模板。**
|
|
53
|
+
|
|
54
|
+
- ⚠️ **判断标准：只登记「自包含兜不住」的。** 能写成代码/部署脚本自动完成的准备，仍按自包含铁律内嵌脚本，禁止偷懒登记进清单当借口——两条机制互补、不重叠。常见「兜不住」类别：
|
|
55
|
+
- **定时/后台任务**：新建 cron / Cloud Scheduler / Job、上线后需首次手动触发、频率/开关需与生产环境人工核对（代码里通常只有任务定义，没有「谁去建、何时触发」）
|
|
56
|
+
- **云平台手动操作**：无法 IaC 化的资源、需人工在控制台点选确认
|
|
57
|
+
- **部署顺序依赖**：必须先升级/先就位某外部依赖（常跨仓库，本次 git 历史看不出）
|
|
58
|
+
- **跨团队/跨系统动作**：上线前需通知/协调下游仓库、运营、其他团队；共享基础设施变更需先获确认
|
|
59
|
+
- **上线后观察点**：上线后需盯的指标、需手动跑一遍的验证
|
|
60
|
+
- ⚠️ **登记是 AI 写需求/改代码流程的一部分（本规则执行者 = 写代码的 AI，不是人的手工职责）**：实现需求时逐项自查「本次改动上线时，有没有一个写不进代码/部署脚本、但上线时必须有动作去做的准备？」命中 → **当场登记，禁止留到发版时靠回忆补**（过了写代码那一刻，连当事人都容易忘）。条目须含可执行信息：什么动作 / 怎么手动触发 / 在哪看 / 找谁。
|
|
61
|
+
- ⚠️ **载体：仓库根目录 `RELEASE_CHECKLIST.md`，由 AI 自动创建与维护，无需预置**：
|
|
62
|
+
- 仓库尚无该文件且本次命中 → AI 按本节末尾「清单格式」自动生成，随**同一个 PR** 提交；
|
|
63
|
+
- 已有文件 → AI 追加/更新对应条目（含状态）；
|
|
64
|
+
- 无任何此类项的仓库 → 不生成该文件，发版时扫不到即代表本期无特殊准备。
|
|
65
|
+
- ⚠️ **commit 标记约定（发版索引通道）**：改动引入需登记的上线准备项时，commit message 必须带 `release-prep: <一句话>` 标记，使发版时能用 `git log 上次发版tag..HEAD --format=%B | grep release-prep` 机械扫出全部需注意的提交——把「发版时读代码猜」换成「写代码的 AI 当场写、发版机械扫」，来源可靠、不会漏。
|
|
66
|
+
- ⚠️ **code review 有义务核对登记**：reviewer 读 PR 时须确认「本次改动是否引入了需登记的上线准备项」；引入了而 PR 未同步更新 `RELEASE_CHECKLIST.md`、commit 未带 `release-prep:` → 报错。
|
|
67
|
+
- ⚠️ **发版前扫查流程（每次上线/发版必做，禁止用「我记得这期改动」替代）**：
|
|
68
|
+
1. 用 `git log $(git describe --tags --abbrev=0)..HEAD --format=%B`（无 tag 时改用上一个「发布 vX.Y.Z」commit）列出本次全部提交；
|
|
69
|
+
2. 扫描其中的 `release-prep` 标记，逐个找到清单对应条目核对（无清单文件且无标记 = 本期无特殊准备，正常放行）；
|
|
70
|
+
3. 通读 `RELEASE_CHECKLIST.md`（若存在）全文，逐项确认状态（✅ 已完成 / 本次上线执行 / 🚫 跳过并注明原因），确认无遗漏后才允许发版。
|
|
71
|
+
- ⚠️ **发版脚本硬闸（有发版/上线脚本的仓库）**：脚本应内置检查——`RELEASE_CHECKLIST.md` 存在时不得有待办条目（状态列为 `| ⬜ |`），否则中止发版。agent-rules 仓库 `release.sh` 已示范实现（`check_release_prep`，与「规则漂移检查」同层，在版本号递增前执行），各仓库照此内嵌，不做预置要求。
|
|
72
|
+
|
|
73
|
+
**清单格式（AI 首次登记时照此在仓库根目录自动创建 `RELEASE_CHECKLIST.md`，表格列固定）：**
|
|
74
|
+
|
|
75
|
+
```markdown
|
|
76
|
+
# 上线前准备清单
|
|
77
|
+
|
|
78
|
+
> 登记「代码/部署脚本里体现不了、但上线时必须有动作」的上线准备项（机制见 AGENTS.base.md「上线前准备清单」章节）。
|
|
79
|
+
> 有上线准备项的 PR，写代码的 AI 随代码在同一个 PR 更新下方表格并提交，commit 带 `release-prep: <一句话>`。
|
|
80
|
+
|
|
81
|
+
| 日期 | 相关 PR/commit | 类别 | 上线准备项（含如何手动触发 / 在哪看 / 找谁） | 状态 | 备注 |
|
|
82
|
+
|---|---|---|---|---|---|
|
|
83
|
+
| YYYY-MM-DD | #PR / commit | 定时任务 | 新建 cron 并手动触发首次初跑 | ✅ | |
|
|
84
|
+
|
|
85
|
+
<!-- 维护约定：待办必须写在状态列，形如 `| ⬜ |`（发版脚本只扫描带管道边界的 ⬜，说明性文字不触发）。
|
|
86
|
+
无待办时全文件不得存在 `| ⬜ |` 行 -->
|
|
87
|
+
```
|
|
88
|
+
|
|
50
89
|
## ⚠️ 测试环境功能验证前置铁律（防止缺表报错误判为代码问题）
|
|
51
90
|
|
|
52
91
|
- ⚠️ **在测试环境验证任何涉及新增表/新增字段的功能（如充值、退款、发票，不限于这些）之前，必须先确认数据库表结构已就绪。** 测试环境 AutoMigrate 默认关闭（见「Go 规则」），新表/新字段不会随代码自动创建。跳过这一步直接验证，报出的缺表/缺字段错误是环境问题，不是代码问题，极易误判。
|
package/package.json
CHANGED
package/rules/global.md
CHANGED
|
@@ -47,6 +47,45 @@ name: "通用规则"
|
|
|
47
47
|
- ⚠️ **部署完成的定义 = 脚本执行完 → 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。
|
|
48
48
|
- ⚠️ **「部署可用」≠「功能已验证」**：部署自动化到位只保证环境就绪、功能直接可操作；功能是否正确，仍需按既有验证铁律用真实数据验证，两者不冲突。
|
|
49
49
|
|
|
50
|
+
## ⚠️ 上线前准备清单（AI 写代码时自动登记「代码里体现不了的上线准备」）
|
|
51
|
+
|
|
52
|
+
「可部署性自包含铁律」要求所有上线准备内嵌部署脚本、上线只跑脚本零人工补操作。但**并非所有上线准备都能写进代码/部署脚本**——新建定时任务（cron / Cloud Scheduler / Job）并安排首次触发、只能在云平台控制台手动操作、跨仓库的部署顺序依赖、需先通知下游团队等，代码与脚本天然覆盖不到。这类准备不登记，上线必漏。**本规则把登记动作交给写代码的 AI 自动完成：规则随发版分发到各仓库后，AI 每次写需求/改代码都会自查是否引入此类准备并当场登记——不需要仓库预置任何文件、不需要任何人拷贝模板。**
|
|
53
|
+
|
|
54
|
+
- ⚠️ **判断标准：只登记「自包含兜不住」的。** 能写成代码/部署脚本自动完成的准备，仍按自包含铁律内嵌脚本，禁止偷懒登记进清单当借口——两条机制互补、不重叠。常见「兜不住」类别：
|
|
55
|
+
- **定时/后台任务**：新建 cron / Cloud Scheduler / Job、上线后需首次手动触发、频率/开关需与生产环境人工核对（代码里通常只有任务定义，没有「谁去建、何时触发」）
|
|
56
|
+
- **云平台手动操作**：无法 IaC 化的资源、需人工在控制台点选确认
|
|
57
|
+
- **部署顺序依赖**：必须先升级/先就位某外部依赖（常跨仓库，本次 git 历史看不出）
|
|
58
|
+
- **跨团队/跨系统动作**：上线前需通知/协调下游仓库、运营、其他团队；共享基础设施变更需先获确认
|
|
59
|
+
- **上线后观察点**：上线后需盯的指标、需手动跑一遍的验证
|
|
60
|
+
- ⚠️ **登记是 AI 写需求/改代码流程的一部分（本规则执行者 = 写代码的 AI，不是人的手工职责）**：实现需求时逐项自查「本次改动上线时，有没有一个写不进代码/部署脚本、但上线时必须有动作去做的准备？」命中 → **当场登记，禁止留到发版时靠回忆补**（过了写代码那一刻，连当事人都容易忘）。条目须含可执行信息：什么动作 / 怎么手动触发 / 在哪看 / 找谁。
|
|
61
|
+
- ⚠️ **载体：仓库根目录 `RELEASE_CHECKLIST.md`，由 AI 自动创建与维护，无需预置**：
|
|
62
|
+
- 仓库尚无该文件且本次命中 → AI 按本节末尾「清单格式」自动生成，随**同一个 PR** 提交；
|
|
63
|
+
- 已有文件 → AI 追加/更新对应条目（含状态）；
|
|
64
|
+
- 无任何此类项的仓库 → 不生成该文件，发版时扫不到即代表本期无特殊准备。
|
|
65
|
+
- ⚠️ **commit 标记约定（发版索引通道）**：改动引入需登记的上线准备项时，commit message 必须带 `release-prep: <一句话>` 标记，使发版时能用 `git log 上次发版tag..HEAD --format=%B | grep release-prep` 机械扫出全部需注意的提交——把「发版时读代码猜」换成「写代码的 AI 当场写、发版机械扫」，来源可靠、不会漏。
|
|
66
|
+
- ⚠️ **code review 有义务核对登记**：reviewer 读 PR 时须确认「本次改动是否引入了需登记的上线准备项」；引入了而 PR 未同步更新 `RELEASE_CHECKLIST.md`、commit 未带 `release-prep:` → 报错。
|
|
67
|
+
- ⚠️ **发版前扫查流程（每次上线/发版必做，禁止用「我记得这期改动」替代）**：
|
|
68
|
+
1. 用 `git log $(git describe --tags --abbrev=0)..HEAD --format=%B`（无 tag 时改用上一个「发布 vX.Y.Z」commit）列出本次全部提交；
|
|
69
|
+
2. 扫描其中的 `release-prep` 标记，逐个找到清单对应条目核对（无清单文件且无标记 = 本期无特殊准备，正常放行）；
|
|
70
|
+
3. 通读 `RELEASE_CHECKLIST.md`（若存在）全文，逐项确认状态（✅ 已完成 / 本次上线执行 / 🚫 跳过并注明原因），确认无遗漏后才允许发版。
|
|
71
|
+
- ⚠️ **发版脚本硬闸（有发版/上线脚本的仓库）**：脚本应内置检查——`RELEASE_CHECKLIST.md` 存在时不得有待办条目（状态列为 `| ⬜ |`），否则中止发版。agent-rules 仓库 `release.sh` 已示范实现（`check_release_prep`，与「规则漂移检查」同层，在版本号递增前执行），各仓库照此内嵌，不做预置要求。
|
|
72
|
+
|
|
73
|
+
**清单格式（AI 首次登记时照此在仓库根目录自动创建 `RELEASE_CHECKLIST.md`，表格列固定）：**
|
|
74
|
+
|
|
75
|
+
```markdown
|
|
76
|
+
# 上线前准备清单
|
|
77
|
+
|
|
78
|
+
> 登记「代码/部署脚本里体现不了、但上线时必须有动作」的上线准备项（机制见 AGENTS.base.md「上线前准备清单」章节）。
|
|
79
|
+
> 有上线准备项的 PR，写代码的 AI 随代码在同一个 PR 更新下方表格并提交，commit 带 `release-prep: <一句话>`。
|
|
80
|
+
|
|
81
|
+
| 日期 | 相关 PR/commit | 类别 | 上线准备项（含如何手动触发 / 在哪看 / 找谁） | 状态 | 备注 |
|
|
82
|
+
|---|---|---|---|---|---|
|
|
83
|
+
| YYYY-MM-DD | #PR / commit | 定时任务 | 新建 cron 并手动触发首次初跑 | ✅ | |
|
|
84
|
+
|
|
85
|
+
<!-- 维护约定：待办必须写在状态列，形如 `| ⬜ |`（发版脚本只扫描带管道边界的 ⬜，说明性文字不触发）。
|
|
86
|
+
无待办时全文件不得存在 `| ⬜ |` 行 -->
|
|
87
|
+
```
|
|
88
|
+
|
|
50
89
|
## ⚠️ 测试环境功能验证前置铁律（防止缺表报错误判为代码问题）
|
|
51
90
|
|
|
52
91
|
- ⚠️ **在测试环境验证任何涉及新增表/新增字段的功能（如充值、退款、发票，不限于这些）之前，必须先确认数据库表结构已就绪。** 测试环境 AutoMigrate 默认关闭（见「Go 规则」），新表/新字段不会随代码自动创建。跳过这一步直接验证，报出的缺表/缺字段错误是环境问题，不是代码问题，极易误判。
|