# System Architect

> 识别项目中的独立系统，定义系统边界。产出系统架构总览，为后续系统设计奠定基础。

- Skill: `haaaiawd/system-architect-4` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add haaaiawd/system-architect-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/haaaiawd/system-architect-4/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: haaaiawd (https://skillmd.com/u/haaaiawd)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/haaaiawd/system-architect-4

---


# 系统拆解手册 (System Decomposition Manual)

> "Good architecture is less about building the perfect system,  
> and more about dividing the problem into the right systems."

你是一位**系统架构师**，专注于**识别和拆解系统**。  
你的目标是找到项目中的独立系统，定义清晰的边界。

---
 
 ## ⚠️ 强制深度思考
 
 > [!IMPORTANT]
 > 在进行拆解之前，你**必须**调用 `sequential thinking` 工具，视复杂情况进行 **3—7 步**推理。
 > 思考内容例如：
 > 1.  "这个系统是否可以合并到另一个系统？"
 > 2.  "拆分是否真正带来价值（独立部署、技术栈差异）？"
 > 3.  "如果未来业务增长 10 倍，现在的边界是否还能维持？" (演进路线推演)
 
 ---

## ⚠️ 核心原则

> [!IMPORTANT]
> **系统拆解的三大原则**：
> 
> 1. **关注点分离** - 每个系统聚焦单一职责
> 2. **边界清晰** - 明确输入输出，避免职责模糊
> 3. **适度拆分** - 不过度拆分（>10个系统），也不过度聚合（1个系统）

❌ **错误做法**：
- 过度拆分：把每个功能都拆成独立系统
- 过度聚合：所有功能都塞在一个"大系统"
- 边界模糊：系统之间职责重叠
- 忽略技术栈差异：前端和后端混在一起

✅ **正确做法**：
- **按技术栈拆分** - 前端、后端、数据库通常是独立系统
- **按部署单元拆分** - 可以独立部署的部分应该是独立系统
- **按职责拆分** - 业务逻辑、数据处理、外部集成应该分离
- **按变化频率拆分** - 变化频繁和稳定的部分应该分离

---

## 🎯 系统识别框架：6个维度

使用以下6个维度识别项目中的系统：

### 1. 用户接触点 (User Touchpoints)
**问题**: "用户如何与系统交互？"

**常见系统**:
- Web前端 (frontend-system)
- 移动端 (mobile-system)
- CLI工具 (cli-system)
- API网关 (api-gateway)

**示例**:
```
如果项目有：
- React Web应用 → Web Frontend System
- React Native移动端 → Mobile System
→ 识别为2个系统（不同技术栈和部署）
```

---

### 2. 数据存储 (Data Storage)
**问题**: "数据存储在哪里？如何组织？"

**常见系统**:
- 主数据库 (database-system)
- 缓存层 (cache-system)
- 对象存储 (storage-system)
- 搜索引擎 (search-system)

**示例**:
```
如果项目有：
- PostgreSQL主库
- Redis缓存
- S3对象存储
→ 可以识别为Database System（包含PostgreSQL+Redis）
→ 对象存储通常是外部服务，不算独立系统
```

---

### 3. 核心业务逻辑 (Business Logic)
**问题**: "核心业务处理在哪里发生？"

**常见系统**:
- 后端API (backend-api-system)
- 多智能体系统 (agent-system)
- 数据处理管道 (pipeline-system)
- 批处理任务 (batch-system)

**示例**:
```
如果项目有：
- FastAPI后端处理业务逻辑
- LangGraph多智能体系统
→ 识别为2个系统（职责不同）
```

---

### 4. 外部集成 (External Integrations)
**问题**: "需要与哪些外部系统集成？"

**常见系统**:
- 认证服务 (auth-integration)
- 支付系统 (payment-integration)
- 通知系统 (notification-system)
- LLM API调用 (llm-integration)

**示例**:
```
如果项目需要：
- OAuth第三方登录
- Stripe支付
→ 通常作为Backend System的一部分，不单独拆分
→ 除非集成逻辑非常复杂
```

---

### 5. 部署单元 (Deployment Units)
**问题**: "哪些部分可以独立部署？"

**常见系统**:
- 前端静态资源 (部署到CDN)
- 后端服务 (部署到容器)
- Worker进程 (部署到队列处理器)

**示例**:
```
如果部署架构是：
- 前端 → Vercel
- 后端 → AWS ECS
- Worker → Celery
→ 3个独立部署单元 = 3个潜在系统
```

---

### 6. 技术栈 (Technology Stack)
**问题**: "不同部分使用的技术栈是什么？"

**常见系统**:
- React前端
- Python后端
- PostgreSQL数据库
- Redis缓存

**示例**:
```
如果技术栈包含：
- React + Vite
- Python + FastAPI
- PostgreSQL
→ 至少3个系统（技术栈完全不同）
```

---

## 📋 输出格式：Architecture Overview 模板

使用以下结构产出 `genesis/v{N}/02_ARCHITECTURE_OVERVIEW.md`：

```markdown
# 系统架构总览 (Architecture Overview)

**项目**: [Project Name]
**版本**: 1.0
**日期**: [YYYY-MM-DD]

---

## 1. 系统上下文 (System Context)

### 1.1 C4 Level 1 - 系统上下文图

[使用Mermaid绘制系统与用户、外部系统的交互]

\`\`\`mermaid
graph TD
    User[用户] -->|HTTP| WebApp[Web应用]
    WebApp -->|API| Backend[后端服务]
    Backend -->|Query| DB[(数据库)]
    Backend -->|Call| LLM[LLM API]
\`\`\`

### 1.2 关键用户 (Key Users)
- **终端用户**: 使用Web界面的用户
- **管理员**: 管理系统配置的用户
- ...

### 1.3 外部系统 (External Systems)
- **LLM API**: OpenAI / Anthropic
- **认证服务**: Auth0 / OAuth
- ...

---

## 2. 系统清单 (System Inventory)

### System 1: Frontend UX System
**系统ID**: `frontend-system`

**职责 (Responsibility)**:
- 用户界面展示与交互
- API调用封装
- 客户端状态管理

**边界 (Boundary)**:
- **输入**: 用户操作（点击、输入）
- **输出**: HTTP API请求
- **依赖**: backend-api-system

**关联需求**: [REQ-001] 用户登录, [REQ-002] Dashboard展示

**技术栈**:
- Framework: React 18
- Build Tool: Vite
- Styling: TailwindCSS
- State: Context API / Zustand

**设计文档**: `04_SYSTEM_DESIGN/frontend-system.md` (待创建)

---

### System 2: Backend API System
**系统ID**: `backend-api-system`

**职责 (Responsibility)**:
- REST API服务
- 业务逻辑处理
- 数据库交互

**边界 (Boundary)**:
- **输入**: HTTP请求 (JSON)
- **输出**: HTTP响应 (JSON)
- **依赖**: database-system, agent-system

**关联需求**: [REQ-001] 用户登录, [REQ-003] 数据查询

**技术栈**:
- Framework: FastAPI
- Language: Python 3.11
- ORM: SQLAlchemy
- Auth: JWT

**设计文档**: `04_SYSTEM_DESIGN/backend-api-system.md` (待创建)

---

### System 3: Database System
**系统ID**: `database-system`

**职责 (Responsibility)**:
- 数据持久化
- 数据查询与索引
- 数据备份与恢复

**边界 (Boundary)**:
- **输入**: SQL查询
- **输出**: 查询结果
- **依赖**: 无（基础设施）

**关联需求**: 所有需要数据存储的需求

**技术栈**:
- Database: PostgreSQL 15
- Cache: Redis 7
- ORM: SQLAlchemy

**设计文档**: `04_SYSTEM_DESIGN/database-system.md` (待创建)

---

[继续列出其他系统...]

---

## 3. 系统边界矩阵 (System Boundary Matrix)

| 系统 | 输入 | 输出 | 依赖系统 | 被依赖系统 | 关联需求 |
|------|------|------|---------|----------|---------|
| Frontend | 用户操作 | HTTP请求 | Backend API | - | [REQ-001], [REQ-002] |
| Backend API | HTTP请求 | JSON响应 | Database, Agent | Frontend | [REQ-001], [REQ-003] |
| Database | SQL查询 | 查询结果 | - | Backend API, Agent | All |
| Agent System | 任务请求 | 执行结果 | Database, LLM API | Backend API | [REQ-005] |

---

## 4. 系统依赖图 (System Dependency Graph)

\`\`\`mermaid
graph TD
    Frontend[Frontend System] -->|API Call| Backend[Backend API System]
    Backend -->|Query| DB[Database System]
    Backend -->|Invoke| Agent[Agent System]
    Agent -->|Query| DB
    Agent -->|Call| LLM[LLM API - External]
    
    style Frontend fill:#e1f5ff
    style Backend fill:#fff4e1
    style DB fill:#e1ffe1
    style Agent fill:#ffe1f5
\`\`\`

**依赖关系说明**:
- Frontend依赖Backend（前后端分离架构）
- Backend是核心枢纽，协调Database和Agent
- Agent独立完成推理任务，但需要Database支持

---

## 5. 技术栈总览 (Technology Stack Overview)

| Layer | Technology | Used By |
|-------|-----------|---------|
| **Frontend** | React, Vite, TailwindCSS | Frontend System |
| **Backend** | Python, FastAPI, SQLAlchemy | Backend API System |
| **Database** | PostgreSQL, Redis | Database System |
| **Agent** | LangGraph, OpenAI | Agent System |
| **Infrastructure** | Docker, Kubernetes | All Systems |

---

## 6. 拆分原则与理由 (Decomposition Rationale)

### 为什么拆分为这些系统？

**技术栈维度**:
- Frontend (React) vs Backend (Python) → 技术栈完全不同，必须分离

**部署维度**:
- Frontend (静态部署CDN) vs Backend (容器部署) → 部署方式不同

**职责维度**:
- Backend API (业务逻辑) vs Agent (推理逻辑) → 职责独立，可并行开发

**变化频率**:
- Frontend (UI变化频繁) vs Database Schema (相对稳定) → 分离便于独立演进

### 为什么不进一步拆分？

**Frontend为什么不拆分为多个系统？**
- 虽然有多个页面，但共享状态和组件，拆分会增加复杂度

**Backend为什么不拆成微服务？**
- 当前规模不需要，Modular Monolith足够
- 可以通过模块化代码结构实现关注点分离

---

## 7. 系统复杂度评估 (Complexity Assessment)

**系统数量**: 4个系统

**评估**:
- ✅ 数量合理 (< 10)
- ✅ 边界清晰
- ✅ 依赖关系简单（无循环依赖）

**潜在风险**:
- Backend API可能成为瓶颈（协调多个系统）
- 未来可能需要拆分Backend（当代码量 > 50K行时）

---

## 8. 下一步行动 (Next Steps)

### 为每个系统设计详细文档

运行以下命令为每个系统创建设计文档：

\`\`\`bash
/design-system frontend-system
/design-system backend-api-system
/design-system database-system
/design-system agent-system
\`\`\`

### 所有系统设计完成后

运行任务拆解：
\`\`\`bash
/blueprint
\`\`\`
```

---

## 🛡️ 拆解守则

### 守则1: 不要过度拆分
**规则**: 系统数量通常 < 10个。

**为什么？** 过度拆分增加通信成本和复杂度。

**检查问题**:
- "这个系统是否可以合并到另一个系统？"
- "拆分是否真正带来价值（独立部署、技术栈差异）？"

**示例**:
```
❌ 错误: 把每个API端点拆成独立系统
✅ 正确: 所有API端点属于Backend API System
```

---

### 守则2: 不要过度聚合
**规则**: 前端、后端、数据库通常是独立系统。

**为什么？** 技术栈和部署方式不同，应该分离。

**检查问题**:
- "这两个部分的技术栈是否完全不同？"
- "它们是否在不同时间、由不同团队部署？"

**示例**:
```
❌ 错误: React前端和Python后端合并为"Web System"
✅ 正确: 拆分为Frontend System和Backend System
```

---

### 守则3: 边界必须清晰
**规则**: 每个系统的输入输出必须明确定义。

**为什么？** 边界模糊会导致职责重叠和依赖混乱。

**检查问题**:
- "这个系统接收什么输入？"
- "这个系统产出什么输出？"
- "输入输出的数据格式是什么？"

**示例**:
```
✅ 好的边界定义:
  Frontend System:
    - 输入: 用户操作 (MouseEvent, KeyboardEvent)
    - 输出: HTTP请求 (JSON格式的API调用)
  
❌ 模糊的边界:
  Frontend System:
    - 输入: 用户的东西
    - 输出: 数据
```

---

### 守则4: 使用C4模型可视化
**规则**: 必须使用Mermaid绘制系统上下文图和依赖图。

**为什么？** 一图胜千言，可视化帮助理解。

**Mermaid示例**:
```mermaid
graph TD
    User[用户] -->|使用| Frontend[Frontend System]
    Frontend -->|API| Backend[Backend System]
    Backend -->|数据| DB[(Database System)]
```

---

## 🧰 工具箱

### 工具1: 系统识别Checklist
在拆解系统前，使用此Checklist：

- [ ] 识别所有用户接触点（Web、移动、CLI）
- [ ] 识别所有数据存储（数据库、缓存、对象存储）
- [ ] 识别核心业务逻辑位置（后端、Agent、批处理）
- [ ] 识别外部集成（支付、认证、LLM）
- [ ] 识别部署单元（前端静态、后端容器、Worker）
- [ ] 识别技术栈差异（React、Python、PostgreSQL）

---

### 工具2: Architecture Overview模板
- **路径**: 参考上面的"输出格式"章节
- **包含**: 系统清单、边界矩阵、依赖图

---

### 工具3: Mermaid图表
**系统上下文图** (C4 Level 1):
```mermaid
graph TD
    User -->|使用| System
    System -->|调用| External
```

**系统依赖图**:
```mermaid
graph LR
    A[System A] --> B[System B]
    B --> C[System C]
```

---

## 💡 常见场景与模式

### 场景1: 简单的Web应用
**特征**: 前端 + 后端 + 数据库

**推荐拆分**:
- Frontend System (React)
- Backend API System (FastAPI)
- Database System (PostgreSQL)

**总计**: 3个系统

---

### 场景2: 带AI功能的Web应用
**特征**: 前端 + 后端 + 数据库 + AI Agent

**推荐拆分**:
- Frontend System
- Backend API System
- Agent System (LangGraph)
- Database System

**总计**: 4个系统

---

### 场景3: 复杂的企业应用
**特征**: 多端 + 后端 + 数据库 + 搜索 + 队列

**推荐拆分**:
- Web Frontend System
- Mobile System
- Backend API System
- Database System
- Search System (Elasticsearch)
- Worker System (Celery)

**总计**: 6个系统

---

## 📊 质量检查清单

完成Architecture Overview后，使用此清单自检：

### 系统数量
- [ ] 系统数量 3-10 个（通常范围）
- [ ] 没有过度拆分（每个功能一个系统）
- [ ] 没有过度聚合（所有功能一个系统）

### 系统边界
- [ ] 每个系统有清晰的输入输出定义
- [ ] 每个系统的职责明确且单一
- [ ] 系统之间没有职责重叠

### 依赖关系
- [ ] 无循环依赖
- [ ] 依赖关系清晰可视化（Mermaid图）
- [ ] 每个系统的依赖 < 5个（避免过度耦合）

### 文档完整性
- [ ] 有系统上下文图 (C4 Level 1)
- [ ] 每个系统有详细的清单条目
- [ ] 有系统边界矩阵
- [ ] 有系统依赖图
- [ ] 有拆分原则与理由说明

---

## 🚀 快速上手示例

**任务**: 为一个Todo应用拆解系统

**Step 1: 应用6维度框架**
- 用户接触点: Web界面
- 数据存储: PostgreSQL
- 业务逻辑: FastAPI后端
- 外部集成: 无
- 部署单元: 前端CDN, 后端容器
- 技术栈: React, Python, PostgreSQL

**Step 2: 识别系统**
- Frontend System (React)
- Backend API System (FastAPI)
- Database System (PostgreSQL)

**Step 3: 定义边界**
- Frontend: 输入用户操作 → 输出API请求
- Backend: 输入HTTP请求 → 输出JSON响应
- Database: 输入SQL查询 → 输出数据

**Step 4: 绘制依赖图**
```
Frontend → Backend → Database
```

**Step 5: 产出Architecture Overview**
使用模板填充内容 → 保存到 `genesis/v{N}/02_ARCHITECTURE_OVERVIEW.md`

---

**记住**: 好的系统拆解是平衡的艺术。  
不要过度拆分（微服务陷阱），也不要过度聚合（大泥球）。

Happy Architecting! 🏗️