back
loading skill details...
用AI写代码一时爽，项目越写越乱火葬场？Superpowers方法论5道Gate卡住质量：设计没想清楚不准动手、没写测试不准提交。把「能跑就行」升级成工程级交付，让AI帮你写出可维护的代码。支持全栈项目（Web/移动端/API/数据）、团队协作规范、CI/CD集成指南。从需求到上线的完整工程化流水线，杜绝"AI生...
---
name: ai-engineering-workflow
version: 1.3.0
description: |
用AI写代码一时爽，项目越写越乱火葬场？Superpowers方法论5道Gate卡住质量：设计没想清楚不准动手、没写测试不准提交。把「能跑就行」升级成工程级交付，让AI帮你写出可维护的代码。支持全栈项目（Web/移动端/API/数据）、团队协作规范、CI/CD集成指南。从需求到上线的完整工程化流水线，杜绝"AI生成代码没法维护"的通病。
触发词：AI编程工程化、Superpowers方法论、编程工作流、Gate门槛、TDD驱动、AI开发流程、工程化开发、AI代码规范、代码质量保障、AI辅助开发流程、软件工程质量、AI编程最佳实践、工程化AI、AI code workflow、TDD with AI、AI development process、code quality gates、AI工程实践、AI编码规范、工程化工作流、AI项目管理、持续集成AI、AI代码审查、开发流程优化、AI交付质量、superpowers workflow、AI native engineering、代码可维护性、技术债务管理、AI重构工作流、交付标准、工程化交付、AI代码太乱怎么办、怎么管理AI代码、AI编程流程、工程化方法论、AI代码审查标准、开发规范化、AI生成代码质量、代码工程化、开发流程标准化、AI辅助编程规范、软件质量门禁、agentic engineering、vibe coding to engineering、AI coding workflow、engineering discipline AI
排除：纯代码编写(无流程)、项目管理工具配置、非AI辅助开发、纯代码补全
---
# AI编程工程化 🏗️
> 从Vibe Coding到Agentic Engineering。AI写的代码不是"能跑就行"，而是"可维护、可测试、可扩展"。
## 触发条件
### ✅ 匹配关键词（满足任一即触发）
| 类别 | 关键词 |
|------|--------|
| 通用 | AI编程工程化 / 工程化开发 / Superpowers方法论 / 编程工作流 / 开发流程 |
| 质量 | 代码质量 / Gate门槛 / TDD驱动 / AI代码规范 / 代码审查 / 代码可维护性 |
| 流程 | 开发流程 / AI开发流程 / 工程化工作流 / 交付标准 / 工程化交付 / 开发规范化 |
| 场景 | 全栈项目 / 微服务 / API设计 / 数据管道 / 前后端协同 / 移动端 |
| 管理 | 技术债务 / 重构工作流 / CI/CD集成 / 持续集成 / AI项目管理 |
| 痛点 | 代码没法维护 / AI写的代码太乱 / 项目越来越乱 / 怎么管理AI代码 / AI代码质量差 |
| 进阶 | agentic engineering / vibe coding to engineering / AI coding workflow / engineering discipline |
| 英文 | AI engineering / code quality gates / TDD with AI / AI code workflow / superpowers workflow / AI native engineering / dev workflow / software quality / engineering methodology |
### ❌ 排除关键词（明确不触发）
- 纯代码补全 / Copilot类 / IDE插件推荐 → 拒绝
- 项目管理工具（Jira/Linear/Notion）配置 → 拒绝
- 非AI辅助的传统开发 → 拒绝
- 纯学习/教程（"教我写代码"）→ 拒绝
- 代码片段生成（无工程化需求）→ 拒绝
## 核心流程（5 Gates + 持续改进）
### Gate 1: 设计门槛
**目标**：确保需求边界和接口契约清晰，避免返工
**通过标准**：设计文档通过所有评审检查项
- 明确需求边界和接口契约
- 输出：设计文档（接口定义/数据模型/约束条件/依赖关系/非功能需求）
- 设计评审清单：
- [ ] 核心实体和关系是否清晰？（ER图/数据字典）
- [ ] API边界是否定义（RESTful/GraphQL/gRPC）？
- [ ] 数据库Schema是否合理（范式/索引/约束/分区）？
- [ ] 错误处理和边界条件是否覆盖？
- [ ] 安全考量（认证/授权/数据校验/加密）是否明确？
- [ ] 性能指标（响应时间/并发量/数据量/QPS）是否量化？
- [ ] 可用性目标（SLA/容灾/降级策略）是否定义？
- [ ] 第三方依赖是否评估（版本/稳定性/许可证）？
- 未通过：返回需求澄清，不可跳过
### Gate 2: 计划门槛
**目标**：将设计拆解为可独立验证的原子步骤
**通过标准**：所有步骤有明确验收标准，依赖关系清晰
- 拆分任务为可独立验证的步骤（每步≤4小时工作量）
- 每步必须有明确的验收标准（输入→预期输出→边界情况）
- 输出：执行计划（步骤/依赖关系/验收标准/预估复杂度/风险点）
- 任务拆分原则：
- 单一职责：每步只做一件事
- 可测试：每步完成后能独立验证
- 有序依赖：明确哪些可以并行，哪些必须串行
- 可回滚：每步完成后提交checkpoint
- 最小风险：高风险步骤优先执行
- 计划模板：
```
| 步骤 | 任务 | 依赖 | 验收标准 | 复杂度 | 风险 |
|------|------|------|----------|--------|------|
| 1 | | 无 | | S/M/L | 高/中/低 |
| 2 | | 1 | | S/M/L | 高/中/低 |
```
- 未通过：返回重新拆分
### Gate 3: 测试门槛
**目标**：先写测试再写实现（TDD红-绿-重构循环）
**通过标准**：测试用例覆盖所有功能点和关键边界
- 先写测试再写实现（红→绿→重构）
- 测试金字塔：单元测试(70%) > 集成测试(20%) > E2E测试(10%)
- 输出：测试用例集（边界/正常/异常/性能/安全/兼容性）
- 测试覆盖要求：
- 核心业务逻辑：≥90%覆盖率
- API接口：100%端点覆盖（包括错误场景）
- 错误路径：至少覆盖所有已知的异常场景
- 边界值：空值/极大值/极小值/特殊字符/并发
- 性能基准：响应时间/吞吐量/资源使用
- 测试命名规范：`test_{功能}_{场景}_{预期结果}`
- 测试分类：
- 单元测试：函数/方法级别
- 集成测试：模块间交互
- 契约测试：API接口契约
- E2E测试：用户场景完整流程
- 性能测试：压力/负载/稳定性
- 安全测试：注入/认证/授权
- 未通过：补充测试覆盖，不进入实现阶段
### Gate 4: 实现门槛
**目标**：按计划逐步实现，每步通过测试才算完成
**通过标准**：所有测试通过，代码符合规范
- 按计划逐步实现，每步通过测试
- 编码规范：
- 函数/方法长度≤50行
- 嵌套深度≤3层
- 魔法数字必须用常量替代
- 复杂逻辑必须有注释说明"为什么"（不是"做了什么"）
- 命名规范：变量/函数语义化，类名PascalCase，函数camelCase
- 每完成一步：
1. 运行测试套件 → 全绿
2. 代码格式化（Prettier/Black/gofmt）
3. Lint检查通过（ESLint/Pylint/golangci-lint）
4. 代码提交 → 有意义的commit message（Conventional Commits）
5. 更新文档 → API变更同步更新
- 技术债务管理：
- 遇到"先这样后面改"的地方，立即记录到TODO清单
- 格式：`// TODO(优先级): 描述 | 影响范围 | 预计工时`
- 每个TODO标注优先级（P0-P3）和影响范围
- 每周清理TODO，不允许超过20个积压
- AI代码特别注意：
- AI生成的代码必须逐行审查（可能引入隐式bug）
- 检查AI是否使用了过时的API/库
- 检查AI是否添加了不必要的依赖
- 检查AI生成的错误处理是否完整
- 未通过：回退到上一个通过的步骤
### Gate 5: 审查门槛
**目标**：多维度审查，确保交付质量
**通过标准**：无严重问题，中等问题已修复或记录
- 代码审查：可读性/可维护性/DRY原则/SOLID原则
- 安全审查：注入/认证/授权/数据泄露/日志安全/CORS
- 性能审查：时间复杂度/空间复杂度/数据库查询/N+1问题/内存泄漏
- 输出：审查报告（问题清单/严重等级/改进建议/通过/不通过）
- 审查清单：
```
□ 安全性：无SQL注入/XSS/CSRF风险，认证授权正确
□ 性能：无N+1查询/无内存泄漏/无阻塞操作/合理使用缓存
□ 可维护性：命名清晰/逻辑分层/无重复代码/职责单一
□ 测试性：可独立测试/无隐式依赖/Mock合理/测试覆盖≥90%
□ 文档性：API文档/关键决策/部署说明/变更日志
□ 兼容性：向后兼容/版本迁移方案/降级策略
□ 可观测性：日志规范/Metrics/Tracing/告警
□ 部署性：CI/CD就绪/配置外部化/健康检查/回滚方案
```
### 持续改进循环（Gate 5之后）
- 上线后监控：错误率/性能指标/用户反馈/资源使用
- 每周回顾：哪些Gate执行不到位，为什么，如何改进
- 知识沉淀：将踩过的坑写入团队规范/Checklist
- 指标追踪：代码质量趋势/交付速度/缺陷密度
- 技术债务复盘：本月新增/清理/剩余债务
## 输出模板
### 项目启动模板
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🏗️ 工程化启动 | {项目名}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 需求概述：{一句话描述}
🎯 核心目标：{量化目标}
🔧 技术栈：{语言/框架/数据库/部署}
⏰ 预估周期：{S/M/L/XL}
📊 复杂度：{高/中/低}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Gate进度：
⬜ Gate 1 设计 | 状态：待开始
⬜ Gate 2 计划 | 状态：待开始
⬜ Gate 3 测试 | 状态：待开始
⬜ Gate 4 实现 | 状态：待开始
⬜ Gate 5 审查 | 状态：待开始
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 产物目录：
├── docs/
│ ├── design.md （设计文档）
│ ├── plan.md （执行计划）
│ └── review.md （审查报告）
├── tests/
│ ├── unit/ （单元测试）
│ ├── integration/ （集成测试）
│ └── e2e/ （E2E测试）
├── src/ （实现代码）
├── docs/
│ ├── changelog.md （变更日志）
│ └── todo.md （技术债务清单）
└── .github/
└── workflows/ （CI/CD配置）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
### 进度更新模板
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🏗️ 工程化进度 | {项目名}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Gate 1 设计 | ✅ Gate 2 计划
⏳ Gate 3 测试 | ⬜ Gate 4 实现
⬜ Gate 5 审查
当前卡点：{无/具体卡点}
技术债务：{X}项（P0: {n}, P1: {n}, P2: {n}）
测试覆盖率：{X}%
代码质量分：{X}/10
本周完成：{N}个步骤
下周计划：{N}个步骤
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
### 审查报告模板
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 审查报告 | {项目名} - Gate 5
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔴 严重问题（必须修复）：
1. {问题描述} → {修复建议}
🟡 中等问题（建议修复）：
1. {问题描述} → {修复建议}
🟢 轻微问题（可选修复）：
1. {问题描述} → {修复建议}
📊 评分：
代码质量：{X}/10
测试覆盖：{X}%
安全等级：{X}/10
性能表现：{X}/10
文档完整：{X}/10
可观测性：{X}/10
🏁 结论：{通过/有条件通过/不通过}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
## 常见场景适配
| 场景 | Gate 1重点 | Gate 3重点 | Gate 5重点 |
|------|-----------|-----------|-----------|
| Web全栈 | API设计+DB Schema+前后端边界 | API集成测试+组件单测 | XSS/CSRF/注入+首屏性能 |
| API/微服务 | 接口契约(OpenAPI)+服务边界 | 契约测试+压力测试 | 限流/熔断/降级+日志链路 |
| 数据管道 | 数据源/Schema+处理逻辑+输出 | 数据质量测试+边界数据 | 性能(大数据量)+幂等性+重试 |
| AI/ML项目 | 模型选型+数据需求+评估指标 | 模型准确性+对抗样本+公平性 | 推理性能+版本管理+可解释性 |
| 移动端 | UI设计+离线策略+推送方案 | UI自动化+兼容性测试 | 包大小+启动速度+内存占用 |
| CLI工具 | 命令设计+参数定义+帮助文档 | 命令行参数测试+集成测试 | 跨平台兼容+安装体验+错误提示 |
## 反模式警示（常见错误）
| 反模式 | 症状 | 正确做法 | 严重程度 |
|--------|------|----------|----------|
| Gate跳过 | "先写代码再补测试" | 严格顺序，不可跳过 | 🔴 严重 |
| 过度设计 | 花3天设计一个CRUD | Gate 1控制在2小时内 | 🟡 中等 |
| 测试形式化 | 只写happy path | 必须覆盖异常和边界 | 🔴 严重 |
| 审查走过场 | "LGTM"直接通过 | 至少检查安全+性能 | 🔴 严重 |
| 债务堆积 | 100+ TODO未处理 | 每周清理，不超过20个 | 🟡 中等 |
| AI盲信 | AI生成的代码不审查 | AI代码更需要严格审查 | 🔴 严重 |
| 完美主义 | 每步都要做到完美 | 完成>完美，迭代改进 | 🟢 轻微 |
| 文档缺失 | "代码即文档" | 关键决策必须有文档 | 🟡 中等 |
## 边界约束
1. **不跳步**：必须按Gate顺序，不可跳过任何Gate
2. **可回退**：任何Gate失败可回退到上一个通过的Gate
3. **文档先行**：每个Gate必须有文档输出才算通过
4. **AI代码更严审**：AI生成的代码审查标准应比手写代码更严格
5. **规模适配**：小项目（<500行）可合并Gate 1+2，大项目（>5000行）每个Gate需要独立评审
6. **时间控制**：每个Gate有时间盒（Gate 1: 2h, Gate 2: 1h, Gate 3: 2-4h, Gate 4: 按步推进, Gate 5: 1-2h）
7. **持续改进**：每个项目结束后复盘，更新Checklist和规范
## Output Language
中文输出
don't have the plugin yet? install it then click "run inline in claude" again.