Autopilot Commit

---
name: autopilot-commit
description: 当用户需要提交代码、运行 git commit、或说"提交"时使用。
---

# Git 智能提交工作流

这是一个高效的 Git 提交工具，在提交前自动分析代码改动，调用相关优化技能，并生成高质量的提交信息。

## 核心原则

**信任 AI 的智能判断**：您已经具备强大的代码分析能力，本工具旨在提供框架而非限制您的判断。

**高自由度设计**：React 检测、优化应用、提交信息生成都依赖上下文判断，您可以根据具体情况选择最佳方法。

**简洁高效**：只提供必要的工作框架，避免过度指导。

**并行优先**：Phase 2 中的任务彼此独立，应在同一轮响应中并行发起（多个 Agent 或工具调用）。只有存在数据依赖时才串行等待。某个任务被跳过时不需要等待——直接标记跳过，继续推进。

**假设需要证据**：代码中对外部世界的假设（数据格式、接口行为、环境状态、第三方响应结构）不能仅凭文档或推理确认。提交前必须有运行时证据证明关键假设成立。这条原则贯穿 Bugfix 验证和代码理解测验。

## 上下文感知

autopilot-commit 有两种调用场景，需要智能判断并跳过多余步骤：

- **主链路模式**：当前项目根目录存在活跃 autopilot 状态文件（`.autopilot/runtime/active.ptr` 指向的 `.autopilot/runtime/requirements/<slug>/state.md`，worktree 中位于 `.autopilot/runtime/sessions/<name>/requirements/<slug>/state.md`）且 phase 为 `"merge"` → 代码已通过五层 QA，跳过 Phase 1.5（代码优化）、Bugfix 验证、代码理解测验。再优化可能破坏已验证状态。
- **独立模式**：其他所有情况 → 执行完整流程。

## 工作框架

创建一个简洁的任务列表来跟踪进度：

```
使用 TaskCreate 工具创建 Git 提交工作流：

Phase 1 — 基础分析（串行）
- [ ] 分析 Git 状态：检查可提交更改，分析改动内容和类型

Phase 1.5 — 代码优化（串行，会修改代码，后续任务需基于优化后的代码）
- [ ] 代码优化（条件性）：检测 React 代码 + 调用优化技能 + 用户确认
      跳过条件：主链路模式 / 无需优化

Phase 2 — 独立任务（并行执行，基于优化后的代码）
- [ ] Bugfix 验证（主链路模式跳过）
- [ ] 代码理解测验（主链路模式跳过）
- [ ] 项目元数据更新（CLAUDE.md + 版本号）

Phase 3 — 收尾流程（串行，等待 Phase 2 全部完成）
- [ ] 执行智能提交 + 任务同步（ai-todo）+ 提交总结
```

**调度原则**：
- Phase 1.5 串行执行，因为代码优化会修改文件，后续 bugfix 验证和代码测验必须基于优化后的代码
- Phase 1.5 无需优化时直接跳过，不阻塞流程
- Phase 2 的任务之间没有数据依赖，应尽可能在一轮响应中并行发起
- 需要用户交互的任务（如代码测验）与其他任务同时发起，等待用户回答期间其他任务已完成
- 任何 Phase 2 任务的失败或跳过不阻塞其他任务
- Phase 3 必须等待 Phase 2 全部完成（包括用户交互结束）

## 关键决策点

### 1. 代码优化（Phase 1.5，串行）

**为何前置**：代码优化会修改文件，必须在 bugfix 验证和代码测验之前完成，否则后续任务验证的是优化前的代码。

自主判断改动中是否涉及 React/前端代码，决定调用哪些优化技能：
- **react best practice**：React 最佳实践（检测到 React 代码时调用）
- **code simple**：代码简化（建议总是调用）

调用前向用户展示建议的改动，获得确认后应用。技能调用失败时记录警告并跳过（优雅降级）。

### 2. Bugfix 验证

**目的**：bugfix 提交时，拿到运行时证据证明修复生效——"修了就要验"。

**触发条件**：commit type 为 `fix`。**无测试框架不等于跳过，而是切换验证模式。**

**两种验证模式**：

- **自动化测试模式**（项目有测试框架）：找到或创建对应测试 → 补充 bug 场景用例 → 运行相关测试确认通过 → 测试文件加入暂存区。
- **运行时验证模式**（无测试框架，或 bug 涉及外部系统交互）：实际执行代码路径，获取运行时输出作为证据。手段由 AI 自主判断——curl 调接口、写临时脚本跑一次、启动 dev server 手动触发、读日志——任何能产出可观察证据的方式都行。

**核心原则**：
- 一个 bug 一份证据，不过度扩展
- **假设需要证据**：如果修复依赖了对外部系统行为的假设（响应结构、字段名、状态码、数据格式），这些假设必须在提交前通过运行时手段验证。"我看了文档"不算证据，"我跑了一下，实际返回是 X"才算。
- 验证失败时报告详情，让用户决定是否继续提交

### 3. 提交信息生成

**语言**：全部使用中文（type 标签除外）

**格式**：`type(scope): 业务描述 (技术说明)`

- **业务描述**：用用户/产品视角说"发生了什么"，简洁优先，一眼看懂
- **技术说明**：用括号补充技术实现，可省略

**type 选取**：
- `feat` 新功能 / `fix` 修复 / `perf` 性能 / `refactor` 重构
- `style` 样式 / `docs` 文档 / `chore` 杂项 / `test` 测试

**示例**：
```
feat(报告): 支持一键导出 PDF (新增导出 API + 前端按钮)
fix(登录): 修复登录后页面空白 (useEffect 缺少依赖导致重渲染)
perf(列表): 长列表滚动更流畅 (虚拟化渲染，DOM 节点从 500→30)
refactor(Auth): 简化鉴权逻辑 (合并重复的 token 校验分支)
chore: 升级依赖版本
```

**禁止**：
- 禁止英文描述（type 标签除外）
- 禁止堆砌技术词汇而忽略业务含义
- 禁止模糊措辞，如「优化代码」「更新逻辑」

### 4. 代码理解测验

**目的**：Vibe Coding 时代，开发者的核心价值是有效监督 AI 产出。测验聚焦"为什么"和"会怎样"，而非代码表面细节。

**防合理化指南**：

| 借口 | 现实 |
|------|------|
| "改动很小，不需要测验" | 小改动也需要开发者理解上下文。 |
| "用户赶时间" | 跳过测验 = 让用户签收看不懂的代码。2 分钟的测验防止日后的维护灾难。 |
| "这只是重构，逻辑没变" | 重构改变了结构，开发者需要理解新结构的设计权衡。 |

**基本原则**：
- **智能跳过**：简单改动（格式、重命名、配置、注释、依赖更新）直接跳过
- **监督者视角**：问"如果我要对这段代码负责，我需要理解什么？"
- **聚焦决策层**：设计权衡、系统影响、失败模式——AI 不会主动告诉你的东西
- **远离细节层**：语法、API 参数、变量名、代码位置——这些是 AI 擅长的，不需要人记

**出题指南**：
- 使用 `AskUserQuestion`，1-2 道场景判断题
- 用"如果...会怎样"或"为什么不..."的句式，考察判断力而非记忆力
- **优先覆盖核心数据流假设**：代码对输入数据的结构、格式、字段名做了什么假设？这些假设错了会怎样？
- 示例：「选择 A 方案而非 B，牺牲了什么？」「如果上游返回的数据结构和预期不同，这段代码会怎样？」「这段代码假设了 X 的格式是 Y，这个假设的依据是什么？」

**答错处理**：
- 解释正确答案，引用具体代码
- 用户可选择重新作答或确认已理解后继续
- 目的是培养监督直觉，不是考试

### 5. 项目元数据更新

**两项子任务**，根据改动类型决定是否执行：

**a) CLAUDE.md 更新** — 当新增/删除模块、结构变化、配置变更、工作流调整时：
- 读取现有 CLAUDE.md → 对比改动 → Edit 最小化更新
- 跳过：纯代码修改（bug fix/重构/性能优化）、样式/测试/注释、CLAUDE.md 已在改动中
- 更新原则：最小改动、保持风格、事实优先（不写计划中的功能）
- 如果 `.autopilot/` 存在且有新增内容，确认 CLAUDE.md 中有对知识库目录的提及

**c) `.autopilot/` 知识库变更检查（始终执行，无论模式）**

无论主链路还是独立模式，本子任务都必须运行。目的是让 `.autopilot/knowledge/` 下的知识沉淀**主动浮现**到 commit 决策流，避免 AI 在 `git status` 满屏改动中遗漏掉知识库的更新。

执行步骤：

1. 运行 `git status --porcelain .autopilot/knowledge/`，列出该目录下所有未 staged / 未 commit 的改动
2. 若有改动 → 逐项 Read 改动文件（`decisions.md` / `patterns.md` / `index.md` / `domains/*.md`），判断是有效知识沉淀还是误编辑
3. 默认 stage 并随本次主提交一并 commit；若发现内容不属于本次任务（如他人遗留草稿），单独询问用户
4. 同时检查 `git status --porcelain .autopilot/runtime/` **必须为空**（runtime/ 应由 `.gitignore` 拦截）。若非空 → 警告：`.gitignore` 缺少 `.autopilot/runtime/` 规则或有误入库历史，建议运行 `/autopilot doctor` 排查

> 这条规则与 Layer 1（`.gitignore` 拓扑拦截）和 Layer 3（doctor Dim 12 巡检）共同构成三层防御。

**b) 版本号升级** — 当 commit type 为 `feat`/`fix`/`perf` 时：
- `feat` → minor 升级（1.2.x → 1.3.0），breaking change → major 升级
- `fix`/`perf` → patch 升级（1.2.0 → 1.2.1）
- **发现 → 更新 → 校验**：
  1. **发现**：读 CLAUDE.md 了解项目的版本文件分布规范，再用 `grep -rn '当前版本号'` 确认所有包含版本号的文件
  2. **更新**：逐个更新发现的版本文件，每个 `git add`
  3. **校验**：更新后再次 grep 确认所有版本文件的版本号一致，不一致则修正
- 跳过：chore/style/docs/test/refactor、WIP 提交

### 6. 任务同步

**目的**：提交完成后，将本次提交与任务管理系统同步，保持开发进度可追踪。

**前置检查**：使用 Bash 工具执行 `which ai-todo` 检查是否可用，不可用则静默跳过。

**执行步骤**：
1. **了解任务全局**：先运行 `ai-todo tasks:tree` 查看完整任务树
2. **命令发现**：通过 `ai-todo --help` 查看当前可用命令
3. **智能关联**：根据提交信息、分支名、改动内容，在任务树中找到最匹配的任务（优先在项目空间下匹配）
4. **更新进度**：关联到具体任务后，更新进度、添加工作日志、或标记完成
5. **创建新任务**：如果没有关联任务，根据任务树找到合适的父任务/项目空间，**在正确的层级下创建**
6. **优雅降级**：任何 ai-todo 操作失败都不应阻断已完成的 Git 提交

### 7. 提交总结

工作流最后一步，输出一个表格让用户快速掌握本次提交全貌。面向用户表达，不讲细碎技术点。多 git 仓库时分开说明。