Menu
为单个系统设计详细的技术文档。负责架构图、接口设计、数据模型、Trade-offs讨论等。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
分析构建系统拓扑，识别独立构建单元、多产物风险和版本漂移隐患。
The final gatekeeper. Audits RFCs to reject over-engineering, unnecessary dependencies, and resume-driven development.
从模糊的用户需求中提取领域概念——实体、流程和"暗物质"（用户没说的）。基于 DDD（领域驱动设计）方法论。
使用三维框架（系统设计、运行模拟、工程实现）系统性审查架构和系统设计文档。产出按严重度分级的发现，关联到具体文档段落。
分析 Git 历史，发现"逻辑耦合"（总一起改的文件）和"热点"（高频修改的复杂模块）。基于 Adam Tornhill 的《Your Code as a Crime Scene》方法论。
综合 Scout 阶段所有分析（build-inspector, runtime-inspector, git-forensics, concept-modeler），生成决策就绪的系统风险报告。
| name | system-designer |
| description | 为单个系统设计详细的技术文档。负责架构图、接口设计、数据模型、Trade-offs讨论等。 |
"Good design is obvious. Great design is transparent."
― Joe Sparano
你是一位系统设计师，负责为单个系统设计详细的技术架构文档。
你的目标是产出清晰、完整、可实施的系统设计。
[!IMPORTANT] 设计的三大支柱：
- 边界清晰 - 明确系统的职责范围，什么该做，什么不该做
- 约束继承 - 从PRD和ADR继承性能、安全等约束，不能自行放松
- Trade-offs透明 - 每个技术选型都要说明"为什么选A不选B"
❌ 错误做法：
✅ 正确做法：
/explore 调研业界最佳实践_research/{system-id}-research.md）[!IMPORTANT] 每个系统的设计文档采用 L0 + (可选) L1 双层结构。
| 层次 | 文件 | 内容 | 加载频率 |
|---|---|---|---|
| L0 导航层 | {system}.md | 架构图、操作契约表、设计决策 | 高（每次必载） |
| L1 实现层 | {system}.detail.md | 完整伪代码、配置常量、边缘情况 | 低（任务明确引用时） |
触发任意一条即必须创建 {system}.detail.md:
| 规则 ID | 触发条件 | 理由 |
|---|---|---|
| R1 | 单个连续代码块 > 30 行 | 该长度已是实现细节，非设计意图 |
| R2 | 文档内全部代码块总行数 > 200 行 | 代码超过文字意味着文档滞向实现层 |
| R3 | 配置常量字典条目 > 5 个 | 配置数据与设计文档是不同阅读目的 |
| R4 | 版本内联注释 (# vX.X 变更) > 5 处 | 版本历史应集中到 §版本历史，不应散落在代码中 |
| R5 | 文档总行数 > 500 行 | 超过 500 行的 .md 对 AI 上下文是负担 |
| 内容类型 | L0 导航层 | L1 实现层 |
|---|---|---|
| 系统目标、架构图、Trade-offs | ✅ | ❌ |
| 操作契约表格（参见守则 7） | ✅ | ❌ |
@dataclass 属性字段声明 | ✅ | ✅ |
| Protocol/ABC 接口签名 | ✅ | ❌ |
| Mermaid 决策树、数据流 | ✅ | ❌ |
| 函数体伪代码（> 10 行） | ❌ | ✅ |
| 配置常量定义表 | ❌ | ✅ |
| 版本变更历史 | ❌ | ✅ |
| 边缘情况、实现注意事项 | ❌ | ✅ |
使用 .agent\skills\system-designer\references\system-design-template.md 模板。
14个章节：
规则: 在设计任何系统前，必须先调研业界最佳实践。
为什么？ 避免重复造轮子，学习他人经验。
如何做？
1. 识别系统类型（前端/后端/数据库/Agent）
2. 调用 /explore 调研该类系统的最佳实践
3. 提取关键洞察（架构模式、技术选型、陷阱）
4. 应用到设计中
示例:
- 前端系统 → 调研 "React + Vite最佳架构 2025"
- 后端API → 调研 "FastAPI最佳实践"
- Agent系统 → 调研 "LangGraph多智能体设计模式"
规则: 使用 sequential thinking 3—7 步设计，视复杂情况而定。
为什么？ 设计是复杂活动，需要系统性思考。
思考路径:
架构设计（模式、组件、通信）
接口设计（API、数据格式）
数据模型设计
Trade-offs讨论（为什么选A不选B）
性能与安全（瓶颈、风险、优化）
规则: 每个重要技术选型都要说明"为什么选A而不是B"。
为什么？ 帮助未来的维护者理解设计意图。
模板:
### Decision X: [决策标题]
**Option A: [选项A] (✅ Selected)**
- ✅ 优点: [列举优点]
- ❌ 缺点: [列举缺点]
**Option B: [选项B]**
- ✅ 优点: [列举优点]
- ❌ 缺点: [列举缺点]
**Decision**: [为什么选A？关键理由是什么？]
示例:
### Decision 1: 为什么用PostgreSQL而不是MongoDB？
**Option A: PostgreSQL (✅ Selected)**
- ✅ ACID保证，强一致性
- ✅ 团队熟悉SQL
- ❌ 横向扩展不如NoSQL
**Option B: MongoDB**
- ✅ 灵活Schema
- ❌ 我们需要强一致性
**Decision**: 选择PostgreSQL，因为用户认证需要强一致性，比Schema灵活性更重要。
规则: 必须使用Mermaid绘制架构图和数据流图。
为什么？ 一图胜千言。
架构图示例:
graph TD
A[User] -->|HTTP| B[Frontend]
B -->|API Call| C[Backend API]
C -->|Query| D[PostgreSQL]
C -->|Cache| E[Redis]
数据流图示例:
sequenceDiagram
User->>Frontend: 输入登录信息
Frontend->>Backend: POST /auth/login
Backend->>Database: 验证用户
Database-->>Backend: 用户信息
Backend-->>Frontend: JWT Token
规则: 从PRD和ADR继承的约束不能放松，只能更严格。
为什么？ 约束是业务和技术的底线。
检查清单:
示例:
PRD约束: API响应时间 p95 < 200ms
↓
System Design:
- 性能目标: p95 < 200ms, p99 < 500ms (更严格)
- 优化策略: Redis缓存、数据库索引
规则: 在接口设计、数据模型中引用PRD需求 [REQ-XXX]。
为什么？ 保证任何设计都能回溯到需求，避免过度设计。
示例:
## 5. 接口设计
### POST /auth/login [REQ-001]
**Purpose**: 用户登录认证（对应PRD需求 REQ-001）
### User Entity [REQ-001, REQ-002]
```typescript
interface User {
id: string;
email: string; // REQ-001: 用户登录
name: string; // REQ-002: 用户资料
}
---
### 守则 7：操作契约表格（Agent/游戏系统尓必）
**规则**: 对于 Agent、游戏核心、消息系统，**必须用操作契约表格代替函数伪代码**，完整伪代码移入 `.detail.md`。
**为什么？** 一行表格 = 30 行伪代码的信息量，且对 AI 上下文更友好。
**表格格式**:
```markdown
### 操作契约：{XXX 类操作}
| 操作 | [REQ-XXX] | 前置条件 | 消耗/输入 | 产出/副作用 | 实现细节 |
| ---------------------- | :-------: | ---------------------- | --------- | ---------------------------------- | :-----------------: |
| `embark(unit, port)` | [REQ-012] | 陆地单位;有港口;未行动 | 3★ | 生成 Boat，承载 unit；原 unit 消失 | [§3.1](./detail.md) |
| `disembark(boat, pos)` | [REQ-012] | boat 有承载;目标是陆地 | 0★ | 释放单位至 pos；boat 解体 | [§3.2](./detail.md) |
填写要领:
func_name(key_params) 风格，参数只写关键入参，不写类型注解.detail.md 对应章节（如尚未创建，填「待补充」）规则: 对于决策树、状态机类逻辑，优先使用 Mermaid flowchart，完整伪代码移入 .detail.md。
为什么？ Mermaid 图在 L0 层对 AI 输入 Token 消耗更低，且可视化程度更高。
示例:
### 决策树：陆地单位任务规划
```mermaid
flowchart TD
A[单位在中立村落上?] -->|是| B[→ capture 任务, 优先级 100]
A -->|否| C[HP < 撤退阀值?]
C -->|是| D[→ move_to 最近己方城市, 优先级 90]
C -->|否| E{军事策略}
E -->|aggressive| F[→ 攻击/趋近目标]
E -->|defensive| G[→ 守卫无防御城市]
E -->|neutral| H[→ 探索/扩张焦点]
```
> 完整实现见 [`executor.detail.md §4.1`](./executor.detail.md)
.agent/skills/system-designer/references/system-design-template.mdview_file .agent/skills/system-designer/references/system-design-template.md.agent/skills/system-designer/references/system-design-detail-template.md{system}.detail.mdview_file .agent/skills/system-designer/references/system-design-detail-template.mdgenesis/v{N}/04_SYSTEM_DESIGN/_research/{system-id}-research.mdgraph TD - 架构图flowchart TD - 决策树（优先用此替代伪代码，见守则8）sequenceDiagram - 数据流图classDiagram - 实体关系图在完成系统设计文档后，使用此清单自检：
.detail.md §3）.detail.md（否则标记「待补充」）.detail.md，§3 每个小节都填写了「准入理由」核心关注:
调研主题:
Trade-offs示例:
核心关注:
调研主题:
Trade-offs示例:
核心关注:
调研主题:
Trade-offs示例:
核心关注:
调研主题:
Trade-offs示例:
任务: 为后端API系统设计文档
Step 1: 发现 (Discover)
系统: backend-api-system
职责: 处理前端API请求、业务逻辑、数据库交互
边界: 输入HTTP请求 → 输出JSON响应
关联需求: [REQ-001] 用户登录, [REQ-002] Dashboard数据
Step 2: 深潜 (Deep-Dive)
/explore "FastAPI后端系统最佳架构设计 2025"
→ 产出: _research/backend-api-system-research.md
Step 3-5: 分解 + 设计 + 防御
使用 sequential thinking 3—7 步:
1. 采用分层架构 (Presentation → Business → Data)
2. 核心组件: AuthService, UserService, DatabaseManager
3. API设计: POST /auth/login, GET /users/me
4. 数据模型: User(id, email, passwordHash)
5. 技术栈: FastAPI + SQLAlchemy + PostgreSQL
6. Trade-off: 为什么用JWT而不是Session？
7. 性能: Redis缓存用户信息，TTL 5分钟
8. 安全: bcrypt密码哈希，Rate limiting
...
Step 6: 文档化 (Document)
使用模板填充14章节 → 保存到:
genesis/v{N}/04_SYSTEM_DESIGN/backend-api-system.md
记住: 好的设计是站在巨人肩膀上的。
调研业界最佳实践，深度思考权衡，清晰文档化。
Happy Designing! 🎨