| name | technical-design |
| description | 技术方案技能。当需求较大、较复杂或技术方案不明确，需要在起草 spec 之前先产出一份供评审的技术方案时使用。适用于执行 /spec-design 命令时触发，或用户说"先做个技术方案""这个需求大，先评审方案"时。 |
技术方案（Technical Design）
在起草 spec 之前，基于原始需求（docs/intake/xxx.md）产出一份供团队评审的技术方案。方案聚焦「用什么思路做、为什么这样选、要拆成几个 spec」，评审通过后指导写出更准确的 spec。
核心原则（必读）
- 先澄清再出方案：方案的质量取决于输入的清晰度。出方案之前必须与用户多轮澄清（需求性质、涉及仓库及 clone 状态、现有实现、核心逻辑与边界、非功能约束、范围），不允许凭空假设。
- 给候选方案让用户选，不直接落盘：至少提出 2-3 个有实质差异的候选方案 + 对比 + 推荐，等用户选定后才写最终方案文档。
- 方案级，不是执行级：本技能产出的是架构方向与技术选型，不写到具体文件的改动步骤（那是
implementation-planning / /spec-plan 的事）。
- 不替业务方拍板需求：业务目标、ROI、验收标准仍由
/spec-draft 阶段 + 人确定，本技能不臆造；技术方案只回答「技术上怎么实现」。
- 核心产出是 spec 拆分建议：大需求往往要拆成多个子 spec，本技能必须给出建议的拆分边界与 slug。
- 输出 status 一定是
draft：不允许直接 approved，必须经团队评审。
⚠️ 与 implementation-planning 区别：implementation-planning 基于已 ready 的 spec输出落地步骤；本技能在spec 之前输出方案与拆分建议。
⚠️ 与 spec-drafting 区别：spec-drafting 产出「要做什么」的需求规格；本技能产出「技术上怎么做」的方案，是 spec 的上游输入。
执行步骤
Step 1: 收集原始需求
- 用户给
docs/intake/xxx.md 路径 → 读取文件
- 用户直接描述 → 先复述理解，确认无误后开始
- 明确本次技术方案要回答的核心技术问题（1-3 个）
Step 2: 澄清需求（关键步骤，不可跳过，可多轮）
出方案前先把输入澄清清楚。一次列 3-6 个最关键问题，按下表分类；用户回答后复述确认，有歧义继续追问。
| 必问类别 | 问题示例 | 目的 |
|---|
| 需求性质 | 全新建设，还是在已有实现上增量改造？ | 决定方案是从零设计还是扩展现有架构 |
| 涉及仓库 + clone 状态 | 涉及哪些仓库？是否已 clone 到 src/<repo>/？逐一确认 | 方案必须基于已有代码；未 clone 的先提示用户 clone，否则相关结论标注「待验证」 |
| 现有实现定位 | 相关现有功能/模块/接口在哪、怎么工作？ | 增量需求必须先摸清现状，复用现有能力 |
| 核心逻辑 | 主流程、输入输出、上下游依赖？ | 方案要覆盖真实主流程 |
| 边界与异常 | 异常分支、并发/幂等、数据量级、失败回滚？ | 边界往往决定方案选型 |
| 非功能约束 | 性能/兼容（如 proto 向后兼容）/安全/时效性硬要求？ | 这些约束会淘汰部分方案 |
| 范围边界 | 本期不做什么？是否分期？ | 框定方案范围 |
Step 3: 现状侦察（调用 codebase-survey，架构视角，基于已确认仓库）
对已 clone 且本需求涉及的仓库，调用 skills/codebase-survey/SKILL.md，侧重架构层面：
- 现有模块边界与职责
- 相关调用链 / 数据流
- 跨系统、跨仓库的交互点
- 可复用的现有能力与约束（增量需求重点定位 Step 2 中用户指出的现有实现）
本步骤不深入到单个函数的实现细节——那些留给 /spec-plan 阶段的 deep 侦察。
未 clone 的涉及仓库：提示用户先 clone，或在方案中显式标注「未侦察，结论待验证」。
Step 4: 提出 2-3 个候选方案（不落盘，等用户选择）
基于澄清与侦察结果，给出 2-3 个有实质差异的候选方案，先在对话中呈现，等用户选定后再落盘：
| 方案 A | 方案 B | 方案 C（可选） |
|---|
| 核心思路 | … | … | … |
| 优点 | … | … | … |
| 缺点 | … | … | … |
| 复杂度/工作量 | … | … | … |
| 主要风险 | … | … | … |
| 对现有代码影响 | … | … | … |
- 给出 AI 推荐项 + 理由
- 附基于推荐方案的「建议 spec 拆分」初步设想
- 停下等用户选择：用户可选定、融合或调整；未明确选定前不写文件
Step 5: 设计最终方案文档（用户选定后）
以用户选定的方案为主线，按下表填写 designs/templates/design-template.md：
| 章节 | 处理原则 |
|---|
| 需求背景与目标 | 忠实复述 intake，不扩写；技术目标可由 AI 提炼，业务目标标 [TBD] 留人确认 |
| 现状分析 | 来自 codebase-survey，描述现有架构与约束 |
| 总体方案 | 一句话点明选定思路 + 架构图 / 数据流（文字或简单图示） |
| 方案对比 | 保留 Step 4 的候选方案与取舍理由（含被淘汰方案，决策可追溯） |
| 关键技术决策 | 记录选了什么、为什么、淘汰了什么（评审后沉淀，供 plan 阶段复用） |
| 跨系统 / 跨仓库影响 | 涉及哪些仓库、接口、上下游系统 |
| 数据结构 / 接口影响（高层） | 大致需要新增/改动的结构与接口，不写最终定义 |
| 建议的 spec 拆分 | 核心产出：建议拆几个 spec、各自边界、slug 建议、依赖关系 |
| 风险与未决问题 | 把不确定项全暴露出来，标 open |
| 评审记录 | 占位，评审时回填 |
Step 6: 写入文件
- 路径：
designs/<VERSION>/<STORYID>-<slug>-design.md
- frontmatter：
Story ID: <数字>（与 intake 一致；暂无用 0）Status: draft（强制，不可直接 approved）Author: [作者名 / TBD]Reviewers: [评审人，TBD]Created / Updated：当前日期
Step 7: 输出方案报告
### 技术方案报告：[Story ID] [标题]
**已写入**：designs/<VERSION>/<STORYID>-<slug>-design.md（status: draft）
**总体方案**（2-5 句）：
...
**需评审拍板的关键决策**：
1. [决策点 1：方案 A vs 方案 B，倾向 A，理由…]
2. [决策点 2…]
**建议的 spec 拆分**：
- spec-1：[slug] — [边界]
- spec-2：[slug] — [边界]
**风险与未决问题**：
- [open 项列表]
**建议下一步**：
1. 团队评审技术方案
2. 回填「评审记录」，status 改为 approved
3. 对每个建议的 spec 执行 /spec-draft（输入 intake + 本 design）
注意事项
❌ 不要做
- 不澄清就直接出方案（需求性质 / 仓库 clone 状态 / 边界没问清就开干）
- 只给单一方案、不做对比，或未经用户选择就直接落盘
- 把技术方案写成「改 xxx.go 第 N 行」级别的实施步骤（越界到 plan）
- 替业务方拍板目标 / 验收标准 / ROI
- 把
Status 直接设为 approved
- 忽略 spec 拆分建议（大需求的技术方案缺了拆分就失去主要价值）
- 涉及仓库未 clone 却凭空给出该仓库的具体结论（应先提示 clone 或标注「待验证」）
✅ 鼓励做
- 出方案前多轮澄清，复述确认理解
- 候选方案给 2-3 个 + 对比矩阵 + 推荐，让用户选
- 用简单架构图 / 数据流图让方案一目了然
- 把不确定项全列进「风险与未决问题」标 open
- 明确建议的 spec 拆分边界，为后续
/spec-draft 铺路
关联资产
- 模板：
designs/templates/design-template.md
- 规则：
rules/10-spec-workflow.md（阶段零前·技术方案）
- 命令：
commands/spec-design.md
- 下游：
skills/spec-drafting/SKILL.md（基于本方案起草 spec）
