Git 集成与提交规范

这是「GSD 全景代码解析」专题的第 35 篇。在本系列中，我们将逐层拆解 Get Shit Done (GSD) 这一 56K+ stars 的 Meta-Prompting 框架，从命令系统到工作流编排，从 Agent 设计到上下文工程，带你一览上下文驱动开发的工程全貌。

---

一、Git 集成总览：将版本控制纳入项目真相源

在 GSD 的架构哲学中，项目的真相源（Source of Truth）不仅包含代码本身，还包含规划状态、执行记录和上下文配置。Git 作为分布式版本控制系统，被 GSD 设计为整个项目生命周期的时间轴基础设施。

1.1 Git 在 GSD 中的三重角色

flowchart TD
    subgraph GitRole[Git 的三重角色]
        direction TB
        R1[代码真相源
Code Source of Truth]
        R2[规划时间轴
Planning Timeline]
        R3[审计线索
Audit Trail]
    end

    R1 -->|版本化代码资产| A[开发工作流]
    R2 -->|版本化计划状态| B[规划工作流]
    R3 -->|不可变操作记录| C[审计与回溯]

GSD 通过 git-integration.md 将 Git 的使用从"代码备份工具"提升为"项目治理基础设施"：

角色	职责	对应文档
代码真相源	所有代码变更的版本化管理	git-integration.md
规划时间轴	.planning/ 目录的状态演进	git-planning-commit.md
审计线索	Agent 操作的完整可追溯记录	audit-trail.md

1.2 为什么 GSD 需要显式定义 Git 规范

传统开发中，Git 的使用往往依赖开发者个人习惯。但在 AI Agent 驱动的开发模式下，这种随意性会带来严重问题：

• Agent 并发操作：多个 Agent 可能同时修改同一文件，需要清晰的分支策略
• 规划状态漂移：.planning/ 中的状态文件如果不被版本控制，会导致"计划与代码脱节"
• 审计需求：AI 生成的代码必须能被精确回溯到生成时的上下文和策略

GSD 的解决方案是：将 Git 规范写成参考文档，让 Agent 像执行代码一样执行 Git 操作。

---

二、分支策略：结构化并行开发

git-integration.md 为 GSD 项目定义了一套完整的分支管理策略，核心目标是在支持并行开发的同时，保证主分支始终可部署。

2.1 主分支保护

GSD 采用 GitHub Flow / GitLab Flow 的变体，对主分支实施严格保护：

flowchart LR
    subgraph MainProtection[主分支保护策略]
        direction TB
        M1[main / master
受保护分支]
        M2[禁止直接推送
No Direct Push]
        M3[必须通过 PR/MR
Pull Request Required]
        M4[CI 检查通过
CI Checks Pass]
        M5[代码审查通过
Code Review Approved]
    end

    M1 --> M2
    M2 --> M3
    M3 --> M4
    M4 --> M5

主分支保护规则清单：

规则	说明	目的
require_pull_request	所有变更必须通过 PR/MR	强制审查，防止误操作
require_status_checks	CI 构建和测试必须通过	保证代码质量门槛
require_up_to_date	合并前必须基于最新主分支	避免隐性冲突
include_administrators	管理员也必须遵守规则	规则面前人人平等
require_signed_commits	推荐签名提交	增强审计可信度

Agent 行为约定：GSD Agent 永远不会直接 git push 到主分支。所有变更都通过功能分支 + PR 的方式提交。

2.2 功能分支命名规范

GSD 要求功能分支使用语义化命名，使分支目的一目了然：

<type>/<issue-id>-<short-description>

类型前缀（Type Prefix）：

前缀	用途	示例
feature/	新功能开发	feature/42-user-auth
fix/	Bug 修复	fix/56-null-pointer
refactor/	代码重构	refactor/63-extract-service
docs/	文档更新	docs/71-api-reference
plan/	规划变更	plan/85-sprint-3-goals
agent/	Agent 工作产物	agent/92-code-review-fixes

命名约束：

• 使用小写字母和连字符（kebab-case）
• 描述不超过 5 个单词
• 关联 Issue ID 时置于类型之后
• Agent 自动生成的分支必须带有 agent/ 前缀

flowchart TD
    subgraph BranchNaming[分支命名决策树]
        B1{变更类型?}
        B1 -->|新功能| B2[feature/]
        B1 -->|Bug 修复| B3[fix/]
        B1 -->|重构| B4[refactor/]
        B1 -->|文档| B5[docs/]
        B1 -->|规划| B6[plan/]
        B1 -->|Agent 产出| B7[agent/]

        B2 --> B8[关联 Issue ID]
        B3 --> B8
        B4 --> B8
        B5 --> B8
        B6 --> B8
        B7 --> B8

        B8 --> B9[简短描述]
        B9 --> B10[完整分支名]
    end

2.3 里程碑分支管理

对于版本发布和长期维护，GSD 定义了里程碑分支（Milestone Branches）：

flowchart LR
    subgraph Milestone[里程碑分支模型]
        direction TB
        M[main] --> F1[v1.0.0]
        M --> F2[v1.1.0]
        M --> F3[v2.0.0]
        F1 --> H1[hotfix/v1.0.1]
        F2 --> H2[hotfix/v1.1.1]
    end

里程碑分支规则：

场景	分支名	生命周期
版本发布	release/v{major}.{minor}.{patch}	从主分支切出，发布后可删除或保留为标签
热修复	hotfix/v{version}-{description}	从对应版本标签切出，合并后打新标签
长期支持	support/v{major}.x	仅对需要长期维护的版本保留

里程碑与 GSD 工作流的映射：

flowchart TD
    subgraph Mapping[GSD 工作流 → Git 分支]
        W1[new-project] --> G1[初始化 main 分支]
        W2[plan] --> G2[plan/ 分支]
        W3[execute] --> G3[feature/ 分支]
        W4[verify] --> G4[PR 到 main]
        W5[deploy] --> G5[release/ 标签]
        W6[audit] --> G6[审计提交历史]
    end

---

三、原子提交：变更的最小可复元单位

GSD 对提交（Commit）的质量要求远高于普通项目。git-integration.md 将**原子提交（Atomic Commit）**定义为版本控制的基本纪律。

3.1 原子提交的定义和重要性

原子提交原则：一个 Commit 应该只包含一个逻辑变更，这个变更要么完整地被应用，要么完全不应用。

flowchart LR
    subgraph Atomic[原子提交原则]
        direction TB
        A1[一个 Commit] --> A2[一个逻辑意图]
        A2 --> A3[一组相关文件变更]
        A3 --> A4[可通过测试验证]
        A4 --> A5[可独立回滚]
    end

为什么原子提交对 AI Agent 至关重要：

1. 精确回滚：当 Agent 生成错误代码时，可以精确回滚到引入问题的前一个 Commit
2. 清晰审查：每个 Commit 的 diff 聚焦单一主题，人类审查者或审查 Agent 更容易理解
3. 自动化验证：CI 可以在每个 Commit 级别运行检查，快速定位问题引入点
4. Cherry-pick 友好：原子 Commit 更容易被挑选应用到其他分支

反模式示例：

# ❌ 非原子提交：混合了功能实现、文档更新和格式化
commit abc1234
  + 实现用户登录功能
  + 更新 API 文档
  + 格式化所有代码文件
  + 修复一个不相关的拼写错误

# ✅ 原子提交：每个 Commit 只做一件事
commit def5678  实现用户登录功能
commit ghi9012  更新 API 文档（登录相关）
commit jkl3456  修复拼写错误

3.2 提交信息规范

GSD 采用 Conventional Commits 的扩展版本，要求提交信息结构化：

<type>(<scope>): <subject>

<body>

<footer>

类型（Type）：

类型	说明	Agent 使用场景
feat	新功能	execute 阶段的功能实现
fix	Bug 修复	debug 或 fix 阶段的修复
docs	文档变更	docs 命令或规划更新
style	代码格式（不影响逻辑）	格式化工具自动提交
refactor	重构	refactor 命令产出
test	测试相关	verify 阶段补充测试
chore	构建/工具变更	依赖更新、配置调整
plan	规划文件变更	.planning/ 目录的更新

Scope 约定：

• planning：.planning/ 目录下的状态文件
• config：配置文件变更
• agent-<name>：特定 Agent 的产出
• 模块名：如 auth, api, ui

Subject 规范：

• 使用祈使句（"Add" 而非 "Added" 或 "Adds"）
• 首字母小写
• 不加句号结尾
• 不超过 50 个字符

Body 规范：

• 解释 "为什么" 而非 "做了什么"（代码本身说明了做了什么）
• 对于 Agent 提交，记录触发命令和上下文信息
• 多行时每行不超过 72 个字符

Footer 规范：

• Refs: #<issue-id>：关联 Issue
• Agent: <agent-name>：记录执行 Agent
• Command: <gsd-command>：记录触发命令

完整示例：

plan(planning): update sprint-3 goals and task decomposition

Update the planning state for sprint 3 after the discuss phase.
Tasks were re-prioritized based on user feedback on API design.

Refs: #85
Agent: gsd-planner
Command: gsd plan --sprint 3 --discuss

3.3 提交粒度控制

GSD 为 Agent 定义了提交粒度的决策框架：

flowchart TD
    subgraph Granularity[提交粒度决策]
        G1{变更规模?}
        G1 -->|单一文件
单一意图| G2[单文件提交]
        G1 -->|多文件
同一意图| G3[多文件提交]
        G1 -->|多意图混合| G4[拆分提交]

        G4 --> G5[git add -p
逐块暂存]
        G4 --> G6[分多次提交]

        G2 --> G7[完成]
        G3 --> G7
        G6 --> G7
    end

粒度控制规则：

场景	粒度建议	工具
单文件单逻辑变更	直接提交	git commit <file>
多文件同一逻辑	一起提交	git add <files>
文件含多个逻辑变更	拆分提交	git add -p
自动生成 + 手动修改	分别提交	两次独立 git add

Agent 自动提交策略：

GSD Agent 在执行工作流时遵循以下自动提交规则：

1. 阶段边界提交：每个 GSD 阶段（Plan → Execute → Verify）结束时自动提交
2. 文件类型隔离：代码变更和规划变更从不混在同一个 Commit
3. 失败回滚：如果某阶段验证失败，自动 git reset --soft 回到阶段开始前的状态

---

四、git-planning-commit.md：规划与版本控制的深度融合

git-planning-commit.md 是 GSD 中一份独特的文档——它定义了规划状态如何被版本化。这是 GSD 将 Git 从"代码管理"扩展到"项目全状态管理"的关键设计。

4.1 规划阶段与 Git 的集成

在传统开发中，规划文档往往是"一次性"的——写完后就与代码演进脱节。GSD 通过以下机制解决这个问题：

flowchart TD
    subgraph PlanningGit[规划与 Git 集成]
        P1[plan 阶段启动] --> P2[切出 plan/ 分支]
        P2 --> P3[修改 .planning/ 状态文件]
        P3 --> P4[阶段性 plan 提交]
        P4 --> P5{规划是否完成?}
        P5 -->|否| P3
        P5 -->|是| P6[PR 到 main]
        P6 --> P7[合并后 plan 分支保留]
        P7 --> P8[执行阶段引用 plan 提交]
    end

集成要点：

1. 规划即分支：每个规划迭代都在独立的 plan/ 分支上进行
2. 规划即提交：规划文件的每次有意义变更都是一次 Commit
3. 规划即引用：执行阶段的 Agent 可以通过 Git 引用精确获取规划时的状态

4.2 计划变更的提交策略

.planning/ 目录中的文件变更需要特殊的提交策略：

flowchart LR
    subgraph PlanCommit[计划变更提交策略]
        direction TB
        C1[计划创建
plan: init sprint goals] --> C2[计划细化
plan: decompose tasks]
        C2 --> C3[计划调整
plan: reprioritize]
        C3 --> C4[计划确认
plan: finalize]
        C4 --> C5[执行启动
feat: implement task-1]
    end

计划提交的粒度：

变更类型	Commit 类型	示例
创建新的规划周期	plan(planning): init <sprint-name>	plan(planning): init sprint-3
分解任务	plan(planning): decompose <goal-id>	plan(planning): decompose GOAL-42
调整优先级	plan(planning): reprioritize <reason>	plan(planning): reprioritize based on API feedback
更新任务状态	plan(planning): update <task-id> to <status>	plan(planning): update TASK-1 to in-progress
完成规划确认	plan(planning): finalize <sprint-name>	plan(planning): finalize sprint-3

计划与代码的关联：

flowchart TD
    subgraph Linkage[计划-代码关联]
        L1[plan: finalize sprint-3
commit: abc1234]
        L2[feat(auth): implement login
commit: def5678]
        L3[feat(auth): implement logout
commit: ghi9012]

        L1 -.->|后续依赖| L2
        L1 -.->|后续依赖| L3
        L2 -->|计划引用| L4[Footer: Plan: abc1234]
        L3 -->|计划引用| L4
    end

GSD 鼓励（但不强制）在功能实现的 Commit Footer 中引用对应的计划提交：

feat(auth): implement user login with JWT

Implement the login endpoint using JWT tokens.
Follows the auth flow defined in the planning doc.

Refs: #42
Plan: abc1234

---

五、工作树管理：规划目录的版本化

.planning/ 目录是 GSD 项目的"第二工作树"——它与源代码同等重要，需要被精心管理。

5.1 .planning/ 目录的 Git 管理

GSD 要求 .planning/ 目录必须被 Git 跟踪，这与传统开发中将计划文档放在 Wiki 或外部系统的做法截然不同：

flowchart LR
    subgraph PlanningTree[.planning/ 目录结构]
        P[.planning/] --> P1[current/
当前周期规划]
        P --> P2[archive/
归档规划]
        P --> P3[templates/
规划模板]
        P --> P4[states/
状态快照]

        P1 --> P1a[sprint-3.md]
        P1 --> P1b[tasks/]
        P2 --> P2a[sprint-1.md]
        P2 --> P2b[sprint-2.md]
    end

目录管理规则：

目录	用途	Git 策略
.planning/current/	当前活动规划	跟踪，频繁提交
.planning/archive/	已完成周期的规划归档	跟踪，归档后只读
.planning/templates/	规划模板和脚手架	跟踪，很少变更
.planning/states/	自动化状态快照	跟踪，由 Agent 自动生成

5.2 状态文件的版本控制

状态文件是 .planning/ 中最特殊的文件类型。它们记录了项目的运行时状态：

# .planning/states/current-state.yml
version: "1.0"
last_updated: "2026-04-24T10:30:00Z"
commit_ref: "abc1234"
current_phase: "execute"
active_sprint: "sprint-3"
completed_tasks:
  - TASK-1
  - TASK-2
in_progress:
  - TASK-3
blocked:
  - TASK-4

状态文件版本控制规则：

1. 每次状态变更都是 Commit：不要累积多个状态变更再提交
2. 提交信息包含触发原因：说明是什么事件导致了状态变更
3. 状态文件与代码同步提交：当任务完成时，代码提交和状态更新应在同一个 Commit 中

flowchart TD
    subgraph StateCommit[状态提交流程]
        S1[任务完成] --> S2[提交代码变更]
        S2 --> S3[更新状态文件]
        S3 --> S4{同一逻辑变更?}
        S4 -->|是| S5[同一 Commit]
        S4 -->|否| S6[分开 Commit]
    end

5.3 忽略规则

.planning/ 目录虽然需要被跟踪，但其中某些文件或子目录应该被忽略：

# .gitignore —— 规划目录相关规则

# 忽略临时规划草稿
.planning/drafts/

# 忽略本地状态缓存（可由 Agent 重建）
.planning/.local/

# 忽略自动生成的日志（保留在 states/ 中的是结构化快照）
.planning/logs/

# 忽略个人笔记
.planning/notes/

# 但保留核心规划文件
!.planning/current/
!.planning/archive/
!.planning/templates/
!.planning/states/

忽略策略原则：

文件类型	是否忽略	原因
规划草稿	是	临时性，可能包含错误信息
本地缓存	是	可由 Agent 重建，不具可移植性
非结构化日志	是	体积大，价值低
个人笔记	是	不属于项目共享知识
结构化状态快照	否	项目运行时状态的一部分
已确认的规划	否	项目真相源的一部分

---

六、Git 工作流实战：从 Plan 到 Commit

让我们通过一个完整的 GSD 工作流，看看 Git 规范如何在实践中运作：

sequenceDiagram
    participant U as User
    participant A as gsd-planner
    participant G as Git
    participant E as gsd-executor

    U->>A: gsd plan --sprint 3
    A->>G: git checkout -b plan/85-sprint-3-goals
    A->>G: git add .planning/current/sprint-3.md
    A->>G: git commit -m "plan(planning): init sprint-3 goals"

    A->>A: 分解任务
    A->>G: git add .planning/current/tasks/
    A->>G: git commit -m "plan(planning): decompose sprint-3 tasks"

    A->>G: git push origin plan/85-sprint-3-goals
    A->>U: 提交 PR

    U->>G: Merge PR
    G->>G: 合并到 main

    U->>E: gsd execute --sprint 3 --task TASK-1
    E->>G: git checkout -b feature/86-task-1-impl
    E->>E: 实现功能
    E->>G: git add src/
    E->>G: git commit -m "feat(auth): implement login
Plan: abc1234"
    E->>G: git push origin feature/86-task-1-impl

    E->>U: 提交 PR，等待审查

---

七、小结

本文解析了 GSD 中 Git 作为项目治理基础设施的核心设计：

1. Git 集成总览：GSD 将 Git 定位为代码真相源、规划时间轴和审计线索的三重角色，超越了传统"代码备份工具"的范畴
2. 分支策略：通过主分支保护、语义化功能分支命名（feature/, fix/, plan/, agent/ 等前缀）和里程碑分支管理，实现了结构化并行开发
3. 原子提交：定义了"一个 Commit = 一个逻辑意图"的原则，配合扩展版 Conventional Commits 规范，让 Agent 的每次变更都精确可追溯
4. git-planning-commit.md：创新性地将规划状态纳入版本控制，通过 plan/ 分支和规划专属 Commit 类型，消除了"计划与代码脱节"的顽疾
5. 工作树管理：.planning/ 目录作为"第二工作树"被显式管理，状态文件与代码同步版本化，同时通过精细的 .gitignore 规则避免噪音

GSD 的 Git 规范揭示了一个深层理念：在 AI 驱动的开发中，版本控制不仅是技术实践，更是项目治理的基础设施。当 Agent 能够像执行代码一样精确执行 Git 操作时，整个项目的演进就变成了一个可审计、可回滚、可理解的时间轴。

---

下一篇预告： 第 36 篇《上下文模板与模式》——解析 GSD 的上下文模板系统：如何通过模板化机制快速生成高质量的 Agent 上下文，以及 GSD 中常用的上下文设计模式与复用策略。