AI越来越智能了，他能操作git，帮你自己使用git提交和推送代码，但是有时候，他直接一堆一起提交，没有采用原子化的方式来操作，wdp-git 是一个 Claude Code skill，它把"提交 → 发布说明 → 评审 → 推送"的 git 日常，实现为一条带断言校验、带安全底线、可配置 的七步流程。它不是文档，是一份可执行的过程规范。一起来看看是否对你有用~
1. 问题域：git 提交流程为什么值得"工程化"
git 的对象模型有三个特性，决定了提交流程的成本结构：
- 内容寻址且不可变：commit 对象的 SHA 由内容 + 父指针 + 元数据哈希得出，一旦创建，历史不可篡改（想改只能"另起一条新历史"）。
- DAG 拓扑：提交通过 parent 指针连成有向无环图。
- 可派生语义 ：
git log、git bisect、git revert、git blame全部建立在"提交是原子的、每个提交可独立理解"这一假设上。
于是"提交是否整洁"直接决定后续所有 git 操作的成本：
| 提交质量 | git bisect 二分 | revert 定点回滚 | 逐 commit 评审 |
|---|---|---|---|
| 一提交一事 | 一次定位到根因提交 | 精确回滚一个功能 | 每个提交可独立评审 |
| 一提交混杂 | 二分到的常是"无关提交" | 回滚牵一发动全身 | 被迫看全量 diff |
所以"分批提交"不是洁癖，而是让历史 DAG 变得可被机器分析的前提。wdp-git 的整个流程，都围绕"产出原子提交（atomic commits）"设计。
2. 为什么用 skill 承载这套流程
skill 的机制本质是：在模型上下文里注入一份确定性的过程规范，让 LLM 作为灵活的解释器去执行。几个工程细节：
- description 是语义检索触发器。模型在每轮都会读 description 判断"是否加载该 skill"，所以 description 只写触发条件、不写流程摘要------否则模型可能照着 description 走捷径，跳过正文里的强制步骤。这是 skill 加载机制层面的一个已知陷阱（SDO，Skill Discovery Optimization）。
- 渐进式披露（progressive disclosure） 。SKILL.md 控制在约 200 行，把前缀表、模板等重内容下沉到
references/按需加载。原因很工程：skill 被加载就占用上下文 token，频繁使用的 skill 必须保持低常驻成本。 - 与 hook / 插件 / slash 命令的边界。hook 在 harness 层拦截事件，无模型参与，适合机械校验；插件扩展工具集；而 skill 承载"需要语义判断的流程"------本 skill 中大量"读 diff → 分类 → 确认 → 提交"环节依赖语义判断，这正是 skill 的适用域。
另一个硬约束塑造了整体设计：本环境不支持交互式 git 命令 （git rebase -i、git add -p、git commit -i 需要 TTY 交互，无法在 Claude Code 中模拟）。所有环节因此必须用非交互等价操作实现，详见 4.3。
3. 七步流程 = git 状态机上的受控转换
git 的工作区可以看作一条四态状态机：
工作区(dirty) → 暂存区(index) → 本地历史(HEAD) → 远程历史(origin)wdp-git 的七步就是这条链上的受控迁移，每一步都带前置条件检查与后置断言：
| 步骤 | 状态迁移 | 前置条件 | 后置断言 |
|---|---|---|---|
| 0 环境检查 | --- | 在仓库内、非分离 HEAD | 分支 / 远程信息明确 |
| 1 分析与分组 | --- | 有变更、已过安全扫描 | 产出分组方案表格 |
| 2 确认方案 | --- | 方案存在 | 用户明确批准 |
| 3 分批提交 | dirty→index→HEAD（逐组） | 暂存内容与方案一致 | git log 展示 N 个原子提交 |
| 4 发布说明 | 新增 / 更新文件 | releasenotes 聚合完成 | 以 docs(release) 提交入库 |
| 5 评审闸门 | --- | 提交完成 | 评审决策明确 |
| 6 推送 | HEAD→origin | 工作区干净、不落后 | 推送成功 |
三层核实机制对应三处"断言"，这也是"分类凭什么可信"的工程答案：
- 归类断言 ：逐文件读
git diff，按 hunk 的实际语义归类。diff 是真实变更的唯一可靠载体------文件名会撒谎（rename、重构、脚手架），分类必须基于内容。 - 方案断言：分组表交用户确认。用户对业务语义拥有最终解释权，AI 是提议者而非决策者，这个断言必须是人给的。
- 暂存断言 ：每组
git add后执行git diff --cach ed --stat，校验"将要进 HEAD 的内容"与方案逐项一致，不一致则git reset回滚重新暂存。这一步把暂存区当作可校验的中间产物，防止 add 错文件产生不可预期的提交。
4. 提交规范的技术设计
4.1 前缀系统 = 提交流的"类型系统"
feat / hotfix / bugfix / docs / refactor / perf / test / style / chore / release 构成对提交做静态分类的类型系统。收益不仅是可读性，还有可编程性：
- 可过滤 ：
git log --grep="^feat"即得全部特性增量； - 可编排：CI 可按类型触发不同流水线（feat → 测试+构建，docs → 只发布文档）；
- semver 联动 ：
feat → MINOR、bugfix → PATCH、BREAKING CHANGE → MAJOR的映射使版本号推断可自动化，release notes 维护（第 5 节）直接受益。
前缀约定默认值写死在 references/commit-conventions.md，可按项目改。
4.2 提交信息格式
<type>(<scope>): <主题>
<正文（可选）：为什么改、影响面>
<BREAKING CHANGE: ...（仅破坏兼容时）>- 主题 ≤ 50 字符：保证
git log --oneline单行可读； - scope 模块化：历史可按模块过滤；
- 正文写动机，不写改动------"改了什么"已经在 diff 里，commit message 的价值在于补足 diff 说不出的"为什么"。
4.3 禁用交互式命令的非交互替代
git add -p 不可用后，同一文件含多类改动时的 hunk 级拆分改用纯管道：
bash
git diff -- <file> > /tmp/f.patch # 1. 导出全量补丁
# 2. 人工筛选出目标类别的 hunk（过滤/编辑 patch）
git apply --cached /tmp/f.patch # 3. 只写入 index，不动工作区git apply --cached 是核心：它把补丁只写进暂存区、保持工作区不变，与 git add -p 行为等价，但全程无需 TTY。拆分过于复杂时，skill 的兜底策略是归入主导类别并在正文说明------不为完美拆分引入新的错误面。
4.4 中文路径的编码问题
git 默认 core.quotepath=true，非 ASCII 路径在输出中会被转义成八进制（如 "\346\226\207\344\273\266.txt"），导致中文文件名在 status/diff 中不可读。skill 统一以 git -c core.quotepath=false 调用输出类命令------这是展示层的编码修复；否则"按文件名归类"在中文项目里会直接失效。
5. releasenotes.md 自动维护：从提交图到发布说明
维护的本质是一次聚合变换：
commit graph（本次 N 个原子提交）
→ 按 type 聚类（feat→✨新增 / hotfix→🚀优化 / bugfix→🐛修复）
→ LLM 语义改写（commit message 面向开发者 → release notes 面向使用者）
→ 增量插入（最新区段置顶）
→ 单独提交 docs(release)三个技术要点：
- "面向用户语言重写"只能由 LLM 完成：commit message 是给开发者的（"重构认证模块"），release notes 是给使用者的（"现在可以保持登录更长时间"）。这是纯规则代码做不好的语义转换，也是 skill 选型（而非 hook）的另一个理由。
- 版本号推断 ：
git tag --sort=-v:refname按语义化版本排序取最新 tag，据此建议下一个版本号；无法确定时降级为[Unreleased]。原则是拿不准就问用户，不让自动化生成错误的版本语义。 - 增量可发布状态（incrementally releasable）：每次流程结束，仓库都处于"releasenotes 已反映全部未发布变更"的状态。发布动作因此被简化成一个纯 tag 操作，杜绝"发布前突击补 notes"。
在这里插入图片描述
6. 评审闸门：把 review 前移到变更成本最低点
git 有一个关键成本模型：
已推送 commit 的修改成本 ≫ 未推送 commit 的修改成本- 未推送 ：
--amend/reset --soft直接改写，历史保持线性； - 已推送 ：改写必须 force-push，会破坏协作者基于旧 SHA 的工作（共享分支上被禁止），唯一安全路径是
git revert追加新提交。
所以评审必须发生在推送前------这正是 skill 把闸门放在第 5 步（提交后、推送前）的动机。
评审范围用 upstream tracking 精确界定：
bash
git diff @{u}...HEAD@{u} 解析为上游分支引用；A...B 是三点语法（merge-base 到 B 的差异）。该表达式的语义恰好是"这次推送会引入的全部变更"------评审该看的内容，不多不少。
闸门通过 AskUserQuestion 提供四档（完整代码评审 / 安全评审 / 两者 / 跳过）。评审发现的问题以新提交修复------不 amend 已展示的提交，保持历史原子性与可复述性。
7. 安全与边界：把 git 的破坏面显式封住
历史不可变性决定了"错误一旦推送，几乎不可撤销"，因此安全底线被写成硬性原则：
- force-push 风险模型 ：
--force无条件覆盖远端任何状态；--force-with-lease带乐观锁（仅当远端自上次 fetch 以来未变化才覆盖，防止覆盖他人刚推送的提交）。skill 默认完全禁止 强推，仅在用户明确要求且目标非保护分支时，才允许--force-with-lease。 - 敏感信息扫描 ：提交前对每个文件跑凭据特征检测（私钥头、
AKIA[0-9A-Z]{16}式 key、.env/*.pem等模式）。理由同样源于不可变性：密钥一旦进历史，光删文件没用，必须git filter-repo式重写历史才能清除------这是最贵的善后，只能前置拦截。 - 保护分支拦截：main / master 上直接提交会触发 AskUserQuestion，引导先建功能分支。把"共享主干不可直接写"的工程铁律强制化。
- 撤销与补救的边界 ：
--amend、reset --soft只允许作用于未推送提交；已推送改动一律走revert。整个 skill 遵循同一原则：可逆操作优先，重写历史必须有明确授权。
8. 可定制架构：约定数据与流程分离
skill 用"两级配置"应对不同项目的差异：
SKILL.md 流程层（骨架，基本不动）
references/commit-conventions.md 约定层（前缀表/格式/分支命名 → 可改）
references/release-notes.md 约定层（模板/版本规则 → 可改）覆盖优先级：仓库显式规范 > 本项目约定表 > 通用兜底。skill 在流程起始会先读 CLAUDE.md / .gitmessage / CONTRIBUTING.md，有则优先遵循------保证进入陌生仓库时"按仓库的规矩办事"，而不是强行推行自己的规范。这是 convention-over-configuration 原则的体现。
9. 效果：一套流程换来的确定性
把流程跑起来后，拿到的不是"更干净的 log"，而是可验证的确定性：
- 历史可追溯：一提交一类一事，按前缀可检索、可过滤、可 bisect；
- releasenotes.md 永不欠账：每次提交自动聚合，发布时打开即用；
- 质量前置：评审从可选项变成必选项，问题在进主干前被抓住；
- 结果一致性：同一指令，无论谁来执行，产出同一套规范------流程被编码进上下文，而不是依赖个人习惯。
10. 使用指南
安装
源文件在 wdp-skills/wdp-git/，通过软链接注册到 ~/.claude/skills/wdp-git/（与 wdp-agi 同一管理模式）。改源文件即改即生效，无需重新安装。
触发
text
/wdp-git ← 斜杠命令
"提交并推送" / "commit" / "push" ← 自然语言
"整理提交记录" / "更新 release notes" ← 专项指令一次完整演示
假设 6 个文件待提交，涉及登录、编辑器、接口三块：
| 步骤 | 动作 | 产出 |
|---|---|---|
| 0 环境检查 | 确认仓库 / 分支 / 远程 | 就绪信息 |
| 1 分析与分组 | 读全部 diff，按内容归类 | 分组方案表 |
| 2 确认方案 | AskUserQuestion | 用户批准 |
| 3 分批提交 | 三组各 add → 核对暂存 → commit |
3 个原子提交 |
| 4 发布说明 | 聚合改写、置顶、单独提交 | releasenotes.md 更新 |
| 5 评审闸门 | 询问并执行 code-review / security-review | 评审结论 |
| 6 推送 | 落后先 rebase，无上游 -u |
推送成功 |
定制
改 references/commit-conventions.md（前缀/格式/分支命名）与 references/release-notes.md（模板/版本规则），改文件即生效；仓库内若有自己的规范文件，会自动优先生效。
结语
wdp-git 的本质，是把"资深工程师提交代码时的所有下意识动作"------分类、核实、防呆、评审、安全------翻译成 AI 能严格执行的规范流程。git 不会替你做决定，但一份好的过程规范，能让每一次提交都不再靠运气。技术上的每一个取舍，都服务于同一个目标：让历史 DAG 可分析、让变更可追溯、让错误可撤销。
关注回复：需要skill，私信免费发送skill技能包。