# Technical Design

> 生产级前期系统架构、技术方案设计 (TDD/RFC)、数据建模与算法状态机规范技能。 涵盖方案先行与审阅确认铁律、苏格拉底式需求收敛协议 (Socratic Refinement)、 附带自动化检验指令的微任务拆解 (Bite-Sized Verifiable Tasks)、完成前铁证验证门禁 (Verification Evidence Gate)、 严禁静默重试与兜底补偿、复杂算法标准 LaTeX 公式推导、领域建模 (ER/索引/分表) 及有限状态机闭环。

- Skill: `garfield247/technical-design` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add garfield247/technical-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/garfield247/technical-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Garfield247 (https://skillmd.com/u/garfield247)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/garfield247/technical-design

---


# 系统架构与前期技术方案设计规范技能 (Technical Design & Architecture Skill)

## 概述 (Overview)

本技能定义了研发工程师与 AI 编码助手在面对新需求、新系统立项、复杂业务模块重构或核心基础设施升级时的**前期系统架构设计、技术方案编写（RFC / Technical Design Document, TDD）与评审交互红线**。

吸纳业界卓越工程纪律与框架（如 `obra/superpowers` 的资深工程师纪律），彻底告别凭感觉写代码（Vibe Coding）。**“前期设计跑偏一步，后期维护百倍代价；任务缺乏验证命令，执行必成半吊子工程”**。本技能旨在保障在动手写任何业务代码之前，架构设计在**需求边界、数据建模、时序交互、算法公式、异常推演、微任务拆解与铁证检验**七大维度上均实现严密闭环，并经由用户严格审阅确认后方可投产。

---

# 1. 核心设计铁律（五大绝对红线）

在开始编写代码前，必须时刻无条件遵守以下铁律：

### 🚨 铁律一：复杂需求必须“方案先行、审阅确认后再编码” (Design-First Rule)
- 凡涉及新增独立模块、多表关联改造、跨服务调用、资金/资产交互或底层重构，**坚决禁止在拿到需求后直接写业务代码**。
- **强制执行机制**：必须先输出结构化的《技术方案设计文档》（TDD/RFC），向用户清晰汇报架构选型、数据模型、流程图与潜在风险。**只有在获得用户的明确确认后，方可进入编码实现阶段**。

### 🚨 铁律二：坚决禁止静默添加重试、兜底与补偿逻辑 (No Silent Fallback/Retry)
- 在方案推演或接口设计过程中，若评估认为某些外部调用、数据库查询或 MQ 消费可能失败，**坚决禁止在方案或代码中静默直接加入自动重试（Retry）、默认值兜底降级（Fallback）或数据补偿逻辑**。
- **必须履行的告知义务**：方案中必须设立专门章节，向用户主动分析：
  1. 为什么需要重试/兜底/补偿？
  2. 潜在副作用与次生风险（防好心办坏事：如脏数据静默写入、重复扣款/重复建单、雪崩重试风暴、掩盖真实线上故障等）；
  3. 可行的备选方案对比。
  **在方案审阅时由用户显式拍板确认后，方可纳入实现计划**。

### 🚨 铁律三：苏格拉底式需求收敛协议 (Socratic Refinement Protocol)
- 如果给出的需求指令信息不足以支撑写出高精度架构方案时，**严禁凭空脑补核心业务边界，严禁长篇大论凭感觉规划 (Vibe Planning)**。
- **应对准则**：
  1. 基于业内成熟通用最佳实践，先提炼出设计基调框架；
  2. 启动单点聚焦提问机制：在方案开头明确列出 **2-3 个最关键的决策确认点**（例如：高并发峰值容忍、读多写少还是强一致性写入、超时兜底偏好、冷热数据隔离周期）；
  3. 通过针对性问答收敛出确定性的产品技术契约（Spec Contract），杜绝返工。

### 🚨 铁律四：复杂算法与数学模型标准 LaTeX 规范 (Mathematical Rigor)
- 方案中若涉及复杂的业务计费公式、评分排名算法、加权负载均衡、概率模型、密码学或几何计算，**必须使用标准的 LaTeX 公式进行原理解释与数学推导**：
  - 行内公式使用 `$公式$`（例如：加权耗损计算 $W_i = \alpha \cdot C_i + (1 - \alpha) \cdot R_i$）；
  - 独立公式块使用 `$$ ... $$`。
- **严禁使用模糊口语化的自然语言指代关键数学公式**，必须给出公式定义域、边界极值与输入输出示例。

### 🚨 铁律五：完成前铁证验证门禁 (Verification Evidence Gate)
- **严禁口头声明完成**：严禁在未经过真实命令验证的情况下向用户汇报“已实现/已完成”。
- 方案中每个实施微任务，必须配有可执行的自动化验证命令（测试用例、编译检查、脚本断言）。
- 落地执行时，**必须在终端真实运行检验命令并输出 Exit Code 0 与测试通过证据**，形成铁证闭环。

---

# 2. 技术方案设计标准交付规范 (TDD / RFC 结构)

技术方案必须严格按照以下结构化模板编写交付，重点突出架构图、关键设计与微任务拆解：

```markdown
# 🏛️ [功能模块名称] 技术架构方案设计 (Technical Design Document)

## 1. 业务场景与需求收敛 (Socratic Refinement)
- **需求概述**：[简明扼要说明本次设计解决的核心业务价值]
- **核心决策待确认点 (若需求模糊)**：
  - [ ] 待确认点 1：[明确列出需用户拍板的技术/业务分支，如选择 Redis ZSet 还是自研发号器]
  - [ ] 待确认点 2：[明确列出性能、事务边界或降级约束]
- **设计边界**：明确 In-Scope（本次交付）与 Out-of-Scope（明确不做的延伸项）。
- **性能与容量指标**：预期并发（QPS/TPS 峰值）、数据增长估算、时延要求（P99 < 200ms）。

## 2. 领域建模与数据存储设计 (Data Architecture)
- **库表结构与实体关系 (ER)**：
  - 核心字段设计、主键生成策略（ULID / 分布式雪花算法 / 自增 ID）；
  - **索引与约束规划**：聚簇索引、最左匹配联合索引、防重唯一索引（考虑软删除兼容性）；
  - 归档与按月分表规划（如满足按月自愈分表红线）。
- **缓存与状态存储 (Redis)**：
  - 标准分环境 Key 命名空间：`{project}:{env}:{module}:{business_key}`；
  - 数据结构选型（String / Hash / ZSet / HyperLogLog）与明确的 TTL 过期时间。

## 3. 业务流程、时序交互与状态机 (Workflow & State Machine)
- **核心业务时序图 (Mermaid Sequence Diagram)**：
  （严格遵循 Mermaid 防崩语法：双引号包裹节点，纯文本连线条件）
- **有限状态机跃迁图 (FSM State Diagram)**：
  - 覆盖所有正向流（如：待支付 -> 已支付 -> 履约中 -> 已完成）；
  - 覆盖所有逆向流（如：超时取消、风控拦截、申请退款、原路退回）；
  - 明确禁止非法反向跃迁。

## 4. 复杂算法与数学公式推导 (若涉及)
- 业务数学模型与公式推导：
  $$S_{final} = \sum_{i=1}^{n} w_i \cdot \frac{x_i - \min(X_i)}{\max(X_i) - \min(X_i)}$$
- 参数边界说明与极值处理（防除零、防溢出）。

## 5. 健壮性、幂等与异常补偿方案 (Robustness & Fallback)
- **幂等与防并发竞态设计**：
  - 业务唯一 Idempotency Key 机制；
  - 分布式锁粒度（精准锁定业务最小维度，严禁大范围粗粒度锁）。
- **兜底、重试与补偿策略评估（核心提醒）**：
  - 拟定重试/兜底逻辑：[说明具体策略]
  - 潜在次生风险：[如是否可能导致脏数据写入、重复消费]
  - 备选方案：[列出替代方案]
  - **👉 请用户确认是否采纳该兜底策略**。

## 6. 实施路线与可验证微任务拆解 (Bite-Sized Verifiable Tasks)
严禁粗粒度“一步到位”，强制拆解为 10~20 分钟粒度的可检验原子任务：

- [ ] **Task 1: [契约与数据模型定义]**
  - **Target Files**: `api/order.api`, `model/order_model.sql`
  - **Intent & Spec**: 声明 API 契约与 SQL Schema，建立防重唯一索引。
  - **Automated Verification**:
    ```bash
    goctl api validate --api api/order.api
    ```
  - **Evidence Gate**: 命令退出码 0，契约校验通过。

- [ ] **Task 2: [核心业务 Logic 编排与事务闭环]**
  - **Target Files**: `internal/logic/create_order_logic.go`
  - **Intent & Spec**: 实现下单编排、分布式防重锁与库存原子预扣。
  - **Automated Verification**:
    ```bash
    go test -v -run TestCreateOrderLogic_Success ./internal/logic/...
    ```
  - **Evidence Gate**: 单元测试 Pass，包含零库存与并发扣减测试。

- [ ] **Task 3: [异常分支覆盖与铁证回归]**
  - **Target Files**: `internal/logic/create_order_logic_test.go`
  - **Intent & Spec**: 覆盖超时回滚与重复提交幂等拦截分支。
  - **Automated Verification**:
    ```bash
    go test -v -race -cover ./internal/logic/...
    ```
  - **Evidence Gate**: 单测覆盖率 >= 80%，Race 竞态检测 0 警告。
```

---

# 3. 领域与技术栈专属设计规范

### 3.1 Go & go-zero 架构设计前置规范
- **契约先行**：严禁在未定义 `.api` 或 `.proto` 文件前编写任何 Handler 或 Logic 代码；
- **资源依赖收敛**：新增的数据库引擎、Redis 连接、RPC 客户端，必须在方案中明确声明挂载于 `ServiceContext`，保持单例无状态；
- **分层穿透规避**：Handler 严禁越权调用 Model，必须经由 Logic 编排；
- **统一响应与错误码规划**：在方案中预先分配好本模块的业务错误码段（如 `20101` ~ `20199`）。

### 3.2 Python & FastAPI 架构设计前置规范
- **Schema 契约前置**：优先定义 Pydantic v2 Request/Response Schema，显式声明 `Field(description="...")`；
- **事务边界规划**：写操作的 `session.commit()` 必须收敛在单一 Service 方法末尾，方案中禁止出现多个并发写操作共享同一脏 Session 的时序设计。

### 3.3 网络爬虫与数据采集设计前置规范
- **协议逆向优先评估**：前期方案必须包含接口抓包可行性验证，优先抓取 XHR/JSON 接口；
- **反爬风险定级**：前置评估目标站点的 WAF 级别、TLS/JA3 指纹要求与频控阈值，选定客户端驱动（`httpx` vs `curl_cffi` vs `playwright`）。

---

# 4. 设计方案评审 Checklist

在方案提交给用户审阅前，逐项检查：
- [ ] 若需求存在模糊之处，是否已通过苏格拉底式提问列出 2-3 个核心确认点？
- [ ] 实施任务是否已拆解为携带【Target Files】与【Automated Verification】的微任务（Bite-Sized Verifiable Tasks）？
- [ ] 是否存在私自静默加入的重试或兜底降级？若有，是否已向用户充分说明原因与风险？
- [ ] 复杂业务算法是否已使用标准 LaTeX 公式进行清晰推导？
- [ ] 状态机图是否包含了逆向分支与超时终态，避免出现无头悬挂状态？
- [ ] 接口是否具备幂等机制防范重复提交？
- [ ] 技术术语是否合规（严禁出现敏感机房代号，统一使用通用术语）？

---

# 5. 高级架构治理：ADR、可观测性与安全前置 (Advanced Architecture Patterns)

吸纳业界顶尖工程架构标准，技术方案必须包含以下前置防护模块：

### 5.1 架构决策记录 (Architecture Decision Record, ADR)
在重大选型或方案折中时，必须在方案中保留 ADR 决策块：
- **Context (背景上下文)**：面临什么业务挑战与性能约束？
- **Decision (最终裁定方案)**：选用了哪种技术路线/设计模式？
- **Rejected Alternatives (被否决的备选方案与原因)**：
  - *方案 B (已否决)*：原因（如：写入并发无法满足要求、改造成本过高、存在单点风险）。
- **Consequences & Trade-offs (代价与妥协)**：带来了哪些已知限制？如何防范技术债？

### 5.2 可观测性前置设计 (Observability-First Design)
严禁系统上线后再补救监控。前期方案必须明确：
1. **指标与 SLO/SLA 阈值**：
   - 吞吐指标（QPS 预期峰值）；
   - 延迟指标（P95 < 100ms，P99 < 300ms）；
   - 错误率红线（5xx 比例 > 0.05% 立即触发 P1 告警）。
2. **全链路 Trace 穿透**：HTTP Header (`x-trace-id`) -> RPC Context -> MQ 消息属性 -> 数据库 SQL 注释统一串联。

### 5.3 安全威胁建模前置 (Security & STRIDE)
- **水平与垂直越权防护 (Anti-IDOR)**：所有基于 ID 操作的数据（如订单、设备、账单），必须在数据持有层校验当前请求租户/用户归属权（`WHERE id = ? AND user_id = ?`）；
- **敏感数据存储**：手机号、身份证、密钥等字段在方案中必须注明脱敏加密策略（AES-256-GCM / 摘要哈希）。