---
name: vaycentsun/sw-technical-spec
source: https://app.decimal.ai/s/vaycentsun-sw-technical-spec@1/SKILL.md
source_sha256: 83ba6f0640cf
---

# 编写 technical-spec

将业务需求澄清后的设计决策，转化为结构化的 technical-spec，用于指导后续开发。

## 何时使用

- 需求已通过 `sw-requirements-clarification` 澄清并确定方案后
- 需要编写可供工程师直接参考的技术文档时
- 需要明确接口定义、数据流、错误处理策略时

## 何时跳过

- 用户明确说"直接改"或"别走流程"
- 已有完整的 technical-spec
- 纯配置、文档或注释的修改

## 核心原则

**铁律：在 technical-spec 完成之前，严禁执行以下任何操作：**
- 调用任何实现类技能（如 sw-subagent-development）
- 编写任何代码
- 创建项目脚手架
- 执行任何实现层面的动作

## 任务清单

必须按顺序完成以下任务：

- [ ] **读取 business-spec** — 从 `docs/sw-agiledevelopment/business-specs/` 读取需求澄清结果
- [ ] **扩展技术细节** — 基于业务决策补充架构、组件、接口、数据流、错误处理
- [ ] **编写 technical-spec** — 保存到 `docs/sw-agiledevelopment/technical-specs/YYYY-MM-DD--<name>.md`
- [ ] **technical-spec 快速自检** — 检查 TODO、占位符、内部矛盾
- [ ] **展示 spec 摘要** — 向用户展示 spec 要点，随后自动进入下一步
- [ ] **自动调用 sw-working-plan** — 创建实现计划

## 流程图

```mermaid
flowchart TD
    Start([开始]) --> ReadBusiness[1. 读取 business-spec<br/>从 docs/sw-agiledevelopment/business-specs/]
    ReadBusiness --> Expand[2. 扩展技术细节<br/>架构、组件、接口、数据流]
    Expand --> WriteSpec[3. 编写 technical-spec<br/>保存到 docs/sw-agiledevelopment/technical-specs/]
    WriteSpec --> QuickReview[4. 快速自检<br/>检查待办、占位符、内部矛盾]
    QuickReview -->|发现问题| Fix[修复问题]
    Fix --> QuickReview
    QuickReview -->|通过| ShowSummary[5. 展示规范摘要]
    ShowSummary --> InvokePlan([6. 调用 sw-working-plan<br/>唯一出口])
```

## 详细流程

### 0. 入口检查

在开始前检查以下两项：
1. **business-spec 是否存在**：`docs/sw-agiledevelopment/business-specs/YYYY-MM-DD--<feature>.md` 是否存在？
2. **需求是否已澄清**：该文档是否已通过 `sw-requirements-clarification` 完成需求澄清？

如果任一检查未通过：
- **business-spec 不存在** → 告知用户："未找到 business-spec 文档。请先执行 sw-requirements-clarification 完成需求澄清阶段。"
- **需求未澄清** → 告知用户："需求尚未澄清。请返回 sw-requirements-clarification 完成需求分析流程。"
- **两项均通过** → 继续执行第 1 步

### 1. 读取 business-spec

读取 `docs/sw-agiledevelopment/business-specs/YYYY-MM-DD--<feature>.md`，理解以下内容：
- 业务目标和背景
- 选定的方案及原因
- 关键组件和接口草案
- 验收标准初稿
- 明确的排除范围（非目标）

### 2. 扩展技术细节

基于 business-spec 中的决策，扩展以下内容：

**架构概述**
- 高层架构图或文字描述
- 组件间的通信方式

**组件设计（详细）**
- 每个组件的完整接口定义
- 输入输出、错误类型
- 依赖关系

**数据流**
- 数据如何在组件间流动
- 状态管理策略

**错误处理**
- 错误分类和处理策略
- 重试机制、降级方案

**安全考虑**
- 身份验证、授权
- 数据加密、输入校验

### 3. 编写 technical-spec

**文档规范**：
- 将完整技术设计保存到 `docs/sw-agiledevelopment/technical-specs/YYYY-MM-DD--<feature-name>.md`
- 遵循 technical-spec 文档结构（参考 subagent-prompts/spec-writer-prompt.md）
- 编写完成后提交到 Git

### 4. technical-spec 快速自检

Agent 自行快速扫描 spec，**不调用 Subagent**，仅检查以下三类致命问题：

- **待办事项 / 待定 / 占位符**：任何标记为 TODO、TBD、待补充、后续完善的内容
- **内部矛盾**：需求之间相互冲突、同一概念前后定义不一致
- **不完整部分**：明显缺失的章节、空白的接口定义、缺失的验收标准

**执行方式**：
1. 逐节浏览 spec，标记上述三类问题
2. 发现问题 → 当场修复 → 重新扫描确认
3. **最多迭代 1 轮**，修复后不再重复全文审查
4. 无致命问题 → 立即进入下一步

**明确不检查的内容**（留给 `sw-working-plan` 阶段处理）：
- 措辞风格、文档格式
- YAGNI 审查（实现计划阶段再判断）
- 清晰性打磨（不影响构建的模糊表述）

### 5. 展示规范摘要

快速自检通过后，向用户展示规范摘要，然后**自动调用 `sw-working-plan`**：

> "technical-spec 已编写并提交到 `docs/sw-agiledevelopment/technical-specs/YYYY-MM-DD--<name>.md`。以下是 spec 要点摘要：
> - [设计概述一句话]
> - [关键组件]
> - [主要接口]
> - [验收标准数量]
>
> 现在自动进入实现计划阶段。"

**自动推进**：展示摘要后立即调用 `sw-working-plan`，无需等待用户回复。用户如有修改需求可随时打断。

### 6. 进入实现规划阶段

**唯一出口**：调用 `sw-working-plan` 技能创建详细实现计划。

**严禁**：
- 调用 sw-subagent-development
- 调用 sw-test-driven-dev
- 直接开始编码

## 关键原则

| 原则 | 说明 |
|------|------|
| **基于业务决策** | 不偏离 business-spec 中已确认的方案和范围 |
| **具体明确** | 每个接口、数据结构、错误类型都必须明确定义 |
| **不新增需求** | 不在 technical-spec 中引入需求澄清阶段未讨论的功能 |
| **快速自检** | 只查致命问题，不追求完美文档 |

## 红旗 - 立即停止

| 想法 | 现实 |
|------|------|
| "business-spec 不清楚，我先按自己的理解写" | business-spec 不清楚 → 回到 sw-requirements-clarification 重新澄清 |
| "跳过规范快速自检" | 快速自检能捕获待办、占位符、内部矛盾。跳过 = 有缺陷的规范进入实现阶段 |
| "在 spec 里补充业务背景" | business-spec 已包含背景，technical-spec 聚焦技术实现 |
| "编写规范后立即开始编码" | 必须通过快速自检。编码是唯一出口后的步骤 |

## 常见借口与真相

| 借口 | 真相 |
|------|------|
| "business-spec 太简单，不需要扩展" | 即使需求简单，接口定义和验收标准仍需明确 |
| "规范自检浪费时间" | 快速自检只需 30 秒，发现待办、占位符、矛盾可避免实现阶段卡住 |
| "先写代码再补规范" | 设计先行是纪律。代码先行 = 即兴开发 |

## YAGNI 原则

**You Aren't Gonna Need It（你不需要它）**

对每个技术决策问：
- 这个功能现在需要吗？
- 可以稍后添加而不破坏现有代码吗？
- 这是假设的需求还是已确认的需求？

如果答案是不确定，删除它。

## 输出示例

**规范文件路径**: `docs/sw-agiledevelopment/technical-specs/2026-04-08--user-authentication.md`

**返回摘要格式**：
```markdown
## technical-spec 完成

**规范文件**: `docs/sw-agiledevelopment/technical-specs/2026-04-08--user-authentication.md`
**设计状态**: ✅ 已完成
**主要决策**:
- 使用 JWT 进行身份验证
- 密码使用 bcrypt 哈希
- 支持邮箱+密码和 OAuth 两种方式

**下一步**: 调用 sw-working-plan 创建实现计划
```

## 与其他技能的集成

**前置 Skill**: sw-requirements-clarification（提供业务需求文档）

**后续 Skill**: 
- **sw-working-plan** - 必须调用的下一个技能
- 严禁直接调用实现类技能

**相关 Skill**: 无