@dijkspicy/openspec-arch

MVP 原型系统设计工作流，构建在 OpenSpec 之上 —— 假设驱动、C1→C3 选择性下钻（C4 代码级 OUT）、验证闭环。

特性

• 假设驱动：先与用户确认目标用户、核心痛点与验证目标，再谈方案
• grilling 拷问：mvp / design 阶段自动加载 grilling skill，以设计树 + frontier 逐轮拷问，直到没有沉默假设
• ADHD 友好成文：mvp / design / reflect 正文与确认汇报按 i-have-adhd skill 风格组织
• C1-C3 选择性下钻：只在承载核心假设或技术风险处（detail 容器）深入 C3，C4 代码级明确 OUT，标准部分一句话带过
• 验证闭环：verify 从 mvp 验证目标派生检查项（代码类 + 设计类），每个验证任务关联假设 ID，原型完成后归档验证结果（坚持 / 转向 / 放弃）

安装

npm install -g @dijkspicy/openspec-arch
# 需要 OpenSpec CLI（>= 20.19）
npm install -g @fission-ai/openspec@latest
# schema 会引用这两个 skill，需要装（不装则运行时会静默退化）
npm install -g @dijkspicy/skills && dskills install --modules common

使用

1. 安装 schema

openspec-arch install              # 安装到用户全局 OpenSpec schemas
openspec-arch install --force      # 覆盖已安装的版本
openspec-arch uninstall            # 卸载

2. 初始化项目

openspec-arch init
openspec-arch init -c "Tech stack: TypeScript, React"
openspec-arch init -s my-schema -c "My project context"

| 参数 | 含义 | 默认值 | |------|------|--------| | -s <schema> | 写入 openspec/config.yaml 的 schema 字段 | spec-driven-mvp | | -c "<context>" | 写入 openspec/config.yaml 的 context 字段 | 不修改 | | 其余参数 | 透传给 openspec init | 自动附加 --tools opencode --no-animation |

init 内部先调用 openspec init（幂等、安全），再以保留注释的方式把 schema / context 写回 openspec/config.yaml。

3. 开始一个 change

# 在支持 OpenSpec 的编辑器里
/opsx:propose "你的 MVP 想法"

思路还模糊？先用 /opsx:explore 自由探索（发散），再进入 propose（收敛）：

/opsx:explore "想法"   →  自由探索：澄清意图、调研代码、对比方案（不实施）
/opsx:propose "想法"   →  创建 change → mvp/design 阶段用 grilling 逐轮拷问直到共识
/opsx:apply            →  按 verifications.md 分解到各子项目实施并验证（代码类 + 设计类）
/opsx:archive          →  验证结果 → 写 reflections.md → 归档

下一轮 /opsx:propose 的 mvp 阶段会先读上一轮归档的 reflections.md（archive/ 下日期最新的一轮），把"给下一轮的建议"纳入拷问——假设继承、教训复用，不会每次从零开始。

工作流

Schema：spec-driven-mvp，四个阶段。

MVP 定义（产品目标层）

生成 mvp.md，一页以内。动笔前先加载 grilling skill 拷问用户，设计树根节点：

• 目标用户是谁？痛点是什么？→ 现有替代方案、切换阈值
• 什么算验证成功？→ 量化指标、定性信号、时限
• MVP 最小边界在哪？→ 有证据地砍掉什么

grilling 结束条件：frontier 为空 + 用户确认达成共识。落笔后循环门禁：用户逐条确认，有异议回到对应小节修改，全部确认才进入下一阶段。

产出：用户与场景、核心假设（H1-H3，可证伪）、特性清单（F1..Fn 编号，关联假设）、验证目标、MVP 边界（In/Out）。

原型设计（C1 → C3 内嵌）

生成 design.md，同样先用 grilling 拷问设计决策，设计树根节点：

• 架构方案：C2 容器怎么切？还能更简单吗？
• 风险焦点：哪个容器承载最高不确定？
• 实施顺序：先验证最高风险假设？

设计引用 mvp 已定的边界、假设与特性，不重复写。 按 C1 → C3 串行撰写，上一层确认后才做下一层，C3 完成后回头整体检查一遍（C4 代码级明确 OUT）：

• C1 · 系统上下文 — 上下文图：边界、外部实体、依赖方向（谁依赖我、我依赖谁）、交互接口（用户触点/外部系统集成面）
• C2 · 容器分解与关系设计 —
  • 容器清单：子项目/容器（微服务）/职责/关联 mvp 特性/技术/下钻标记
  • 容器间关系：一张图——边标功能（谁连谁、满足什么请求）与数据方向，影响假设处标交互风格（同步/异步/共享存储）；一表——数据归属（归属/产生/消费）；协议/字段不关键，集成不确定处才展开
• C3 · 容器内关键设计 — 仅 detail 容器，聚焦 关键/影响大/有风险

验证计划与实施

生成 verifications.md，规划本轮验证任务，按容器/子项目编排，detail 容器优先：

• 代码类（含测试）：从 mvp 验证目标与特性派生检查项——切片能跑、指标可测、构建/命令验证；验证目标需要行为测试时补单测/集成
• 设计类：实现与 C2 接口功能/数据流、C3 关键设计的一致性核对
• 每个验证任务关联 mvp 假设 ID——验证目标回溯到假设

实施时按 verifications.md 推进，每个任务一道门禁：

• 有子项目（git submodule 承载，由不同人负责）：父仓不碰子项目仓库，为每个子项目创建一份 propose（三件套：设计约束 + 验证任务含通过标准 + 关联假设背景，一个子项目一份），交付方式问用户（Issue / Handoff 文档 / 自选）；回传 = 人工反馈——父仓按反馈在 verifications.md 打勾并标注 [人工反馈]，不二次验证；未反馈条目问用户：等反馈或标注 [未反馈]+理由 跳过
• 没有子项目：用主项目直接实施并验证，通过后打勾
• 局部调整（不动方向）直接改 verifications.md 继续；方向需重大调整时暂停，建议 archive 本轮、propose 新 change

归档

原型验证完成后，先问用户验证结果，再写 reflections.md：

• 验证摘要：假设 | 结果（成立/不成立/部分成立）| 证据（可跳转指针 / 凭印象 / 凭反馈）
• 关键发现
• 决策：坚持（方向成立，继续投入）/ 转向（重开 change）/ 放弃（停止投入）
• 给下一轮的建议（三档映射）：成立 → 下钻细节/推进下一假设/闭环不再重复论证；部分成立 → 拆分重测；不成立 → 剔除/改写/衍生

决策由用户做出，你只记录。 归档完成后问用户下一步（继续下一轮 / 暂停）。reflections.md 随 change 归档，下一轮 mvp 会读它。

context 怎么写

context 会被注入到所有 artifact 的 instruction，是 AI 理解项目的关键。写项目独有的信息：

context: |
  技术栈:
    - 前端: React 18 + TypeScript + Tailwind CSS
    - 后端: Node.js 22 + Express + Prisma
    - 数据库: PostgreSQL 16

  代码约定:
    - 错误处理: Result<T, E> 模式
    - 提交: conventional commits

  领域知识:
    - 核心实体: Organization / Subscription / Invoice
    - 关键约束: 账单数据不可篡改；三方支付 3s 超时
    - 合规: 保留 7 年审计日志

原则：

• 只写项目独有的，不写 AI 已知的通用知识
• 写会影响设计决策的约束
• 新贡献者第一周需要知道的
• 通常 1-2KB 足够（上限 50KB）

开发

npm install
node bin/openspec-arch.js --help