当 AI 也成为提交者：ThinkFlow 的 Git 提交规范，是怎么定的

在 ThinkFlow 项目里，AI Coding Agent 已经不只是"辅助补全"的角色了。它会从 main 切分支、改实现、跑测试、提 PR。人写的提交和模型写的提交，逐渐混在同一个历史里。

这带来一个过去没有的问题：当你三个月后回看一个 commit，你可能分不清------这段逻辑是谁设计的？为什么选了滑动窗口而不是固定过期？这个局限是不是当时就已知的？

Conventional Commits 回答了"改了什么"，但没回答"谁改的、怎么想的、还有什么没做完"。

我们因此整理了一份 ThinkFlow Git 提交规范。它同时约束人类开发者和 AI Agent，整体偏严格------强制开分支、禁止直推主干、人工收口合并。目的不是把流程搞复杂，而是让机器产生的工作也能被审计、被回滚、被信任。

下面把它拆开看。

---

一、九章在管什么（一表看懂）

章节	管的事	关键约束
1. 分支管理	从哪切、叫什么	agent/<task-id>-<desc>，禁止直推 main
2. Commit 格式	message 怎么写	Conventional Commits + 4 个 Agent trailer
3. Atomic Commit	一个 commit 多大	单一语义、可编译、可回滚
4. Checkpoint	长任务怎么留痕	[WIP] 草稿，PR 前 rebase 整理
5. 提交前检查	出门自检	8 项 checklist
6. 禁止提交内容	红线	密钥 / 依赖 / 构建产物 / 大文件
7. PR 流程	怎么合并	模板 + 人工 merge
8. 多 Agent 并发	并行隔离	强制每 Agent 一个 worktree
9. 自检清单	总览	14 项速查

---

二、最值得讲清楚的几个设计

1. Agent Trailer：给每次提交装个"黑匣子"

规范里最有 ThinkFlow 特色的设计，是 commit message 末尾的四个 trailer：

• Agent-Task：原始任务或任务 ID
• Agent-Model：用了哪个模型
• Agent-Decision：关键设计决策及理由
• Agent-Limitation：已知局限或后续 TODO

它要求 Agent 在每次提交时交代四件事：在干啥、是谁干的、为什么这么干、还有什么没干完。这相当于给机器的工作留了一份可回放的记录------出问题时翻 commit 就能还原当时的决策上下文。

我尤其看重 Agent-Limitation。Agent 的提交常常"看起来很完整"，但只有它自己知道哪里还有坑。强制把局限写进去，等于逼它诚实，也帮后续维护者少踩雷。

而且这四个字段是机器可检索的：

git log --format='%(trailers:key=Agent-Task,valueonly)'
git log --grep="^Agent-Task:" --all

一行就能把某个 Agent 任务的来龙去脉拉出来。这是规范顺手埋下的"可观测性"接口。

2. 分支即隔离：强制开分支、禁止直推主干

和"允许直推 main"的宽松流派不同，ThinkFlow 选了严格一侧：所有任务必须从最新 main 切出 agent/<task-id>-<desc> 分支，禁止直接 push 到 main/master，也禁止在已有分支上叠不相关任务。

为什么偏严？因为 Agent 没有"我已经在这个分支上干了一半"的上下文记忆，最容易把一个无关任务顺手塞进当前分支。用固定前缀 + task-id，一是可追溯（每个分支对应一个任务），二是便于后续清理和 review。

分支命名的正反例写得很直白：

正确：agent/PROJ-234-refresh-token-rotation
正确：agent/ISSUE-456-fix-login-redirect
错误：fix-bug          # 缺 agent/ 前缀和 task-id
错误：agent/my-work    # task-id 不可追溯

3. Checkpoint：长任务先打草稿，交卷前再整理

超过 15 分钟的任务，规范要求在关键节点打 [WIP] checkpoint：模型 / 接口定义完、核心逻辑完、测试完、文档完，各留一个存档。

价值在于容错：Agent 跑长任务随时可能断、被中断或上下文爆掉。每个节点留一个可编译的 WIP，至少能从最近的节点续上，而不是从头来。

但 WIP 是草稿不是终稿。任务完成、建 PR 前必须 rebase -i 把一堆 [WIP] squash 成有语义的提交，并保证每个保留的 commit 仍带齐 Agent trailer。同时立了一条铁律：已共享的远程分支不得擅自 force push。

4. Atomic Commit：可回滚是一切的前提

规范反复强调"一个 commit 对应一个逻辑变更""每个节点可编译、测试可通过"。对 Agent 尤其关键------它常一口气改了模型、服务、接口、测试。不拆，回滚一个 bug 就要连带 revert 一大片无关改动；拆细了，git revert 才是精准的。

推荐按"领域对象 → 实现 → 接口 → 测试"切：

feat(auth): add RefreshToken domain model and repository interface
feat(auth): implement JWT refresh token issuance in AuthService
feat(auth): expose POST /auth/refresh endpoint
test(auth): add unit tests for refresh token rotation logic

5. 多 Agent 并发：用 worktree 做物理隔离，人工收口

当多个 Agent 并行，规范强制每个 Agent 一个独立 git worktree，文件操作互不污染。这是被"两个 Agent 同时改公共模块导致冲突"教育出来的。规则里还有一条很实在：公共接口变更必须同步更新所有消费方。

最后一道闸在 PR：Agent 不得自行合并自己的 PR，merge 由人工触发。这条是人和 AI 之间的责任边界------机器可以干，但合不合并、什么时候合，由人拍板。

---

三、红线清单：碰了没有"下次注意"

• API keys、tokens、passwords
• .env、.env.local、*.local 等本地配置
• node_modules/、__pycache__/、.venv/ 等依赖目录
• dist/、build/、.next/ 等构建产物
• 大于 1 MB 的二进制（用 Git LFS）
• 临时调试代码、被注释掉的测试用例

Agent 最容易干的蠢事，是"为了跑通临时塞个 token 进去测一下"，然后顺手 commit。这条红线，就是防你的密钥明天出现在泄漏推送里。

---

四、这套规范真正解决什么

它不追求"好看"，而是解决 AI 协作里的三个具体痛点：

• 可追溯：task-id + Agent-Model，知道哪段代码是哪个模型在什么任务下写的。
• 可解释：Agent-Decision 把设计理由固化，降低后续维护的猜测成本。
• 可收回：Atomic + 自检清单，保证任何时候都能干净回滚或拆分。

而贯穿始终的一条原则是：人始终握着 merge 的按钮。

---

下面是这份规范的完整原文，可直接复制落地 👇

---

# ThinkFlow Git 提交规范

本文档整理自项目当前的 `AGENTS.md`，用于开发者和 AI Coding Agent 执行 Git 提交、分支管理与 PR 协作。

## 1. 分支管理

- 所有任务必须从最新的 `main` 切出新分支。
- 禁止在已有分支上叠加不相关任务。
- 禁止直接 push 到 `main` 或 `master`。
- 分支命名格式：

```text
agent/<task-id>-<brief-description>
```

正确示例：

```text
agent/PROJ-234-refresh-token-rotation
agent/PROJ-301-migrate-postgres-schema
agent/ISSUE-456-fix-login-redirect
```

错误示例：

```text
fix-bug          # 缺少 agent/ 前缀和 task-id
agent/my-work    # task-id 不可追溯
```

## 2. Commit Message 格式

每个 commit 必须遵循 Conventional Commits，并包含 Agent 专属 trailer。

```text
<type>(<scope>): <summary>

<正文：描述变更背景、内容与动机>

Agent-Task: <原始任务描述或任务 ID>
Agent-Model: <使用的模型>
Agent-Decision: <关键设计决策及理由>
Agent-Limitation: <已知局限或后续 TODO>
```

### 常用 type

- `feat`：新增功能
- `fix`：修复缺陷
- `refactor`：不改变外部行为的重构
- `perf`：性能优化
- `test`：新增或调整测试
- `docs`：文档修改
- `style`：不影响逻辑的格式或样式调整
- `build`：构建系统或依赖调整
- `ci`：CI/CD 配置修改
- `chore`：其他维护性变更
- `revert`：回滚已有提交

### 完整示例

```text
feat(auth): implement JWT refresh token rotation

Add sliding-window refresh token support to reduce re-login friction
while maintaining session security.

Agent-Task: PROJ-234 - Add refresh token support to auth service
Agent-Model: gpt-5
Agent-Decision: Used a 7-day sliding window and stored refresh tokens in httpOnly cookies to reduce XSS exposure.
Agent-Limitation: Redis TTL is not yet aligned with token expiry on logout.
```

### 查询 Agent 提交历史

```bash
git log --format='%(trailers:key=Agent-Task,valueonly)'
git log --grep="^Agent-Task:" --all
```

## 3. Atomic Commit 原则

每个 commit 只表达一个可解释、可回滚、可验证的语义变化。

- 一个 commit 对应一个逻辑变更。
- 每个 commit 节点的代码都应可编译、测试可通过。
- 不要把重构和功能修改混在同一个 commit。
- 不要把多个不相关模块的改动混在同一个 commit。
- 一个逻辑上不可分割的改动可以跨多个 package。

推荐拆分：

```text
feat(auth): add RefreshToken domain model and repository interface
feat(auth): implement JWT refresh token issuance in AuthService
feat(auth): expose POST /auth/refresh endpoint
test(auth): add unit tests for refresh token rotation logic
```

不推荐：

```text
feat(auth): implement refresh token
```

如果该提交同时包含大量模型、服务、接口和测试代码，将难以审查与回滚。

## 4. Checkpoint Commit 策略

预计耗时超过 15 分钟的任务，应在关键节点创建 checkpoint commit：

1. 完成数据模型或接口定义。
2. 完成核心逻辑实现。
3. 完成测试编写。
4. 完成文档更新。

Checkpoint commit 的 message 以 `[WIP]` 开头：

```text
[WIP] feat(auth): draft refresh token domain model
```

任务完成、创建 PR 前，应整理提交历史：

```bash
git log --oneline main..HEAD
git rebase -i main
git log --oneline main..HEAD
```

整理要求：

- 将 `[WIP]` checkpoint commit squash 成有意义的语义提交。
- 保证最终每个 commit 都能独立理解和回滚。
- 每个保留的 commit 都包含 `Agent-Task`、`Agent-Decision` 等 trailer。
- 已推送的远程分支禁止擅自 force push，除非已确认无人使用。

## 5. 提交前检查

提交前必须确认：

- 当前分支符合 `agent/<task-id>-<description>` 格式。
- 没有直接在 `main` 或 `master` 上开发或推送。
- 只暂存本次任务相关文件，避免使用未经核对的 `git add -A`。
- Commit message 符合 Conventional Commits。
- Commit 包含 `Agent-Task`、`Agent-Model`、`Agent-Decision`、`Agent-Limitation`。
- 每个 commit 都是单一逻辑变化，且可编译、可验证、可回滚。
- 没有混入无关的用户本地修改。
- 已运行与改动风险相匹配的构建、测试或静态检查。

## 6. 禁止提交的内容

以下内容禁止进入任何 commit：

- API keys、tokens、passwords。
- `.env`、`.env.local`、`*.local` 等本地配置。
- `node_modules/`、`__pycache__/`、`.venv/` 等依赖目录。
- `dist/`、`build/`、`.next/` 等构建产物。
- 大于 1 MB 的二进制文件；需要时应使用 Git LFS。
- 临时调试代码。
- 被注释掉的测试用例。

敏感配置必须通过环境变量或项目批准的安全配置方式注入。

## 7. PR 流程

- 使用项目指定模板：`.github/pull_request_template/agent.md`。
- 确保相关 CI 检查通过后再请求 review。
- Agent 不得自行合并自己的 PR，merge 由人工触发。
- 不得直接 push 到 `main` 或 `master`。

PR 描述必须包含：

```text
## Task Description
## What Changed
## Key Design Decisions
## Alternatives Considered
## Test Coverage
## Known Limitations
## Review Guidance
```

## 8. 多 Agent 并发规则

多个 Agent 并行开发时，每个 Agent 必须使用独立 worktree：

```bash
git worktree add ../agent-task-234 -b agent/PROJ-234-refresh-token
git worktree add ../agent-task-301 -b agent/PROJ-301-pg-migration
git worktree list
```

规则：

- 一个 Agent 对应一个 worktree。
- 文件操作限制在各自 worktree 内。
- 避免多个 Agent 同时修改同一个公共模块。
- 公共接口变更必须同步更新所有消费方。
- 任务完成且 PR 合并后清理 worktree。

## 9. 快速自检清单

- [ ] 分支名符合 `agent/<task-id>-<description>`。
- [ ] 分支从最新 `main` 创建。
- [ ] 未直接 push 到 `main` 或 `master`。
- [ ] Commit message 符合 Conventional Commits。
- [ ] Commit 包含全部 Agent trailer。
- [ ] 每个 commit 是单一逻辑变化。
- [ ] 代码在该 commit 节点可编译、测试可通过。
- [ ] 未提交密钥、本地配置、依赖目录或构建产物。
- [ ] 未混入用户无关修改。
- [ ] PR 描述按模板填写完整。
- [ ] CI 检查通过。
- [ ] 长任务的 WIP commit 已在 PR 前整理。
- [ ] 未擅自 force push 已共享的远程分支。
- [ ] Agent 未自行合并 PR。

---