system-design

name	system-design
description	系统架构决策与设计文档：Design Doc（含 Alternatives Considered 强制段）、ADR、结构影响分析。用于多模块、存量系统改造、共享边界、高风险集成、重大技术选型。不管前端技术栈和视觉表达（那是 frontend-design-research 的事）。

系统架构决策

技能定位

本技能处理"系统怎么切"的问题：模块边界、数据流向、存储选型、API 契约、依赖拓扑、扩展点。

核心方法论：Alternatives Considered 强制 + trade-off 诚实。没有 alternatives 段的 Design Doc 是推销文档，不是设计文档。

何时进入

• 多模块项目或跨模块改造
• 存量系统新增模块（需评估是否破坏现有边界）
• 高风险集成（第三方服务、跨团队 API）
• 重大技术选型（数据库、消息队列、部署架构）
• req-suite:project-spec 路由过来

何时不进入

• 前端技术栈选型（Next.js/Vite/状态管理）→ frontend-design-research
• 视觉/动效/组件库 → frontend-design-research
• 纯 UI 项目无后端 → 不需要本 skill
• 单模块小项目、local-light 模式 → 不需要本 skill

前置输入

从 req-suite:project-spec 获取：

• knowledge/product-specs/PRODUCT-BRIEF.md（目标结果 + 非目标）
• knowledge/references/research-*.md（调研结果，如有）
• 选择题清单中和架构相关的 🟡/🔴 项

核心流程

1. 结构影响分析 → 2. Design Doc / ADR → 3. 更新 ARCHITECTURE.md

步骤 1：结构影响分析

回答这些问题：

• 这次变化涉及哪些模块？
• 有没有模块不该碰（boundary violation）？
• 数据流方向是什么？有没有循环依赖？
• 失败模式是什么？一个模块挂了会影响什么？
• 有没有共享状态需要加锁/同步？

步骤 2：写 Design Doc 或 ADR

根据决策规模选用：

大 Design Doc（重要方案决策）

核心段（按社区最佳实践）：

段	写什么	质量标准
Context	背景事实 + 相关链接，不写观点	3-5 行，读完知道为什么在讨论这件事
Goals / Non-goals	要达成什么、明确不追求什么	可验证的 bullet 列表
Proposed Design	方案概述 + 关键架构图	Agent 读完能开始实现
Alternatives Considered	考虑过的其他方案 + 每个的 trade-off	这是核心。没有这段的 doc 是推销文档
Risks & Mitigations	已知风险和应对	每条 risk 有对应 mitigation
Success Criteria	怎么判断方案成功	可测量、可验证

规模：1-3 页小方案，5-10 页大方案。超过 10 页说明该拆。

产出写入 knowledge/design-docs/DESIGN-DOC-[标题].md。

小 ADR（单个决策记录）

适用于具体技术选择、配置决策、依赖选型。

# ADR-NNN: [决策标题]

## Status
Proposed | Accepted | Superseded by ADR-NNN | Deprecated

## Context
[驱动这个决策的背景力量、约束、需求]

## Decision
[选了什么、怎么做]

## Consequences
[好的后果 + 坏的后果 + trade-off]

一个文件一个决策，不合并。不修改已 Accepted 的 ADR，用新 ADR 替代。

产出写入 knowledge/design-docs/ADR-NNN-[标题].md。

步骤 3：更新 ARCHITECTURE.md

将稳定的结构事实写入项目根的 ARCHITECTURE.md（不是 knowledge/ 下的）：模块拓扑、关键依赖、数据流向。只写事实，不写决策理由（理由住在 Design Doc / ADR 里）。

与 frontend-design-research 的边界

两个 skill 是正交子域，不是上下层：

本 skill 管	frontend-design-research 管
模块边界、数据流、存储、API 契约	主语言、参考案例、动效采访、视觉 token
依赖拓扑、扩展点	前端技术栈（框架/路由/状态/构建）
跨层集成协议	组件库路由、动效资产库

边界冲突裁决：

• 前端技术栈（Next.js/Vite 等）→ 归 frontend-design-research（和视觉/动效紧密耦合）
• API 契约 → 归本 skill（跨层协议）
• 全栈项目先跑本 skill 定系统骨架，再跑 frontend-design-research 定前端表达

知识库路由

触发	知识库条目	路径
结构影响分析	架构分层思考框架	~/note/01-AI工程/项目方案方法/架构分层思考框架.md
多方案对比	方案对比指南	~/note/01-AI工程/项目方案方法/方案对比指南.md
上游方法论	req-project-spec 方法论	~/note/01-AI工程/Agent系统/方法/02-需求与项目方案/从需求到项目方案：req-project-spec 方法论.md