# 三支柱架构（Harness + OpenSpec + Superpowers）

本项目 Vibe Coding 工作流由三件工具协作，各司其职、互不重叠。

## 分工口诀

| 支柱 | 管什么 | 载体 |
|---|---|---|
| 🛠 Harness（Claude Code） | **环境怎么配合** — 规范、权限、执行环境 | `CLAUDE.md`、`.claude/settings.json` |
| 📋 OpenSpec | **要做什么** — 需求与变更的单一事实源 | `openspec/`（specs + changes，spec-driven） |
| 🧭 Superpowers | **怎么一步步做对** — 过程方法论 | 全局插件 + `.claude/skills/` |

## 图 1 · 架构总览

```mermaid
flowchart LR
    subgraph HARNESS["🛠 Harness · Claude Code<br/>执行环境 — 环境怎么配合"]
        H1["CLAUDE.md<br/>规范 · 工作流"]
        H2[".claude/settings.json<br/>权限 allowlist"]
    end

    subgraph OPENSPEC["📋 OpenSpec<br/>单一事实源 — 要做什么"]
        O1["specs/ 主 spec<br/>shared · frontend · backend"]
        O2["changes/ 变更提案<br/>proposal → specs → design → tasks"]
    end

    subgraph SUPER["🧭 Superpowers<br/>过程方法论 — 怎么一步步做对"]
        S1["brainstorming<br/>分类 / 设计"]
        S2["writing-plans<br/>实施计划"]
        S3["TDD · debugging<br/>review · verification"]
    end

    BRIDGE["🔗 openspec-superpowers-bridge<br/>openspec 阶段 ↔ superpowers 技能"]

    HARNESS -.->|"约束 / 授权"| OPENSPEC
    HARNESS -.->|"约束 / 授权"| SUPER
    OPENSPEC --- BRIDGE --- SUPER
```

## 图 2 · 架构总览（技术分层视图）

三支柱映射到经典 DDD 分层：Harness 是基础设施容器、OpenSpec 是领域核心、
Superpowers 是横切关注点。与图 1 是同一架构的两种视角——图 1 强调「谁与谁协作」，
本图强调「分层依赖与横切」。

```mermaid
flowchart TB
    subgraph PRES["① 表现层 · 交互入口"]
        N1["用户需求 / 变更请求<br/>Claude Code 对话（CLI / IDE）"]
    end

    subgraph APP["② 应用层 · 编排（三支柱协作点）"]
        N2["openspec-superpowers-bridge<br/>openspec 阶段 ↔ superpowers 技能映射"]
        N3["工作流：brainstorming → propose → plan → apply → archive"]
    end

    subgraph DOM["③ 领域层 · 单一事实源 —— OpenSpec"]
        N4["specs/ 主 spec<br/>shared · frontend · backend"]
        N5["changes/ 变更提案<br/>proposal → specs → design → tasks"]
    end

    subgraph INF["④ 基础设施层 · 执行容器 —— Harness"]
        N6["CLAUDE.md · 规范"]
        N7[".claude/settings.json · 权限"]
        N8["执行环境（权限 / 沙箱 / git）"]
    end

    subgraph ART["⑤ 产物层 · 输出"]
        N9["sources/ 各端源码"]
        N10["docs/ 需求 · spec · 计划"]
    end

    subgraph CROSS["⑥ 横切关注点 · 过程方法论 —— Superpowers"]
        N11["test-driven-development"]
        N12["systematic-debugging"]
        N13["requesting-code-review"]
        N14["verification-before-completion"]
    end

    PRES --> APP --> DOM --> INF --> ART
    CROSS -.-> APP
    CROSS -.-> DOM
    CROSS -.-> INF
```

## 图 3 · 一次变更的生命周期

```mermaid
flowchart TB
    REQ(["👤 需求 / 变更请求"])

    STEP1["1️⃣ brainstorming　<i>Superpowers</i><br/>分类：spike / bounded / architectural"]

    STEP2["2️⃣ /opsx:propose　<i>OpenSpec</i><br/>proposal → specs → design → tasks"]

    STEP3["3️⃣ writing-plans　<i>Superpowers</i><br/>实施计划 → docs/superpowers/plans/"]

    STEP4["4️⃣ /opsx:apply　<i>Superpowers</i><br/>TDD 实现 · systematic-debugging · review"]

    STEP5["5️⃣ /opsx:archive　<i>OpenSpec</i><br/>增量 spec 合并回主 spec"]

    DONE(["✅ 完成"])

    REQ --> STEP1
    STEP1 -->|"architectural"| STEP2
    STEP1 -.->|"spike：直接给答案"| DONE
    STEP1 -.->|"bounded：in-chat 短设计"| STEP4
    STEP2 --> STEP3
    STEP3 --> STEP4
    STEP4 --> STEP5
    STEP5 --> DONE
```

## openspec 阶段 → superpowers 技能（桥接映射）

| openspec 阶段 | superpowers 技能 |
|---|---|
| proposal / specs / design | brainstorming → writing-plans |
| tasks 编排与执行 | writing-plans 产物 → executing-plans / subagent-driven-development |
| 实现 | test-driven-development · systematic-debugging |
| 收尾 | requesting-code-review · verification-before-completion · finishing-a-development-branch |

> 桥接由 `.claude/skills/openspec-superpowers-bridge` 负责：把 openspec 各阶段映射到对应 superpowers 过程技能。