用途
Technical Design 用于在动手实现之前，把有实质影响的技术选择记录下来，使其可被评审，同时避免把设计写成编码配方。它服务于一个明确指定或当前唯一的 Feature 或子 Task，帮助团队在架构、数据、接口、并发、安全等关键问题上达成一致。
主要能力
- 判断设计是否必要：先识别阅读规格与仓库惯例后仍未解决的具体技术问题。只有无法安全留给实现阶段判断、且涉及架构/模块职责/接口、数据归属与持久化形态、状态流转、非平凡算法或协议、并发/一致性/安全/隐私/性能/运维行为、集成契约或测试接缝、以及具有不同长期后果的真实技术备选方案时，才值得设计。
- 实质性门槛：当可行方案后果差异明显，或该选择确立了非显而易见的不变量、归属边界、数据契约、生命周期、并发模型、迁移规则、安全边界或运维约束时，问题才算实质性。Feature 大小、缺少设计文件、或仅仅涉及数据/状态/安全/多模块，都不足以作为证据。
- 独立工作：先锁定一个确切的 Feature 或 Task，优先使用请求中的 ID、链接、路径或产物；否则读取 .waypoint/local.yaml 并按 actor_id 过滤。仅当恰好剩一个候选时继续，否则询问。绝不回退到其他执行者的工作、队列顺序、时间新旧、Git 历史或当前分支。
- 产出设计产物：当至少一个问题通过门槛时，优先更新已有的合适设计产物或 technical-design 章节；否则在 Feature 或 Task 旁提出最小的 Markdown 产物。保留 Feature 行为契约与子 Task 归属，遇到矛盾或缺失需求应指出而非默默重定义。
- 持久层设计：记录决策而非推导过程，引用相关行为需求而非复述。只包含实质性部分：当前技术上下文与约束、提议的架构或方案、模块职责/接口/接缝/集成契约、数据模型与归属/持久化形态/生命周期/状态流转/事件流、执行模型与副作用边界、失败机制/并发/原子性/一致性/安全/隐私/性能/运维、技术备选方案与理由、验证接缝与可观测性、未决技术决策及其影响。
- 表达方式：选择最便于评审每个实质决策的表示。关系型持久化变更展示表、列与逻辑类型、主外键、可空性/默认值、唯一性与约束、由访问路径证明的索引、归属与迁移兼容影响；文档/事件/缓存/线格式展示持久形态、身份与版本规则、生产者消费者归属、兼容预期与代表性载荷；生命周期密集行为用状态表或状态图；分支逻辑用流程图；跨参与者交互用序列图；架构或部署边界用组件或容器图。优先使用仓库原生文本、Markdown 表格与 Mermaid 图，使源码可 diff 可评审。
- 边界：把常规解析、校验、归一化、映射与普通控制流留给实现，仅当其语义定义持久契约或影响身份、持久化、失效、兼容、安全等实质不变量时才记录。优先稳定的模块、接口、契约与数据概念，而非逐文件指令。仅在表达非平凡算法或协议时使用伪代码。除非属于技术不变量，否则不涉及交付顺序。
使用方式
- 解析一个确切的 Feature 或 Task。
- 阅读仓库说明、Feature/Task 契约、相关代码与测试、现有架构与决策记录、本地设计惯例。
- 区分已由 feature-spec 固定的行为、仓库事实与惯例、可机械推导的实现、以及仍需技术判断的具体问题。
- 应用实质性门槛，决定是否创建或更新设计产物。
- 若通过门槛，更新已有设计产物或提出最小 Markdown 产物；为每个纳入领域记录技术问题、所选方案、理由与由此产生的不变量或后果。
- 仅在设计产物存在后，向 feature.md 或所属 task.md 添加设计 Reference，只链接实际仓库原生文件名。
- 当多个执行者可能实现同一 Feature 时，使共享归属、接口、模式、生命周期规则与验证接缝足够稳定，以便任务规划拆分工作。
适用场景
- 存在需要技术判断的实质性问题，且其后果差异明显或确立非显而易见的不变量时。
- 多个执行者可能并行实现同一 Feature，需要稳定共享契约与接缝时。
- 需要记录数据模型、状态流转、并发模型、安全边界、迁移规则等持久决策时。
限制
- 若规格与仓库实践已确定做法、只剩机械可推导的实现，则只需简要方案预览，不产出设计产物，也不创建跳过设计的标记。
- 除非用户当前请求另行指派该确切 Feature 或 Task，否则不开始实现。
- 设计批准仅授权该产物；不分解 Task、不写实现计划、不修改生产代码，除非用户当前请求明确包含该独立规划结果。
- 不要求为行为契约已可评审的未拆分 Feature 单独提供 Feature 规格，也不要求工作流、文档目录、跟踪器、分支、计划或评审仪式。
- 当未决选择会改变用户或运维可见行为、兼容性或产品策略时，应退回 feature-spec，而非围绕其设计机制。
- 若仓库无法渲染 Mermaid，则使用其既有图表格式或紧凑文本图。
- 可选配套技能来自 mattpocock/skills，可用 npx skills add mattpocock/skills --skill <name> 安装，它们不拥有设计产物。