用途
这是一个供 AI(尤其是 Claude)在执行期间阅读的 Git 操作参考,目标是实现令牌高效的 Git 操作,涵盖提交/PR 流程,以及用于隔离工作流变更的 git worktree。
主要能力
提交工作流(安全扫描 + 自动拆分)
令牌高效 Git:最多 2-4 次工具调用。
- 暂存 + 安全扫描:暂存文件,检查 diff 统计,扫描密钥(api_key|token|password|secret|credential)。若发现密钥:停止,展示匹配项,阻止提交。
- 拆分决策:若类型混合(feat+fix)、文件数 >10 且不相关、多个范围(前端+后端)则拆分;若类型/范围相同、文件数 ≤3 且行数 ≤50、逻辑相关则单次提交。
- 提交信息:格式为 type(scope): description(少于 72 字符,现在时,祈使句)。类型包括 feat、fix、docs、chore、refactor、test、perf。
- 确认 → 提交 → 推送:绝不自动提交或自动推送。展示 git diff --stat 与拟定的提交信息,等待用户明确确认后再执行 git commit;提交后单独询问是否 git push,仅在用户要求时推送。无例外。
PR 工作流
执行 git fetch origin main,查看自 main 以来的提交日志与 diff 统计,然后使用 gh pr create --title "type(scope): description" --body "## Summary\n- bullets\n\n## Test Plan\n- steps" 创建 PR。
输出示例
staged: 3 files (+45/-12 lines) | security: passed | commit: a3f8d92 feat(auth): add token refresh
Worktree 隔离
启动工作流时自动创建 git worktree,所有变更位于隔离分支,失败时丢弃,对主分支零损害。
使用方式
何时使用
- 自动:/run 且 AF_WORKTREE=true 时
- 手动:用户说“use a worktree”时
- 跳过:快速修复、配置变更、单文件编辑
生命周期
worktree_lifecycle[5]{event,action}:
- run:start → "git worktree add .worktrees/[id] -b af/[id]"
- Phase 1 approved → 所有编辑在 worktree 目录中进行
- Phase 5 complete → 提供选项:merge / create PR / keep branch / discard
- run:cancel → "git worktree remove .worktrees/[id]"
- run failed → 丢弃 worktree,主分支不受影响
配置
export AF_WORKTREE=true export AF_WORKTREE_DIR=".worktrees" # default
将 .worktrees/ 添加到 .gitignore。
适用场景
适用于需要 AI 辅助执行 Git 提交、创建 PR 以及通过 worktree 隔离工作流变更的场景,尤其适合希望控制令牌消耗、避免密钥泄露、并保持主分支安全的开发流程。
限制与安全规则
safety[4]{rule,reason}:
- 绝不在有未提交变更时强制删除(用户可能丢失工作)
- 始终提供 merge/PR/keep/discard 选项(由用户决定)
- 仅在明确取消/失败时自动丢弃(不要假设)
- 丢弃前进行检查点提交(最后的恢复机会)
该技能与 phase-checkpoint.cjs 配合使用——检查点是 worktree 分支上的提交,在明确合并前主分支始终不受影响。
人类可读说明参见 docs/architecture/HIERARCHICAL_PLANNING.md 或 docs/getting-started/(视主题而定)。