vibe-commit

Vibe Commit

概述

提交请求意味着创建一个干净、范围恰当的提交，而不是运行 git add -A && git commit。选出面向用户的变更，排除无关或不安全的路径，阅读暂存区差异，安全地传递提交说明，并检查已保存的提交。对于仅涉及命令或呈现状态的请求，展示适用的命令序列，但不要声称已执行；对于受阻的请求，则停在阻碍处。

提交说明内容与提交执行

此技能负责暂存、验证、提交说明传递、页脚和历史安全。准备、检查、修订或修复提交说明时，请使用 references/history-and-trailers.md。常规验证——运行的命令、通过的检查或测试套件、测试数量、审查者或模型致谢——不属于提交说明内容；应另行报告。用户或仓库规则要求验证章节时，应遵循该要求；在仅回复计划的情况下，只能使用已提供的证据：如果提供的状态未记录某项检查已通过，则该检查为“未运行”，绝不能声称已通过。

权限与安全边界

本地提交可以撤销；发布则不可撤销。除非用户明确要求，否则应留在可撤销操作范围内。

影响与写入边界

不得写入超出该阶段声明的影响类别和边界所允许的内容。

• 按阶段自身文本声明的影响类别执行；如果本包规定了更严格的限制，则以更严格的限制为准。
• 只读：在聊天中报告；不得编辑任何文件，不得运行任何会改变状态的命令，也不得暂存、提交、打标签、推送、更改版本、删除数据或启动服务。只有在用户明确要求生成已保存的产物时，才可写入文件。
• 仅产物：只创建或更新该阶段负责的产物，以及其文本声明的配套路径，例如已确认计划的记录或决策记录，并将它们留在工作区中。
• 仅产物阶段绝不能实现可执行行为，不能作为实现工作编辑代码或测试，不能生成其他阶段的产物，不能执行发布工作，也不能将其产物视为同一轮中的实现授权。
• 状态变更：仅在声明的范围内编辑和运行命令，并以最小且经过验证的单元进行；除非用户选择，否则不得触碰其他路径、已有变更、运行时状态或外部状态。
• 这些限制同样适用于 Shell 命令（重定向、sed -i、tee、mv、cp、rm、git checkout --）和文件工具；将被拒绝的写入报告为边界阻止，不得改用其他工具重试。
• 每项不可逆或对外操作都必须单独征得同意。

此工作流声明的范围是它要执行的提交——该提交的索引、历史记录和说明——且不会修改源文件。

遵守 .gitignore 和约定的范围。 除非用户在了解某路径为何被忽略以及由此产生的风险后，明确要求纳入该路径，否则绝不能运行 git add -f 暂存被忽略的路径。绝不能暂存提交变更范围之外的文件。

持久记录

提交前，检查 docs/decisions/README.md；如果 docs/decisions/ 存在但缺少索引文件，则检查记录本身，找出其 paths 与暂存区差异涉及路径相符的已接受记录。如果存在此类记录、文件集合包含决策记录或发现报告，或要移交决策或发现内容，则应阅读 references/durable-records.md。此阶段通常既不写入 docs/decisions/，也不写入 docs/reports/findings/；应按照该参考文档的定义，将它们作为后续传递资料包移交。

提交选择

只有明确的用户请求、已绑定的计划项，或工作流自身已验证的检查点，才能选定提交。

• 提交前先说明依据：当前用户的请求、已批准的已绑定计划检查点，或此工作流针对自身已验证单元的检查点默认规则。若没有依据，则不要提交；将更改留在工作树中并说明。
• 绝不能将路由、调用、编辑权限、便于停下的节点、已跟踪的更改，或可用的提交工作流视为依据。提交执行本身没有检查点默认规则。
• 检查点默认规则：一个独立单元完成实现、验证、审查，并处置其重要发现后，应立即仅在本地提交该单元，无需等待单独指示；绝不能让多个单元堆积着未提交。
• 不得从仅用于发现问题、受阻、未更改、失败、未经验证或仍在进行中的状态中选定提交。
• 只暂存该单元：排除工作流未创建的预存更改，以及该单元范围外的路径；若无法将该单元与其他更改分开，则报告混合状态并询问。
• 该单元创建且必需的新文件（如源文件或测试文件）属于该单元，但凭据或机密除外；只有在明确表示要跟踪，或因强制耦合而必须纳入时，才将生成的输出、临时文件和报告一并提交。
• 将每个选定的提交交由提交执行处理，并提供其范围、测试与审查证据、排除项，以及任何拟议的提交说明；该工作流负责暂存、差异审查、提交说明传递和提交后验证。
• 若为修复较早提交自身的缺陷而选定修复项，且没有远程跟踪引用、标签、其他分支或工作树包含该提交，则无需询问，直接将修复并入该提交；否则，或若合并失败，则单独提交并说明原因。
• 除上述合并外，执行推送、修订提交、变基、会移动 HEAD 的重置（soft、mixed 或 hard）、filter-* 改写或脚本化的多提交重放之前，必须取得用户的明确授权；提交请求或检查点绝不代表已获授权，已发布的历史记录是共享的。
• 绝不能将提交请求或检查点视为同意发布、修改版本、创建标签、贮藏、更广泛的压缩提交、破坏性清理、强制添加、跟踪该单元之外的新构件或产生外部副作用；这些操作各自都需要单独授权。

示例：“用户本轮要求提交”说明了依据；“现在是个不错的停顿点”则不是依据。

例外：若当前指示要求不提交、已绑定的计划禁止提交，或项目政策暂停默认规则，则将已验证的更改留在工作树中并说明原因。

此工作流即为提交执行；指定范围的检查点交接以针对所列路径的提交请求形式到达，并通过以下所有关卡。

历史安全

不要重写共享历史。 只能修改或变基尚未离开本机的提交。如果你因需要重写已推送的历史或强推共享分支而暂停征求同意，请在同一条回复中说明代价——其他克隆会产生分歧，协作者可能必须变基、重置或协调重复提交——并列出你提供的修正途径，包括后续提交是否能触及该缺陷。

未经单独确认暂停，绝不要让脚本化重写删除仍在使用的文件。 当脚本化或循环执行的多提交重写会从历史中移除路径时，必须从每个提交自身的树中获取其目标列表（使用带目录字面前缀的 git ls-tree -r），绝不能从 git status 或其他工作树快照获取，否则会删除与该提交无关的文件。确认范围和树查询均已成功后，才能信任空结果。打印完整解析后的列表，并要求明确确认暂停后，才能执行任何删除；脚本可以一带而过的预览不算把关，备份也绝不是删除授权。请遵循 references/history-and-trailers.md。

脚本化的 trailer 修复和路径移除重放仅适用于简单、未推送的线性提交范围；合并提交需要单独制定计划。如果发生冲突、元数据保留缺失、trailer 重复或分支已移动，trailer 修复会停止，且不会重新指向原分支。

核心工作流：“commit please” → 一个干净的提交

遵循这一主线。每个步骤都列出关键命令；参考资料会深入说明需要判断的情形。

1. 发现所有内容。 git status --short --branch --untracked-files=all 和 git status --ignored 会在一个视图中显示所有已修改、已暂存、未跟踪和 已忽略的路径。再运行 git log -1 --oneline 和 git branch --show-current，以了解当前分支以及可能要扩展的提交。
2. 检查意图。 阅读实际变更：先看 git diff --stat，再用 git diff -- <file> 查看特定文件，并用 git diff -- <newfile>（或直接打开） 查看未跟踪文件。在决定某个路径是否应纳入之前，先判断它究竟是什么。
3. 分类并选择。 将每个变更路径分为 (a) 构成一个逻辑变更的核心交付内容 ——实现及其测试，以及它所落实的文档/CHANGELOG/规范——或 (b) 范围外编辑或 生成产物。新选定的未跟踪产物必须有明确的跟踪意图，或与仓库或所属工作流存在 强制性耦合；相关性、存放位置、在同一会话中创建，或提交权限，都只能使其成为 候选项。单元自身变更所创建且必需的新源文件、测试文件或夹具文件，属于此类 耦合，应纳入该单元，除非其中包含凭据或机密。生成输出、临时文件和报告仍需 明确的跟踪意图或其他强制性耦合。将无关事项拆分为单独的提交；只有在一个诚实 且共享的契约无法涵盖整个补丁时才拆分。参见 references/file-selection.md。
4. 有意排除。 不要暂存生成文件、临时文件、不属于任何负责方的计划/规范、 构建产物、无关锁文件、Agent 状态文件（.agents/、.claude/、.codex/） 及机密路径，并说明每项排除的原因。由所属工作流的限定检查点交接明确指定且 已核实的需求或计划产物属于受管内容，不是一般临时文件。 如果锁文件记录了所选提交所需的依赖变更，则它与清单文件一样属于变更范围； 不要仅因它是锁文件就将其排除。 不确定某个路径是否被忽略时，运行 git check-ignore -v <path>。参见 references/file-selection.md。
5. 明确暂存。 使用完整路径名运行 git add -- <path1> <path2> …。工作树 有未提交变更时，避免使用 git add . / -A / 通配符，以免悄悄把无关文件 一并纳入。对于同时包含范围内和范围外代码块的文件，使用 git add -p <file>。
6. 重新核验暂存内容（强制关卡）。 提交之前，确认即将提交的内容： git diff --cached --name-only（确切文件）、git diff --cached --stat （检查变更量是否合理）、git diff --cached（阅读代码块）、 git diff --cached --check（检查空白字符/行尾错误）。范围内文件应存在， 范围外/已忽略文件应不存在，且差异应符合预期。声明的验证前提必须覆盖候选 字节；偶然生成的测试报告不会产生新的前提。只有当你在本轮亲自阅读了某路径的 完整补丁，并证明其暂存补丁（包括元数据）在同一基准上完全相同时，才可跳过 重新阅读该路径的代码块（例如，将 git diff --cached -- <path> 的哈希值与 阅读时保留的哈希值进行比较）；文件数量、其他或不完整补丁的哈希、审阅者的 阅读记录、测试结果以及关于未触及路径的声明，都不符合要求。调用提交命令前， 必须先阅读关卡输出；钩子或退出状态检查不能代替阅读。
7. 使提交说明与确切目标差异相符（强制内部关卡）。 阅读最终暂存补丁的完整 内容（第 6 步中已证明相符的路径可用该证明替代），并将每项实质性事项对应到 拟定的类型、范围、结果、正文覆盖情况以及单次提交或拆分的决定。源内容发生 漂移时，必须重新核对。若已接受的决策记录约束了变更路径，则应停止，并报告 任何不符合之处，交由用户解决。
8. 合并或新增提交。 如果修复的是先前提交自身的缺陷且符合条件，则将其合并到 该提交中：若目标是 HEAD，则 amend；若目标较旧，则运行 git commit --fixup=<sha>，再运行非交互式的 GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash <sha>^。此操作要求工作树 干净、不使用 autostash、范围内没有合并提交，且修复不依赖后续提交。 否则新增提交并说明原因。符合条件的合并无需用户授权；需记录并报告合并前的 HEAD，以便通过 reflog 恢复；保留目标提交说明，除非修复改变了说明内容；并 跳过第 9–10 步。参见 references/history-and-trailers.md 了解资格条件和 操作流程。
9. 撰写提交说明。 使用 Conventional Commits 格式 type(scope): summary（祈使语气，≤72 个字符）说明结果，空一行，然后在主题 和差异未能说明变更缘由时添加正文，且将原因放在首位，即使规则允许仅写主题也 一样。例行验证信息按上述规则处理；references/history-and-trailers.md （精简提交说明规则）列出了正文可陈述的验证事实。先检测仓库使用的 trailer 惯例：git log -5 --format='%H%n%B'。
10. 安全传递提交说明。 对于任何多行正文，使用 heredoc （git commit -F - <<'EOF' … EOF，分隔符需加单引号）或 git commit -F <file>。使用 git commit ... --trailer 'Key: value' 命令添加或修正作者信息 trailer；本地重写时也应使用 git commit --amend ... --trailer 或 git commit -C <ref> --trailer ...， 而不是将其输入正文或合成的消息载荷中。绝不要在单个 -m 中嵌入原始换行。 参见 references/history-and-trailers.md。
11. 提交后核验已保存的提交。 阅读 git show -s --format=%B HEAD 和已提交 的补丁；合并后，改为阅读合并目标的新 SHA 对应的提交说明和合并后补丁，并确认 后续提交及最终工作树与已核验状态一致。使用 git status --short 确认只剩下 预期文件。只有当该提交仍符合合并条件时，才修正不一致之处；否则停止并报告。
12. 出错时可逆地恢复。 优先采用破坏性最小的修复方式： git restore --staged <file> 取消暂存，git reset --soft HEAD~1 撤销提交但 保留变更，使用 git commit --amend --no-edit --trailer … 修正刚创建的本地 提交。移动 HEAD 的 reset 仍需先获得用户明确授权；符合合并条件的提交可直接 amend，无需授权；git restore --staged 也无需授权。参见 references/staging-and-recovery.md。

当请求范围更窄时

并非每次调用都是完整的“请提交”。请跳转到相关参考文档：

• 仅需提供回复的任务给出了所表示的仓库状态，并要求不要检查或修改当前检出目录 → 将提供的暂存、未提交更改、验证、权限和历史事实视为目标状态。展示适用的完整决策和命令门槛，但不要执行；不要用空的评估沙箱替代所表示的更改，也不要声称所表示的命令确实运行过。
• “我暂存的内容对吗？”，“检查已暂存内容”、拆分提交、删除误加的文件 → references/staging-and-recovery.md
• “这个文件已提交，但不该提交”，撤销/取消暂存、修正错误的文件集合、恢复丢失的工作 → references/staging-and-recovery.md
• 修复上一次提交、修订、重写提交说明、添加/修正 Co-Authored-By、修复多行提交说明损坏 → references/history-and-trailers.md
• 重写历史必须跨多个提交丢弃或删除路径（而不只是修复尾注）→ references/history-and-trailers.md
• “我应该提交什么/排除什么？”，排除生成文件或机密文件 → references/file-selection.md
• “提交已暂存的更改” → 不要臆造额外的暂存操作，但在提交前仍须执行强制的已暂存文件集合检查，并在提交后验证已存储的提交。
• “显示准确的提交命令”或“只要提交命令” → 包含准确的 git commit ... 调用，但不要将答案缩减为这一行。安全的产物应是命令序列：验证已暂存文件集合、提交命令，然后验证已存储的提交说明/文件集合。简单的文档提交和仅修改尾注的提交也不例外。
• 用户提供了 git status、git diff 或 git log 摘录 → 将其视为证据，但仍须在命令序列中运行或展示相应的检查命令。不要根据用户提供的摘录直接开始暂存、提交、修订或拆分。
• 提交主题需要证据 → 在展示可执行的 git commit 命令前，先选择具体的 Conventional Commit 主题；否则就停在提交命令之前。即使用户意图较宽泛，也要采用用户提供的信息：具名的功能、错误修复、模块或行为变更，足以作为保守的主题。不要仅为让主题更精确，就把可用的宽泛主题推迟到未来查看差异后再定。如果唯一证据是路径/状态，且没有提供任何行为或修复类别，则先检查 git diff 或 git diff --cached；在仅提供命令计划的回复中，展示该检查步骤，并在能够写出具体主题前省略 git commit。提交命令块中的主题若含有尖括号文本、未解决标记用词，或要求稍后填写主题的指示，即使说明文字称不要运行，该命令仍然无效。
• 需要部分暂存 → 使用针对具体文件的差异验证两边：用 git diff --cached <file> 检查要提交的代码块，用 git diff <file> 检查有意保留在本地的代码块。提交前明确展示这两个验证命令；说明文字或 git status 不能替代它们。
• 用户指定的路径未出现在 git status 中 → 在作出决定前运行 git check-ignore -v <path> 检查。如果该路径被忽略，尤其是本地配置或类似机密的数据，不要仅因用户指定了该路径就强行添加；应说明，除非在了解忽略规则后获得明确覆盖指示，否则无法完全提交所请求的范围。