Technical Design

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

# 技术方案设计与实施技能

## 产物去向

技术方案 / 实施说明**默认只在响应中呈现**（必载片 §响应消息优先于文件写入）——
多数方案讨论完就落进代码，不需要再留一份文档。

用户明确要求存档时才落盘，归属查 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 迁移 / 多文件协调 / 高风险变更。

> **入口前置阅读**：进入完整路径前，先读 `reference/engineering-discipline.md`（工程纪律：DRY / 副作用边界 / 异常处理 / 文档同步等），把其中的判断标准带入第 2-3 步的方案设计与风险评估。轻量路径不强制读，但若涉及架构敏感修改也建议参考。
>
> **路径写法**：Read 按**会话工作目录**解析相对路径，不按 skill 所在目录——照抄 `./reference/…` 必然报「File does not exist」。要读的是 `"$(cat .workframe/state/plugin-root.txt)/skills/technical-design/reference/engineering-discipline.md"`；插件目录在项目外时可能读不到，那就按本 skill 正文的判断标准推进，别卡在取文件上。

### 第 1 步：需求理解

读取需求来源（`projects/modules/<basic>/<sub>/requirements/<req_slug>/<sub_req_slug>/prd.md`、task description、issue 等），提取：
- 功能范围（做什么、不做什么）
- 验收标准（AC，GWT 或规则式）
- 实质性约束（性能、安全等）——从 PRD「需求背景与目标 · 边界」与对应功能模块的就近规则提取（PRD 不设独立非功能章）
- 依赖关系（依赖哪些已有功能、外部服务）

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

### 第 2 步：方案设计

输出完整技术方案：

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

> **给用户过目的方案必含五段**，全程大白话、不堆术语：①改前 vs 改后对比 ②好处 ③局限与坏处，以及能不能规避 ④对其他地方的影响面（第 3 步的产物，在方案里说清）⑤业界通常怎么做。
>
> 最常缺的是③和⑤：只讲好处的方案让用户无从判断该不该做，而「业界怎么做」往往是用户手上唯一能独立核实的一项。

### 第 3 步：风险评估

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

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

### 第 4 步：实施拆分

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

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

### 第 5 步：实施 + 每步自测

按拆分计划逐步实施，每步完成后：
- Lint 检查（语法规范）
- 类型检查（若为强类型语言）
- 关键路径单元测试
- 相关集成点验证

> **先定档，再决定自测做到哪**（三问全部问完，命中取最高档；答「是」或「说不准」都算命中）：
> ① 错了会不会传出这个文件之外 → 至少**档 2**　② 有没有东西会因**你改的那部分内容**产出可比较的结果（通过/不通过、分数、diff、快照）→ 至少**档 3**　③ 改的对象本身的职责就是「判断别的东西对不对」吗（测试 / 校验 / 断言 / 自查清单 / 评分标准）→ **档 4**；全不命中 → **档 1**。
>
> 档 1 只验主路径与一致性；每升一档累加：引用面核对 → 跑真实消费方并排对照 + 边界矩阵 → 用它自己的失败方式打一遍。**档位是爆炸半径，不是用心程度**——判在档 1 就按档 1 交付。
>
> 详表、反例与非代码场景对照在 `test-scoping.md`（若能读到插件目录：`"$(cat .workframe/state/plugin-root.txt)/skills/test-case-design/reference/test-scoping.md"`）。**插件目录在项目外，读不到是常态**——上面三问已够定档，别卡在取文件上。

#### 双检的时点

一检（构建者正向）/ 二检（审计者反向）的完整判据在必载片 §验证纪律——**该 rule 每次会话必载，此处不复述**。本 skill 只定两件它不管的事：

- **时点**：双检挂在**每步自测之后、第 6 步交付说明之前**，不是收口时补一次——积累到最后做，二检面对的是一整批改动，边界矩阵跑不动
- **收尾**：二检末尾**清除全部测试数据**——实施期造的 fixture、临时开关、打桩返回值逐一撤干净，撤完再交付

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

### 第 6 步：交付说明

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

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

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

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

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

---

## 状态流转

完成实施 + 自测后：
- **研发任务**（编码、Bug 修复、部署变更、Schema 迁移等）：响应末尾标注"开发已完成，需 @qa 介入验证"，看板状态流转到 `pending_qa`（详见 `task-management` 流转规则）

> **本 skill 的轻量／完整双档判的是「怎么实施」，不是「谁签发」——两者是不同维度，别互相推导。** 轻量路径的判据是实施复杂度（单文件、简单、低风险）；签发档的判据是「有没有覆盖本轮 delta 的独立结论」＋ 爆炸半径 ＋ 否决项（必载片 §谁签发这次收口）。**走了轻量路径不等于可以自签**：一行改动落在爆炸半径档 4（改的东西自己就是判据）时，地板仍然卡在完整验证。反过来，走完整路径也不意味着必须多签一轮。
>
> 这两个维度最容易被合并读，因为「简单」和「安全」在直觉上是一回事——而它们不是：**改一行判定式的实施成本最低、失效后果最静默**。
- **非研发任务**（技术咨询、方案评估、架构梳理等纯交付物）：可从 `in_progress` 直接 `completed`

> 不在 skill 内派发其他角色；状态流转通过看板 + 响应文字标注（见子 agent 必载片 §协作边界）。

---

## 下游衔接

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

## 反模式（不要这样做）

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