@wneng/create-keel 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wneng/create-keel",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Scaffolder for Contract First + Vibe Coding projects (keel conventions)",
   "keywords": [
     "scaffold",

package/src/templates/ci-gitee/files/PULL_REQUEST_TEMPLATE.md

@@ -18,13 +18,26 @@
 - [ ] **Tier 4** architecture / breaking — 跨服务 / 鉴权变化 / 删字段。已附 ADR + 详细设计 + 迁移 / 回滚预案
 - [ ] **Tier 5** spike — 探索性改动。分支为 `spike/*`，**不会**合入 `main`（合入需重新走 Tier 1-4）
 
+## 文档投入（Doc Weight）
+
+> 与 Tier 正交。AI 推荐默认值，作者可覆盖。详见 `docs/governance/change-tiers.md` §3。
+>
+> **AI 推荐**：Tier 0/1/2/3 默认 lite；Tier 4 默认 standard；Tier 5 默认 lite。**勾选一项**。
+
+- [ ] **lite** — PR 描述自身即文档（含动机 / 方案 / 影响面）。Tier 3 时还要契约 diff + CHANGELOG + 锚点；Tier 4 时还要 ADR
+- [ ] **standard** — lite 之上 + 简短 04 / 05 设计（每份 2-3 段）；Tier 4 时还要迁移 / 回滚预案
+- [ ] **full** — standard 之上 + PRD（`docs/01/prd-<slug>.md`）；如涉及前端还要 UI 稿
+
+> **关键**：Tier 3（加 API / 字段）默认 lite——契约 diff 本身就是设计真值。仅在业务复杂度高（多状态机、跨服务、跨团队）时才升 standard / full；reviewer **不应**仅因"没写设计文档"而打回 Tier 3 + lite 的 PR。
+
 ## 关联引用
 
-<!-- Tier 0/1/2 可省略；Tier 3+ 必须填 -->
+<!-- Tier 0/1/2 可省略；Tier 3+ 必须填契约锚点；standard / full 还要填 04/05/PRD -->
 
 - 契约锚点：`contracts/openapi/api.yaml#/paths/...` 或 `contracts/events/event-catalog.yaml#/events/...`
-- 设计文档：`docs/04-后端详细设计/<slug>.md` 或 `docs/05-前端客户端详细设计/<slug>-<platform>.md`
+- 设计文档（standard / full 时填）：`docs/04-后端详细设计/<slug>.md` 或 `docs/05-前端客户端详细设计/<slug>-<platform>.md`
 - ADR（Tier 4 必填）：`docs/02-系统方案与架构/adr-<NNNN>-<slug>.md`
+- PRD（full 时填）：`docs/01-背景与需求/prd-<slug>.md`
 - spec：`.kiro/specs/<feature>/`（如适用）
 
 ## 变更类型

package/src/templates/ci-github/files/PULL_REQUEST_TEMPLATE.md

@@ -18,13 +18,26 @@
 - [ ] **Tier 4** architecture / breaking — 跨服务 / 鉴权变化 / 删字段。已附 ADR + 详细设计 + 迁移 / 回滚预案
 - [ ] **Tier 5** spike — 探索性改动。分支为 `spike/*`，**不会**合入 `main`（合入需重新走 Tier 1-4）
 
+## 文档投入（Doc Weight）
+
+> 与 Tier 正交。AI 推荐默认值，作者可覆盖。详见 `docs/governance/change-tiers.md` §3。
+>
+> **AI 推荐**：Tier 0/1/2/3 默认 lite；Tier 4 默认 standard；Tier 5 默认 lite。**勾选一项**。
+
+- [ ] **lite** — PR 描述自身即文档（含动机 / 方案 / 影响面）。Tier 3 时还要契约 diff + CHANGELOG + 锚点；Tier 4 时还要 ADR
+- [ ] **standard** — lite 之上 + 简短 04 / 05 设计（每份 2-3 段）；Tier 4 时还要迁移 / 回滚预案
+- [ ] **full** — standard 之上 + PRD（`docs/01/prd-<slug>.md`）；如涉及前端还要 UI 稿
+
+> **关键**：Tier 3（加 API / 字段）默认 lite——契约 diff 本身就是设计真值。仅在业务复杂度高（多状态机、跨服务、跨团队）时才升 standard / full；reviewer **不应**仅因"没写设计文档"而打回 Tier 3 + lite 的 PR。
+
 ## 关联引用
 
-<!-- Tier 0/1/2 可省略；Tier 3+ 必须填 -->
+<!-- Tier 0/1/2 可省略；Tier 3+ 必须填契约锚点；standard / full 还要填 04/05/PRD -->
 
 - 契约锚点：`contracts/openapi/api.yaml#/paths/...` 或 `contracts/events/event-catalog.yaml#/events/...`
-- 设计文档：`docs/04-后端详细设计/<slug>.md` 或 `docs/05-前端客户端详细设计/<slug>-<platform>.md`
+- 设计文档（standard / full 时填）：`docs/04-后端详细设计/<slug>.md` 或 `docs/05-前端客户端详细设计/<slug>-<platform>.md`
 - ADR（Tier 4 必填）：`docs/02-系统方案与架构/adr-<NNNN>-<slug>.md`
+- PRD（full 时填）：`docs/01-背景与需求/prd-<slug>.md`
 - spec：`.kiro/specs/<feature>/`（如适用）
 
 ## 变更类型

package/src/templates/docs-skeleton/files/governance-change-tiers.md

@@ -1,133 +1,192 @@
 ---
-last-reviewed: 2026-05-16
+last-reviewed: 2026-05-17
 ---
 
 # 变更分级（Change Tiers）
 
 > AGENTS.md §6 的细则。澄清"先文档先契约再 code"在不同场景下应该有多厚。
 
-## 0. 为什么需要分级
+## 0. 两件正交的事，不要绑死
 
-`AGENTS.md` §2 的"Contract First"和 §6 的"先补契约和文档，再补实现"在小改动场景下容易被 AI 过度解读。常见误读：
+`AGENTS.md` §2 的 Contract First 与 §6 的"变更分级"要拆成**两件独立的事**：
 
-- 改一个 typo → 想去补 PRD
-- 修一个不涉及 API 的 bug → 想去更新 OpenAPI
-- 加一行配置 → 想去写 ADR
+| 维度 | 是什么 | 谁定 |
+|---|---|---|
+| **Tier**（变更影响面） | 改动客观属性：动了哪些层、是否破坏性、有几个团队耦合 | AI 按决策树自动判定 |
+| **Doc Weight**（文档投入） | 团队 / 项目 / 这次 PR 想花多少笔墨在 markdown 上 | AI 给默认建议；PR 作者最终决定 |
 
-这浪费时间、噪声 PR、让团队反感框架本身。
+它们是 **and**，不是 **=**。
 
-**正确的理解**：
-- **A. 方案讨论必须有书面结论**（载体可大可小）—— 总成立
-- **B. 契约必须在 code 之前冻结**—— 仅当变更触及契约时成立
+20 人银行项目和 2 人工具型 startup 改同一个 API 字段，Tier 都是 3，但前者会写后端设计 + 前端联动说明（Doc Weight = standard），后者只在 PR 描述里写一段（Doc Weight = lite）。框架不强行统一两者。
 
-A + B 不是绑死的。改一个不动 API 的 bug，B 不触发；改一个 typo，A 也只需要 PR title + 一行描述。
+## 1. 六档 Tier（变更影响面）
 
-## 1. 六档 Tier
+| Tier | 名称 | 典型场景 | 是否动契约 |
+|---|---|---|---|
+| **0** | trivial | 拼写、注释、格式化、补测试、依赖 patch 升级 | 不动 |
+| **1** | bugfix | 修 NPE、错误的 SQL、UI 显示错位（无新行为，行为符合既有契约） | 不动 |
+| **2** | small change | 加按钮 / 排序 / 导出列、调文案、加配置项 | 通常不动 |
+| **3** | contract change | 加 API / 字段 / 错误码 / 事件 / 状态（兼容新增） | **必须**先冻结契约 + CHANGELOG |
+| **4** | architecture / breaking | 跨服务、鉴权变化、删字段、改类型、新依赖、数据迁移 | **必须** ADR + 契约 + 迁移说明 |
+| **5** | spike | 探索性、方案未明 | 在 `spike/*` 分支自由探索；合入 `main` 前补到对应 tier |
 
-| Tier | 名称 | 典型场景 | A：方案记录的最小载体 | B：是否动契约 |
-|---|---|---|---|---|
-| **0** | trivial | 拼写、注释、格式化、补测试、依赖 patch 升级 | PR title + 1-2 行描述 | 不动 |
-| **1** | bugfix | 修 NPE、错误的 SQL、UI 显示错位（无新行为） | PR 描述：**重现 + 根因 + 修复点 + 回归测试** | 不动 |
-| **2** | small change | 加按钮 / 排序 / 导出列、调文案、加配置项 | PR 描述（含动机 + 方案 + 影响面），或 1 页 markdown 进 `docs/过程文档/drafts/` | 通常不动 |
-| **3** | contract change | 加 API / 字段 / 错误码 / 事件 / 状态 | 简短设计章节（写在 `docs/04` 或 `docs/05` 的对应模块里）+ contracts 更新 + CHANGELOG | **必须**先冻结契约 |
-| **4** | architecture / breaking | 新模块、跨服务、数据迁移、鉴权模型变化、删除字段 | PRD（若来自需求）→ ADR → 详细设计 → 契约 → code | **必须** ADR + 契约 + 迁移说明 |
-| **5** | spike | 探索性、方案未明 | 在 `spike/*` 分支自由探索 | 合入 `main` 前补齐到对应 tier |
+## 2. Tier 判定决策树
 
-## 2. 判定决策树
+按从严到宽问自己：
 
-按从严到宽顺序问自己：
+1. 改了 `contracts/` 任何文件？ → 至少 **Tier 3**
+2. 改动会改变 API / DB schema / 事件 / 鉴权 / 安全语义？（即使现在 contracts 还没收录） → **Tier 3 或 4**，先补契约再继续
+3. 删除或不兼容地修改了已有契约字段？ → **Tier 4** 必须 ADR
+4. 跨服务、跨模块边界、跨执行环境（server↔web↔mobile）？ → **Tier 4**
+5. 影响 ops/ 或 deploy/ 实际拓扑（新加 service / 新开端口 / 改加密策略）？ → **Tier 4**
+6. 探索 / 调研，方案不清楚？ → **Tier 5**（`spike/*` 分支）
+7. 以上都不是，纯局部、可逆的改动？ → 按体量定 **Tier 0/1/2**
 
-1. **改动改了 `contracts/` 任何文件？** → 至少 Tier 3
-2. **改动会改变 API / DB schema / 事件 / 鉴权 / 安全语义？**（即使现在 contracts 还没收录）→ Tier 3 或 4，**先把契约补上再继续**
-3. **删除或不兼容地修改了已有契约字段？** → Tier 4，**必须** ADR
-4. **跨服务、跨模块边界、跨执行环境（server↔web↔mobile）？** → Tier 4
-5. **会影响 ops/ 或 deploy/ 实际拓扑（新加一个 service / 新开一个端口 / 改加密策略）？** → Tier 4
-6. **是探索 / 调研，方案还不清楚？** → Tier 5（用 `spike/*` 分支）
-7. **以上都不是，纯局部、可逆的改动？** → 按体量定 Tier 0/1/2
+## 3. 三档 Doc Weight（文档投入）
 
-## 3. 反例（避免过度反应）
+> **默认值**：每个 Tier 的"AI 推荐 doc weight"如下，PR 作者可在 PR 模板里覆盖。
 
-下面这些情况 **不要** 升级 tier：
+| Tier | AI 默认推荐 | lite 时只要 | standard 时再加 | full 时再加 |
+|---|---|---|---|---|
+| **0** trivial | **lite**（除非异常） | PR 描述 1-2 行 | — | — |
+| **1** bugfix | **lite** | PR 描述：重现 + 根因 + 修复 + 回归测试 | — | — |
+| **2** small change | **lite** | PR 描述：动机 + 方案 + 影响面 | 1 页 markdown 进 `docs/过程文档/drafts/` | — |
+| **3** contract change | **lite**（关键！） | PR 描述 + 契约 diff + CHANGELOG + 契约锚点 | 简短后端 / 前端设计章节进 `docs/04` 或 `docs/05`，每份 2-3 段 | + PRD（`docs/01/prd-<slug>.md`） |
+| **4** arch / breaking | **standard** | PR 描述 + 契约 diff + CHANGELOG + ADR | 简化 04 / 05 详细设计 + 迁移 / 回滚预案 | + PRD + UI 设计稿（如涉及前端） |
+| **5** spike | **lite**（探索期不需要文档） | spike 分支自由实验；合入 `main` 时按目标 tier 补齐 | — | — |
 
-| 情形 | 正确 tier | 错误反应 |
-|---|---|---|
-| 修 `web/src/utils/format-date.ts` 的 typo 注释 | 0 | 写 PRD |
-| `GET /users/{id}` 的实现里漏判 null，500 改 404 | 1（行为符合契约） | 改 OpenAPI |
-| 给已有列表加"最近 7 天"筛选选项（前端筛选，后端无变化） | 2 | 写 ADR |
-| `package.json` 里 `lodash 4.17.20 → 4.17.21`（patch） | 0 | 走完整升级流程 |
-| 改 README 一段错别字 | 0 | 同步多份治理文件 |
-| 重构一个内部 helper 函数（不导出） | 0 或 1 | 写详细设计 |
-| 加测试覆盖既有功能 | 0 | 写 PRD |
+**关键修正**（相对 0.4.0）：**Tier 3 默认 doc weight 是 lite，不是 standard**。理由：契约 diff 本身就是设计真值；额外的中文设计文档反而和契约漂移。只在业务复杂度高到契约说不清时（复杂状态机、多模块交互、跨团队协作），作者主动升 standard / full。
 
-下面这些情况 **必须** 升级 tier：
+### 3.1 lite 的最小载体
 
-| 情形 | 正确 tier | 误判风险 |
-|---|---|---|
-| 给 `GET /users/{id}` 加返回字段 `lastLoginAt` | 3 | 想成 Tier 2 / 文档"顺手补" |
-| 给已有 List API 加 `?status=` 查询参数 | 3 | 想成 Tier 2 |
-| 把鉴权从 cookie 改为 Bearer token | 4 | 想成 Tier 3 |
-| 把 RBAC 从扁平改为支持继承 | 4 | 想成 Tier 3 |
-| 引入新的消息队列 / 缓存层 / 第三方支付 | 4 | 想成 Tier 3 |
-| 删除 `User.email` 字段 | 4 | 想成 Tier 3（删除 ≠ 兼容新增） |
-| 升级 Spring Boot major 版本（3.x → 4.x） | 4 | 想成 Tier 0（只是版本号） |
+**lite ≠ 没文档**。PR 描述本身就是文档；契约本身就是真值。lite 只是不再要求**额外的 markdown 文件**。
 
-## 4. PR 模板里的 Tier 框
+PR 描述至少包含：
 
-PR 模板顶部要求作者明示 tier。Reviewer 第一眼看到 tier 后：
+- **What**：改了什么
+- **Why**：为什么（业务动机 / 用户痛点 / 技术债）
+- **影响面**：哪些路径 / 服务 / 团队会被影响
+- 如有契约 diff：契约锚点（`contracts/openapi/api.yaml#/paths/~1users/post`）
+- 如是 Tier 1 bugfix：重现步骤 + 根因 + 修复点 + 回归测试
 
-- **Tier 0/1/2**：着重看代码 / 测试 / 描述完整性，不要求 ADR / 契约改动
-- **Tier 3**：必须看到 contracts 同步、CHANGELOG 同步、契约锚点引用
-- **Tier 4**：必须看到 ADR 存在或新增、详细设计文档、迁移 / 回滚预案
-- **Tier 5**：分支必须是 `spike/*`；如果想合入 `main`，作者必须在合入 PR 中标明落地到了哪个 tier
+### 3.2 何时升 standard / full
 
-CI 不强制校验 tier 标签（语义判定是 reviewer 的责任）；但 CI **会**校验：
+AI 在以下信号下**主动建议**升级 doc weight，并在 PR 描述里写一句理由：
 
-- 改了 `contracts/` 的 PR 必须同改 `contracts/CHANGELOG.md`（已有规则）
-- `spike/*` 分支不能直接合入 `main`（PR 模板 + CODEOWNERS）
+| 信号 | 建议 |
+|---|---|
+| 契约 diff > 5 个 endpoint / schema 变化 | standard |
+| 引入新状态机或改既有状态机的状态数 | standard |
+| 跨服务联动（server 改 + web 改 + 第三方 webhook 改） | standard |
+| 删字段 / 改类型 / 改鉴权（即 Tier 4） | standard 或 full |
+| 业务规则复杂到契约的 description 字段写不下 | standard |
+| 来源是产品同学的需求文档（PRD 是上游产物） | full（PRD 落到 `docs/01/`） |
+| 跨多团队 / 多季度的项目 | full |
+
+PR 作者也可主动**降级**：如果 AI 推荐 standard 但作者认为契约自身已说清楚，可以 lite 通过；reviewer 不应仅因"没写设计文档"而打回。
+
+## 4. 反例
+
+下面这些情况 **不要** 升级 tier 或 doc weight：
+
+| 情形 | 正确 Tier | 推荐 Doc Weight | 错误反应 |
+|---|---|---|---|
+| 修 `web/src/utils/format-date.ts` 的 typo 注释 | 0 | lite | 写 PRD |
+| `GET /users/{id}` 实现里漏判 null，500 改 404 | 1 | lite | 改 OpenAPI |
+| 加"最近 7 天"前端筛选选项（后端无变化） | 2 | lite | 写 ADR |
+| `lodash 4.17.20 → 4.17.21`（patch） | 0 | lite | 走完整升级流程 |
+| 改 README 错别字 | 0 | lite | 同步多份治理文件 |
+| 重构一个内部 helper 函数（不导出） | 0 或 1 | lite | 写详细设计 |
+| 加测试覆盖既有功能 | 0 | lite | 写 PRD |
+| **给 `GET /users/{id}` 加返回字段 `lastLoginAt`**（兼容新增） | **3** | **lite**（只改契约 + CHANGELOG） | 想成必须写 04 后端设计 |
+| **给已有 List API 加 `?status=` 查询参数** | **3** | **lite** | 想成 Tier 2 / 必须写 PRD |
+
+下面这些情况 **必须** 升级 tier：
 
-## 5. AI 在 PR 描述中的引用义务
+| 情形 | 正确 Tier | 推荐 Doc Weight |
+|---|---|---|
+| 把鉴权从 cookie 改为 Bearer token | 4 | standard 或 full |
+| 把 RBAC 从扁平改为支持继承 | 4 | full（PRD + ADR + 详细设计） |
+| 引入新消息队列 / 缓存层 / 第三方支付 | 4 | full |
+| 删除 `User.email` 字段 | 4 | standard（迁移预案 + ADR） |
+| 升级 Spring Boot major 版本（3.x → 4.x） | 4 | standard（兼容性扫描 + 测试矩阵） |
+
+## 5. PR 模板里的两个框
+
+PR 作者填两件事：
+
+```
+## Tier（影响面，AI 自动判）
+- [ ] 0 trivial
+- [ ] 1 bugfix
+- [x] 2 small change   ← AI 建议
+- [ ] 3 contract change
+- [ ] 4 architecture / breaking
+- [ ] 5 spike
+
+## Doc Weight（文档投入，AI 推荐 + 作者覆盖）
+- [x] lite      ← AI 推荐：PR 描述足够，不需额外文档
+- [ ] standard
+- [ ] full
+```
+
+Reviewer 看到 Tier + Doc Weight 后：
+
+- **Tier 0/1/2 + lite**：着重看代码 / 测试 / 描述完整性
+- **Tier 3 + lite**：看契约 diff + CHANGELOG + 契约锚点；不要求 04/05 markdown
+- **Tier 3 + standard**：以上 + 简短后端 / 前端设计章节（2-3 段就够）
+- **Tier 3 + full**：以上 + PRD（如有产品需求来源）
+- **Tier 4 + standard**：必须 ADR + 详细设计 + 迁移预案
+- **Tier 4 + full**：以上 + PRD + UI 稿（如涉及）
+
+CI 不强制 doc weight 与 tier 的对应关系（reviewer 责任）；但 CI **会**校验：
+
+- 改了 `contracts/` 必须同改 `contracts/CHANGELOG.md`（已有规则）
+- `spike/*` 分支不能直接合入 `main`（PR 模板 + CODEOWNERS）
 
-按 tier 升级：
+## 6. AI 引用义务（按 Tier，doc weight 无关）
 
 | Tier | 引用义务 |
 |---|---|
-| 0/1/2 | 不强制；PR 描述本身就是方案记录 |
-| 3 | 必须引用契约锚点（如 `contracts/openapi/api.yaml#/paths/~1users/post`） |
-| 4 | 必须引用 ADR / 详细设计文档；契约锚点也必须 |
-| 5 | 必须标明 spike 分支与最终目标 tier |
+| 0/1/2 | 不强制 |
+| 3 | 必须引用契约锚点（lite 也要） |
+| 4 | 必须引用 ADR + 契约锚点；详细设计在 standard / full 时引用 |
+| 5 | 必须标明 spike 分支与目标 tier |
 
-AI 不要在 Tier 0/1/2 主动制造文档噪音；reviewer 也不要因"AI 没引用契约"而打回 Tier 0/1/2 的 PR。
+AI 在 Tier 0/1/2 不要主动制造文档噪音；reviewer 不要因"AI 没引用契约"打回 Tier 0/1/2 的 PR。
 
-## 6. 与 spike 的关系
+## 7. 与 spike 的关系
 
-`spike/*` 分支是 Tier 5 的载体。它允许 AI 与开发者**暂时**绕过 Contract First：
+`spike/*` 分支是 Tier 5 的载体，**doc weight 默认 lite**：
 
 1. 创建 `spike/<topic>` 分支
 2. 自由写代码、跑实验、改方向
 3. 结论清楚后：
    - 不采纳 → 文档进 `docs/过程文档/spike-investigations/`，分支保留备查
-   - 采纳 → 反向走完 Tier 1-4 该补的内容（PRD / ADR / 详细设计 / 契约），再合入 `main`
+   - 采纳 → 反向按目标 Tier 与 Doc Weight 补齐对应内容，再合入 `main`
 
-Spike 不是"绕过框架的永久后门"。`spike/*` 不能直接合入 `main`；合入 PR 必须用 `feat(...)` / `feat(ai)(...)` 等正式 type 重写。
+Spike 不是"绕过框架的永久后门"。`spike/*` 不能直接合入 `main`。
 
-## 7. 何时升级 / 降级
+## 8. 何时升级 / 降级
 
-升级（向上）：开发过程中发现影响面比预想大 → 立即升 tier，停下补对应文档 / 契约。
+**Tier 升级**：开发过程中发现影响面比预想大 → 立即升 tier，停下补对应契约 / 文档。  
+**Tier 降级**：通常**不允许**。一旦你声明 Tier 3+ 并写了契约 / ADR / 设计，就保留它（除非改动被裁掉变成 Tier 2）。
 
-降级（向下）：通常**不允许**。一旦你声明 Tier 3+ 并写了契约 / ADR / 设计，就保留它。降级只在明确的"改动被裁掉了"场景下成立（例如：本来要加一个字段，最后发现可以用既有字段实现），此时把 tier 改成实际生效的层级，并在 PR 描述里写明。
+**Doc Weight 升级**：欢迎随时升级（写更多文档不是错）。  
+**Doc Weight 降级**：作者可在 PR 评审中说明降级理由（"契约已自解释"），reviewer 同意即可。
 
-## 8. 与契约 SemVer 的关系
+## 9. 与契约 SemVer 的关系
 
 | Tier | 契约动作 | SemVer 影响 |
 |---|---|---|
 | 0/1/2 | 不动 | 无 |
 | 3（兼容新增） | `MINOR` bump | `0.x.y → 0.(x+1).0`（pre-1.0）/ `x.y.z → x.(y+1).0`（≥1.0） |
-| 3（破坏性，但还在 0.x） | `MINOR` bump + CHANGELOG 标 BREAKING | 同上（pre-1.0 允许） |
+| 3（破坏性，但 0.x） | `MINOR` bump + CHANGELOG 标 BREAKING | 同上（pre-1.0 允许） |
 | 4（破坏性，≥1.0） | `MAJOR` bump | `x.y.z → (x+1).0.0` |
 
 完整版本策略 → [`../../contracts/README.md`](../../contracts/README.md)。
 
-## 9. 关联文档
+## 10. 关联文档
 
 - [`../../AGENTS.md`](../../AGENTS.md) §6（变更分级摘要）
 - [`git-workflow.md`](git-workflow.md)（PR 模板与 CODEOWNERS 完整规则）

package/src/templates/root-files/files/AGENTS.md

@@ -140,31 +140,45 @@
 - 完整规则 → [`docs/governance/integrations.md`](docs/governance/integrations.md)
 <% } %>
 
-## 6. 核心协作规则（变更分级）
+## 6. 核心协作规则（变更分级 + 文档投入）
 
-变更分**六档**，文档与契约的"厚度"匹配影响面。完整判定决策树、反例、与 SemVer 关系 → [`docs/governance/change-tiers.md`](docs/governance/change-tiers.md)。
+变更走**两个独立维度**：**Tier**（影响面，AI 自动判）+ **Doc Weight**（文档投入，AI 推荐 + 作者覆盖）。完整判定决策树、反例、与 SemVer 关系 → [`docs/governance/change-tiers.md`](docs/governance/change-tiers.md)。
 
-| Tier | 典型 | 文档要求 | 契约动作 |
-|---|---|---|---|
-| 0 trivial | typo / 格式化 / patch 升级 / 补测试 | PR title + 1-2 行描述 | 不动 |
-| 1 bugfix | 修 NPE / SQL / UI 错位（无新行为） | PR 描述：重现 + 根因 + 修复 + 回归测试 | 不动 |
-| 2 small | 加按钮 / 排序 / 文案 / 配置项 | PR 描述（动机 + 方案 + 影响面） | 通常不动 |
-| 3 contract | 加 API / 字段 / 错误码 / 事件 / 状态 | 简短设计章节进 `docs/04` 或 `docs/05` | **必须**先冻结契约 + CHANGELOG |
-| 4 arch | 跨服务 / 鉴权变化 / 删字段 / breaking | PRD（如来自需求）→ ADR → 详细设计 → 契约 → code | **必须** ADR + 契约 + 迁移说明 |
-| 5 spike | 探索 / 方案未明 | `spike/*` 分支自由探索 | 合入 `main` 前补到对应 tier |
+**Tier（影响面）**
+
+| Tier | 典型 | 是否动契约 |
+|---|---|---|
+| 0 trivial | typo / 格式化 / patch 升级 / 补测试 | 不动 |
+| 1 bugfix | 修 NPE / SQL / UI 错位（无新行为） | 不动 |
+| 2 small | 加按钮 / 排序 / 文案 / 配置项 | 通常不动 |
+| 3 contract | 加 API / 字段 / 错误码 / 事件 / 状态 | **必须**先冻结契约 + CHANGELOG |
+| 4 arch | 跨服务 / 鉴权变化 / 删字段 / breaking | **必须** ADR + 契约 + 迁移说明 |
+| 5 spike | 探索 / 方案未明 | `spike/*` 分支自由探索；合入前补到对应 tier |
 
 **判定**：改 `contracts/` → 至少 Tier 3；改鉴权 / 跨服务 / 删字段 → Tier 4；纯局部 → 0/1/2；探索 → 5。
 
-**AI 引用义务**（按 tier 升级）：
-- Tier 0/1/2：PR 描述自身即方案记录，**不强制**引用契约或 ADR
-- Tier 3+：必须显式引用契约锚点（如 `contracts/openapi/api.yaml#/paths/~1users/post`）
-- Tier 4：必须引用 ADR / 详细设计文档
+**Doc Weight（文档投入，AI 推荐 + 作者覆盖）**
+
+| Tier | AI 默认推荐 | lite 时 | standard 加 | full 加 |
+|---|---|---|---|---|
+| 0/1/2 | **lite** | PR 描述（含动机 / 方案 / 影响面） | — | — |
+| 3 contract | **lite**（关键） | PR 描述 + 契约 diff + CHANGELOG + 锚点 | 简短 04 / 05 设计（2-3 段） | + PRD（`docs/01/prd-<slug>.md`） |
+| 4 arch | **standard** | PR 描述 + 契约 + ADR | 简化 04 / 05 + 迁移 / 回滚预案 | + PRD + UI 稿 |
+| 5 spike | **lite** | spike 分支自由实验 | — | — |
+
+> **关键**：Tier 3 的默认 doc weight 是 **lite**——契约 diff 本身就是设计真值，额外的中文设计文档反而易和契约漂移。复杂度高时（多状态机、跨服务、跨团队）作者主动升 standard / full。
+
+**AI 引用义务**（按 Tier，与 Doc Weight 无关）：
+- Tier 0/1/2：PR 描述自身即方案记录，**不强制**引用契约 / ADR
+- Tier 3+：commit / PR 必须显式引用契约锚点（如 `contracts/openapi/api.yaml#/paths/~1users/post`）
+- Tier 4：必须引用 ADR；详细设计在 standard / full 时引用
 
 其他：
-- `spike/*` 分支允许暂时跳过契约（即 Tier 5）；合入 `main` 前必须补齐到对应 tier
+- `spike/*` 分支允许暂时跳过契约（即 Tier 5）；合入 `main` 前必须补到对应 tier
 - 完整 PR 模板与 CODEOWNERS → [`docs/governance/git-workflow.md`](docs/governance/git-workflow.md)
 - 契约 SemVer / CHANGELOG / 废弃流程 → [`contracts/README.md`](contracts/README.md)
 
+
 ## 7. 按需加载索引
 
 ### 7.1 路径触发表