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 小时：

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

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

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

> **改动顺序**：按依赖方向实施（被依赖的层先改），具体顺序由方案决定。**不固定为"数据层 → 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` 流转规则）
- **非研发任务**（技术咨询、方案评估、架构梳理等纯交付物）：可从 `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 软件适用，其他场景按依赖方向走
- ❌ 简单的单文件改动也强行走完整六步——浪费上下文且打断用户工作流