technical-design v3.1.0A

Immutable. This exact content is served forever at /api/v1/blob/7243fb3cd1bac6b7.

---
name: technical-design
description: 将已确认需求和代码现状转成技术方案；可独立交付设计，或在 Brainstorming 中作为只读探针发现下一项高价值技术决定。
metadata:
  author: "devkeel"
  version: "3.1.0"
---

# 技术设计

产出能直接指导实现和验证的方案。

## 调用方契约

先识别调用模式：

- `probe`：由 Brainstorming 调用，只返回候选 gap 与证据，不向用户提问、不写文件、不生成设计；
- `deliverable`：用户明确要求独立技术设计时，按下述方法形成方案。

OpenSpec 下游 artifact 的投影阶段不得调用本 skill。design/specs/tasks 必须只投影已确认的 D-*、
A-*、仓库事实与机械拆分；发现新选择时退出投影并交回 Brainstorming。

- 调用方提供具体模板，或 artifact instruction 已明确标题、字段与顺序时，严格交付到该
  结构；不追加默认模板章节，不另建方案副本。
- 只有输出路径或设计约束、没有具体结构时，不视为已提供模板；按默认模板交付到指定位置。
- 复用当前 Agent 的热需求、调查和决策；上下文冷却、压缩、外部变更或关键事实不确定时，
  才重读必要输入。
- 只完成技术设计并返回调用方。不自动生成 tasks、启动 apply、调用其他专项 skill 或分派实现。
- 需求存在会改变范围或验收的空缺时，先交还需求分析，而不是用技术假设掩盖。

## Probe 输出契约

仅在 probe 模式按 Brainstorming 传入的讨论深度、目标与边界、已有决定、仓库依据和探查重点工作：

- Lite：围绕当前方案，定向检查可行性、实现边界、关键失败路径与验证缺口；
- Full：额外检查关键技术假设、合理替代路径、相关失败模式、兼容与维护代价；
- 未传深度时保持定向补缺；不自行切换讨论档位，不改变独立 deliverable 模式。

复用下文维度选择规则，Full 也只读取相关资料，不全量展开领域清单。只返回内部候选列表，每项
必须是一件可能改变实现结构、可观察行为或后续维护方式的决定，标明阻塞缺口或可选建议，并包含
仓库证据、当前猜测、影响与不确定性。
不输出设计文档、候选大全、覆盖矩阵或方法论摘要。

调用方会与需求 gap 合并去重，只向用户询问当前最高价值的一项。已有 D-* 覆盖、可由仓库事实
唯一确定或属于明确 A-* 自主范围的内容不算 gap；新证据揭示已确认决定存在冲突或风险时，指出
证据并交回 Brainstorming。可选建议不自动成为 O-* 或新范围；没有候选缺口时返回简短检查结论
与依据，不为了 Full 制造问题或替代方案。

## 输出结构优先级

1. 用户或调用方提供的具体模板优先。保留其标题、顺序、必填字段和格式；方法论只用于
   填充模板需要的内容。
2. artifact instruction 明确给出结构时，将其视为调用方模板；仅有目标、约束或输出路径时，
   将这些内容作为设计约束，而不是结构模板。
3. 没有提供模板时，读取 `references/default-template.md`，再按领域、触点和风险裁剪；不适用
   的可选章节不输出，不用默认模板覆盖调用方结构。

## 1. 确认输入与现状

读取已确认需求，以及受影响入口、直接依赖、现有模式、测试接缝和项目约束。默认由当前
Agent 聚焦调查。只有多领域只读调查可以独立并行且收益明显时才使用调查 subagent，主
Agent 负责证据和最终决策。

## 2. 内部裁剪设计维度

始终读取 `references/dimension-selection.md`。从需求和代码识别 frontend、backend、
desktop、native-service、mobile、cli、sdk、devops 或 custom 领域，只读取命中的
`references/domain-profiles/*.md`，再只读取实际需要的 `references/dimensions/Dxx-*.md`。

在内部用 `core / supporting / checklist / skip` 控制深度：

- `core`：决定方案成败，展开职责、机制、取舍和验证；
- `supporting`：影响落地，给出足够的决策与边界；
- `checklist`：落实到风险、验证或发布检查；
- `skip`：不进入输出。

不要在最终文档写维度矩阵、领域/profile 清单、优先级、skip 理由、覆盖证明或方法论摘要。
C4、ATAM、STRIDE、SLO、状态机等只在能改善具体决策时使用，不展示工具名称
来代替方案。

## 3. 形成可落地方案

先确定最小可行方案，再处理与本次触点相关的内容：

- 系统、模块、进程或部署边界，以及每个部分负责和不负责什么；
- 主流程、状态转换、失败路径、重试/降级/恢复；
- API、CLI、SDK、事件、IPC、数据模型或持久化契约；
- 兼容、迁移、版本、灰度、回滚和外部协调；
- 被风险实际触发的性能、可靠性、安全、隐私和可观测设计；
- 测试接缝、验收方法、发布检查与剩余风险。

比较候选方案时只保留真实候选、决定因素和取舍。优先沿用项目现有模式；偏离时说明原因
和影响。关键设计必须能映射到实现职责和验证方式。

## 4. 输出结果

按上述优先级选择结构。默认模板承接以下结果，不强制空章节：

- 一句话方案与首版交付边界；
- 现状约束和方案结构；
- 关键流程、接口、数据/状态及异常恢复；
- 兼容迁移、发布回滚和风险控制；
- 关键决策与取舍；
- 验证方案、未决项和明确假设。

结构、时序、状态或跨系统关系复杂时优先使用 Mermaid；简单关系用文字或小表格即可。
输出设计事实和可执行决策，不输出分析过程。

## 完成条件

方案应让实现者知道改哪里、各部分如何协作、哪些契约不能破坏、失败时如何恢复、怎样
验证和回滚。标出真正需要用户或外部方决定的事项，然后停止并把控制权交还调用方。