Moltbot(Clawdbot) inspired - Atomic Commit Strategy Skill

原子化提交策略技能

一套严谨的版本控制与迭代开发方法，让你既能保持高频提交，又能确保代码库的稳定性和可追踪性。

核心理念

“一次提交，只做一件事。”

这个原则能带来实实在在的好处：

• 通过 git bisect 快速定位问题
• 安全、精准的回滚操作
• 清晰、易于审查的代码历史
• 快速迭代，且不会引发连锁故障

提交信息格式

遵循约定式提交规范：

<类型>(<范围>): <描述>

[可选正文]

[可选脚注]

提交类型

示例

# 好的示例：原子化、单一目的的提交
fix: honor state dir override in config resolution
feat: add webhook retry with exponential backoff
docs: update API authentication examples
refactor: extract validation logic into utils module
test: add edge cases for date parsing
chore: bump typescript to 5.4.0

# 坏的示例：多功能混杂的提交
fix: various bug fixes and improvements
feat: add new features and fix some issues
update: changes to multiple files

实施规则

规则一：一次提交仅包含一个逻辑变更

提交前，先问问自己：

• 这次提交是否只做了一件事？
• 能否不用“和”（and）这个词，就用一句话描述清楚？
• 如果回滚这个提交，是否只影响一个功能或修复？

出现以下情况时，拆分提交：

• 同时修复一个缺陷并添加一个新功能
• 在重构的同时又改变了行为
• 更新依赖的同时，还修改了使用这些依赖的代码

规则二：类型隔离

每种提交类型都有严格的功能边界：

• fix：不能改变公共API或添加功能。
• feat：必须有清晰的范围；对破坏性变更进行文档说明。
• refactor：不能改变外部行为（测试应能不变地通过）。
• docs：不能包含代码变更（文档注释除外）。
• test：不能修改生产代码。
• chore：不能影响运行时行为。

规则三：提交频率

尽早提交，频繁提交：

• 每个逻辑工作单元完成后
• 在切换到不同任务的上下文之前
• 当现有变更通过测试时

规则四：有意义的历史

每条提交信息应该：

• 标题以小写开头（在类型前缀之后）
• 使用英式祈使语气（用“add”，而非“added”）
• 简洁但有描述性（标题不超过50个字符）
• 适用时引用相关 issue：fix: resolve timeout error (#123)

质量门禁

每次提交前

# 1. 检视暂存的变更
git diff --staged

# 2. 确保是单一逻辑变更
# 自问：“这只是做了一件事吗？”

# 3. 运行相关测试
npm test -- --related  # 或等效命令

# 4. 代码规范/格式检查
npm run lint

提交清单

• 仅包含单一逻辑变更
• 选择了正确的提交类型
• 测试通过（或为新代码添加了测试）
• 未包含无关的变更
• 信息清晰地描述了变更内容

渐进式发布策略

适用于有发布周期的项目：

功能分支 → beta/canary 分支 → stable/main 稳定分支

工作流

1. 开发阶段：高频提交至功能分支。
2. Beta 发布：合并到 beta 分支，使用 -beta.N 标签。
3. 验证阶段：Beta 用户测试；修复以原子化提交继续。
4. 稳定发布：将验证通过的 beta 版本提升为稳定版。

# Beta 发布
chore: prep 2024.3.15-beta.1 release

# 验证后
chore: release 2024.3.15

持续强化模式

安全和稳定性改进应该是：

• 渐进式的，而非整体性的
• 用 fix: harden 前缀清晰标记
• 专注于单一的攻击向量或故障模式

fix: harden file path tra versal checks
fix: harden auth token validation
fix: harden rate limiting for API endpoints
fix: harden input sanitization for user content

文档即产品

文档提交应频繁且同步：

• 每个 feat: 都应有一个对应的 docs:（可在同一 PR 或后续提交中）
• API 变更需立即更新文档
• README、CHANGELOG 和内联注释都是一等公民

目标：约 10-15% 的提交应是文档提交

Git 工作流程命令

交互式暂存（用于拆分提交）

# 暂存特定的代码块
git add -p

# 暂存特定的文件
git add path/to/specific/file.ts

# 取消暂存误加的文件
git reset HEAD path/to/file.ts

修改最近提交（仅在推送前使用）

# 修正最后一条提交信息
git commit --amend -m "fix: corrected message"

# 将遗漏的文件加入最后一次提交
git add forgotten-file.ts
git commit --amend --no-edit

使用二分法查找缺陷

git bisect start
git bisect bad                 # 标记当前提交是有问题的
git bisect good    # 标记已知良好的提交
# Git 会进行二分查找；标记每次结果为好/坏
git bisect reset               # 完成后重置

需避免的反模式

与 AI 辅助开发的集成

使用 AI 编程助手时：

1. 仔细审查 AI 生成的变更后再提交。
2. 如果 AI 的输出涉及多个关注点，将其拆分为原子化提交。
3. 验证每个逻辑单元的测试是否通过。
4. 可用 AI 草拟提交信息，但需确保其准确性。

# 让 AI 建议，但由你来决定提交边界
# AI 可能生成：“Add validation and fix bug and update docs”
# 你应将其拆分为：
#   fix: resolve edge case in date validation
#   feat: add email format validation
#   docs: update validation API examples

成功指标

跟踪以下指标来衡量策略的采用情况：

速查卡

提交公式：
  <类型>(<范围>): <祈使语气描述>

类型：
  fix | feat | docs | refactor | test | chore | perf | style

规则：
  ✓ 每次提交只做一个逻辑变更
  ✓ 遵守类型边界
  ✓ 提交前测试通过
  ✓ 信息清晰且具体

提交前：
  1. git diff --staged （检视）
  2. 这是一件事吗？ （验证）
  3. npm test （验证）
  4. git commit -m "类型: 描述" （提交）

参考资料

• 约定式提交规范
• Git Bisect 文档
• 语义化版本控制