研发工作流¶

结论：研发工作流用七个步骤连接想法、调研、决策、issue、PR 和 Project 进度。

版本 0.7 · 2026-10-28

本文以 Covio 当前的 issue 流程为基线。本文规定从想法到合并 PR 的研发规则。

1. 目的与范围¶

本文规定研发团队如何创建对象、推进交付和记录证据。

个人账号没有 issue types 和 issue fields。团队只用标签和 Project 字段区分对象。

Covio 的准确字段和模板以仓库文件为准。本文与仓库规则冲突时，执行仓库规则。

2. 对象与主流程¶

先用下表选择对象。不要用同一种对象表达所有工作。

主流程有七个步骤。S6 与 S7 贯穿各步。

flowchart LR
  A["S1 Discussion"] -->|"3 人回复或要求调研"| B["S2 Research issue"]
  A -->|"做法清楚"| E["S5 Feature 或 Task"]
  B --> C["S3 结论写回 issue"]
  C -->|"否决"| D["关闭 issue"]
  C -->|"长期决策"| F["S4 ADR"]
  C -->|"可直接做"| E
  F --> E
  E --> G["sub-issue / branch / PR"]
  G --> H["Project 8 Done"]

3. 角色¶

负责人默认是 issue 的创建人。改派工作时，同步更换 assignee。

ADR 和流程文档的 PR 需要非作者批准。单人仓库由负责人自查。自查结论仍要记录。

4. 七个步骤¶

S1 想法进入 Discussions¶

何时用： 有一个问题，但做法不清楚。
谁做： 提交人。

1. 打开仓库的 Discussions。
2. 创建 Ideas 或 Q&A 帖子。
3. 写清问题、受影响的人和具体场景。
4. 不写解法。
5. 添加 idea 标签。没有 triage 权限时，请维护人添加。
6. 如果达到 3 人回复或收到调研请求，进入 S2。
7. 如果 30 天无信号，提醒提交人。
8. 如果没有回应，关闭讨论。
9. 关闭讨论时，写明原因。

完成标准： 帖子包含问题、受影响的人和具体场景。

警告： Discussions 无法进入 Project。需要排期时，创建 issue。

S2 用一个 Research issue 回答一个问题¶

何时用： 问题清楚，但做法、成本、风险或可行性有未知项。
谁做： 负责人。

1. 打开 .github/ISSUE_TEMPLATE/research.yml。
2. 只写一个待答问题。问题使用问句。
3. 填写背景、预期产出和负责人。
4. 将标题写成 research: <问题>。
5. 将时间盒设为 2 个工作日。
6. 需要延长时，将时间盒设为 3 个工作日。
7. 添加 research 标签。
8. 到期后开 15 分钟评审。
9. 评审只决定结题或延长。
10. 延长只允许一次。延长时间不超过原时间盒。
11. 如果延长后仍未答出，按 S3 结束。

完成标准： issue 只含一个问题，且有负责人、时间盒和预期产出。

警告： Research issue 的代码不得合并到 main。调研代码只用于取得证据。

S3 把结论写回 issue 正文¶

何时用： Research issue 到期，或调研可以结束。
谁做： 负责人。

1. 编辑 Research issue 正文。
2. 填写结论、依据和后续动作。
3. 依据填写数据或链接。
4. 如果结论是否决，写明理由。
5. 填写 decision: 指向。
6. 决策编号未知时，填写 decision: pending。
7. 如果原 Discussion 存在，回复一句结论和 issue 链接。
8. 按结论关闭 issue。
9. 已结题时，选择 completed。
10. 已否决时，选择 not planned。

完成标准： 只读正文即可理解结论、依据和后续动作。

规则： 结论写在正文，不写评论。结论未写回正文前，不关闭 issue。

S4 用 ADR 保存长期决策¶

何时用： 决策影响多个模块、改起来成本高，或半年后仍会被问到。
谁做： 负责人。

1. 从 doc/adr/adr-template.md 复制模板。
2. 新建 doc/adr/adr-NNNN-<slug>.md。
3. 取现有最大编号加一。编号不复用。
4. 填写背景、决策、状态和后果。
5. 创建 PR。
6. 请求一名非作者评审。
7. 合并前，将 Status 改为 accepted。
8. 合并后，在 5 个工作日内回填 decision: pending。

状态： proposed 只用于未合并的 PR。accepted 表示生效。deprecated 表示不再推荐。superseded 表示已被替代。

类型： architecture 表示技术决策。process 表示流程决策。

需要推翻旧 ADR 时，完成以下三项：

1. 写一份新 ADR。
2. 在新 ADR 中填写 Supersedes: ADR-NNNN。
3. 将旧 ADR 的状态改为 superseded，并填写 Superseded by: ADR-NNNN。

三项改动放在同一个 PR。

警告： 不要删除或改写旧 ADR 正文。删除会丢失决策历史。

S5 创建 Feature、Task 和 sub-issue¶

何时用： 做法清楚，可以开始交付。
谁做： 负责人。

1. 先判断 Feature 和 Task。
2. 大功能打开 .github/ISSUE_TEMPLATE/feature.yml。
3. 小功能创建 Task issue。
4. 如果 Task 属于 Feature，将 Task 建成 sub-issue。
5. 添加 feature 或 task 标签。
6. 将标题写成英文祈使句。
7. 填写目标。
8. 填写可判定的验收标准。
9. 填写 decision: 和 research: 指向。
10. 在正文填写 Priority 和 Size。
11. 将负责人设在 assignee 字段。
12. 大功能建立 GitHub 原生 sub-issue。
13. 每个 sub-issue 写一行验收标准。
14. 每个 sub-issue 预计 1 到 3 天完成。
15. 用 blocked by 记录交付顺序。
16. 为每个 sub-issue 建立一条分支和一个 PR。

大功能判据： 满足以下任一条即可。

1. 需要 2 个以上 PR。
2. 预计超过 5 个工作日。
3. 需要先改设计。

层级： 从 Feature 开始最多 3 层。GitHub 支持更多层级，但第 4 层不便于阅读。

完成标准： 每个 sub-issue 都有验收标准，且工期为 1 到 3 天。

规则： issue 是讨论和验收的起点。不要把完整 PRD 复制到 issue。

取消工作时，执行以下三项：

1. 关闭 Feature 和未完成的 sub-issue，原因选择 not planned。
2. 在 Feature 正文写取消原因。
3. 在关联 ADR 中填写 Cancelled by: #N。

S6 用文本指针关联对象¶

何时用： 一个对象需要引用另一个对象。
谁做： 负责人。每条引用只维护一次。

规则： 未定值在 5 个工作日内回填。本仓库引用写 #N。跨仓库引用写 owner/repo#N。每行只放一个引用。

UI 候选预览不新增文本指针。使用 GitHub 原生 sub-issue 和 blocked by 关联。

检索：

gh issue list --state all --search "decision"
gh issue list --state all --search "decision pending"
gh search issues "decision" --owner wyz541

GitHub 的 issue 搜索不保证支持标点。命令只使用关键词 decision。

S7 用 Project 8 跟踪进度¶

何时用： Feature 建好后配置一次。之后每周检查。
谁做： 维护人。

1. 打开 Project 8。
2. 核对字段名称和取值。
3. 打开 Project 的 ⋯ 菜单。
4. 选择 Workflows。
5. 打开 Auto-add to project。
6. 将筛选条件设为 repo:wyz541/kmp-Covio is:issue。
7. 打开 table 视图。
8. 按 Parent issue 分组。
9. 显示 Sub-issues progress 字段。
10. 用 Target date 建立 roadmap 视图。
11. 每周检查 blocked by 关系。

Start date 和 Target date 只写在 Project。不要在 issue 正文维护第二份日期。开始实施后，将 Status 设为 In progress。PR 合并后，将 Status 设为 Done。

自动加入失效时，执行以下命令：

gh project item-add 8 \
  --owner wyz541 \
  --url https://github.com/wyz541/kmp-Covio/issues/123

完成标准： Feature 的进度可以直接从 Sub-issues progress 读取。

警告： 未打开自动加入时，gh 和表单创建的 issue 不会进入 Project。
警告： roadmap 视图不能展开子项。查看子项时，切回 table 视图。
注意： 字段名是 Sub-issues progress。复数不能写错。

5. 界面变更与 PR 验收¶

界面变更先建立 UI issue。UI issue 负责问题、范围、表现预期和验收标准。

不要恢复强制 Compose Web 预览。候选预览可以放在 issue 正文。

界面 issue 的执行顺序如下。

1. 在实施前创建 Task 或 Feature issue。
2. 写清用户问题、范围和表现预期。
3. 写清可观察的验收标准。
4. 如果 Task 涉及界面，将候选方案放在同一 issue 的 ## 预览。
5. 如果 Feature 涉及界面，先建 preview sub-issue。
6. 将候选方案、截图或链接放在 preview sub-issue 的 ## 预览。
7. 为每个实施 sub-issue 添加 blocked by，并指向 preview sub-issue。
8. 将评审结论写回 issue 正文。
9. 评审通过后，开始实施。

UI issue 不写 Visual verification。UI issue 只记录决策和表现预期。

在不涉及界面的 PR 中，将 Visual verification 写成“不适用”。

界面代码 PR 必须提供真机证据。

1. 使用同一条分支完成一个 issue。
2. 运行 bash scripts/test-all.sh。
3. 使用同一页面和同一状态采集亮色 Before/After。
4. 使用同一页面和同一状态采集深色 Before/After。
5. 将截图文件放入 docs/design/previews/。
6. 使用固定 commit 的 GitHub 图片地址。
7. 在 PR 中记录截图来源和日期。
8. 在 PR 中记录设备型号和系统版本。
9. 在 PR 中记录页面、状态和完整 commit SHA。
10. 在 Visual verification 中放入两张 Before/After 表。
11. 在 Design preview 中写 issue 和评审结论。
12. 在 Proof 中写测试命令和结果。
13. 在 Risk 中写剩余风险。没有风险时，写 None。
14. 在所有检查通过后，将 PR 标记为 ready。
15. 使用 Closes #N 关闭对应 issue。

未准备好时，使用 draft PR。Feature 的全部 sub-issue 未完成时，不关闭父 Feature。

Commit 标题使用英文祈使句。标题首字母大写，最多 72 个字符。标题不加句号，也不加 feat: 等前缀。有 issue 时，在提交正文写 Refs #N。agent 创建的提交还要写 Co-Authored-By: Claude Code <noreply@anthropic.com>。

PR 至少包含以下段落：

警告： UI 截图缺失或图片链接失效时，不得标记 ready，不得合并。
警告： 测试失败时，不得标记 ready，不得合并。
警告： 不要直接推送 main。
警告： 不要使用 git add -A 或 git add .。只暂存本次修改的文件。

更细的质量门禁见质量保证 SOP。

6. 每周检查¶

维护人执行以下检查。

1. 搜索 decision pending。
2. 通知负责人回填超期引用。
3. 查开放的 research issue。
4. 提醒超过 3 个工作日的 Research issue 结题。
5. 查已合并但状态仍为 proposed 的 ADR。
6. 通知 ADR 作者修正状态。
7. 检查 blocked by 关系。
8. 检查 Feature 的 Sub-issues progress。
9. 检查等待 UI 评审超过 3 个工作日的 issue。
10. 检查 Project 自动加入是否正常。
11. 检查过期的 Target date。

7. 例外与变更¶

Research 时间盒只允许延长一次。延长上限是 3 个工作日。

个人账号不得使用 issue types 或 issue fields。使用标签和 Project 字段替代。

测试失败或 UI 证据缺失时，不设例外。

流程发生变化时，创建 PR。PR 需要非作者批准，并同步更新本文和版本。

8. 参数¶

9. 依据¶

本文在 2026-10-28 核对以下 Covio 仓库来源：

1. AGENTS.md
2. doc/process/workflow.md
3. doc/process/project-fields.md
4. .github/ISSUE_TEMPLATE/research.yml
5. .github/ISSUE_TEMPLATE/feature.yml
6. covio-issue-pr skill 的 issue 与 PR 交付规则

10. 更新记录¶