用途
devdocs-system-design 用于基于需求文档创建或更新系统设计文档，支持初始设计和增量设计两种模式。它面向需要系统/技术设计、架构或 API 设计的场景，以及新功能加入、优化建议确认或技术改进后需要设计变更的场景。
主要能力
- 自动检测设计模式：检查 02-system-design.md 是否存在，不存在则进入初始设计模式，存在则进入增量设计模式，并检查是否有新增需求（F-XXX）未覆盖。
- 初始设计：读取需求、询问偏好、探索代码、按需进行外部研究，进入 Plan 模式呈现技术选型、架构方向、模块划分，用户审批后生成设计文档。
- 增量设计：识别变更来源（新功能 F-XXX、优化建议 INS-XXX、技术改进），进行影响分析与兼容性评估，进入 Plan 模式呈现影响范围、变更策略、迁移方案，审批后更新文档并生成变更记录。
- 设计前外部研究：当涉及不熟悉技术或复杂集成时，扫描现有代码模式与 docs/devdocs/patterns/、查阅官方文档、搜索最佳实践，并将研究结论写入设计文档。
- 文档拆分：当文档超过 300 行、模块超过 5 个或 API 接口超过 10 个时，拆分为主文档、API 设计文档和数据模型文档。
- 子 Agent 摘要：作为子 Agent 运行时返回结构化摘要，包含模式、新增模块、接口、数据模型、破坏性变更等字段。
使用方式
运行命令：
- /devdocs-system-design → 自动检测模式（初始/增量）
- /devdocs-system-design --fast → 跳过 Plan 模式，使用合理默认值，仅最终确认
前置条件：需求文档 docs/devdocs/01-requirements.md，如不存在建议先运行 /devdocs-requirements。
设计前必问：必须使用 AskUserQuestion 询问技术栈偏好、目标平台、部署环境、现有系统集成。
输出文件：主文件 docs/devdocs/02-system-design.md，按需拆分为 02-system-design-api.md 和 02-system-design-data.md。
适用场景
- 用户已完成需求文档，项目无系统设计。
- 用户要求系统/技术设计、架构或 API 设计。
- 新功能加入后需要设计变更（来自 /devdocs-feature）。
- 优化建议确认后需要设计调整（来自 /devdocs-insights）。
- 技术改进需要架构调整。
- 用户要求更新/修改现有设计。
限制
- 本技能仅产出文档，严禁编写或生成任何实现代码（源代码、脚本、配置变更）。
- Write 工具仅用于写入 docs/devdocs/ 下的 Markdown 文档。
- “核心接口”章节仅定义签名，严禁包含实现逻辑。
- 编码实现由 /devdocs-dev-workflow 负责，本技能不涉及。
- 增量设计前必须进行影响分析，必须评估向后兼容性，破坏性变更必须标注处理方式。
- 涉及不熟悉技术且有外部检索工具时，应在 Plan 模式前完成外部研究；无外部工具时基于现有代码模式扫描和用户输入进行研究。
- --fast 模式跳过研究步骤。
- 遵循 MTE 原则（可维护性、可测试性、可扩展性），避免过度设计。
- 安全约束：敏感数据不明文存储，需认证的 API 已标注，用户输入有验证，敏感操作有日志记录。
设计原则
- MTE 原则：模块职责单一、依赖清晰；核心逻辑可单元测试、依赖可 Mock；预留扩展点、接口抽象、开闭原则。
- 设计模式选择：根据对象创建、行为扩展、结构组织、状态管理、数据访问等场景选择合适模式，只在必要时使用。
- 设计层次：接口层（薄层）→ 服务层（核心业务逻辑）→ 领域层（实体/值对象）→ 基础设施层（数据访问/外部服务）。
文档结构
目标平台、架构概览（Mermaid）、技术选型、模块设计、核心接口、设计模式、代码结构、数据模型、API 设计、状态流转、异常处理、日志设计、扩展性、需求追溯。
Skill 协作
- /devdocs-feature：新功能触发增量设计。
- /devdocs-insights：洞察确认后触发增量设计。
- /testing-guide：确保核心逻辑可单元测试。
- /code-quality：MTE 原则指导设计。
- /ui-orchestrator：路由到专业的外部 UI/UX Skill。
- /devdocs-retrofit：从现有代码逆向提取接口定义并同步到设计文档。
下一步
初始设计后，建议运行 /devdocs-test-cases 进入测试用例设计阶段。增量设计后，如有新增功能点运行 /devdocs-test-cases 补充测试用例；如有数据模型变更准备数据库迁移脚本；如有破坏性变更通知相关依赖方。文档变更较大时，建议运行 /agent-memory 同步记忆文件。