@routerhub/agent-rules 1.5.12 → 1.5.13
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 +76 -0
- package/CHANGELOG.md +6 -0
- package/package.json +1 -1
package/AGENTS.base.md
CHANGED
|
@@ -12,6 +12,82 @@
|
|
|
12
12
|
- 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。
|
|
13
13
|
- commit 信息必须中文，禁止 `git push --force`。
|
|
14
14
|
|
|
15
|
+
## PR 提交、评审与合入规范
|
|
16
|
+
|
|
17
|
+
- PR 的目标是让审阅者在不依赖私下沟通的情况下独立理解、验证并放心 Approve；一个好的 PR 必须自解释。
|
|
18
|
+
- 一个 PR 只做一件事（One logical change per PR），必须是完整、独立、可审阅的逻辑改动，禁止把重构、修 bug、加功能混在同一个 PR。
|
|
19
|
+
- PR 应保持小而聚焦，尽量控制在约 200 行以内，超过 500 行应优先拆分；小 PR 审得快、回滚风险低、`git bisect` 定位更精准。
|
|
20
|
+
- 大改动必须拆成 Stacked PRs（例如 PR1 → PR2 → PR3），每个 PR 都要能独立 review、独立合入；底层先合，上层后合。
|
|
21
|
+
- 每个 PR 必须能独立通过编译与测试，禁止出现“这个 PR 编译不过，要等下一个 PR 才能跑”的状态；每一层都应是绿色可发布状态。
|
|
22
|
+
- PR Title 必须用祈使句、现在时态描述“做了什么”，建议加模块/组件前缀，保持简洁且一行说清。
|
|
23
|
+
- PR Title 示例：`[auth] Fix token refresh race condition on concurrent requests`、`[payments] Add idempotency key to charge API`、`[infra] Migrate cache layer from Redis 6 to Redis 7`。
|
|
24
|
+
- PR Title 禁止使用 `fix bug`、`update code`、`改了一下` 等无法表达实际改动的标题。
|
|
25
|
+
- PR Description 必须足够充分，至少回答 What（改了什么）、Why（为什么改，解决什么问题或满足什么需求）、How（采用什么方案，为什么选该方案）。
|
|
26
|
+
- 涉及行为变更、接口变更、数据迁移、性能影响时，必须在 Description 中显式写出。
|
|
27
|
+
- 有意不做的事、已知局限、后续 follow-up 必须写清楚，避免 reviewer 重复追问。
|
|
28
|
+
- 关联 issue 必须在 PR 中链接，并优先使用 GitHub 关键字自动关闭，例如 `Closes #123`、`Fixes #123`。
|
|
29
|
+
- Description 推荐模板：
|
|
30
|
+
|
|
31
|
+
```markdown
|
|
32
|
+
## Description
|
|
33
|
+
背景：当前在并发刷新 token 时存在竞态，会导致少量请求拿到过期 token 被拒。
|
|
34
|
+
|
|
35
|
+
改动：给 token 刷新加分布式锁，保证同一时刻只有一个刷新在飞，其余请求等待复用结果。
|
|
36
|
+
|
|
37
|
+
方案取舍：考虑过乐观重试，但在高并发下重试风暴更糟，故选锁方案。锁超时 2s 兜底。
|
|
38
|
+
|
|
39
|
+
不在本 PR 范围：监控告警接入留作后续 follow-up（#457）。
|
|
40
|
+
|
|
41
|
+
Closes #456
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
- Test Plan 是硬性必填项，没有 Test Plan 的 PR 不允许进入审阅，建议写进 `.github/PULL_REQUEST_TEMPLATE.md` 固定章节。
|
|
45
|
+
- Test Plan 必须说明如何验证改动正确，并提供可复现步骤或证据，包括自动化测试命令与结果、手动验证步骤、截图、录屏、日志输出、请求响应、修复前后对比等。
|
|
46
|
+
- UI 改动必须贴前后对比截图；接口改动必须贴请求响应；修 bug 必须贴复现前与修复后的对比。
|
|
47
|
+
- Test Plan 必须覆盖必要边界情况，例如并发、异常、空值、回滚路径等。
|
|
48
|
+
- 禁止只写 `tested locally`、`测了没问题`；能用文字日志说明的，也要贴日志原文。
|
|
49
|
+
- Test Plan 推荐模板：
|
|
50
|
+
|
|
51
|
+
```markdown
|
|
52
|
+
## Test Plan
|
|
53
|
+
1. 单元测试：
|
|
54
|
+
$ npm test -- auth/token/
|
|
55
|
+
-> 全部通过（截图见下）
|
|
56
|
+
|
|
57
|
+
2. 手动复现原 bug：
|
|
58
|
+
- 开 50 并发同时调 /refresh
|
|
59
|
+
- 修复前：约 3% 请求返回 401（日志附后）
|
|
60
|
+
- 修复后：0 失败（截图：dashboard 401 曲线归零）
|
|
61
|
+
|
|
62
|
+
3. 回滚验证：关闭 feature flag 后行为回到旧逻辑，正常。
|
|
63
|
+
|
|
64
|
+
[截图1：测试通过结果]
|
|
65
|
+
[截图2：修复前后 401 曲线对比]
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
- 每个 PR 至少需要一名 reviewer Approve 才能合入，建议用 Branch protection 强制 `Require a pull request before merging` 和至少 1 个 Approval。
|
|
69
|
+
- Reviewer 优先指定最熟悉对应模块的 owner，并通过 `CODEOWNERS` 自动请求对应 owner 审阅。
|
|
70
|
+
- 涉及多模块时，每个模块都要指定对应 reviewer。
|
|
71
|
+
- 高风险改动（安全、支付、数据迁移、对外接口）必须通过 `CODEOWNERS` 设置 Required review，由对应 owner 通过后才能合入。
|
|
72
|
+
- 作者不能 Approve 自己的 PR。
|
|
73
|
+
- PR 其他元数据必须完整：Assignees 填负责人，Labels 填类型/优先级/模块，Linked Issues/Projects 关联需求来源与项目看板，Milestone 按需关联发布里程碑。
|
|
74
|
+
- 尚未准备好审阅时必须先开 Draft PR，准备好后再标记 `Ready for review`。
|
|
75
|
+
- 作者提交审阅前必须完成自查：PR 只做一件事；没有夹带格式化、顺手改动等无关改动；Title 清晰；Description 写明 What/Why/How；Test Plan 完整且带证据；已自审 `Files changed`；已移除调试代码、注释代码和无效 TODO；没有泄露密钥、token、内部地址、PII 等敏感信息；已指定合适 reviewer；已关联 issue；本地编译、lint、测试通过；CI status checks 全绿。
|
|
76
|
+
- 满足以下全部条件才允许 Merge：至少一名 reviewer 已 Approve；`CODEOWNERS` required review（如有）已通过；所有 required status checks（构建、单测、lint、静态分析等）全部绿色；所有 review 评论和 `Request changes` 均已解决并 Resolve conversation；分支与目标分支无冲突且已更新到最新；Stacked PR 的所有底层依赖已先行合入。
|
|
77
|
+
- 建议开启 Branch protection 强制合入门禁，并开启 `Require branches to be up to date`。
|
|
78
|
+
- 团队应统一 Merge 方式，多数情况用 `Squash and merge` 保持主干历史干净；需要保留完整提交历史时再用 merge commit。
|
|
79
|
+
- Reviewer 收到 review 请求后应尽量在 1 个工作日内给出首次反馈。
|
|
80
|
+
- Reviewer 必须看懂再 Approve；看不懂就提问，禁止为了快而盲目 Approve。
|
|
81
|
+
- Reviewer 反馈必须区分等级：必须改用 `Request changes`，建议项标注 `nit:` 或 `optional:`，疑问标注 `question:`，避免作者误判优先级。
|
|
82
|
+
- Review 评论必须对事不对人，针对代码与方案并保持尊重。
|
|
83
|
+
- Reviewer Approve 即代表认可该改动可以上线，并对该判断负责。
|
|
84
|
+
- 作者必须回复每一条 review 评论，即使只是 `Done` 或解释为何不改，并 Resolve 对应 conversation。
|
|
85
|
+
- 有分歧时优先在 PR 上公开讨论，结论必须写回 PR，避免私聊后无记录。
|
|
86
|
+
- 较大方案分歧可以升级为线下或会议讨论，但最终结论必须回写到 PR。
|
|
87
|
+
- 改动后必须使用 `Re-request review` 重新请求审阅，并在评论里简述本次更新改了什么。
|
|
88
|
+
- 必须避免以下反模式：Test Plan 只写“测了没问题”；一个 PR 改 2000 行且跨多个模块；Description 只有“fix bug”；CI 红着或跳过检查直接合；把格式化/重命名和逻辑改动混在一起；评论不回复、不 Resolve 就直接重提 review。
|
|
89
|
+
- PR 规范可按团队约定微调字段，但“充分的 Description + 带证据的 Test Plan + 至少一人 Approve + 状态检查全绿才能 Merge”是不可妥协的核心要求。
|
|
90
|
+
|
|
15
91
|
## 安全
|
|
16
92
|
|
|
17
93
|
- 用户明确要求上线/部署生产环境时，直接执行，无需二次确认。
|
package/CHANGELOG.md
CHANGED