touyun-elderly-care/docs/architecture.md

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

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

分工口诀

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

图 1 · 架构总览

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 强调「谁与谁协作」， 本图强调「分层依赖与横切」。

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 · 一次变更的生命周期

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 过程技能。