Skip to content

xinetzone/SpecWeave / .agents/skills/atomic-commit-cmd

atomic-commit-cmd

Verified

当用户提到'提交'、'commit'、'原子提交'、'代码提交'、'提交代码'、'提交变更'、'git commit'、'保存更改'时,必须使用此技能。提供Git原子化提交规范执行能力:检查变更(三查暂存法)→预提交验证→构建提交信息→执行提交→验证结果。遵循Conventional Commits规范,确保单次提交单一职责。不要直接git commit——本Skill封装了预检查、三查暂存验证、提交信息格式和验证流程。

Atomic-Commit 原子提交命令 Skill

⚠️ 本Skill是命令入口门面(L1索引层),遵循渐进式披露三层架构:

1. Skill ID

atomic-commit-cmd

2. 功能描述

提供Git原子化提交执行能力,确保单次提交遵循单一职责原则:

方案推荐场景优势
标准原子提交⭐ 日常代码/文档提交完整预检查+规范信息格式
快速提交⭐ 小改动/紧急修复跳过非必要检查(仍需基本验证)
提交前CI检查⭐ 重要功能/重构提交运行完整CI检查套件

核心功能:检查变更范围→执行预提交验证→构建规范提交信息→执行提交→验证结果。

为什么用本Skill而非直接git commit? 直接commit容易混入无关文件、提交信息不规范、跳过必要检查;原子提交确保每次提交只做一件事、提交信息说明"为什么"而非"做了什么"、预提交检查通过后才能提交,保持提交历史清晰可追溯。

3. 何时使用本技能

当用户提到以下任何内容时触发:

  • "提交"、"commit"、"git commit"、"原子提交"
  • "提交代码"、"提交变更"、"代码提交"
  • "保存更改"、"保存一下"、"提交一下"
  • 功能开发完成、Bug修复完成、文档更新完成后

关于触发:任何Git提交操作都应使用本Skill,以确保符合Conventional Commits规范和原子提交原则。如果是原子化拆分后的提交,应配合atomization-cmd完成内容拆分后再提交。

4. 方案选择决策树

需要执行Git提交?
├─ 提交前需要完整CI验证? → 提交前CI检查(运行ci-check.ps1)
├─ 日常小改动/文档更新? → 标准原子提交
├─ 紧急Hotfix修复? → 快速提交(仍需基本链接/格式检查)
└─ 原子化拆分完成后的提交? → 先确认原子化收尾已完成,再标准提交

⚠️ 强制:触发时记录输入参数日志

决策前输出CMD_START日志(session前缀 cmt-YYYYMMDD-<topic>):

[CMD-LOG] | level=INFO | cmd=atomic-commit | step=S0 | event=CMD_START | session=cmt-... | msg=开始原子提交:<简述> | ctx={"files":"...","type":"feat/fix/docs/refactor/test/chore/ci","dry_run":true/false}

为什么决策前必须记录日志? 原子提交涉及文件暂存和提交信息生成,选错提交类型或scope会导致提交历史混乱,CMD_START记录原始输入便于回溯提交决策。

提交类型速查(Conventional Commits):

类型用途类型用途
feat新功能fixBug修复
refactor重构(不改功能)test测试相关
docs文档更新chore构建/工具/依赖
perf性能优化

5. 快速开始

步骤1:读取 [.agents/commands/atomic-commit.md](../../commands/atomic-commit.md) 了解完整流程
步骤2:三查暂存验证(git status --short):
   - 查新增(A):排除__pycache__/*.pyc等构建产物,确认都是本次需要的
   - 查修改(M):确认所有修改属于单一职责范围
   - 查删除(D):确认所有删除记录都已add(注意:git add新目录不会自动暂存旧文件删除!)
步骤3:执行预提交验证(check-links.py、相关检查脚本、单元测试,重要提交运行ci-check.ps1)
步骤4:构建提交信息(格式:type(scope): subject,中文描述"为什么")
步骤5:执行提交(显式git add <每个文件> — 禁止git add .)
   - **提交集必须点名钉死**(暂存区是共享可变状态,核对过≠提交时仍干净,详见 [commit-staging-integrity.md](../../rules/commit-staging-integrity.md)):
     · 首选带文件清单:`python .agents/scripts/git-commit-utf8.py -m "<msg>" <路径…>` —— 该工具在 add 前检测清单外的已暂存文件即中止、add 后校验暂存集必须等于指定集;同时自动处理中文编码
     · 直连 git(无中文 / 子模块 gitlink / 工具不可用):`git commit -F <msg文件> -- <路径…>`
     · 禁止裸 `git commit`:它提交的是「此刻索引里的一切」,会把并发会话的在途工作一并带上
步骤6:验证结果(git log -1确认信息正确无乱码,git status确认无遗漏)
   - **批量提交场景**:全部提交完成后必须重新执行 `git status --short`,若仍有残留变更,回到步骤1分析是否需要追加提交(禁止假设残留是已处理的)

完整RACI矩阵、CI检查清单、提交信息规范详情见L2文档 commands/atomic-commit.md。

为什么禁止 git add .? git add . 会把工作目录中所有变更(包括临时文件、调试日志、敏感配置、无关修改)一股脑加入暂存区,是原子提交原则的最大敌人——它使"一次提交只做一件事"变成不可能。原子提交要求显式指定每个要提交的文件,迫使你在add阶段审查每个变更,从源头防止无关文件混入。

6. 安全检查清单(提交质量门)

  • 变更范围符合单一职责(一次提交只做一件事)
  • 三查暂存验证完成:
    • 查新增(A):无__pycache__/、*.pyc、临时文件等构建产物
    • 查修改(M):所有修改文件都属于本次提交范围
    • 查删除(D):所有删除记录都已显式git add(注意:git add新目录不会自动暂存旧文件删除)
  • 没有无关文件混入提交(明确指定文件,禁止 git add .)
  • 提交集已点名钉死:走了带文件清单的提交入口,或直连 git 时用了 -- <路径…>;没有裸 git commit
  • 点名路径自身无混入:git diff <路径> 过一遍,确认该路径内没有不属于本次的改动(路径级只挡别的路径,不挡同一路径内的无关改动)
  • 索引含他人暂存文件时:已与文件主人确认并摘出(git restore --staged),未使用 --no-verify 绕过钩子
  • 提交信息遵循Conventional Commits格式(type(scope): subject)
  • 提交信息用中文描述"为什么"而非"做了什么"
  • 预提交检查已执行(链接/格式/测试,适用时)
  • 没有提交敏感信息(密钥、密码、token等)
  • vendor/目录变更符合子模块管理规范(不直接提交vendor内容)
  • spec目录白名单检查:
    • 若变更涉及 .trae/specs/ 下已完成/归档状态的spec目录,确认没有将分析报告(analysis-report.md)、任务输出(task*-*.md)、文章内容(article-content.md)等产出物文件遗留在spec目录中
    • 产出物文件必须归档至 docs/ 对应目录,spec目录仅保留过程件与索引:spec.md/tasks.md/review.md(规划三件套)、facts.md/insights.md、e-stage-pattern.md/v-adversarial-review.md(seven-concepts-comprehensive-retro 复盘流程过程件)、README.md/.gitkeep
    • 可运行 python .agents/scripts/check-spec-output-archive.py 快速验证
  • fix类型提交专项检查:
    • 若本次提交包含Bug修复(type=fix),是否包含预防措施(检查脚本/测试用例/规则更新/反模式清单)?
    • 如属于平凡修复(拼写/格式/注释/清理),确认符合豁免条件
    • commit message中注明预防措施类型(如[prevent: test-case])或引用跟踪Issue
  • Windows 平台:
    • commit message含中文/非ASCII时,优先使用UTF-8临时文件法(commit-msg.txt)
    • 提交后用 git cat-file -p HEAD 验证存储字节未乱码
  • 批量提交场景:全部提交完成后重新扫描工作区(git status --short),确认无残留变更或已识别后续处理方式

7. 执行日志(CMD-LOG)

执行原子提交命令集时,必须按 CMD-LOG规范 输出结构化日志:

⚠️ 铁律一(🔴强制):S0 CMD_START 必须是命令集执行后的第一条输出,禁止在CMD_START之前输出任何其他内容(包括调试信息、中间结果)。违反将导致日志链路断裂,CI步骤19(CMD-LOG合规检查)失败。

  • cmd=atomic-commit,session前缀 cmt-YYYYMMDD-<short-hash>
  • 步骤编号 S0-S6(启动→检查范围→预提交验证→构建信息→执行提交→结果验证→推送通知)
  • 关键特有事件:SCOPE_CHECK、UNRELATED_FILES、SENSITIVE_FILE、TEMP_FILE_FOUND、VENDOR_CHANGE、CHECK_FAIL、VERIFICATION_BLOCKED、COMMIT_MSG_BUILT、COMMIT_EXECUTED、COMMIT_FAILED

完整字段说明、20个事件表格、日志示例见L2文档 cmd-log-specification.md §7.5。

8. 提交信息速查

✅ 正确示例:

  • feat(skills): 新增5个命令集Skill门面增强能力发现
  • fix(links): 修复原子化后相对路径错误导致的断链
  • docs(sop): 沉淀三角验证法为可复用SOP文档

❌ 错误示例:update / fix / 提交代码 / 更新了一些东西

为什么提交信息要写"为什么"而非"做了什么"? "做了什么"从git diff就能看出来(如"修改了auth.ts"),但"为什么做"(如"修复JWT过期时间配置错误导致的凌晨登出问题")是三个月后回滚或排查问题时唯一能理解变更意图的线索。提交历史是项目的集体记忆,写清楚"为什么"才能让后来人(包括未来的自己)理解当时的决策上下文。

完整提交类型表见§4决策树,详细规范见L2 commands/atomic-commit.md。

9. Gotchas(陷阱与反直觉行为)

为什么需要Gotchas? 错误处理记录"已知错误码及修复方式",Gotchas记录"容易踩的坑、反直觉行为、容易被忽略的约束条件"——不会产生明确错误码但会导致结果不符合预期的隐性陷阱。

  • Windows中文commit message编码:PowerShell 5默认使用GBK编码,直接在命令行传递中文commit message会导致Git存储时乱码。最佳方案是使用项目已有的 git-commit-utf8.py 工具:python .agents/scripts/git-commit-utf8.py -m "type(scope): 中文描述" <files>,它会自动检测非ASCII字符并通过stdin bytes通道安全提交,还会自动检查暂存区一致性。手动方案是将提交信息写入UTF-8编码(无BOM)的临时文件 commit-msg.txt,使用 -F 参数提交,或升级到PowerShell 7+。
  • git add <新目录>不会自动暂存旧文件删除:这是git最容易踩的反直觉陷阱之一——当你将一个大文件拆分为包目录时,执行 git add new_package/ 只会添加新目录下的文件,不会自动暂存父目录中原大文件的删除记录。必须显式执行 git add deleted_old_file.py 来暂存删除,否则提交后旧文件仍然存在,需要amend修复。
  • git add前检查diff:原子提交要求"一次提交只做一件事",在 git add 之前务必用 git diff 和 git status --short 执行三查验证(新增/修改/删除),避免临时调试文件、pycache、意外修改的配置文件被混入提交——禁止直接使用 git add .。
  • amend只会修改最后一次提交:git commit --amend 只能修改最近一次提交,无法amend更早的commit。如果需要修改更早的提交,必须使用交互式rebase(git rebase -i),操作复杂度显著增加,因此提交前务必通过三查验证确认信息正确。
  • Conventional Commits type必须小写:提交类型必须使用小写(feat/fix/docs/refactor/test/chore/perf),大写开头(Feat/Fix/Docs)不符合规范,会被CI检查拦截。
  • 空提交需要--allow-empty:触发CI流水线但无代码变更时(如重新运行失败的CI),需要创建空提交,此时必须添加 --allow-empty 参数(git commit --allow-empty -m "ci: 触发流水线重跑"),否则Git会拒绝提交。
  • 暂存区是共享可变状态:核对 git diff --cached 与提交之间存在时间窗,期间其它 IDE 窗口、其它智能体会话或自动化脚本都可能往索引里写。核对过 ≠ 提交时干净,故提交集必须路径级点名(详见 commit-staging-integrity.md);核对与提交要紧邻,中间不要插入长等待或切去别的会话干活。
  • 「用了工具」不等于「走了守卫」:git-commit-utf8.py 的「暂存集 == 指定集」守卫只在带文件清单时生效——省略清单它只做编码处理,把当前暂存区原样提交。且它的守卫也只在「校验那一刻」成立(提交调用本身不带路径级指定),因此索引可能被并发写入的仓库里仍需 R2 的路径级点名兜底。
  • 索引被污染时不得用 reset --hard 清场:那会连工作区一起回滚,销毁并发会话尚未提交的在途工作(比误提交严重得多)。正确处置:git reset --soft HEAD~1 → git restore --staged <他人路径> → 路径级重提交。

10. 关键参考

参考层级路径何时查阅
完整命令文档(RACI/参数/CI清单)L2commands/atomic-commit.md每次使用必读
CMD-LOG日志规范L2cmd-log-specification.md日志格式、事件定义、解析方法
Windows中文提交工具L1工具git-commit-utf8.pyWindows平台提交中文必用,自动处理编码,支持-m/-F/--auto
开发规范(提交规范章节)L2docs/development-standards.md确认提交规范
CI检查脚本L1工具ci-check.ps1重要提交前验证
Git忽略验证L1工具check-gitignore.py怀疑有不该提交的文件时
提交暂存区完整性规则L1规则commit-staging-integrity.md每次提交前:确认提交集已点名钉死、核对与提交紧邻、索引污染时的处置

11. Changelog

  • v1.10.0 (2026-10-19): §6 spec目录白名单检查同步复盘流程过程件口径——检查脚本白名单已补入 e-stage-pattern.md/v-adversarial-review.md(seven-concepts-comprehensive-retro 声明的 E 阶段模式萃取与 V 对抗审查过程件,见该 Skill 的 references/repo-conventions.md「2. Spec 目录与产物」),本清单与脚本修复指引随之同步,消除文档与实现的口径漂移。基于 xuanspace 复盘目录(已完成态)因白名单滞后被误判 exit 1 的根因修复。
  • v1.9.0 (2026-10-15): 接入「提交暂存区完整性」规则(commit-staging-integrity.md)——§5 步骤5 改为「提交集必须点名钉死」(首选带文件清单的工具入口,直连 git 用 -- <路径…>,禁止裸 git commit);§6 安全检查清单新增 3 项(提交集点名、点名路径自身无混入、索引含他人暂存文件时的处置);§9 Gotchas 新增 3 条(暂存区是共享可变状态、「用了工具 ≠ 走了守卫」、禁用 reset --hard 清场)。基于 sc-20261015 会话两次实测:一次裸 git commit -F 被并行会话暂存污染(多出 4 个文件)、一次路径级提交成功拦下 1700 行在途改动。
  • v1.8.0 (2026-09-20): 对齐 spec 白名单口径至现行标准——检查脚本白名单补入 review.md(TRAE-spec-mode 规划三件套)与 facts.md/insights.md(工作流声明的过程件),checklist.md 降级为存量兼容命名。清除了 553 次 review.md 类误报(492 项历史告警中 414 项为白名单漂移误报,真实债务 78 项)。基于 492 项历史遗留告警的根因复盘。
  • v1.7.0 (2026-07-13): 新增"spec目录白名单检查"安全项,强制产出物归档至docs/而非遗留在spec规划目录中。配套check-spec-output-archive.py自动化检查脚本(19种产出物命名模式匹配),已集成至ci-check流水线Step 7(当前warn-only,待历史51个遗留spec清理后升级为error)。基于文章分析任务产出物路径错误问题的第一性原理复盘萃取。
  • v1.6.0 (2026-07-06): 新增"批量提交场景重扫描"检查项,解决批量原子提交后工作区残留变更被误判为已处理的隐患。三处同步增强:§5步骤6新增重扫描提示、§6安全检查清单新增批量提交项、L2文档atomic-commit.md步骤5新增第5项验证。基于5次批量原子提交复盘中"4个文件未显示在初始扫描"问题萃取。
  • v1.5.0 (2026-07-05): 新增"fix类型提交专项检查"清单,强制执行"修复即闭环"三阶段SOP(修复→预防→闭环),禁止纯点修复提交。平凡修复(拼写/格式/注释/清理)可豁免但须自查确认。基于SpecWeave 13天全生命周期复盘洞察萃取。
  • v1.4.0 (2026-07-03): 新增"三查暂存法"验证流程(查新增/修改/删除),明确git add新目录不会自动暂存旧文件删除的反直觉陷阱;强化Windows中文提交最佳实践(优先使用UTF-8临时文件法),安全检查清单细化为三查子项和Windows平台双项检查;基于14个大文件批量拆分复盘的经验萃取。
  • v1.3.0 (2026-07-01): 在§4决策树后添加S0 CMD_START强制日志规范,记录触发时的输入参数(files/type/dry_run)便于回溯提交决策;补充第3个Why解释(提交信息写"为什么"而非"做了什么"的原因)。
  • v1.2.2 (2026-07-01): 新增 Windows 编码验证清单项(commit message 含非 ASCII 时必须用 git cat-file 验证存储字节),对应 L2 步骤5 新增 Windows 平台编码陷阱说明与 stdin-bytes 修复方案。
  • v1.2.1 (2026-06-30): 补充Why设计意图解释(禁止git add .的原因),通过质量检查why.explanations≥2要求。
  • v1.2.0 (2026-06-30): 按渐进式披露三层架构重构,将CMD-LOG详细事件表(59行)迁移至L2规范文档,提交类型表压缩为双列,提交示例精简,禁止git add.提示内联到checklist,关键参考表增加层级列。
  • v1.1.0 (2026-06-29): 添加CMD-LOG结构化日志规范,定义20个关键日志事件。
  • v1.0.0 (2026-06-29): 初始版本(Skill门面),基于atomic-commit命令集封装。
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall