8阶段通用开发流水线
1. 流水线概述
本流水线将"一个需求从规格到代码提交"的全过程，拆解为8个原子化阶段。每个阶段对应一个独立的子Skill，且有明确的输入Schema、产出物Schema、退出闸门（Gate）。
核心哲学：流程化、原子化、可校验化——让AI像执行SOP一样工作，将代码生成率稳定提升至94%+。
技术栈无关：流水线骨架不绑定任何特定语言或框架。通过内置的模板自动匹配机制，AI根据项目类型自动切换工具链（编译、Lint、测试、格式化）。
2. 流水线总览图（输入→输出传递链）
[用户触发流水线 + PRD需求文档]
↓
┌─────────────────────────────────────────────────────────────────────┐
│ 阶段0：项目感知与设计确认 → 产出 ai_pipeline/ + 确认设计方向 │
└─────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────┐
│ 节点1 (Skill-01)：需求结构化 → 产出 SPECIFICATION.md │
└─────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────┐
│ 节点2 (Skill-02)：需求拆解 → 产出 TASK_LIST.md (原子任务清单) │
└─────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────┐
│ 节点3 (Skill-03)：代码定位 → 产出 LOCATE_MAP.md (精确行号+上下文) │
└─────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────┐
│ 节点4 (Skill-04)：代码实现 → 产出 修改后源文件 + IMPLEMENTATION_ │
│ REPORT.md │
└─────────────────────────────────────────────────────────────────────┘
↓ (Critical红线校验)
┌─────────────────────────────────────────────────────────────────────┐
│ 节点5 (Skill-05)：静态验证 → 产出 VERIFY_REPORT.md │
└─────────────────────────────────────────────────────────────────────┘
↓ (Critical红线校验)
┌─────────────────────────────────────────────────────────────────────┐
│ 节点6 (Skill-06)：可配置验证 → 产出 VERIFY_RUNTIME_REPORT.md │
│ (测试覆盖/Eval基准/组合模式) │
└─────────────────────────────────────────────────────────────────────┘
↓ (质量红线校验)
┌─────────────────────────────────────────────────────────────────────┐
│ 节点7 (Skill-07)：知识沉淀 → 更新 TECH_SPEC.md │
└─────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────┐
│ 节点8 (Skill-08)：语义提交 → 产出 COMMIT_MESSAGE.md + Git Commit │
└─────────────────────────────────────────────────────────────────────┘
↓
🎉 交付完成
3. 模板自动匹配
AI在启动流水线时，自动检测项目根目录标志文件，确定技术栈：
pyproject.toml+src/存在 → Python技术栈（mypy / ruff / pytest）package.json+tsconfig.json存在 → TypeScript技术栈（tsc / eslint / jest）- 两者均不存在 → 询问用户确认技术栈
- 两者同时存在 → 询问用户选择目标技术栈
选定技术栈后，AI直接使用项目已有的类型检查、Lint、格式化配置，不额外生成配置文件。
4. 各节点串联逻辑（输入/产出/闸门详述）
阶段0：项目感知与设计确认（前置步骤，必须执行）
- 触发条件：用户触发流水线。
- 执行动作：
1. 读取项目：AI先完整扫描项目目录结构，读取关键源码文件，理解现有架构、模块划分、接口定义和代码风格。
2. 创建追踪目录：在项目根目录下创建ai_pipeline/目录，用于存放流水线核心追踪文件。创建时告知用户路径，工作流不中断继续执行。
3. 设计拆解确认：基于PRD和项目现状，生成初步设计拆解摘要（功能模块划分、接口契约概要、数据流方向、状态机草图），以简洁形式呈现给用户并等待确认。
4. 语义澄清：若任何文件名、模块名、代码片段的作用或语义不明确，必须暂停并询问用户，禁止猜测后继续。此步骤是为了避免后续阶段基于错误理解做无意义工作。 - 产出物：
ai_pipeline/目录（含初始化的PIPELINE_STATUS.md）。 - 出口闸门：用户确认设计拆解方向；所有语义歧义已澄清。
- 下游传递：确认后的设计方向进入节点1。
阶段1：需求结构化（Skill-01）
- 触发条件：用户提供 PRD文档 + API规范 + 接口契约。
- 执行动作：调用子Skill-01，提取功能模块、定义接口契约、梳理数据流与状态机、枚举边界条件。
- 产出物：
SPECIFICATION.md（含功能树、接口契约表、数据流图、状态机、边界条件、依赖清单）。 - 出口闸门：完整性红线校验通过（无Critical缺失，所有接口有明确的输入/输出Schema）。
- 下游传递：将
SPECIFICATION.md路径写入上下文，进入节点2。
阶段2：原子化拆解（Skill-02）
- 触发条件：接收到
SPECIFICATION.md及原始PRD。 - 执行动作：调用子Skill-02，自上而下切割为"单文件/单函数"粒度的任务，并做拓扑排序。
- 产出物：
TASK_LIST.md（含任务ID、依赖关系、变更类型）。 - 出口闸门：原子性红线校验通过（无超大任务、无模糊描述）。
- 下游传递：将
TASK_LIST.md+SPECIFICATION.md传入节点3。
阶段3：精准代码定位（Skill-03）
- 触发条件：接收到
TASK_LIST.md。 - 执行动作：调用子Skill-03，利用"三级金字塔知识库"+"五步定位法"（脚本辅助），将每个任务映射为绝对路径、函数名、行号范围。工具链按当前模板选择（Python用ast/ripgrep，TypeScript用ts-morph/grep）。
- 产出物：
LOCATE_MAP.md（含每个任务的物理路径+上下文代码块，总Token≤约30K）。 - 出口闸门：唯一性红线校验通过（无同名文件/函数冲突）。
- 下游传递：将
LOCATE_MAP.md+TASK_LIST.md+SPECIFICATION.md传入节点4。
阶段4：确定性代码实现（Skill-04）
- 触发条件：接收到
LOCATE_MAP.md。 - 执行动作：调用子Skill-04，严格按拓扑顺序执行每个任务。AI生成业务逻辑骨架，所有精确计算/正则/幂等操作下沉到脚本，脚本回填结果后原地注入文件。工具链按当前模板选择。
- 产出物：物理修改后的源文件 +
IMPLEMENTATION_REPORT.md（含注入行号、脚本调用日志）。 - 出口闸门：即时编译校验（按模板对应的编译器，如
mypy --strict）通过（最多自愈3次，否则中断）。 - 下游传递：修改文件列表 +
IMPLEMENTATION_REPORT.md+LOCATE_MAP.md传入节点5。
阶段5：硬性静态闸门（Skill-05）
- 触发条件：接收到修改后的源文件列表。
- 执行动作：调用子Skill-05。第一阶段：Critical红线（编译/类型检查/关键Import）——失败则立即中断全流水线并回滚。第二阶段：Standard红线（Lint/命名/调试残留）——AI自动修复循环（最多3轮）。
- 产出物：
VERIFY_REPORT.md（含Critical/Standard逐项结论）。 - 出口闸门：Critical全部通过；Standard无残留或仅剩
[MANUAL_REQUIRED]警告项。 - 下游传递：修改文件列表 +
VERIFY_REPORT.md+SPECIFICATION.md传入节点6。
阶段6：可配置运行时验证（Skill-06）
- 触发条件：接收到静态验证通过的文件 +
SPECIFICATION.md。 - 执行动作：调用子Skill-06。根据当前模板+项目配置选择验证模式：
- Mode A（测试覆盖率）：运行测试套件，检查覆盖率阈值。
- Mode B（Eval基准）：运行预设的eval benchmark，评测行为质量（适用于AI Agent项目）。
- Mode C（组合）：Mode A + Mode B 同时执行。
- 产出物：
VERIFY_RUNTIME_REPORT.md（含测试覆盖率报告 / Eval得分 / 组合结论）。 - 出口闸门：Mode A覆盖率达标 / Mode B得分达标 / 无
Uncaught运行时错误。 - 下游传递：修改文件列表 +
VERIFY_RUNTIME_REPORT.md+IMPLEMENTATION_REPORT.md+TASK_LIST.md+SPECIFICATION.md传入节点7。
阶段7：知识沉淀与传承（Skill-07）
- 触发条件：接收到所有前序报告及最终源码。
- 执行动作：调用子Skill-07。提取
git diff变更清单 → AI将"改了啥"翻译为"为啥改"（ADR/踩坑记录）→ 增量合并至TECH_SPEC.md。 - 产出物：更新后的
TECH_SPEC.md（含概述、变更清单、ADR、遗留问题、测试指引）。 - 出口闸门：任务-文档完整性红线（
TASK_LIST中所有任务均在TECH_SPEC中有对应条目）。 - 下游传递：修改文件列表 +
TECH_SPEC.md+IMPLEMENTATION_REPORT.md传入节点8。
阶段8：语义化提交与交付（Skill-08）
- 触发条件：接收到最终源码及
TECH_SPEC.md。 - 执行动作：调用子Skill-08。AI聚合变更分组 → 生成Conventional Commits格式信息（含Body引用ADR、Footer带Warning）→ 提交前红线（扫描调试残留/超大文件，检测项按模板切换）→ 执行
git commit。 - 产出物：
COMMIT_MESSAGE.md+ 实际Git提交记录 +PIPELINE_SUMMARY.md（流水线终结报告）。 - 出口闸门：提交前红线100%通过；流水线正式结束。
5. AI如何使用本主Skill（操作指南）
前置准备（一次性）
- 将8个子Skill（
SKILL_01_DESIGN.md~SKILL_08_COMMIT.md）存放于项目.ai/skills/目录下。 - 确保本地环境具备（AI会自动检测并提示缺失项）：
- Git仓库（已初始化）
- 对应语言运行时（Python 3.9+ / Node.js 18+）
- 项目已有类型检查、Lint、格式化等规范配置
触发流水线（单次需求）
向AI发送以下指令模板（示例）：
> "请按本仓库的8阶段流水线，完成以下需求开发：
>
> - PRD说明：[需求描述、业务规则、边界条件]
> - API规范：[接口定义、输入输出Schema]
> - 目标分支：feature/xxx"
AI执行时的自动化流转逻辑
- 自动模板匹配：AI检测项目标志文件，自动选择模板（参见第3章）。
- 自动加载：主Skill顺序读取并激活子Skill-01至08。
- 上下文传递：每个阶段的产出物路径会被自动追加到工作上下文中，作为下一阶段的输入（无需人工搬运）。
- 闸门交互：
- 若某阶段触发 Critical红线（阻断级），AI会暂停流水线，输出错误报告，并询问"是否回滚并终止，或人工修复后继续"。
- 若触发 Standard红线（自愈级），AI自动修复并在报告中记录，无需人工干预。 - 人工确认节点（可选）：在节点6完成后，若存在"带警放行"项（如覆盖率略低于阈值），AI会输出报告并等待"确认放行"指令后再进入节点7。
- 断点续传：若流水线因意外中断（如网络超时），AI可读取最后一份成功产出的报告，从中断节点恢复执行。
执行完毕后交付物清单
- 代码仓库：已提交的新增/修改源码（附带规范Commit信息）。
- 文档资产：更新后的
TECH_SPEC.md（项目长期记忆库）。 - 验证附件：
VERIFY_RUNTIME_REPORT.md（含测试覆盖率/Eval得分）、IMPLEMENTATION_REPORT.md（行号审计日志）。 - 终结报告：
PIPELINE_SUMMARY.md（总耗时、修改文件数、关卡通过情况）。
关键约束提醒（AI必须遵守）
- 绝不跳阶段：即使自认为"简单需求"，也必须走完阶段0+8个节点，否则视为违规。
- 绝不猜测语义：遇到不确定的文件名、模块名、代码意图时，必须暂停并询问用户确认，禁止猜测后继续。
- 绝不留占位符：任何产出物（文档/代码）中不允许出现
TODO、待补充等未完成标记流出流水线。 - 先读后写：在任何代码修改前，必须先完整理解项目现有架构和代码风格。
- 每轮更新：每个节点完成后，更新
ai_pipeline/PIPELINE_STATUS.md记录当前进度。
