用途:把已完成的工作整理成小而可审查的提交,做到范围明确、验证到位、附带相关任务状态更新,且不包含无关文件。它关注最小提交、精确暂存路径、任务状态耦合、验证与提交信息,不是审查模板或台账模板。
适用场景:用户要求提交、拆分提交、精确暂存路径或避免无关改动;准备提交前需要查看 git status 或 diff 以排除无关工作;工作区有多个改动需判断哪些属于同一逻辑提交;被跟踪任务完成、变更或失效,其状态更新需随相关提交一起走;项目要求 Conventional Commits 或每次提交配台账条目。
所需输入:当前 git status、git diff、git diff --cached;用户目标与已完成的验证;当前任务状态载体(如 tasks.md、docs/tasks.md 或仓库 issue 跟踪引用);仓库提交规则及台账条目是否必须同提交。
执行顺序:先读 git status 与相关 diff,区分自己的改动与无关改动;再按“一个提交一个逻辑行为”拆分暂存路径,纳入相关任务状态更新,并运行最小相关验证;最后写 Conventional Commit 信息、提交,并复查状态与提交内容。
步骤:运行 git status --short --branch 列出全部改动;对每个拟提交文件读 git diff -- <path>,不理解就不提交;若无提交规范,按 references/build-when-missing.md 建立最小分组与验证清单;判断改动是否完成、变更或使某跟踪任务失效,若是则把对应任务状态更新纳入同一逻辑提交;按逻辑边界分组,docs、tests、实现、harness、台账、任务状态不应混在一起,除非属于同一逻辑改动或仓库规则要求同提交;对每组运行最小匹配验证命令,失败先修复;使用 git add <exact paths>,避免 git add .,除非整个工作区只有该改动;写 Conventional Commit 主题,正文可写验证、跳过原因、任务 ID 或关联产物;提交后运行 git show --stat --oneline HEAD 与 git status --short。
检查项:范围上每个提交只有一个逻辑目的;归属上不误含用户自有改动或临时生成文件;任务耦合上,完成、变更或失效跟踪任务时任务状态更新在场,且无无关任务变动;验证上提交有匹配的提交前验证;信息上主题描述行为而非“update files”;台账上若仓库要求 agent_chats 同提交,则与改动一起暂存。
输出格式为“Atomic Commit Plan”,含 Detected Mapping(work-state、ledger、validation)、Worktree State、Commit Groups(Subject、Paths、Task-state updates、Validation)、Excluded Changes、Final Checks(First、Then、Finally)。
常见错误:用 git add . 带入无关文件;把功能、格式化、文档、重构、临时修复混在一个提交;把已完成任务的状态更新拆到之后无关提交;未读 diff 就提交;写“fix”“update”之类信息;验证失败仍提交。
限制:资料未提供具体安装命令、平台支持、收费或价格信息,暂未提供。