technical-design

name	technical-design
description	技术方案设计与实施，提供轻量路径（小改动直接落地）和完整路径（架构/数据/API/多文件高风险变更走完整方案+实施+交付）双档分流
when_to_use	用于技术方案设计、架构选型、API 设计、Schema 设计、实施拆分、交付说明时调用。 典型触发："做技术方案" / "架构怎么选" / "API 怎么设计" / "实施 X" / "完成报告"。 典型反例：bug 调试（用 systematic-debugging）/ 代码审查（用 code-review）/ Prompt 相关（用 prompt-design）。 路径选择：单文件简单改动 / 配置调整 → 走轻量路径；架构、数据、API、多文件、高风险 → 走完整路径（详见 SKILL body）。
user-invocable	true
allowed-tools	["Read","Write","Edit","Glob","Grep","Bash"]

技术方案设计与实施技能

产物去向

技术方案 / 实施说明默认只在响应中呈现（response-output.md：响应优先于文件写入）—— 多数方案讨论完就落进代码，不需要再留一份文档。

用户明确要求存档时才落盘，归属查 skill: document-norms §1：跨模块的架构方案 → projects/specs/plans/<YYYY-MM-DD>-<plan-name>.md；单模块的技术决策 → projects/modules/<basic>/<sub>/decisions/。不要默认写文件，也不要写完才问。

适用场景

拿到 specs / board task 后准备开始实施时调用。涵盖代码 / 配置 / Schema / 部署的变更。

不适用：bug 调试（用 systematic-debugging）/ 代码审查（用 code-review）/ Prompt 相关（用 prompt-design）。

路径选择（轻量 vs 完整）

维度	轻量路径	完整路径
改动范围	单文件 / 配置调整 / 文档级修改	多文件 / 跨模块 / 架构调整
风险级别	低（无破坏性、不影响现有数据/接口）	中-高（引入新依赖 / 改 Schema / 影响线上行为）
数据/API	不动	改 Schema / 改 API 签名
不确定性	需求清晰、实现路径明确	需要选型 / 多方案对比 / 影响面不明

任一维度命中"完整"列 → 走完整路径。 模糊时倾向走完整。

---

轻量路径（Lightweight Path）

适用：单文件 / 配置 / 文档级修改 / 小修小补。

1. 快速理解：读需求 + 当前相关文件状态
2. 声明假设：响应中列出 1-3 条隐含假设（如"假设这个常量没在其他地方被引用"），让用户能截停
3. 直接改动 + 自测：
   • Lint + 类型检查（若语言适用）
   • 关键路径手动验证
4. 简短交付说明：响应中 1-3 行说"改了什么 + 风险点（若有）"

轻量路径不强制等待用户确认；不强制六步流程；不固定改动顺序。

---

完整路径（Full Path）

适用：架构变更 / 新增依赖 / Schema 迁移 / 多文件协调 / 高风险变更。

入口前置阅读：进入完整路径前，先 Read ./reference/engineering-discipline.md（工程纪律：DRY / 副作用边界 / 异常处理 / 文档同步等），把其中的判断标准带入第 2-3 步的方案设计与风险评估。轻量路径不强制读，但若涉及架构敏感修改也建议参考。

第 1 步：需求理解

读取需求来源（projects/modules/<basic>/<sub>/requirements/<req_slug>/<sub_req_slug>/prd.md、task description、issue 等），提取：

• 功能范围（做什么、不做什么）
• 验收标准（AC，GWT 或规则式）
• 实质性约束（性能、安全等）——从 PRD「需求背景与目标 · 边界」与对应功能模块的就近规则提取（PRD 不设独立非功能章）
• 依赖关系（依赖哪些已有功能、外部服务）

信息不足时使用 [待确认: {说明}] 占位，严禁编造需求内容。

第 2 步：方案设计

输出完整技术方案：

维度	内容
涉及文件	新建/修改的文件清单（项目相对路径）
API 变更	新增/修改的 API 接口签名、请求/响应结构（若适用）
数据结构	新增/修改的数据模型、字段变更（若适用）
依赖关系	依赖的外部库、内部模块、上下游接口
技术选型	关键技术决策和替代方案权衡

第 3 步：风险评估

列出技术风险和影响面（Blast Radius）：

风险类型	具体描述	缓解措施
技术风险	新技术未经验证 / 性能瓶颈 / 并发问题	预研、压测、降级方案
影响面	改动波及哪些模块	回归测试范围
兼容性	对现有数据/接口的破坏性	迁移方案、版本控制
安全	注入、越权、数据泄露风险	输入校验、权限校验

第 4 步：实施拆分

按步骤拆分实施计划，每步 ≤4 小时：

step_1:
  description: "{改动描述}"
  files: ["路径1", "路径2"]
  self_check:
    - "{自测命令或检查点}"
step_2:
  ...

第 5 步：实施 + 每步自测

按拆分计划逐步实施，每步完成后：

• Lint 检查（语法规范）
• 类型检查（若为强类型语言）
• 关键路径单元测试
• 相关集成点验证

改动顺序：按依赖方向实施（被依赖的层先改），具体顺序由方案决定。不固定为"数据层 → API → 业务 → UI"——这只对典型 Web 软件适用，对 LLM 应用、数据管道、CLI 工具、内容运营脚本等场景不一定贴合。

第 6 步：交付说明

代码完成后产出交付说明（供 @qa 审查参考）：

## 变更摘要
- 改了什么：{具体改动点列表}
- 为什么这样改：{设计理由}
- 不这样改的后果：{替代方案的劣势}

## 自测结果
- Lint: pass
- TypeCheck: pass
- Unit Test: {通过/失败的用例}
- Key Path Verification: {手动验证结果}

## 需要 QA 关注的点
- {测试重点1}
- {测试重点2}

## 回归测试建议
- {建议回归的历史功能点}

---

状态流转

完成实施 + 自测后：

• 研发任务（编码、Bug 修复、部署变更、Schema 迁移等）：响应末尾标注"开发已完成，需 @qa 介入验证"，看板状态流转到 pending_qa（详见 task-management 流转规则）
• 非研发任务（技术咨询、方案评估、架构梳理等纯交付物）：可从 in_progress 直接 completed

不在 skill 内派发其他角色；状态流转通过看板 + 响应文字标注（见 workframe core rule: agent-protocols §2 协作边界）。

---

下游衔接

• @qa：通过交付说明和回归建议进行测试
• systematic-debugging：测试发现 Bug 时调用该 skill 做根因分析和修复
• code-review：@qa 或独立审查者基于交付说明做代码审查

反模式（不要这样做）

• ❌ 跳过假设声明 / 影响面判断（无论轻量还是完整路径）
• ❌ 完整路径方案设计只说"要改什么"，不说"怎么改"
• ❌ 完整路径每步不做自测，积累到最后一次性测
• ❌ 交付说明只说"做完了"，不说"改了什么、有什么风险、QA 关注什么"
• ❌ 研发任务跳过 pending_qa 直接标 completed
• ❌ 把所有改动都套"数据层 → API → 业务 → UI"顺序——只对典型 Web 软件适用，其他场景按依赖方向走
• ❌ 简单的单文件改动也强行走完整六步——浪费上下文且打断用户工作流