工作单元提交与PR最佳实践

v20260906

work-unit-commits

本指南指导开发者如何将大型、复杂的代码功能分解成多个独立、可审查的小单元提交（Work Units）。它强调了良好的版本控制流程，确保每个提交都代表一个清晰的、可交付的行为或修复，从而减轻代码审查者的认知负担，提高代码质量。

Git 版本控制软件开发提交 PR 最佳实践

431 次下载

概览

When to Use

Load this skill when deciding what belongs in each commit or PR.

Use it for:

Rule	Requirement
Commit by work unit	A commit represents a deliverable behavior, fix, migration, or docs unit.
Do not commit by file type	Avoid `models`, then `services`, then `tests` if none works alone.
Keep tests with code	Tests belong in the same commit as the behavior they verify.
Keep docs with the user-visible change	Docs belong with the feature or workflow they explain.
Tell a story	A reviewer should understand why each commit exists from its diff and message.
Future PR-ready	Each commit should be a candidate chained PR when the change grows.
SDD workload guard	If SDD tasks forecast a >400-line change, group commits into chained PR slices before implementation.
Budget is not code-golf	Never shrink a diff by deleting comments, blank lines, docs, or tests, or by compressing code, to fit the review budget (400 by default, or the session `review_budget_lines`). Slice by work unit or report the overage.

Before committing, confirm:

The commit has one clear purpose.
The repo still makes sense after applying only this commit.
Tests or docs for this unit are included when relevant.
Rollback is reasonable without reverting unrelated work.
Focused test command and exact result are recorded.
Runtime harness command/scenario and exact result are recorded, or explicit N/A explains why no runtime boundary exists.
Rollback boundary names the exact files/behavior removable without unrelated work.
The commit message explains the outcome, not the file list.

Weak split	Better work-unit split
`add models`	`feat(auth): add token validation domain model and tests`
`add services`	`feat(auth): wire token validation into login flow`
`add tests`	Tests included with each behavior commit
`update docs`	Docs included with the user-facing change they explain

Use work-unit commits as the foundation for chained PRs:

Build the smallest independent work unit.
Include verification for that unit.
Commit it with a Conventional Commit message.
If the PR approaches 400 changed lines, promote commits or groups of commits into chained PRs.

When sdd-tasks produces a Review Workload Forecast:

Low risk: keep work-unit commits inside one PR.
Medium risk: commit by work unit and monitor changed lines before PR creation.
High risk: follow SDD delivery_strategy — ask on ask-on-risk, auto-slice on auto-chain, require size:exception on over-budget single-pr, or record accepted size:exception on exception-ok.
Count authored additions plus deletions for the >400 threshold. Exclude generated goldens from that authored count, but include every generated file in complete snapshot identity and receipt validation.
Splitting is bounded: after one honest slicing pass, if no cohesive work-unit split fits the budget, stop and report the smallest honest count with a size:exception recommendation. Do not iterate shrinking the code to reach the number.

Each SDD work unit should map cleanly to a commit or PR with:

Its implementation evidence MUST include:

Focused test command and exact result.
Runtime harness command/scenario and exact result, or explicit N/A with reason.
Rollback boundary stated independently of commit creation; uncommitted work units still require it.
When fixing a bounded review ledger, group atomic work units inside the single correction transaction; work-unit count never creates another fix budget.

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

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

信息

Category 编程开发

Name work-unit-commits

版本 v20260906

大小 4.48KB

Source Gentleman-Programming/gentle-ai

更新时间 2026-09-07