用途
system-design 用于基于需求文档创建或更新 keel 技术设计文档，覆盖架构、接口、数据模型与变更影响。它扮演系统架构师角色，关注技术取舍、模块边界、接口契约与可扩展性，回避用户故事细节、产品优先级排序以及 UI 视觉与交互实现。其判断倾向是优先简单方案，复杂度需有明确理由。
该技能不适合在需求尚未编写时使用（应先运行 /requirements），也不适合处理 UI 设计（应使用 ui-orchestrator）。
主要能力
- 初始设计：自顶向下按 L1 架构层、L2 模块层、L3 接口行为层、L4 数据模型层分层推进，生成系统设计文档。
- 增量设计：针对新功能、优化建议或技术改进，进行变更范围分类、影响分析与兼容性评估，更新设计文档并追加 ADR 记录。
- 对抗性审查：按复杂度分级触发 SOLID+LoD 原则校验，审查结论写入文档。
- 设计前外部研究：当涉及不熟悉技术或复杂集成时，扫描现有代码模式、查阅官方文档、总结最佳实践，并将研究结论写入设计文档。
- 文档拆分：当文档超过 300 行、模块超过 5 个或 API 超过 10 个时，可拆分为主文档、API 设计文档与数据模型文档。
- Realign 模式：当 system-design 规范升级后，对已有设计文档按新规范查漏补缺。
使用方式
常见命令：
/system-design：自动检测初始或增量模式。/system-design --realign：规范升级回扫，按新 spec_version 查漏补缺。/system-design --realign=<scope>：限定范围，如 layer1/layer2/layer3/layer4 或具体章节名。
初始设计流程：读取需求文档 → 询问技术栈、平台、集成偏好 → 探索代码 → 按需外部研究 → 自顶向下分层设计 → 对抗性审查 → 生成 docs/devdocs/02-system-design.md → 验证功能点覆盖 → 有岔路则拍板后定稿。
增量设计流程：读取现有设计 → 识别变更来源 → 影响分析 → 兼容性评估 → 呈现变更方案与对抗性审查 → 用户确认 → 更新文档 → 追加变更记录。
设计前必问：技术栈偏好、目标平台、部署环境、是否需要与现有系统集成。
输出文件：主文件为 docs/devdocs/02-system-design.md，可按需拆分为 02-system-design-api.md 和 02-system-design-data.md。
适用场景
- 用户已完成需求文档，需要创建系统或技术设计。
- 需要架构或 API 设计。
- 新功能加入后需要设计变更。
- 优化建议确认后需要设计调整。
- 技术改进需要架构调整。
- 需要更新或修改现有设计。
限制
- 文档阶段不得产出实现代码，核心接口章节仅定义签名和行为契约，严禁包含实现逻辑。
- 接口契约内不得出现算法细化、内部状态、控制流、伪代码等越界内容。
- 跨模块依赖时，模块表依赖接口引用列不得出现具体实现类名或裸模块名。
- 增量设计不得仅追加 ADR 而正文相关章节未更新。
- 生成或更新文档必须在顶部写入 generated_by / spec_version / generated_at 三字段 YAML frontmatter。
- 必须先询问用户技术栈偏好和目标平台。
- 必须指定目标平台和最低版本要求。
- API 设计必须包含请求/响应示例。
- 数据模型必须考虑索引和查询模式。
- 必须识别与现有系统的集成点。
- 优先使用项目现有技术栈。
- 不为未来可能的需求设计，只为当前需求设计。
- 不创建只有一个实现的接口，除非为了可测试性或跨模块边界。
- 敏感数据不明文存储，需要认证的 API 已标注，用户输入有验证，敏感操作有日志记录。
- 涉及不熟悉技术且有外部检索工具时，应在方案确认前完成外部研究，研究结论必须写入设计文档。
- 初始设计存在岔路时必须展示方向选择并等待用户拍板，无岔路时直接产出。
- 增量设计必须进行影响分析、向后兼容性评估与变更范围分类。
与其他技能协作
- /feature：新功能触发增量设计。
- /insights：洞察确认后触发增量设计。
- /testing-guide：确保核心逻辑可单元测试。
- /code-quality：MTE 原则指导设计。
- /ui-orchestrator：路由到专业的外部 UI/UX Skill。
- /codebase-insight：提取现有代码的公开接口清单。
初始设计后建议运行 /test-cases 进入测试用例设计阶段。