AI 工程化开发的三层架构：从「单兵作战」到「工业化生产」

大家好我是玄姐。PSSDD AI 编程干货直播欢迎点击预约直播见。当 AI 编程从「Demo 级玩具」走向「生产级系统」我们需要的不是更强大的模型而是一套完整的工程化架构。OpenSpec、Superpowers、Harness 分别对应需求层、纪律层、调度层三层解耦、各自演进才是可持续的 AI 工程化路径。一、问题本质为什么单模型编程走不远直接用 LLM 写代码本质上是单点故障语义漂移同样的 Prompt三次输出三种接口设计过程黑盒模型怎么想的、怎么改的不可追溯质量随机有测试还是无测试、有审查还是直出全看模型「心情」协作混乱多个 Agent 同时工作时没有「总线」做状态同步这就像一个没有图纸、没有施工规范、没有项目经理的工程队盖个草棚可以盖楼必塌。要解决这个问题需要借鉴传统软件工程的分层思想将「做什么」、「怎么做」、「谁来做」彻底解耦形成三层架构。二、三层架构详解Spec → Discipline → OrchestrationLayer 1OpenSpec 需求层的「唯一真相源」OpenSpec 不是简单的 Prompt 管理工具而是Spec-Driven Development规范驱动开发的基础设施。它的核心架构设计围绕一个目标让需求成为可版本化、可验证、可共享的契约。架构核心四级状态机propose: # 变更提案阶段 —— 记录意图、影响面、回滚策略spec: # 规格固化阶段 —— 接口定义、数据模型、验收标准ACverify: # 产出验证阶段 —— 自动化检查是否符合 specarchive: # 知识归档阶段 —— 沉淀为可复用的领域知识目录结构即架构openspec/├── proposals/ # RFC 式变更提案Why├── specs/ # 技术规格说明书What│ ├── api-schema.yml # OpenAPI 规范│ ├──>Schema-first先定义接口契约再生成代码避免「实现污染接口」ACAcceptance Criteria显性化将「看起来对了」转化为可执行的 Given-When-Then 语句Git-nativespec 与代码同仓管理PR 即变更评审Code Review 同时审 spec 和实现Layer 2Superpowers 纪律层的「强制约束」如果说 OpenSpec 是「图纸」Superpowers 就是「施工规范手册」。它是一个面向 AI 的技能约束框架Skill Constraint Framework通过声明式配置强制 Agent 遵循工程最佳实践。技能系统的架构设计Superpowers 采用策略模式Policy Pattern设计每个技能是一个独立的 Markdown 文件遵循「触发条件-约束规则-检查清单」三段式结构# Skill: test-driven-development## Trigger- file_pattern: *.py- task_type: feature_implementation ## Constraints1. 必须先提交 test_cases/ 目录下的测试文件2. 实现代码必须通过 pytest 且覆盖率 gt; 80%3. 禁止在生产代码中直接修改测试断言 ## Checklist- [ ] 测试先行Red-Green-Refactor- [ ] 边界条件覆盖Null, Empty, Overflow- [ ] 测试即文档描述性行为驱动命名关键技能矩阵技能工程纪律防呆机制writing-plans强制设计先行禁止直接输出代码必须先输出设计文档code-review同行评审关键文件必须经第二 Agent 审阅才能合并verification-before-completion完成定义DoD必须运行验证命令并粘贴输出结果dependency-check供应链安全引入新依赖前必须说明许可证与漏洞扫描结果架构原则最小权限加载根据任务类型动态加载技能避免上下文膨胀可组合性技能可以叠加如 TDD Code Review也可以互斥如快速原型模式关闭 TDD零侵入纯文本配置不绑定特定 IDE 或 Agent 框架Layer 3Harness 协作层的「调度中枢」Harness 是 Multi-Agent SystemMAS的编排引擎解决的是分布式开发中的共识、并发、容错三大难题。角色拓扑与权限模型Harness 引入基于角色的访问控制RBAC和空间隔离Namespace Isolation# AGENTS.md —— 团队拓扑定义team: architect: scope: [openspec/specs/, docs/architecture/] permissions: [read-all, propose-spec] backend: scope: [src/, tests/] permissions: [read-specs, write-implementation] skills: [test-driven-development, code-review] qa: scope: [tests/, openspec/reports/] permissions: [read-all, write-reports, block-merge] team_lead: scope: [*] permissions: [orchestrate, approve-merge, override]工作流编排引擎Harness 的核心是一个状态机驱动的任务调度器任务分解Team Lead Agent 读取 OpenSpec 的tasks/目录生成 DAG有向无环图并发调度无依赖的任务并行分派Backend 与 Frontend 同时开工依赖解耦通过 Spec 中的接口契约解耦前后端基于 Mock 契约并行开发质量门禁提交前触发 Git HooksLint、Test、Security Scan 必须全绿故障回灌测试失败自动创建 Bug Ticket 并分配给原开发 Agent关键技术机制Context 隔离每个 Agent 只能看到其scope内的文件防止「上下文污染」事件总线Agent 间通过harness/events/目录异步通信解耦直接对话依赖不可变历史所有 Agent 操作通过 Git 提交记录完整可追溯Audit Trail三、三层协同完整的工程化闭环将三层串联形成一个从需求到交付的工业化流水线┌─────────────┐ ┌─────────────┐ ┌─────────────┐│ OpenSpec │───▶│ Harness │───▶│ Superpowers ││ (Spec层) │ │ (调度层) │ │ (纪律层) ││ │ │ │ │ ││ • 需求契约 │ │ • 角色分派 │ │ • TDD约束 ││ • 接口定义 │ │ • 并发调度 │ │ • 代码审查 ││ • 验收标准 │ │ • 质量门禁 │ │ • 完成验证 │└─────────────┘ └─────────────┘ └─────────────┘ │ │ │ ▼ ▼ ▼openspec/specs/ AGENTS.md skills/*.md │ │ │ └───────────────────┴───────────────────┘ │ ▼ ┌─────────────────────┐ │ Agent Team │ │ • Architect │ │ • Backend │ │ • Frontend │ │ • QA │ └─────────────────────┘ │ ▼ ┌─────────────────────┐ │ Delivery │ │ • 可验证的代码 │ │ • 可追溯的变更 │ │ • 可复用的知识 │ └─────────────────────┘关键协同点Spec 是契约Harness 的所有任务分派基于openspec/tasks/Superpowers 的验收基于openspec/acceptance.md纪律是常量无论团队规模如何变化1 个 Agent 还是 10 个Superpowers 的技能约束不变调度是变量Harness 根据项目阶段POC / MVP / Production动态调整 Agent 拓扑但始终遵循 OpenSpec 和 Superpowers 的约束四、生产级落地的架构演进路径不是所有项目都需要三层全量部署。建议按架构成熟度模型渐进式引入阶段一单 Agent OpenSpec规范先行哪怕只有 1 个 Agent也强制要求先写spec.md再写代码建立「无 spec 不开发」的硬性文化产出需求文档化、接口契约化阶段二多 Agent Superpowers纪律加固引入 TDD 和 Code Review 技能强制质量门禁建立「红绿重构」的开发节奏产出代码可维护、测试有覆盖阶段三Agent Team Harness工业化协作定义 AGENTS.md 角色拓扑启用并发开发集成 CI/CD 流水线自动化验证产出可扩展团队、可并行交付五、架构设计的取舍与边界在落地这套体系时需要明确各层的职责边界避免过度设计反模式问题正确做法在 OpenSpec 中写实现细节Spec 变成伪代码失去抽象价值Spec 只定义「做什么」不定义「怎么做」Superpowers 技能全加载上下文过长模型注意力分散按需加载每个 Agent 最多 2-3 个核心技能Harness 角色过于细分调度复杂度超过业务复杂度小团队3 Agent合并角色降低协调成本三层循环依赖Harness 修改 SpecSpec 依赖技能技能依赖 Harness严格单向依赖Spec → Harness → Superpowers六、结语工程化的本质是约束OpenSpec、Superpowers、Harness 三层架构的本质是在 AI 的「创造力」之上施加「工程约束」OpenSpec 约束需求范围防止镀金Scope CreepSuperpowers 约束实现过程防止走捷径Technical DebtHarness 约束协作方式防止混乱Chaos当这三层约束到位AI 编程才能从「 Artisanal Craft手工艺品」进化为「Industrial Production工业化生产」可预期、可验证、可规模。架构设计需要权衡。本文提出的这三层模型适用于中大型软件项目1万行代码、2人协作对于脚本级任务可能过重。建议根据项目复杂度选择合适的架构层级。PSSDD AI 编程干货直播欢迎点击预约直播见。好了这就是我今天想分享的内容。如果你对构建企业级 AI 原生应用新架构设计和落地实践感兴趣别忘了点赞、关注噢~—1—加我微信扫码加我有很多不方便公开发公众号的我会直接分享在朋友圈欢迎你扫码加我个人微信来看加星标★不错过每一次更新⬇戳”阅读原文“立即预约