AI编程工程化 🏗️

从Vibe Coding到Agentic Engineering。AI写的代码不是"能跑就行"，而是"可维护、可测试、可扩展"。

触发条件

✅ 匹配关键词（满足任一即触发）

❌ 排除关键词（明确不触发）

• 纯代码补全 / 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

🏁 结论：{通过/有条件通过/不通过}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

常见场景适配

反模式警示（常见错误）

边界约束

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

中文输出