增量提交Skill：把多文件改动拆成可追溯的原子提交
核心结论速览
- 增量提交（incremental-commits）是一个面向多文件改动的 Git 提交规划技能，核心方法是「波次（Wave）」拆分：一个逻辑关注点对应一个提交。
- 它明确给出了五层波次模型：类型 → 工厂/构建器 → 合约/API → 基础设施 → 消费者，按依赖顺序自底向上推进。
- 每个波次都要求原子性、可构建性（能通过类型检查）、聚焦性与完整性，避免半成品提交。
- 它同时定义了「巨型提交」和「微提交」两种反模式，帮助团队把握提交粒度的中间地带。
- 适合重构、破坏性 API 变更、涉及 3 个以上文件的功能开发，以及「加依赖并立刻使用」这类需要分层落地的任务。
该技能叫什么？如何一键安装 AI 技能提升开发效率？
基本信息
| 项目 | 内容 |
|---|---|
| 技能中文名 | 增量提交 |
| 技能英文名 | incremental-commits |
| 技能ID | 11872 |
| 技能定位 | 将多文件更改分解为按依赖顺序排列的原子提交 |
它解决什么问题
在真实项目里，一次重构往往牵动类型定义、工厂函数、公共接口、工具函数和应用层代码。如果一次性全部改完再提交，就会得到一个巨大的「refactor: 更新模式系统」提交：无法二分查找定位问题、无法部分回滚、代码评审只能看到一大团差异，历史里也读不出「这个功能是怎么长出来的」。
增量提交技能要解决的正是这个问题：在动手写代码之前，先做提交规划；在写代码过程中，按波次推进，每个波次都能编译、都能独立通过类型检查，最终形成一段「会讲故事」的 Git 历史。
一键安装 AI 技能的思路与步骤
「一键安装」的本质是把这份技能说明交给支持技能机制的 AI 编程助手，让它在后续对话中按此规范工作。通用流程如下（具体命令与入口以官方说明为准）：
- 确认前提：你的 AI 编程助手需要支持自定义技能 / 指令文件机制，并具备读取项目文件、执行命令（如类型检查）的能力。
- 获取技能：通过技能市场、技能仓库或管理后台，按技能ID 11872 或技能名 incremental-commits / 增量提交 检索并安装。
- 放入生效位置：若为文件式技能，通常需要将技能说明写入约定的技能目录或项目内的指令文件位置；具体路径以官方说明为准。
- 验证是否生效：向助手提出一个多文件重构需求，观察它是否先输出「波次规划」（列出文件、按层分组、按依赖排序），而不是直接开始改代码。若能主动给出波次清单并逐波次提交，即说明技能已生效。
- 建立项目约定：在团队内统一提交信息格式（如
feat(scope): 描述），让技能产出的历史风格保持一致。
该技能的主要功能和特点
- 波次拆分模型：提供从类型、工厂/构建器、合约/API、基础设施到消费者的五层参考结构，并说明「并非每个变更都需要所有波次」——简单 bug 修复可能只有一个波次，横切重构可能需要五个。
- 波次质量四要素：原子性（一个逻辑关注点）、可构建性（波次结束后代码可编译）、聚焦性（改动只属于一个层或关注点）、完整性（波次内不留半途而废的工作）。
- 依赖顺序启发法：用一句可执行的判断标准排序——「这个文件导入了什么？」。不导入任何内容的文件排在最前，导入所有内容的文件排在最后。
- 明确的适用边界：用表格给出何时使用波次（单文件修复不用、跨 5 个以上文件的重构要用、破坏性 API 变更要用），避免过度工程。
- 反模式清单：点名「巨型提交」「微提交」「错误顺序」三类典型错误，并解释各自的具体危害（无法二分、噪音过大、波次无法编译）。
- 完整工作流与检查清单：从编码前规划、单波次实现、类型检查验证、常规提交格式到最终 PR，配套开始前 / 每波次 / 全部完成三份勾选清单。
- 分支策略配套：给出在特性分支上逐波次提交、让 PR 呈现功能演进过程的实践方式。
和普通提交习惯相比强在哪：普通做法是「写完再想怎么提交」，技能的做法是「想清楚怎么提交再动手」，把提交规划前置为设计活动的一部分，而不是事后补救。
如何使用该技能？
步骤一：编码前规划波次
先列出本次改动涉及的所有文件，按层分组，再按依赖顺序排序。示例：
types.ts → 不导入任何内容（基础）
factories.ts → 导入 types.ts
contract.ts → 导入 types.ts
converters.ts → 导入 types.ts，可能添加依赖
app/ → 导入以上所有内容
步骤二：逐个波次实现
明确告诉 AI 助手本波次的范围。输入示例：
「现在只做波次1：在 types.ts 中添加 IconDefinition、CoverDefinition 和 FieldMetadata 类型，不要改 factories.ts 和 contract.ts。」
期望输出：仅对 types.ts 的改动，并给出一条符合常规提交格式的提交信息，例如：
feat(schema): 添加IconDefinition、CoverDefinition和FieldMetadata类型
- 添加IconDefinition判别联合（emoji | external）
- 添加CoverDefinition判别联合（external）
- 在所有字段类型中添加带可选名称/描述的FieldMetadata
- 更新TableDefinition以使用icon/cover而不是emoji/order
步骤三：验证波次
运行类型检查（技能中以 bun run tsc --noEmit 为示例，实际命令按你的项目工具链调整），确保本波次没有引入错误。若检查不通过，说明波次切分或顺序有问题，应调整而非强行提交。
步骤四：提交波次
使用常规提交格式，标题说明本波次完成了什么，正文列出具体更改。只 git add 本波次涉及的文件，避免误带无关改动。
步骤五：重复直到所有波次完成
典型的分层推进顺序为：类型 → 工厂 → 合约 → 基础设施 → 消费者。全部完成后做最终类型检查，如适用再运行测试，最后创建带有清晰提交历史的 PR。
步骤六：分支策略
git checkout -b feat/my-feature
# 波次1 改动 → git add <files> && git commit -m "feat(scope): 波次1描述"
# 波次2 改动 → git add <files> && git commit -m "feat(scope): 波次2描述"
# …… 继续波次 ……
完成后，每个波次都是分支上的独立提交，PR 会清晰展示特性是如何演进的。
同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| 增量提交（incremental-commits） | 提交规划方法论型技能 | 五层波次模型、依赖顺序启发法、反模式清单、工作流与清单 | 需支持技能机制的 AI 助手；零额外依赖；以官方说明为准 | 多文件重构、破坏性 API 变更、跨层功能开发 | 优势：方法可迁移、约束具体、能显著改善可评审性；不足：依赖使用者自觉控制波次边界，不提供自动拆分工具 |
| 通用 AI 编程助手（默认模式） | 代码生成与修改 | 直接改代码、生成差异 | 低，开箱即用 | 小改动、单文件修复 | 优势：快；不足：多文件任务常产出一个大提交，缺乏提交规划，历史不可二分 |
| 交互式 Git 暂存工具（如 git add -p） | 提交粒度控制工具 | 按块挑选暂存内容、拆分已有改动 | 中，需熟悉命令行交互 | 事后整理已完成的改动 | 优势：不改工作方式即可细化提交；不足：属于事后补救，无法保证每个中间提交都能编译 |
| 提交信息规范工具（如 commitlint 类方案） | 提交格式校验 | 校验提交信息格式、拦截不合规提交 | 中，需配置钩子与规则 | 团队规范统一 | 优势：格式强制力强；不足：只管「怎么写」，不管「怎么拆」，对提交粒度无约束 |
选型建议：格式规范与波次规划解决的是不同层次的问题，二者可以叠加使用——用规范工具约束提交信息的形状，用增量提交技能约束提交的内容边界。
该技能的典型应用场景与实际体验情况
场景一：模式系统重构（把元数据从工作空间迁移到表）
角色：负责 schema 包的后端/全栈工程师。痛点：改动横跨类型、工厂、合约、转换器和应用层，一次性提交后评审意见集中在「这一大团到底是什么」。
使用方式：按技能给出的真实示例走五个波次——波次1 只改 types.ts 添加判别联合与元数据类型；波次2 只改 factories.ts 让工厂函数接受可选名称与描述；波次3 只改 contract.ts 从 WorkspaceSchema 移除 emoji 与 description；波次4 在 to-drizzle.ts 与 package.json 中引入 slugify 并添加 SQL 列名辅助函数；波次5 更新消费者应用。
实际体验：历史可读性提升最明显，评审者能按波次逐个理解演进路径；注意点在于波次3 这类破坏性变更必须与波次5 同分支推进，中间提交虽然能编译，但语义上处于「接口已变、消费者未更新」的过渡态，需要在 PR 描述中说明。
场景二：破坏性 API 变更
角色：维护公共库的开发者。痛点：接口一改，下游调用方全部报错，无法判断哪些是预期内的连带修改。
使用方式：严格按「类型 → API → 消费者」三段推进，每个波次结束后运行类型检查，把错误收敛在本波次范围内。
实际体验：类型检查成为天然的波次验收标准，错误来源更容易定位；注意不要为了「让检查通过」而提前修改下游文件，否则顺序会退化为自顶向下，导致第一个波次无法编译。
场景三：添加依赖并立即使用
角色：需要引入新工具库的功能开发者。痛点：依赖安装与业务改动混在一个提交里，回滚时难以分离。
使用方式：设置一个「基础设施波次」——只添加依赖和封装辅助函数；再设置一个「使用波次」——在业务代码中调用它。
实际体验：依赖升级或回滚的边界非常干净；注意 package.json 与锁文件应归属基础设施波次，不要散落。
场景四：跨 5 个以上文件的重构
角色：技术负责人。痛点：需要评估风险与工作量，但改动本身混沌一团。
使用方式：先用技能给出的「开始前清单」列出全部文件、按层分组、按依赖排序，把这份清单直接作为任务拆解与工时估算依据。
实际体验：规划阶段的产出即可用于沟通，降低了协作成本；注意事项是要克制「微提交」冲动——一个逻辑变更拆成二十个提交同样是噪音，技能对此有明确警示。
该技能能为用户带来的价值
- 提升可评审性：一个波次一个关注点，评审者可以按提交逐个阅读，评审意见能精确落到某一层，而不是笼统地评价一大团差异。
- 提升可运维性：原子提交带来可二分查找（bisect）与可部分回滚的能力，出问题时能快速定位到具体波次。
- 降低认知门槛：依赖顺序启发法把「先改哪个文件」这种模糊判断，变成「这个文件导入了什么」的可执行问题，新手也能按规则推进。
- 保障中间状态质量：以类型检查作为波次验收标准，避免出现「改到一半无法编译」的中间提交，主分支与 PR 的健康度更高。
- 沉淀团队方法论：五层模型、反模式清单与检查清单可直接作为团队提交规范的一部分，长期看能显著改善仓库历史质量，让 Git 历史从流水账变成可阅读的演进故事。
- 可量化收益方向：提交平均涉及文件数下降、单个 PR 中可独立回滚的提交比例上升、代码评审轮次减少——这些都可以在团队内自行统计跟踪。
常见问题 FAQ
Q1：这个技能怎么安装？需要额外装插件或付费吗？
A：通过支持技能机制的 AI 编程助手，按技能ID 11872 或技能名 incremental-commits（增量提交）检索并安装。若为文件式技能，需要写入约定的技能目录或指令文件位置，具体路径、命令与是否收费均以官方说明为准。技能本身以方法论说明为核心，不引入额外的运行时依赖。
Q2：它适用于哪些情况，什么情况下不该用？
A：适合跨 5 个以上文件的重构、破坏性 API 变更、需要分层落地的多文件功能，以及「添加依赖并马上使用」的任务。单文件 bug 修复不必使用——一个变更一个提交即可；只涉及 1-2 个文件的改动也应谨慎，避免把小任务拆出不必要的波次。
Q3：波次到底拆多细？我怕拆成二十个微提交。
A：判断标准是「逻辑关注点」，而不是「文件数量」。一个波次应该是一个完整、可编译、只属于某一层的逻辑变更。技能的示例中，波次1 只改 types.ts 但包含多个类型的新增，正是这个粒度。若你的提交标题里出现大量「添加 X 类型」「更新 Y 字段」这类碎片，说明拆过头了。
Q4：每个波次都必须能编译吗？会不会做不到？
A：这是技能的硬性要求。可行性来自顺序：自底向上推进，先建基础再改接口，最后改消费者。如果你发现某个波次无法编译，通常是顺序错了（比如先改应用再补类型），需要回头调整波次规划，而不是放宽验收标准。
Q5：和团队现有的提交信息规范、以及 git add -p 这类工具冲突吗？
A：不冲突，层次不同。提交信息规范管「信息长什么样」，git add -p 管「已完成的改动怎么切」，增量提交技能管「改动在写之前怎么规划」。三者可以叠加：先规划波次，再逐波次实现，提交时用规范格式，必要时用暂存工具微调。