| 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-3 条隐含假设（如"假设这个常量没在其他地方被引用"），让用户能截停
- 直接改动 + 自测：
- Lint + 类型检查（若语言适用）
- 关键路径手动验证
- 简短交付说明：响应中 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 软件适用，其他场景按依赖方向走
- ❌ 简单的单文件改动也强行走完整六步——浪费上下文且打断用户工作流
