work-unit-commits

适用场景

在决定每个提交或 PR 应包含哪些内容时，加载此技能。

适用于：

• 将功能拆分为便于审查的工作单元。
• 在创建 PR 前准备提交。
• 将大型变更拆分为串联或堆叠的 PR。
• 合理控制审查者的认知负担。
• 应用 SDD 任务时，避免意外产生超过 400 行变更的 PR。

关键规则

规则	要求
按工作单元提交	一个提交对应一个可交付的行为、修复、迁移或文档单元。
不要按文件类型提交	如果 models、接着 services、再接着 tests 的拆分方式都无法独立成立，就应避免这样拆分。
测试与代码放在一起	测试应与其验证的行为放在同一个提交中。
文档与用户可见变更放在一起	文档应与其说明的功能或工作流放在一起。
讲清楚变更脉络	审查者应能通过差异和提交消息理解每个提交的目的。
为未来 PR 做好准备	当变更逐渐增大时，每个提交都应能作为串联 PR 的候选内容。
SDD 工作量守护	如果 SDD 任务预计会产生超过 400 行的变更，应在实现前将提交分组为串联 PR 切片。

工作单元检查清单

提交前，请确认：

• 此提交只有一个明确目的。
• 仅应用此提交后，代码库仍然合理。
• 相关的测试或文档已纳入此工作单元。
• 回滚时无需撤销无关工作，且操作合理。
• 已记录聚焦测试命令和确切结果。
• 已记录运行时测试框架命令／场景和确切结果，或通过明确的 N/A 说明为何不存在运行时边界。
• 回滚边界指出无需涉及无关工作的情况下，可移除的确切文件／行为。
• 提交消息说明了变更结果，而非文件列表。

拆分示例

较差的拆分方式	更好的工作单元拆分方式
add models	feat(auth): add token validation domain model and tests
add services	feat(auth): wire token validation into login flow
add tests	测试与各行为提交一同纳入
update docs	文档与其说明的面向用户的变更一同纳入

PR 关系

以工作单元提交为基础，构建串联 PR：

1. 构建最小的独立工作单元。
2. 纳入该单元的验证。
3. 使用 Conventional Commit 消息提交。
4. 如果 PR 接近 400 行变更，就将提交或提交组拆分为串联 PR。

ODD 的关系

有机驱动开发（ODD）要求每项实质性任务都以功能分支上的工作单元提交收尾：

• 每项 ODD 任务都至少以一个工作单元提交收尾；若当前位于默认分支，则先创建分支；测试和文档须与行为变更一并提交，并使用 Conventional Commit 消息。
• 原生评审候选对象是该提交；若延后评审，则是它所属的 PR 切片，相对于上一个已评审边界进行评审。它绝不是 TODO 复选框，也不是累积了所有变更的功能分支。
• 工作单元提交中持续累计的作者行数，决定交付策略的术语：ask-on-risk、auto-chain、single-pr、exception-ok。
• 对于 >400 阈值，统计作者新增行数与删除行数之和。生成的 golden 文件不计入作者行数，但每个生成文件都必须纳入完整快照标识和收据验证。
• ODD 功能文档将提交标识记录为证据；一旦适用交付策略，还须记录选定的链式策略和切片边界（每个 PR 包含哪些提交）。

每个 ODD 工作单元都应清晰对应一个提交或 PR，并具备：

• 明确的起始状态，
• 明确的完成状态，
• 同一工作单元内的验证，
• 不会移除无关工作的回滚方式。

其实现证据必须包括：

• 专项测试命令和确切结果。
• 运行时测试框架的命令／场景和确切结果；若不适用，则明确标注 N/A 并说明原因。
• 独立于提交创建流程说明回滚边界；未提交的工作单元也必须说明。
• 修复范围受限的评审记录时，将原子工作单元归入同一个更正事务；工作单元数量不得增加修复预算。

命令

# Review the story before committing
git diff --stat
git diff --cached --stat

# Check recent commit style
git log --oneline -5