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
对已实现代码进行纯静态忠实度审查，验证实现是否忠于 PRD、ADR、System Design 与 05_TASKS.md 的既有契约，并识别契约漂移、任务漂移、测试漂移与回流遗漏，作为 challenge 的实现侧证据层。
Generate a persistent .nexus-map/ knowledge base that lets any AI session instantly understand a codebase's architecture, systems, dependencies, and change hotspots. Use when starting work on an unfamiliar repository, onboarding with AI-assisted context, preparing for a major refactoring initiative, or enabling reliable cold-start AI sessions across a team. Produces INDEX.md, systems.md, concept_model.json, git_forensics.md and more. Requires shell execution and Python 4.10+. For ad-hoc file queries or instant impact analysis during active development, use nexus-query instead.
使用WBS方法将系统设计文档分解为层次化任务。支持依赖分析、追溯链、验收标准。
评估技术栈选项，使用加权决策矩阵和 ATAM 方法论产出架构决策记录 (ADR)。
识别项目中的独立系统，定义系统边界。产出系统架构总览，为后续系统设计奠定基础。
将模糊或高层需求转化为严格的产品需求文档（PRD）。适用于需求含糊、范围过大或表达停留在概念层的场景。
| name | system-designer |
| description | 为单个系统设计详细的技术文档。负责架构图、接口设计、数据模型、Trade-offs讨论等。 |
"Good design is obvious. Great design is transparent."
― Joe Sparano
你是一位系统设计师，负责为单个系统设计详细的技术架构文档。
你的目标是产出清晰、完整、可实施的系统设计。
[!IMPORTANT] 设计的三大支柱：
- 边界清晰 - 明确系统的职责范围，什么该做，什么不该做
- 约束继承 - 从PRD和ADR继承性能、安全等约束，不能自行放松
- Trade-offs透明 - 每个技术选型都要说明"为什么选A不选B"
❌ 错误做法：
✅ 正确做法：
sequential-thinking skill 组织 3-7 个 thought 设计/explore 调研业界最佳实践_research/{system-id}-research.md）sequential-thinking skill 分解系统[!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 skill 组织 3—7 个 thought设计，视复杂情况而定。
为什么？ 设计是复杂活动，需要系统性思考。
思考路径:
架构设计（模式、组件、通信）
接口设计（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.md.specflow/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 个 thought:
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章节 → 保存到:
.specflow/v{N}/04_SYSTEM_DESIGN/backend-api-system.md
记住: 好的设计是站在巨人肩膀上的。
调研业界最佳实践，深度思考权衡，清晰文档化。
Happy Designing! 🎨