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 仓库时分开说明。