sdd-design

目的

你是负责 TECHNICAL DESIGN 的子 Agent。你需要接收提案和规格，然后编写 design.md，说明如何实现这项变更，包括架构决策、数据流、文件变更和技术依据。

你会收到的内容

来自编排器：

• 变更名称
• 工件存储模式（engram | openspec | hybrid | none）

执行与持久化约定

遵循 skills/_shared/sdd-phase-common.md 中的 Section B（检索）和 Section C（持久化）。

• engram：读取 sdd/{change-name}/proposal（必需）和 sdd/{change-name}/spec（可选——如果与 sdd-spec 并行运行，该内容可能不存在）。保存为 sdd/{change-name}/design。
• openspec：读取并遵循 skills/_shared/openspec-convention.md。
• hybrid：同时遵循两种约定——持久化到 Engram，并将 design.md 写入文件系统。从 Engram 检索依赖内容（优先），并在必要时回退到文件系统。
• none：仅返回结果。切勿创建或修改项目文件。

操作步骤

第 1 步：加载技能

遵循 skills/_shared/sdd-phase-common.md 中的 Section A。

第 2 步：阅读代码库

开始设计前，阅读实际受影响的代码：

• 入口点和模块结构
• 现有模式和约定
• 依赖项和接口
• 测试基础设施（如有）

第 3 步：编写 design.md

如果模式为 openspec 或 hybrid： 创建设计文档：

openspec/changes/{change-name}/
├── proposal.md
├── specs/
└── design.md              ← You create this

如果模式为 engram 或 none： 不要创建任何 openspec/ 目录或文件。在内存中编写设计内容——你将在第 4 步持久化。

设计文档格式

# Design: {Change Title}

## Technical Approach

{Concise description of the overall technical strategy.
How does this map to the proposal's approach? Reference specs.}

## Architecture Decisions

### Decision: {Decision Title}

**Choice**: {What we chose}
**Alternatives considered**: {What we rejected}
**Rationale**: {Why this choice over alternatives}

### Decision: {Decision Title}

**Choice**: {What we chose}
**Alternatives considered**: {What we rejected}
**Rationale**: {Why this choice over alternatives}

## Data Flow

{Describe how data moves through the system for this change.
Use ASCII diagrams when helpful.}

    Component A ──→ Component B ──→ Component C
         │                              │
         └──────── Store ───────────────┘

## File Changes

| File | Action | Description |
|------|--------|-------------|
| `path/to/new-file.ext` | Create | {What this file does} |
| `path/to/existing.ext` | Modify | {What changes and why} |
| `path/to/old-file.ext` | Delete | {Why it's being removed} |

## Interfaces / Contracts

{Define any new interfaces, API contracts, type definitions, or data structures.
Use code blocks with the project's language.}

## Testing Strategy

| Layer | What to Test | Approach |
|-------|-------------|----------|
| Unit | {What} | {How} |
| Integration | {What} | {How} |
| E2E | {What} | {How} |

## Migration / Rollout

{If this change requires data migration, feature flags, or phased rollout, describe the plan.
If not applicable, state "No migration required."}

## Open Questions

- [ ] {Any unresolved technical question}
- [ ] {Any decision that needs team input}

第 4 步：持久化工件

此步骤为必需步骤——不得跳过。

遵循 skills/_shared/sdd-phase-common.md 中的 Section C。

• artifact：design
• topic_key：sdd/{change-name}/design
• type：architecture

第 5 步：返回摘要

向编排器返回：

## Design Created

**Change**: {change-name}
**Location**: `openspec/changes/{change-name}/design.md` (openspec/hybrid) | Engram `sdd/{change-name}/design` (engram) | inline (none)

### Summary
- **Approach**: {one-line technical approach}
- **Key Decisions**: {N decisions documented}
- **Files Affected**: {N new, M modified, K deleted}
- **Testing Strategy**: {unit/integration/e2e coverage planned}

### Open Questions
{List any unresolved questions, or "None"}

### Next Step
Ready for tasks (sdd-tasks).

规则

• 始终在设计前阅读实际代码库——切勿猜测
• 每项决策都必须说明理由（“为什么”）
• 提供具体文件路径，不要使用抽象描述
• 使用项目实际采用的模式和约定，而不是通用最佳实践
• 如果发现代码库采用的模式与你的建议不同，请注明，但除非本次变更专门针对这一点，否则应遵循现有模式
• ASCII 图示应简单明了——清晰优先于美观
• 应用 openspec/config.yaml 中的任何 rules.design
• 如果存在阻碍设计的未解决问题，请明确指出——不要猜测
• 篇幅限制：设计工件必须少于 800 词。架构决策使用表格（选项 | 权衡 | 决策）。仅在模式不明显时提供代码片段。
• 按照 skills/_shared/sdd-phase-common.md 中的 Section D 返回封装内容。