63 lines
7.3 KiB
Markdown
63 lines
7.3 KiB
Markdown
<!-- 导航元信息: {"内容描述": "分支策略、双环交付、敏捷提交、统一审查与合并门禁", "使用场景": "制定 plan、委派、集成与决定提交节奏时", "使用要求": "新功能分支/worktree快跑，终验后统一审查合入；小改动直提main，远程与合并需授权"} -->
|
||
# 计划与提交
|
||
|
||
适用于需要制定 plan 的开发任务。本文件定义任务、分工、交付批次、提交与独立审查；执行与验证节奏见[模块依赖](模块依赖.md)。计划和 Skill 均不授予提交、合并、发布或外部调用权限。
|
||
|
||
## 任务与交付批次
|
||
|
||
- **双环交付模型**：
|
||
- **内环（敏捷小增量）**：以可独立验收的能力拆分成敏捷小任务（Task），包含必要入口、执行与失败恢复路径；支持在 Plan 内部快速小步推进、局部验证并通过本地 commit 固化检查点。开发过程中允许根据新发现合理调整后续 Task。
|
||
- **外环（Plan 终验全量闭环）**：交付批次（Plan）作为集中验收与合并的单位；整个 Plan 声明交付时，必须执行全量自动化验收（全量离线测试与核心集成验证），确保全局无回归破坏。
|
||
- **开工边界**：每项任务写清做什么、不做什么、交付物、修改边界、前置依赖、维护者、完成标准和验证方式。缺项或关键前提未确认时只阻塞受影响任务，继续其他已授权的独立工作。
|
||
- **审查单位**：Plan 是集中验收与最终审查的单位；大型计划可在执行合同中预先划定多阶段，并明确跨阶段集成顺序与最终验收。
|
||
|
||
## 依赖与分工
|
||
|
||
- **按能力衔接**：依赖的是具体输入和已验证能力，不是整个前置包的完成标签；尚未接通真实上游的部分明确留待集成验收，不以替身通过冒充完成。
|
||
- **独立任务主动并发**：前置满足、输入与修改范围互不影响且有实际收益的任务分工并发实现、验证和交付；共享状态、连续决策和简单任务由主代理处理，不为并发而制造拆分。
|
||
- **隔离与归属**：各线使用包含所需改动的同一可核验基线，并发写入者使用隔离工作区；共享接口、迁移、装配和生成文件指定唯一维护者。无法安全隔离时说明具体限制，先推进不冲突工作。
|
||
- **集成有负责人**：委派给出输入、输出、文件边界和完成判据，主代理按依赖顺序承接差异与证据，验证实际消费者和跨任务链路。重测试按环境与预算容量限流，可变数据库、端口和会话相互隔离。
|
||
|
||
## 研发相位（判据可判定）
|
||
|
||
| 相位 | 进入判据 | 验证义务 |
|
||
|---|---|---|
|
||
| 开发期 | 任务尚未通过自身完成标准 | 跑受影响快速检查或相关文件测试，及时修复失败；鼓励随时常态化运行全量离线测试（`make 测试`）快速捕捉回归破坏 |
|
||
| 能力稳定 | 任务自身完成标准全绿（按 L 级证据口径） | 跑相应回归与真实接缝验证；替身与隔离遵守[测试隔离](测试隔离.md) |
|
||
| 批次稳定 / 终验 | 批次内全部任务能力稳定 | 集中本批完整门禁（`make 检查` + 全量测试）与必要真实入口验证，进入最终验收 |
|
||
|
||
- 发现影响目标或授权的设计缺口时返回对应决策，不以临时替身掩盖，也不扩大无关任务；已有目标、方案和证据仍有效时直接承接。
|
||
- **证据复用**：确认代码、合同、输入、环境、配置和工具版本仍适用后复用证据；出现相关变更、证据失效、新失败或未解决疑点时重验对应范围，影响不清时扩大到能覆盖风险的范围。
|
||
- **排版格式化为静默辅助**：格式化（`make 格式写入`）仅作为 AST 等价的代码美化，在保存或提交前静默触发即可，不将其当做“破坏性语义变更”，不因格式化作废有效测试结论。
|
||
- **测试分层与门禁**：日常快速循环使用秒级 `make 快检 范围=<受影响路径>`；离线全套 `make 测试`（~70秒）鼓励常态全量运行；仅涉及存储/迁移/触发器时跑局部数据库测试（`make 数据库测试 范围=<路径>`）。Plan 终验时运行 `make 验收数据库` 完成全量闭环，移除繁琐的人为环境变量卡点。
|
||
|
||
## 验证级别
|
||
|
||
| 级别 | 适用范围 | 完成证据 |
|
||
|---|---|---|
|
||
| L1 | 文档、注释、索引类改动 | 对应机械检查通过，含本批链接、索引或声明核对 |
|
||
| L2 | 常规局部实现与缺陷修复 | 相关单元或契约测试通过，以及 `git diff --check` |
|
||
| L3 | 核心底层契约破坏（Breaking Changes）、不可逆核心表结构变更、生产数据清洗、鉴权核心逻辑重构 | 约定模块门禁、真实接缝验证，以及独立整体审查 |
|
||
|
||
不可逆操作包括生产凭据变更、核心数据清洗与破坏性表结构演进。不可逆操作或核心底层重构须先评审方案，再对稳定批次审查；常规功能演进与小步修复不滥用 L3。缺对应证据时标记 `needs_verification`，不以手工台账计数代替。
|
||
|
||
## 验证、提交与审查
|
||
|
||
- **验证不过不收尾**：任务未通过与自身完成标准相称的验证时，继续实现并重验受影响部分；不以“基本完成”隐去失败或推给无关后续任务。
|
||
- **分支策略与本地沙盒自治**：
|
||
- **新功能开发分支**：默认在主仓库切出独立特性分支进行开发，使用独立分支或 `git worktree` 隔离；
|
||
- **简易小型修改**：对于简易、小型的局部修复或修改，允许直接在主仓库（`main` 分支）进行提交；
|
||
- **敏捷小步提交（Commit early and often）**：开发过程中敏捷推进，鼓励每个小任务测试完成后即执行一次本地 `git commit` 保存检查点与回滚锚点，无需逐步向人类申请审批。
|
||
- **阶段收口与统一审查**：
|
||
- 代码审查严格基于已提交的 Git Commit 进行；
|
||
- 全部任务完成后，再集中统一进行审核（Review）并修复发现的问题，不逐笔前置卡点阻塞开发；
|
||
- 最终全量验证通过后，将特性分支（或 worktree 成果）合并回 `main` 分支。
|
||
- **关键操作授权门禁**：向远程仓库推送（`git push`）、向 `main` 主干分支合并或发起 PR、清理带有未保存改动的工作区前，必须获得用户明确授权。
|
||
- **审查基于 Git Commit**：代码审查严格基于已提交的 Git Commit 进行，不搞针对未提交工作树的审查；重点审查逻辑完整性、一致性、合理性、可行性，以及任务间链路与被替代实现残留。
|
||
- **整体验收不省略**：多任务或多批次计划最终必须通过全量验收（包含全量离线测试与核心集成链路），确保全局没有隐性破坏，不能仅凭各小任务局部通过代替整体验收。
|
||
- **集中收尾**：按批次同步权威记录和索引，清理本次替代内容，框架与创作内容分开审查、分开提交；按已交付能力、具体阻塞和剩余验收项汇报，不以测试或文档数量替代进度。
|
||
|
||
## 判定依据
|
||
|
||
任务边界和批次范围由计划逐项复核；运行命令、退出码、输入与代码版本构成验证证据；审查记录列明真实差异范围、审查结论和未覆盖项。链接、索引和格式使用现有机械检查；内容是否完整由独立语义审查判断，不以字符串存在性检查冒充流程正确。
|