Subsystem Design Spec

子系统设计规格

A Subsystem Design Spec is the bridge between a high-level System Spec and OpenSpec's change workflow. It takes one subsystem from the system-level architecture and produces a comprehensive, implementation-ready specification with opinionated progressive phases.

Core principle: Define contracts and phases before any code exists. Each phase is independently testable, contract-bounded, and follows FP progression: types -> pure functions -> effects -> composition.

子系统设计规格是高层系统规格与OpenSpec变更工作流之间的桥梁。它从系统级架构中取出单个子系统，生成包含约定式渐进阶段的完整、可直接落地的规格说明。

核心原则： 在编写任何代码之前先定义契约和阶段。每个阶段都可独立测试、有明确的契约边界，并且遵循FP演进顺序：类型 -> 纯函数 -> 副作用 -> 组合。

When to Use

适用场景

A System Spec (high-level) exists with subsystems identified
You're ready to deep-dive on one subsystem before starting OpenSpec
You're creating the second+ subsystem spec and need convention consistency

Do NOT use for:

High-level system specs (use
```
superpowers:brainstorming
```
)
OpenSpec artifacts (proposal, design, tasks) — OpenSpec handles those
Specs that don't decompose into implementation phases

已有高层系统规格，且已明确划分各子系统
你已准备好在启动OpenSpec之前深入设计单个子系统
你需要编写第2个及以上的子系统规格，需要保持规范一致性

禁止用于：

高层系统规格（请使用
```
superpowers:brainstorming
```
）
OpenSpec产出物（提案、设计、任务）—— 这类内容由OpenSpec直接处理
无法拆解为落地阶段的规格说明

Process

流程

Step 1: Load Conventions

步骤1：加载规范约定

Before writing anything, check for a project conventions file:

Search: docs/conventions.md, docs/spec-conventions.md

If conventions file exists: Load it. It contains established naming patterns, section structure, phase coding, and cross-subsystem contracts. Skip scanning individual specs — the conventions file is the single source of truth.

If no conventions file exists: Scan for prior subsystem specs:

Search: docs/**/*-spec*.md, docs/**/*-design*.md, docs/prd/**/*.md

If prior specs are found, extract conventions from them:

Section structure and depth — which sections, how detailed
Phase coding scheme — e.g., S1.1, S1.2 (carry forward S2.1, S2.2, etc.)
Naming patterns — design decisions (D1, D2...), user stories (US-{n}), acceptance criteria (AC-{n}.{y})
Cross-subsystem contracts — types, traits, or schemas already defined
Phase granularity — typical size estimates, task counts per phase

Present extracted conventions to the user before proceeding. Follow-on subsystem specs MUST maintain consistency with established conventions.

在编写任何内容之前，请先检查项目是否存在规范约定文件：

Search: docs/conventions.md, docs/spec-conventions.md

如果存在约定文件： 直接加载使用。文件中包含已确定的命名规则、章节结构、阶段编码、跨子系统契约。无需扫描单个历史规格，约定文件是唯一可信来源。

如果不存在约定文件： 扫描已有的子系统规格：

Search: docs/**/*-spec*.md, docs/**/*-design*.md, docs/prd/**/*.md

如果找到历史规格，从中提取约定规则：

章节结构和深度 —— 包含哪些章节、详细程度要求
阶段编码规则 —— 例如S1.1、S1.2（后续沿用S2.1、S2.2等格式）
命名规则 —— 设计决策（D1、D2...）、用户故事（US-{n}）、验收标准（AC-{n}.{y}）
跨子系统契约 —— 已定义的类型、特征、Schema
阶段粒度 —— 典型的规模估算、每个阶段的任务数量

在继续操作前先向用户展示提取到的约定规则。后续的子系统规格必须与已确立的约定保持一致。

Step 2: Reference the System Spec

步骤2：关联系统规格

Load the parent System Spec section for this subsystem. Extract:

Subsystem purpose and boundaries
Input/output contracts with adjacent subsystems
Technology choices already decided at system level
Architecture principles (FP-first, immutability, etc.)

加载当前子系统对应的父级系统规格章节，提取以下内容：

子系统目标和边界
与相邻子系统的输入/输出契约
系统层面已经确定的技术选型
架构原则（优先FP、不可变性等）

Step 3: Guide Document Creation

步骤3：指导文档创建

Create the subsystem design spec iteratively with the user. The document follows this structure (all sections required unless marked optional):

markdown

undefined

与用户协作迭代生成子系统设计规格。文档需遵循以下结构（除非标注可选，否则所有章节必填）：

markdown

undefined

S{n} {Subsystem Name} — Subsystem Design Spec

Version: x.y Status: Draft Date: YYYY-MM-DD Parent Spec: System Spec Name (Section N, S{n})

1. Overview

1.1 Goals

1.2 Non-Goals

2. Architecture

2.1 Component Diagram (mermaid)

2.2 Key Design Decisions

D1 — {Title}: rationale, tradeoffs D2 — {Title}: rationale, tradeoffs ...

3. User Stories

US-1: {Story} with AC-1.1, AC-1.2, ... US-2: {Story} with AC-2.1, AC-2.2, ... ...

4. Detailed Design

Per-component subsections with behavior, schemas, flows

5. Output Contract

Data schemas, file structures, API contracts, column definitions, constraints — the interface downstream consumers depend on

6. Error Handling

Exit codes, error categories, handling strategy per category

7. Testing Strategy

7.1 Unit Tests — what's covered, key scenarios

### 7.2 Integration Tests — with mocks, full flows
### 7.3 End-to-End Tests — opt-in, real external services

7.1 Unit Tests — what's covered, key scenarios

### 7.2 Integration Tests — with mocks, full flows
### 7.3 End-to-End Tests — opt-in, real external services

8. Performance Considerations

9. Future Considerations (out of scope for v1)

10. Dependencies

10.1 Packages/Crates

### 10.2 External Dependencies

10.1 Packages/Crates

### 10.2 External Dependencies

11. Implementation Phases

(See Phase Design Discipline below)

12. Acceptance Summary

Numbered list of acceptance conditions

Appendices (optional)

Reference material, API response structures, etc.

undefined

Reference material, API response structures, etc.

undefined

Step 4: Apply Phase Design Discipline (Section 11)

步骤4：应用阶段设计规范（第11章）

This is the core opinionated section. Each phase must satisfy:

Independently testable — verifiable with mocks, no prior phase fully needed
Contract-bounded — exposes explicit types/traits/interfaces for downstream
Reviewable — a human can review the phase's OpenSpec output in <=30 minutes
Sized for OpenSpec — each phase becomes one OpenSpec change with <=8 tasks

这是核心的约定式章节，每个阶段必须满足以下要求：

可独立测试 —— 可通过Mock验证，不需要完全依赖前置阶段
契约边界清晰 —— 为下游暴露明确的类型/特征/接口
可评审 —— 评审人员可在30分钟内完成该阶段OpenSpec产出的评审
适配OpenSpec规模 —— 每个阶段对应一个OpenSpec变更，包含不超过8个任务

Phase Template

阶段模板

markdown

undefined

markdown

undefined

S{n}.{m}: {Phase Name}

Scope: What this phase delivers — concrete, verifiable Size estimate: ~N files, ~N lines Contracts consumed: Prior phase contracts (or "None") Contracts exposed:

Type/trait/interface names and signatures Gate: Exact command to verify (e.g.,
```
cargo build && cargo test
```
) Verification: How a human reviewer manually verifies this phase works beyond the gate command — what to inspect, what to run, what output to expect. This becomes the reviewer's checklist during the human review checkpoint. Review tier: gate-only | spot-check | full-review (see Review Tiers below) Dependencies: Which prior phases, and what specifically (contracts only)

undefined

Scope: What this phase delivers — concrete, verifiable Size estimate: ~N files, ~N lines Contracts consumed: Prior phase contracts (or "None") Contracts exposed:

Type/trait/interface names and signatures Gate: Exact command to verify (e.g.,
```
cargo build && cargo test
```
) Verification: How a human reviewer manually verifies this phase works beyond the gate command — what to inspect, what to run, what output to expect. This becomes the reviewer's checklist during the human review checkpoint. Review tier: gate-only | spot-check | full-review (see Review Tiers below) Dependencies: Which prior phases, and what specifically (contracts only)

undefined

Phase Ordering — FP Progression

阶段排序 —— FP演进逻辑

Phase 1 — always: Domain types, core traits/interfaces, project scaffolding. No business logic. Only the type-level skeleton.
Early phases (parallel-safe): Config parsing, state management, I/O utilities, rate limiting — independent modules consuming Phase 1 types.
Middle phases: Pure-core logic, then effects/IO at boundaries. Concrete trait implementations (e.g., data source providers).
Final phase: Integration wiring, CLI/main entry point, dependency assembly. The imperative shell.

第1阶段（固定）： 领域类型、核心特征/接口、项目脚手架。无业务逻辑，仅包含类型层面的骨架。
早期阶段（可并行）： 配置解析、状态管理、I/O工具、限流 —— 依赖第1阶段类型的独立模块。
中期阶段： 纯核心逻辑，边界层的副作用/IO。具体的特征实现（例如数据源提供者）。
最终阶段： 集成编排、CLI/主入口、依赖组装。命令式外壳。

Phase Design Checklist

阶段设计检查清单

Phase Dependency Graph

阶段依赖图

Include a text diagram showing phase dependencies:

S{n}.1 (Types & Contracts)
 |-- S{n}.2 (Component A)
 |-- S{n}.3 (Component B)      <- parallel with S{n}.2
 |-- S{n}.4 (Component C)      <- parallel with S{n}.2, S{n}.3
 |    |
 |    |-- S{n}.5 (Provider X)  <- depends on S{n}.4
 |
 |-- S{n}.6 (Orchestration)    <- depends on S{n}.2-S{n}.4 contracts
      |
      --- S{n}.7 (CLI Wiring)  <- depends on all

Parallelizable: S{n}.2, S{n}.3, S{n}.4 can proceed in parallel after S{n}.1.

包含文本图示说明阶段依赖关系：

S{n}.1 (Types & Contracts)
 |-- S{n}.2 (Component A)
 |-- S{n}.3 (Component B)      <- parallel with S{n}.2
 |-- S{n}.4 (Component C)      <- parallel with S{n}.2, S{n}.3
 |    |
 |    |-- S{n}.5 (Provider X)  <- depends on S{n}.4
 |
 |-- S{n}.6 (Orchestration)    <- depends on S{n}.2-S{n}.4 contracts
      |
      --- S{n}.7 (CLI Wiring)  <- depends on all

Parallelizable: S{n}.2, S{n}.3, S{n}.4 can proceed in parallel after S{n}.1.

Review Tiers

评审等级

Each phase is assigned a review tier that determines how much human attention it needs at the checkpoint. This prevents the human from becoming the bottleneck in a large system with many phases.

Tier	When to Use	What Happens at Checkpoint
gate-only	Scaffolding, boilerplate, type definitions, infrastructure. Low risk, mechanical output.	Gate command passes → auto-proceed. Human is notified but doesn't need to act.
spot-check	Well-constrained phases with clear contracts. Moderate risk.	Human glances at the diff, verifies gate passed, proceeds unless something looks off.
full-review	Orchestration, business logic, external integrations, security-sensitive code. High risk.	Human reads the diff, runs verification guide, thinks about edge cases before proceeding.

Guidelines for assigning tiers:

Phase 1 (types & scaffolding): gate-only — if it compiles and tests pass, the types are correct
Pure utility phases (rate limiting, CSV writer): spot-check — contracts constrain the implementation, quick glance suffices
External integration phases (API clients, data sources): full-review — HTTP behavior, error handling, and edge cases need human judgment
Orchestration / composition phases: full-review — this is where subtle bugs hide
CLI / wiring phases: spot-check — mechanical assembly of already-reviewed components

每个阶段分配对应的评审等级，决定检查点需要投入的人力关注程度，避免在多阶段大型系统中人力成为瓶颈。

等级	适用场景	检查点流程
gate-only	脚手架、样板代码、类型定义、基础设施。低风险、机械性产出。	Gate命令通过 → 自动进入下一阶段。仅通知评审人员无需操作。
spot-check	契约清晰、边界明确的阶段。中等风险。	评审人员扫一眼Diff，确认Gate通过，无明显问题即可进入下一阶段。
full-review	编排逻辑、业务逻辑、外部集成、安全敏感代码。高风险。	评审人员通读Diff，运行验证指南，充分考虑边界情况后再进入下一阶段。

评审等级分配指南：

第1阶段（类型与脚手架）：gate-only —— 如果编译和测试通过，类型就是正确的
纯工具阶段（限流、CSV写入器）：spot-check —— 契约已经约束了实现，快速扫一遍即可
外部集成阶段（API客户端、数据源）：full-review —— HTTP行为、错误处理、边界情况需要人工判断
编排/组合阶段：full-review —— 这是隐性Bug容易隐藏的地方
CLI/组装阶段：spot-check —— 已经评审过的组件的机械组装

Step 5: Produce Conventions File

步骤5：生成约定文件

After the first subsystem spec is complete and reviewed, produce (or update) a lightweight conventions file at

docs/conventions.md

. This file is the single source of truth for subsequent subsystems — they read this instead of scanning all prior specs.

markdown

undefined

在第一个子系统规格完成并评审通过后，在

docs/conventions.md

路径生成（或更新）轻量的约定文件。这个文件是后续子系统的唯一可信来源，无需再扫描所有历史规格。

markdown

undefined

Project Conventions

Naming

Subsystem codes: S1 (Downloader), S2 (DB Sync), S3 (Stream Ingest), ...
Phase codes: S{n}.{m} (e.g., S1.1, S1.2)
Design decisions: D{n} — {Title} with rationale
User stories: US-{n} with acceptance criteria AC-{n}.{y}

Subsystem codes: S1 (Downloader), S2 (DB Sync), S3 (Stream Ingest), ...
Phase codes: S{n}.{m} (e.g., S1.1, S1.2)
Design decisions: D{n} — {Title} with rationale
User stories: US-{n} with acceptance criteria AC-{n}.{y}

Document Structure

Phase Design

Ordering: types -> pure functions -> effects -> composition
Max tasks per phase: 8
Each phase exposes contracts consumed/exposed
Phase dependency graph required

Ordering: types -> pure functions -> effects -> composition
Max tasks per phase: 8
Each phase exposes contracts consumed/exposed
Phase dependency graph required

Established Contracts

<list cross-subsystem contracts defined so far> - S1 output: CSV files at data/{market}/{ticker}/{resolution}.csv (Section 5) - S1 types in sati-contracts: OhlcvBar, TickerInfo, Resolution, CsvRecord ```

Update this file after each subsystem spec is finalized. Add new cross-subsystem contracts and any convention refinements. Keep it under 50 lines.

<list cross-subsystem contracts defined so far> - S1 output: CSV files at data/{market}/{ticker}/{resolution}.csv (Section 5) - S1 types in sati-contracts: OhlcvBar, TickerInfo, Resolution, CsvRecord ```

每个子系统规格定稿后都要更新这个文件，添加新的跨子系统契约和约定优化，保持文件长度不超过50行。

Step 6: Review and Iterate

步骤6：评审与迭代

Present the draft spec to the user. Iterate on:

Phase boundaries — are they clean? Any hidden coupling?
Contract completeness — are all inter-phase interfaces explicit?
Design decisions — are tradeoffs documented?
Size estimates — realistic for the scope?

向用户展示规格草稿，围绕以下点迭代：

阶段边界 —— 是否清晰？有没有隐藏耦合？
契约完整性 —— 所有跨阶段接口是否明确？
设计决策 —— 取舍是否都有文档记录？
规模估算 —— 对应范围是否合理？

Naming Conventions

命名规范

Element	Format	Example
Subsystem code	S{n}	S1, S2, S3
Phase code	S{n}.{m}	S1.1, S1.2, S2.3
Design decision	D{n}	D1, D2, D3
User story	US-{n}	US-1, US-2
Acceptance criterion	AC-{story}.{criterion}	AC-1.1, AC-1.2, AC-3.4
Spec file	{project}-s{n}-{name}-v{version}.md	sati-s1-downloader-v1.md

元素	格式	示例
子系统编码	S{n}	S1, S2, S3
阶段编码	S{n}.{m}	S1.1, S1.2, S2.3
设计决策	D{n}	D1, D2, D3
用户故事	US-{n}	US-1, US-2
验收标准	AC-{story}.{criterion}	AC-1.1, AC-1.2, AC-3.4
规格文件	{project}-s{n}-{name}-v{version}.md	sati-s1-downloader-v1.md

Anti-Rationalization Table

认知误区对照表

Thought	Reality
"The system spec is detailed enough"	System specs define boundaries. Design specs define internals. Different levels.
"I'll figure out phases during implementation"	Phases defined after coding starts are retrofitted, not designed. Contracts leak.
"These two phases are too small, I'll combine them"	Small phases are a feature. They enable focused review and parallel work.
"The contract is obvious, no need to write it"	Explicit contracts enable mock testing and subsystem isolation. Write it.
"I'll add the dependency graph later"	The graph exposes parallelization. Without it, phases are assumed sequential.
"This subsystem is simple, skip the full structure"	Simple subsystems still need contracts, phases, and testing strategy.
"I'll just follow the same structure as last time"	Read the existing specs and extract conventions explicitly. Memory drifts.

错误认知	实际情况
"系统规格已经足够详细了"	系统规格定义边界，设计规格定义内部实现，是不同层级的文档。
"我可以在落地过程中再拆分阶段"	编码开始后定义的阶段是事后补的，不是预先设计的，容易出现契约泄漏。
"这两个阶段太小了，我合并成一个吧"	小阶段是优势，能支持聚焦评审和并行工作。
"契约很明显，不用写出来"	明确的契约支持Mock测试和子系统隔离，必须写出来。
"我后面再加依赖图就行"	依赖图能暴露可并行的点，没有的话大家会默认阶段是串行的。
"这个子系统很简单，不用完整结构"	即使是简单子系统也需要契约、阶段和测试策略。
"我照着上次的结构写就行"	要读取现有规格明确提取约定，记忆会出现偏差。

subsystem-design-spec

Original

Translation

Subsystem Design Spec

子系统设计规格

When to Use

适用场景

Process

流程

Step 1: Load Conventions

步骤1：加载规范约定

Step 2: Reference the System Spec

步骤2：关联系统规格

Step 3: Guide Document Creation

步骤3：指导文档创建

S{n} {Subsystem Name} — Subsystem Design Spec

S{n} {Subsystem Name} — Subsystem Design Spec

1. Overview

1. Overview

1.1 Goals

1.1 Goals

1.2 Non-Goals

1.2 Non-Goals

2. Architecture

2. Architecture

2.1 Component Diagram (mermaid)

2.1 Component Diagram (mermaid)

2.2 Key Design Decisions

2.2 Key Design Decisions

3. User Stories

3. User Stories

4. Detailed Design

4. Detailed Design

5. Output Contract

5. Output Contract

6. Error Handling

6. Error Handling

7. Testing Strategy

7. Testing Strategy

7.1 Unit Tests — what's covered, key scenarios

7.1 Unit Tests — what's covered, key scenarios

8. Performance Considerations

8. Performance Considerations

9. Future Considerations (out of scope for v1)

9. Future Considerations (out of scope for v1)

10. Dependencies

10. Dependencies

10.1 Packages/Crates

10.1 Packages/Crates

11. Implementation Phases

11. Implementation Phases

12. Acceptance Summary

12. Acceptance Summary

Appendices (optional)

Appendices (optional)

Step 4: Apply Phase Design Discipline (Section 11)

步骤4：应用阶段设计规范（第11章）

Phase Template

阶段模板

S{n}.{m}: {Phase Name}

S{n}.{m}: {Phase Name}

Phase Ordering — FP Progression

阶段排序 —— FP演进逻辑

Phase Design Checklist

阶段设计检查清单

Phase Dependency Graph

阶段依赖图

Review Tiers

评审等级

Step 5: Produce Conventions File

步骤5：生成约定文件

Project Conventions

Project Conventions

Naming

Naming

Document Structure

Document Structure

Phase Design

Phase Design

Established Contracts