technical-design

name	technical-design
description	技术方案技能。当需求较大、较复杂或技术方案不明确，需要在起草 spec 之前先产出一份供评审的技术方案时使用。适用于执行 /spec-design 命令时触发，或用户说"先做个技术方案""这个需求大，先评审方案"时。

技术方案（Technical Design）

在起草 spec 之前，基于原始需求（docs/intake/xxx.md）产出一份供团队评审的技术方案。方案聚焦「用什么思路做、为什么这样选、要拆成几个 spec」，评审通过后指导写出更准确的 spec。

核心原则（必读）

1. 先澄清再出方案：方案的质量取决于输入的清晰度。出方案之前必须与用户多轮澄清（需求性质、涉及仓库及 clone 状态、现有实现、核心逻辑与边界、非功能约束、范围），不允许凭空假设。
2. 给候选方案让用户选，不直接落盘：至少提出 2-3 个有实质差异的候选方案 + 对比 + 推荐，等用户选定后才写最终方案文档。
3. 方案级，不是执行级：本技能产出的是架构方向与技术选型，不写到具体文件的改动步骤（那是 implementation-planning / /spec-plan 的事）。
4. 不替业务方拍板需求：业务目标、ROI、验收标准仍由 /spec-draft 阶段 + 人确定，本技能不臆造；技术方案只回答「技术上怎么实现」。
5. 核心产出是 spec 拆分建议：大需求往往要拆成多个子 spec，本技能必须给出建议的拆分边界与 slug。
6. 输出 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）