# AI × GitHub 协作工作流（可移植启动材料）

把这份文件放进新工作区，作为 AI 的默认上下文。它沉淀的是**思考原则 + 一条够用的 Issue/PR 链**，不是某个产品仓库的现行规章。

对照 GitHub 开源协作：Issue 管「为什么/做到什么算完」，PR 管「改了什么」，Maintainer 管合并与发布，Contributor 不管生产按钮。下面用同一套角色说话，不绑定项目专有名词。

---

## 0. 角色（开源映射）

| 角色 | 开源习惯 | 做什么 | 不做什么 |
|---|---|---|---|
| **维护者 / 主控** | Maintainer / Triage | 拆需求、写/改 Issue、拍板范围、派活、关单、汇总状态 | 默认不改业务代码、不 merge、不点生产发布 |
| **执行者** | Contributor | 一个 Issue → 一个分支 → 本地验证 → Draft PR | 不自行 Ready/merge/部署/发版 |
| **收尾者** | Release steward / CODEOWNER | CI、可合并性、merge、环境回填、分支清理 | 不扩需求、不顺手改产品方案 |
| **用户 / 所有者** | Project owner | 产品方向、优先级、**生产发布授权** | — |

一人多角可以，但**同一条决策不要既当 Contributor 又偷偷发生产**。

---

## 1. Issue 是什么

Issue 不是待办便签。它同时是：

1. **产品记忆**：聊过、定过、踩过的坑留在 GitHub，不留在某次对话。
2. **执行契约**：范围、不做清单、验收标准，执行者只读这一份就能动手。
3. **验证台账**：本地 / 测试 / 生产分别验证过什么。

聊天用来拍板；拍完写进 Issue。没写进 Issue 的结论，下一轮 AI 当它不存在。

**两类 Issue，不要混：**

- **归档 / Epic**（索引）：模块「现在怎样」。长期 OPEN。不绑一个 commit 关闭。
- **执行单**：能被一个人在一个 PR 里做完。有验收就能关。

开源习惯：Discussion/Epic 管方向，Issue 管可交付；不要用 Epic 当 sprint 任务。

---

## 2. 默认链路（从开源 PR 流程压出来的最小集）

```
聊天拍板 → Issue（或更新已有单）
        → 独立分支（不要占用 main checkout）
        → 最小完整改动 + 本地验证
        → Draft PR（Closes / Refs 关联）
        → CI 绿
        → 维护者 Review → Ready → merge 到 main
        → 测试环境验证（需要账号态的，用固定测试号）
        → 用户明确授权后才生产发布
        → Issue / PR / Release 回填
        → 清理短命分支
```

铁律：

- **一个执行 Issue，一个分支，一个 PR。** 并行 Issue 用并行分支，不要共占用一份工作区改来改去。
- 执行者停在 **Draft PR**。Corrective 从最新 `main` **新开分支和新 PR**，禁止在已交接的冻结 head 上继续推。
- `main` 是唯一长期开发线。测试/生产是部署目标，不是长期 Git 分支。
- **生产必须用户明说「发布」**。合并、关 Issue、测试过、收尾台正在处理，都不是生产授权。
- 关联：做完并应关单用 `Closes #N`；索引/审计/不应自动关用 `Refs #N`。

测试环境若是**共享、后部署覆盖先部署**的，复测前先核「现在驻留的是哪次 commit」。多 PR 要一起验收，由维护者做临时 integration 分支一次部署，执行者不许抢环境、不许取消别人的部署队列。

---

## 3. 什么时候必须开 Issue

要动仓库（代码、配置、CI、部署、目录、非平凡文档）→ 先有 Issue。  
只读解释、问答、不改仓库 → 不必开。

开新单前先搜 open / 最近 closed，避免重复。相近就更新旧单；范围或验收不同再新开，并互相链接。

同一执行 Issue 同时只允许一个执行者、一个分支、一个 PR。已有远端分支或 open PR 时，后来者先在 Issue 上声明接手，等交接再动。

---

## 4. AI 思考原则（比流程更重要）

新工作区的 AI **先用这些想，再用流程做**。前半是编码姿态（卡帕西式），后半是 Issue/关单判断（本轮台账踩坑）。

### 4.0 卡帕西式编码姿态

写代码、改代码时默认遵守这四条。和「最小完整改动」「执行者不扩需求」是同一件事。

1. **编码前思考**  
   不要默默假设或把困惑藏起来。先用几句话简述你的理解和假设；有歧义就列出不同解释和关键权衡；发现明显更简单的做法要主动提出；确实不清楚就先问，不要猜着写。

2. **简洁优先**  
   只写解决**当前问题**所需的最少代码。不增加未要求的功能、一次性抽象、预想式灵活性、或为不可能场景准备的防御逻辑。能用 50 行就不要写 200 行。

3. **精准修改**  
   只改必须改的内容，并匹配周围已有风格。不顺手重构、格式化或清理相邻代码；只清理由**本次改动产生的**废代码。每一行 diff 都应能追溯到用户请求或 Issue 验收项。

4. **目标驱动**  
   先把任务转成可验证的成功标准。多步骤用「步骤 → 验证」短计划推进；根据测试和报错循环修正，直到目标达成，或明确说出阻塞（缺权限、缺拍板、环境不对），而不是用更多代码绕过去。

### 4.1 证据看代码和用户效果，不看故事

- 用户说「不是已经做了吗」时，**先对照 `main`（或生产驻留 commit）**，再发表关单意见。
- Release notes 写了 ≠ Issue 验收闭环。Notes 是发布说明，Issue 是契约。
- 旧 Issue 原文没逐条落地 ≠ 一定还要做。后面的方案完全可以更好，也完全可以故意不一致。

### 4.2 覆盖判定（关单用这一条）

问：**现在这模块给用户/运营的实际效果，是否已经达到或超过旧方案想解决的问题？**

- 是，且没有必须保留的残留债 → **关 completed**（或 `not_planned`：方向被取代）。
- 现行实现更安全/更能用，但还剩一截运营动作（刷库存、一次性迁移）→ **关功能单，另开 ops 单**。
- 现行更弱、方向相反、或只做了底座没形成可用效果 → **留着**，不要用「有相关文件」当覆盖。

禁止：

- 用「生产 Release 提到了」关执行单。
- 用「子 PR 合了」关总单，却不看用户效果。
- 把「设计探索 / 原文方案」和「现行更好的实现」绑死——不一致往往是进步。

### 4.3 关单理由要诚实

| reason | 何时用 |
|---|---|
| `completed` | 效果已交付（按 4.2，不必原文逐条） |
| `not_planned` | 不做了 / 被取代 / 重复单 / 原方案废弃 |

关单评论写清：授权来源、对照了什么代码/发布、为什么算覆盖或废弃、残留是否另开单。  
`not_planned` 不要写成「已交付」。被新流程**绕开**的旧需求（例如「合 main 前 UAT」被改成「合后 RC 再 UAT」）应标取代，不要放进「已交付」栏。

### 4.4 台账卫生

- 归档索引保持 OPEN，不当 sprint。
- 重复单关 `not_planned`，交付记在留下的那张上。
- 伞单 ≠ 子决策。子决策做完可以关子单；伞还在就留伞，或把伞改成归档并写清现状。
- 功能已上、删旧代码没做 → 另留 P2「退役」单，不要让已上线的主链 Issue 一直 OPEN。
- 总控/Epic 在子项都关或效果已覆盖后关；不要等一个无关的监控单把可靠性总单卡死——拆干净再关。

### 4.5 决策方式

产品方向（做不做、降不降级、挂不挂起）必须用户拍板。AI 给 **选项 + 推荐 + 一行后果**，不要一次抛 80 张。  
拍板后立刻：Issue 评论（证据）→ 关/改标签 → 再问下一张。  
「挂起」是合法状态：真债、现在不排期。再问等于重复，除非用户要求「按代码再审会不会其实已经更好了」。

### 4.6 执行与派发

- 维护者默认不改业务代码。紧急本地修必须用户明说，并记录授权、范围、风险。
- 派给子代理的 prompt **自包含**：工作区路径、分支、base SHA、验收、禁止事项。子代理看不到主对话。
- 完成或失败都要留下可复用结论（任务名、坑与解法、最终方案）。对话结束自动抽取会漏，重要结论要显式写回 Issue 或记忆。
- 通道失败（超时、fetch failed）先做最小连通探针，再派**新**执行者；不要对已死对话反复续跑。
- 工作区打不开 / 权限异常时换新路径重建，不要死磕锁定目录。

### 4.7 验证与发布

- CI 绿 ≠ 真环境过。要账号态的流程，用约定测试号在目标环境跑。
- 共享测试场：后部署覆盖先部署。被覆盖后的页面不能当该 Issue 的验收。
- 破坏性内容动作（批量下架、替换、重生成并发布）永远单独授权，不跟「小修复已验证」捆绑。

---

## 5. 给新工作区的最小落地（可比 MOIRAISM 全套更短）

新仓库不必上批次链、UAT 锁、双台。够用的开源形是：

1. `CONTRIBUTING` 里写清：Issue → 分支 `issue-N-slug` → Draft PR → Review → merge。
2. 标签最少：`type:`（feat/bug/docs/cleanup）+ `priority:`（p1/p2）+ 可选 `status:blocked`。
3. 执行者不停在「本地 main 上直接提交」。
4. 维护者合并前看：CI、范围有没有漂、验收有没有写在 PR 上。
5. 发布：有用户的产品，合并 ≠ 上线；上线单独一句授权。
6. 关单用第 4 节的效果标准，并在 Issue 留证据评论。

若仓库以后变大，再加：独立 worktree、测试环境驻留账本、生产 tag。那是规模问题，不是原则问题。

---

## 6. 启动时 AI 应先做的三件事

1. 读本文件；若仓库另有更具体的 `AGENTS.md` / 工作流，**以仓库文件为准**，本文件只补思考方式。
2. `git status` / `git fetch`，确认自己在哪条分支、有没有脏改动、有没有同号分支/PR。
3. 要改代码先找到或创建执行 Issue；只盘点/关单就对照 `main` 与用户效果，不要凭 Release 目录或聊天记忆关单。

---

## 7. 反模式（直接禁止）

- 在主控对话里默默改业务代码、提交、部署。
- 执行者 merge、取消别人的 CI/部署、扩需求消冲突。
- 用过期文档/过期清单当现行路由真相。
- 把「有相关模块文件」当成「用户效果已达到」。
- 重复派活到已冻结 PR。
- 没有用户授权就生产发布。
- 没问清歧义就开始写；为未来需求预埋抽象；顺手格式化/重构无关代码。
- 没有可验证成功标准就宣称「做完了」。