ai-coding-workflow

name	ai-coding-workflow
description	当用户需要统一的 AI 编程工作流时使用，涵盖新项目、新功能、bug fix、规划、代码审查、QA、发布及存量项目接入。使用本技能时 Superpowers 插件必装；代理将任务路由至 spec-kit/gstack 等阶段能力，并强制 Phase 顺序与完成前验证（ref-09）。

⚠️ 初次安装必做：将本技能加入全局强制规则 → 跳至文末「初次配置」章节，完成后再回来阅读。

详细说明、命令参考、模板按场景拆分为以下文件：

文件	内容
references/ref-01-task-routing.md	§0 规范导言（术语/MUST-SHOULD-MAY/Phase 结构规范）+ §1 任务路由（任务类型→Phase表、命令速查、场景→命令映射）+ §4 文档结构（文件路径速查表）
references/ref-02-tool-stack.md	§2 工具体系总览 + §10 各工具详细说明（spec-kit/gstack/Superpowers/OMC/gitleaks/自检）+ §11 参考来源
references/ref-03-full-workflow.md	§5 完整开发工作流 Phase 0~10（含 ceo-review 模板、spec 模板）
references/ref-04-governance-checklist.md	§3 AI治理（数据边界/高风险操作/人工责任/留痕）+ §6 最佳实践清单（5组 checklist）
references/ref-05-legacy-onboarding.md	§7 存量项目接入（三档策略 A/B/C + Bug Fix 简化流程）
references/ref-06-branch-parallel.md	§8 分支策略（主干开发、PR合并规则）+ §9 并行开发（Git Worktree + OMC 多代理选型）
references/ref-07-advanced-practices.md	§12 进阶实践（P1 测试分层/依赖安全/DORA/Hooks；P2 AI信任边界/环境策略/合规审查/成本管理）
references/ref-08-host-installation-and-cc-switch.md	Claude Code/Codex/Gemini 安装 + CC Switch provider/model 切换
references/ref-09-verification-gate.md	§13 验证铁律 + 阶段顺序纪律（Superpowers 横切层、Iron Law、Gate Function）
references/ref-10-experience-quality.md	§14 经验质量判定（三镜头 + 九类垃圾排除 + 写入前检查），memory/patterns.md 写入前必读

AI Coding 工作流

核心原则：规格驱动 → 测试先行 → 最小改动 → 审查验证 → 持续复盘
纪律层：使用本技能时 Superpowers 插件必装；Phase 按文档顺序推进；任何完成宣称 必须附 fresh 验证证据（详见 references/ref-09-verification-gate.md）
适用：按 ai-coding-workflow 推进的 AI 辅助开发（新项目/新功能/bug fix/存量接入）；与具体 Agent / IDE 无关

何时使用：当用户要你按统一研发流程处理开发任务时使用，典型包括：新项目、新功能、bug fix、存量项目接入、代码审查、QA、发布、工具升级、并行开发。

不适用：纯闲聊、单次信息查询、纯文案改写、纯翻译、仅做简短说明而不进入研发流程的场景。

本技能中的“工作流”默认指统一的 AI Coding Workflow。Phase 0~10 与 Phase 5B 是唯一主线阶段定义；Superpowers（纪律层，使用本技能时必装）、spec-kit、gstack、外部代理编排能力、Context7 MCP、gitleaks、git worktree、AGENTS.md/CLAUDE.md/memory 等都属于按阶段介入的工作流能力，MUST NOT 理解为彼此分离的并行流程。

详细阶段、工具映射与治理规则见下方章节和 references/。

涉及前端交互需求时，所有前端设计文档（DESIGN.md、specs/<feature-id>/interaction-design.md、specs/<feature-id>/design-system-context.md、设计引用与可视化基线）都必须在 Phase 2/spec 阶段完成并锁定。Phase 3 之后只负责引用、拆解、实施、验证这些已锁定设计输入；页面实现、组件开发、视觉还原属于后续实施阶段，MUST NOT 在实施阶段临场补写或新建设计文档。

工具不可用时的统一降级策略

当 host 未安装 gstack 时，所有引用 /review、/qa、/ship 的步骤统一降级为：人工审查、测试命令或 CI 流程。后续各 Phase 不再重复声明此降级规则。

Superpowers 不可降级：使用本技能时 Superpowers 插件 MUST 已安装；未安装 MUST NOT 进入 Phase 6+（见 ref-02 § 10.6.B）。这与 gstack 降级规则不同。

命令映射

正文优先描述“动作”，不重复绑定宿主命令；具体命令按下表选择：

动作	Claude Code	Codex CLI	gstack 不可用时
constitution	/speckit.constitution	$speckit-constitution	手动维护项目原则
specify	/speckit.specify	$speckit-specify	需安装 spec-kit
clarify	/speckit.clarify	$speckit-clarify	需安装 spec-kit
checklist	/speckit.checklist	$speckit-checklist	手动 checklist
plan	/speckit.plan	$speckit-plan	需安装 spec-kit
tasks	/speckit.tasks	$speckit-tasks	手动任务拆解
taskstoissues	/speckit.taskstoissues	$speckit-taskstoissues	手动在 GitHub 创建 Issues
analyze	/speckit.analyze	$speckit-analyze	手动一致性核对
implement	/speckit.implement	$speckit-implement	手工实施
review	/review	/review（若 host 已装 gstack）	人工审查/CI
qa	/qa	/qa（若 host 已装 gstack）	手工测试/CI
ship	/ship	/ship（若 host 已装 gstack）	宿主常规发布流程

---

阶段主线（默认语义）

工作流阶段统一按以下主线理解，不再拆成单独的 spec-kit 流程或 gstack 流程：

Phase 0  项目初始化
Phase 1  产品方向（支持简版）
Phase 2  需求规格
Phase 3  技术方案
Phase 3.5  原型验证（可选）
Phase 4  任务拆解
Phase 5  一致性分析 + TDD
Phase 5B Bug Fix 简化流
Phase 6  代码实施
Phase 7  审查
Phase 8  QA 验证
Phase 9  发布
Phase 10 复盘

每个阶段可按需接入不同能力：例如 Superpowers 提供横切纪律（阶段顺序、验证铁律），spec-kit 负责规格/方案/任务/实现骨架，gstack 负责方向评审、架构评审、审查、QA、发布与复盘，外部代理编排能力负责并行执行或多模型复核，Context7 MCP 负责核对上游官方文档，gitleaks 负责 Secret 扫描，memory 负责沉淀决策与踩坑记录。

---

场景识别

用户意图	执行场景
新项目/方向未定/MVP 边界未定/架构重大影响	→ 场景 A
新项目，但方向已被强约束锁定	→ 场景 A（Phase 1 简版）
方向已定的新功能（多文件或新模块）	→ 场景 B
小变更（小功能或 bug fix）	→ 场景 C
接入存量旧项目	→ 场景 D
工具安装、配置、升级	→ 场景 E
多功能并行开发	→ 场景 F
纯视觉微调（不改逻辑/接口/路由，且改动文件 ≤ 3 个）	→ 场景 G

意图模糊时先询问：「是 A 新项目/B 新功能/C 小变更/D 存量接入/E 工具配置升级/F 并行开发？」

---

场景 A：新项目（方向未定走全流程；方向已锁定走 Phase 1 简版）

详细流程 → references/ref-03-full-workflow.md；命令速查 → references/ref-01-task-routing.md

执行顺序：

A0 项目初始化（一次性）
specify init . --integration <agent-key> → 执行 constitution → 补写 AGENTS.md/CLAUDE.md

A1 产品方向
默认先用 /office-hours 梳理问题空间，再执行 /plan-ceo-review，确认 MVP 边界。若新项目方向已被合同、上级决策、既有 PRD、客户需求等外部约束锁定，则可走 Phase 1 简版：跳过 /office-hours，直接执行 /plan-ceo-review，并在 ceo-review.md 中写明“方向已锁定的依据”与“本次不再讨论的范围”。将结论写入 specs/<feature-id>/ceo-review.md。

A2 需求规格 执行 spec-kit 规格链路：specify → clarify → checklist。先生成初稿 → 重复澄清 直到规格无歧义 → 推荐在 plan 前执行 checklist 并闭环问题；高风险或高歧义需求 MUST 执行 → 锁定 spec.md。 IF 任何 UI 可见变更（非纯逻辑/API 变更），THEN 视为涉及前端交互需求。 IF 涉及前端 UI/UX 且项目级 DESIGN.md 不存在，THEN 生成 DESIGN.md，遵循 Google Stitch DESIGN.md 基础格式；本工作流追加以下章节要求：Responsive Behavior/Iteration Guide。完成后 SHOULD 运行 npx @google/design.md lint DESIGN.md 验证格式。IF 存在，THEN 直接引用。为当前 feature 生成 specs/<feature-id>/design-system-context.md（MAY 降级为 interaction-design.md 中的 Design System Context 章节；若仅引用 ≤5 个 token，SHOULD 直接在 interaction-design.md 中列出 token 引用表）。 涉及前端交互需求时，本阶段 MUST 产出 interaction-design.md，按设计基线分级 gate（L1/L2/L3）填写对应章节。若存在可视化设计稿，按以下标准操作流处理：

1. 获取：IF 设计稿托管于在线平台（Figma/蓝湖/其他），获取长久分享链接；IF 仅有离线文件（PDF/截图/原型包），记录文件名与存放路径
2. 记录：将在线链接（或离线文件路径）写入 interaction-design.md 的「设计引用」章节（MUST，唯一主入口）
3. 拉取（可选）：如需本地查看，临时拉取到 specs/<feature-id>/design-assets/，该目录须加入 .gitignore，不提交 Git

涉及前端交互需求时，按设计基线完整度分三级 gate：

• L1 完整设计：有在线设计稿（Figma/蓝湖等）或离线文件（PDF/截图/原型包）→ interaction-design.md 完整填写（含「设计引用」章节记录链接或文件路径），spec.md 锁定后进入后续阶段。
• L2 文字+草图：有文字需求描述 + 草图/白板照片/线框图/原型说明 → interaction-design.md 填写页面结构、交互流转与状态矩阵，「设计引用」标注「无正式设计稿」。可锁定 spec.md，Phase 6 实施前 MAY 要求补充视觉参考。
• L3 纯文字：仅有文字需求，无任何可视化参考 → interaction-design.md 填写页面结构与状态矩阵，spec.md 标注「视觉细节待设计确认」。spec.md 可锁定；进入 Phase 6 前若仍缺少 L2 级以上设计基线，MUST 返回 Phase 2 补齐并重新锁定规格。 注意：clarify 追加写入，可多次执行；specify 会覆盖整个 spec.md，仅在推倒重来时使用。

A3 技术方案 执行 spec-kit plan → /plan-eng-review，生成 plan.md、research.md、data-model.md、contracts/、arch-review.md。若已产出前端交互设计，则 plan.md MUST 同时引用 interaction-design.md 和 design-system-context.md（或 interaction-design.md 中的 Design System Context 章节），说明后续前端实现如何消费设计产物与设计系统规则。 若进入本阶段后发现任一前端设计文档或设计基线缺失，MUST 返回 Phase 2 补齐并重新锁定规格，MUST NOT 在 Phase 3+ 直接补写设计文档。

A4 任务拆解 执行 spec-kit tasks，生成 tasks.md。若已产出前端交互设计，则前端任务 MUST 基于 interaction-design.md 拆解，而不是只依据文字规格。前端任务 MUST 包含设计还原验证任务，明确截图/人工验收/视觉对比证据。

A5 TDD + 实施（详见 § Phase 5-6） 执行一致性分析 → 先写失败测试 → 执行实现（必要时用外部代理编排能力并行）→ 绿灯。具体页面实现与组件开发在 Phase 6 执行，不在需求阶段提前落代码。IF 涉及前端实施，THEN Agent MUST 将 DESIGN.md 中的 design tokens 映射为 CSS 变量或 Tailwind 配置，MUST NOT 在组件中硬编码颜色/字体/间距值。

A6 审查 + QA + 发布（详见 § Phase 7-9） 执行审查 → QA → 按 Phase 9 发布链路进入 CI/Review/合并/staging quick QA/production。若涉及前端交互，QA MUST 将 interaction-design.md、design-system-context.md（或 interaction-design.md 中的 Design System Context 章节）及「设计引用」章节中的设计基线（在线链接或离线文件路径）作为对照输入之一。若 QA 发现设计效果与目标基线不一致，MUST 返回 Phase 6 修复；若基线缺失或错误，返回 Phase 2。

A7 复盘
/retro → 有价值经验写入 memory/patterns.md（写入前先按 references/ref-10-experience-quality.md 做质量判定：三镜头 + 九类垃圾排除 + 去重合并）。复盘输出末尾 MUST 执行「收尾反思两问」并如实作答：① 眼下最没把握的是什么？② 我最大的遗漏是什么？我没意识到什么？（前者源自 Sam Altman，后者源自 Claude；暴露本次迭代的置信度边界与盲点，不否定复盘结论）。

---

场景 B：方向已定的新功能（Phase 2 → 9）

详细流程 → references/ref-03-full-workflow.md § Phase 2-9

Phase 2：需求规格（执行 spec-kit 规格链路：specify → clarify → checklist。生成初稿 → 重复澄清至无歧义 → 推荐在 plan 前执行 checklist，高风险或高歧义需求强制执行 → 锁定 spec.md；IF 任何 UI 可见变更（非纯逻辑/API 变更），THEN 视为涉及前端交互需求，按设计基线 L1/L2/L3 分级 gate 执行，MUST 产出 `interaction-design.md`；`design-system-context.md` MAY 作为独立文件产出，也 MAY 降级为 `interaction-design.md` 章节，设计基线记录到「设计引用」章节）
Phase 3：技术方案（spec-kit plan → /plan-eng-review → arch-review.md；若涉及前端交互，`plan.md` MUST 同时引用 `interaction-design.md` 和 `design-system-context.md`（或 `interaction-design.md` 中的 Design System Context 章节）作为实现输入）
Phase 4：任务拆解（spec-kit tasks → tasks.md；若涉及前端交互，前端任务 MUST 基于设计产物拆解；前端任务 MUST 包含设计还原验证任务）
Phase 5：一致性分析 + TDD（spec-kit analyze → 对 `spec.md`/`interaction-design.md`/`design-system-context.md`（或 `interaction-design.md` 中的 Design System Context 章节）/`plan.md`/`tasks.md` 做一致性分析 → 先写失败测试 → 提交测试基线）
Phase 6：实施（spec-kit implement；必要时配合外部代理编排能力 → 绿灯 → 原子提交）
Phase 7：审查（执行 review；安全敏感改动追加安全专项审查）
Phase 8：QA（执行 qa → qa-reports/；feature branch 默认 diff-aware；若涉及前端交互，MUST 对照 `interaction-design.md`、`design-system-context.md`（或 `interaction-design.md` 中的 Design System Context 章节）及「设计引用」章节中的设计基线验证；若设计效果不一致 MUST 返回 Phase 6 修复，基线缺失返回 Phase 2）
Phase 9：发布（按 Phase 9 发布链路执行）

关键约束：

• 模型与推理档位遵循当前 CLI/仓库默认配置，MUST NOT 在工作流文档中硬编码固定模型分工
• 每完成一个原子任务执行 /commit-message，确认后再提交；提交信息格式以 /commit-message 技能定义为准，如需标识 task-id，可写入摘要或说明列表
• 发现规格有误 MUST 返回 Phase 2 正式修改，MUST NOT 绕过

---

场景 C：小变更

bug fix 详细流程 → references/ref-03-full-workflow.md § Phase 5B

C1 小功能：单文件且非 bug fix，或 < 50 行净变更。从 Phase 2 开始，跳过 Phase 1（产品方向），走 Phase 2→9。若涉及 UI/UX，仍继承 Phase 2 的设计基线硬 gate。

C2 Bug Fix：以修复缺陷为目的时，走 Phase 5B 简化流，而不是复用完整 Phase 5 定义。适用于单文件或多文件修复，但不适用于新增需求或扩 scope。

① 先写失败/复现测试（固化问题，防止回归）
② 定位并修复
③ 已安装 gstack 时执行 /review（仅审改动范围）；未安装时改为人工审查或 CI 校验
④ 按 ref-09 Gate Function 确认测试通过（附 fresh 命令输出）
⑤ 已安装 gstack 时执行 /qa（feature branch 默认 diff-aware；需要显式模式时再加 --quick/--regression）；未安装时改为人工或 CI 验证
⑥ 已安装 gstack 时执行 /ship；未安装时走宿主常规发布流程
⑦ 踩坑追加写入 memory/issues.md

---

场景 D：接入存量旧项目

三档接入策略详情 → references/ref-05-legacy-onboarding.md

三档选择：

档位	适用场景	预估耗时
A 轻量接入	活跃维护中，快速规范化	1 天内
B 标准接入	准备规范化，有改造时间	1~3 天
C 全面接入	有专项技术改造计划	按模块排期

档位 A 最小动作：补写 AGENTS.md → 建 memory/ → 启用 Context7 MCP（无 MCP 时降级为 use context7/library ID/官方文档）→ 新功能走完整流程

---

场景 E：工具配置与升级

各工具安装/升级命令 → references/ref-02-tool-stack.md；宿主 CLI 安装与 CC Switch 切换 → references/ref-08-host-installation-and-cc-switch.md

工具	升级命令
Superpowers	各 Agent 插件市场 reinstall / /add-plugin superpowers
gstack	/gstack-upgrade
specify-cli（CLI）	uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z && uv cache clean
spec-kit 项目文件	specify init --here --force --integration <agent-key>
gitleaks	brew upgrade gitleaks
oh-my-claudecode	omc update 或 npm i -g oh-my-claude-sisyphus@latest（npm 发布包名，项目品牌名相同）；刷新 config 需另跑 omc setup、/setup 或 /omc-setup

进入场景 E 或用户明确要求时，代理 SHOULD 按 § 10.6.A 检查能力工具版本；使用本技能时 MUST 按 § 10.6.B 确认 Superpowers 已安装。默认不在每次会话开始时自动升级工具。

---

场景 F：多功能并行开发

Git Worktree 命令 + OMC 多代理选型 → references/ref-06-branch-parallel.md

# 开两条并行 feature 线
git worktree add ../project-feature-a username_a/feature/report-page
git worktree add ../project-feature-b username_b/feature/auth-refactor

# 各自独立 Claude Code 实例
cd ../project-feature-a && claude
cd ../project-feature-b && claude

代理架构选择：

场景	方案
同一任务内多模型分工实现	/team（Claude Code 会话内团队编排）或宿主等价能力
启动 Codex/Gemini CLI worker	omc team N:codex "..."/omc team N:gemini "..."；/omc-teams 为兼容入口
同一 diff 多模型交叉审查	/ccg 或 /ask codex + /ask gemini（或宿主等价交叉评审能力）
并行功能开发	多个独立代理实例（各自 worktree）

---

场景 G：UI 快车道（纯视觉微调）

适用条件（MUST 同时满足）：

• 改动仅涉及视觉层：颜色、间距、字号、图标、文案、排版
• 不新增组件、不改逻辑、不改接口、不改路由
• 改动文件 ≤ 3 个

IF 以上任一条件不满足，THEN MUST 退回场景 B 或 C，走完整流程。

执行顺序：

① 用一句话描述要改什么（不需要写 spec.md）
② Phase 6：直接实施改动
③ Phase 8：视觉 Review（截图对比或人工确认）
④ Phase 9：按常规发布流程上线

不产出 spec.md/plan.md/tasks.md，改动记录写入 commit message 即可。

---

项目定制层（推荐模式）

技能本身定义通用工作流。各接入项目 SHOULD 通过薄定制层记录项目特有信息，而非维护完整副本：

memory/workflow.md              ← 项目定制层（参考技能，记录本地增量）

定制层内容

内容	说明	示例
命令映射	本项目能用的具体宿主命令	/speckit.specify vs specify，gstack 未安装时的降级路径
文档路径	本项目实际文件布局	specs/<id>/spec.md、memory/decisions.md
工具可用性	各工具是否安装、降级策略	gstack 未安装 → 人工审查 / CI；Superpowers 未安装 → 阻断 Phase 6+

模板

# AI Coding Workflow（项目定制层）

> 完整工作流定义见技能文档：`~/.claude/skills/ai-coding-workflow/SKILL.md`
> 本文档只记录本项目特有的定制信息，不重复通用定义。

## 命令映射

| 动作 | 本项目命令 |
|------|-----------|
| 规格 | ... |
| 方案 | ... |

## 文档路径

| 产物 | 本项目路径 | 阶段 |
|------|-----------|------|
| 需求规格 | ... | Phase 2 |
| 技术方案 | ... | Phase 3 |

## 工具可用性

| 工具 | 状态 | 降级策略 |
|------|------|---------|
| gstack | 未安装 | 人工审查 / CI |
| Superpowers | 未安装 | 阻断 Phase 6+，先安装插件 |
| Context7 MCP | 已配置 | 按技能规则 |

收益：

• 自动继承更新：技能迭代（Phase 新增、场景调整）无需手动同步
• 零维护成本：不存储通用定义，不产生重复内容
• 上下文聚焦：AI 直接从定制层获取路径和命令，需要细节时去读技能

---

AI 治理（核心边界）

完整规则 → references/ref-04-governance-checklist.md §3；进阶实践（测试分层/依赖安全/合规/成本）→ references/ref-07-advanced-practices.md

• 客户数据、生产数据、密钥 MUST NOT 发送给任何模型
• AI MUST NOT 在无人工批准的情况下直接执行生产发布、回滚、权限变更、数据库迁移
• AI 生成内容一律视为待确认产物，最终责任 MUST 由人工承担

---

初次配置（全局强制生效）

技能部署后属于按需触发。若需在所有项目中自动强制遵守，按所用 AI agent 选择对应配置步骤。

---

Claude Code

在 ~/.claude/CLAUDE.md 末尾追加以下内容：

## AI Coding 工作流（强制遵守）

1. 进行开发任务时，默认使用 `~/.claude/skills/ai-coding-workflow/SKILL.md`。
2. “工作流”指统一的 AI Coding Workflow，按 `Phase 0~10/Phase 5B` 顺序推进，不把 spec-kit/gstack 视为分离流程。
3. 使用本 workflow 时 Superpowers 插件 MUST 已安装；未安装不得进入 Phase 6+。
4. Phase 退出条件未满足前不得进入下一 Phase；任何完成/通过宣称 MUST 附 fresh 验证命令输出（见技能 `ref-09-verification-gate.md`）。
5. 阶段内可按需使用 spec-kit、gstack、Superpowers、外部代理编排、Context7 MCP、gitleaks、memory 等能力。
6. 意图模糊时，先判断场景：新项目/新功能/小变更/存量接入/工具升级/并行开发。

验证：新开一个对话，说「帮我做一个功能」，确认 Claude 会主动询问任务类型，而不是直接写代码。

---

OpenAI Codex CLI

在 ~/.codex/AGENTS.md 末尾追加以下内容（文件不存在则新建）：

## AI Coding 工作流（强制遵守）

1. 进行开发任务时，默认使用 `<your-skills-path>/ai-coding-workflow/SKILL.md`。
2. “工作流”指统一的 AI Coding Workflow，按 `Phase 0~10/Phase 5B` 顺序推进，不把 spec-kit/gstack 视为分离流程。
3. 使用本 workflow 时 Superpowers 插件 MUST 已安装；未安装不得进入 Phase 6+。
4. Phase 退出条件未满足前不得进入下一 Phase；任何完成/通过宣称 MUST 附 fresh 验证命令输出（见技能 `ref-09-verification-gate.md`）。
5. 阶段内可按需使用 spec-kit、gstack、Superpowers、外部代理编排、Context7 MCP、gitleaks、memory 等能力。
6. 意图模糊时，先判断场景：新项目/新功能/小变更/存量接入/工具升级/并行开发。
7. Codex CLI 中 spec-kit 使用 `$speckit-*`；gstack 未安装时可降级为人工审查、测试命令或 CI；Superpowers 不可降级。

验证：新开一个 Codex CLI 会话，说「帮我做一个功能」，确认会主动询问任务类型。

---

其他 Agent

各 Agent 全局配置文件写入内容与上方 Claude Code 版内容块一致，将技能路径替换为实际路径；若宿主存在命令映射差异，再补充一行最小必要说明。

Agent	全局配置文件
Google Gemini CLI	~/.gemini/GEMINI.md
Cursor	~/.cursor/rules/ai-coding-workflow.mdc
Windsurf	项目级 .windsurfrules
GitHub Copilot	.github/copilot-instructions.md

---

参与贡献

仓库地址：https://github.com/liuhean2021/Anan-Agent-Skills 技能目录：skills/ai-coding-workflow/