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

大家好，我是玄姐。

PS：

SDD AI 编程干货直播，欢迎点击预约，直播见。

当 AI 编程从「Demo 级玩具」走向「生产级系统」，我们需要的不是更强大的模型，而是一套完整的工程化架构。OpenSpec、Superpowers、Harness 分别对应需求层、纪律层、调度层：三层解耦、各自演进，才是可持续的 AI 工程化路径。

一、问题本质：为什么单模型编程走不远？

直接用 LLM 写代码，本质上是单点故障：

语义漂移：同样的 Prompt，三次输出三种接口设计
过程黑盒：模型怎么想的、怎么改的，不可追溯
质量随机：有测试还是无测试、有审查还是直出，全看模型「心情」
协作混乱：多个 Agent 同时工作时，没有「总线」做状态同步

这就像一个没有图纸、没有施工规范、没有项目经理的工程队，盖个草棚可以，盖楼必塌。

要解决这个问题，需要借鉴传统软件工程的分层思想：将「做什么」、「怎么做」、「谁来做」彻底解耦，形成三层架构。

二、三层架构详解：Spec → Discipline → Orchestration

Layer 1：OpenSpec 需求层的「唯一真相源」

OpenSpec 不是简单的 Prompt 管理工具，而是Spec-Driven Development（规范驱动开发）的基础设施。它的核心架构设计围绕一个目标：让需求成为可版本化、可验证、可共享的契约。

架构核心：四级状态机

propose:   # 变更提案阶段 —— 记录意图、影响面、回滚策略spec:      # 规格固化阶段 —— 接口定义、数据模型、验收标准（AC）verify:    # 产出验证阶段 —— 自动化检查是否符合 specarchive:   # 知识归档阶段 —— 沉淀为可复用的领域知识

目录结构即架构

openspec/├── proposals/          # RFC 式变更提案（Why）├── specs/              # 技术规格说明书（What）│   ├── api-schema.yml  # OpenAPI 规范│   ├── data-model.md   # 领域模型定义│   └── acceptance.md   # 验收标准（Given-When-Then）├── tasks/              # 任务拆解（WBS）└── reports/            # 验证报告与合规证明

关键技术决策：

Schema-first：先定义接口契约，再生成代码，避免「实现污染接口」
AC（Acceptance Criteria）显性化：将「看起来对了」转化为可执行的 Given-When-Then 语句
Git-native：spec 与代码同仓管理，PR 即变更评审，Code Review 同时审 spec 和实现

Layer 2：Superpowers 纪律层的「强制约束」

如果说 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 3：Harness 协作层的「调度中枢」

Harness 是 Multi-Agent System（MAS）的编排引擎，解决的是分布式开发中的共识、并发、容错三大难题。

角色拓扑与权限模型

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 Hooks，Lint、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 修改 Spec，Spec 依赖技能，技能依赖 Harness	严格单向依赖：Spec → Harness → Superpowers

六、结语：工程化的本质是约束

OpenSpec、Superpowers、Harness 三层架构的本质，是在 AI 的「创造力」之上施加「工程约束」：

OpenSpec 约束需求范围防止镀金（Scope Creep）
Superpowers 约束实现过程防止走捷径（Technical Debt）
Harness 约束协作方式防止混乱（Chaos）

当这三层约束到位，AI 编程才能从「 Artisanal Craft（手工艺品）」进化为「Industrial Production（工业化生产）」，可预期、可验证、可规模。

架构设计需要权衡。本文提出的这三层模型适用于中大型软件项目（>1万行代码、>2人协作），对于脚本级任务可能过重。建议根据项目复杂度，选择合适的架构层级。

PS：

SDD AI 编程干货直播，欢迎点击预约，直播见。

好了，这就是我今天想分享的内容。如果你对构建企业级 AI 原生应用新架构设计和落地实践感兴趣，别忘了点赞、关注噢~

—1—

加我微信

扫码加我👇有很多不方便公开发公众号的我会直接分享在朋友圈，欢迎你扫码加我个人微信来看👇

加星标★，不错过每一次更新！

⬇戳”阅读原文“，立即预约！