architecture-design

name	architecture-design
description	在用户要求设计软件架构、撰写架构设计文档、做架构评审，或讨论模块划分/层间依赖/对外API设计时使用此skill。引导按照"整体先行、模块职责明确、易用性优先、模块隔离、依赖倒置"等设计原则自顶向下展开设计，并产出结构化的架构文档。触发场景包括但不限于："帮我设计一下这个SDK/模块的架构"、"写一份架构设计文档"、"这个架构合理吗，帮我评审一下"、"这几个模块该怎么划分职责"、"这个功能该放在哪一层"。既适用于通用软件架构，也适用于iOS/移动端SDK架构（此时会给出更具体的模式建议）。即使用户没有直接说"架构"两个字，只要讨论的是顶层模块拆分、对外接口设计、层间依赖关系，也应主动使用此skill。

架构设计

帮助以自顶向下、原则驱动的方式设计软件架构，并产出结构化的架构文档。这不是一个"填模板"的机械流程——每一步都是为了让最终的架构对使用它的人（无论是调用你API的其他工程师，还是未来维护这段代码的自己）尽可能友好、稳固、不易腐化。

硬性要求：架构图和类图不能省略

任何一份架构文档，必须包含一张整体架构图（第 2 步产出）和至少一张核心模块的类图（第 4 步产出），用 mermaid 的 graph/flowchart 和 classDiagram 表示。文字描述模块关系或类关系时非常容易含糊带过——"A 依赖 B 的抽象接口"这句话读起来通顺，但只有画出图才能立刻暴露出这句话背后到底有没有想清楚。

这两张图是产出物的一部分，不是"如果篇幅允许就加上"的锦上添花。写完文档后，在交付前自查一遍：这份文档里有没有整体架构图？关键模块有没有类图？ 如果没有，说明设计流程还没走完，不要跳过图直接把文字部分交出去。做架构评审（而非从零设计）时同样适用——评审意见里如果指出了模块关系问题，也应该用图把问题点画出来，而不是只用文字描述。

为什么要自顶向下

架构设计最容易踩的坑，是过早陷入某个模块内部的实现细节，还没想清楚模块之间该怎么划分职责，就已经在纠结某个类该用什么设计模式了。这样做出来的架构往往是"拼凑"出来的——模块边界模糊、职责重叠、后期改一个模块要牵连一堆其他模块。

所以设计顺序应该是：先定整体骨架，再填模块细节。具体来说，遵循下面四步，不要跳步：

1. 明确整体架构范围与约束 —— 不了解使用场景和边界，任何架构决策都是猜测
2. 整体架构总览 —— 划分模块、明确每个模块"是干什么的"（一句话概括职责，不涉及内部实现）
3. 模块间依赖关系 —— 谁依赖谁，是否存在循环依赖或不合理的耦合
4. 关键模块详细设计 —— 只对核心/复杂模块展开内部设计，边缘模块无需展开

第一步：明确设计范围（先问，别猜）

在动笔画架构之前，向用户确认（如果对话里已经提到了，就不用重复问）：

• 这个架构服务于谁？上层调用者是谁（是应用层开发者？是SDK的接入方？还是团队内其他模块）？
• 现有的技术约束是什么（语言、平台、必须复用的现有模块、性能/包体积限制）？
• 大概的功能边界在哪里？哪些明确不做？
• 是全新设计，还是在现有架构上做调整/评审？

如果用户已经在需求里给出了这些信息，不要机械地重复提问——直接进入设计，把你的理解简要复述一遍作为确认即可。

第二步：整体架构总览

先不要展开任何模块的内部实现，只做三件事：

1. 划分模块：按职责边界拆出顶层模块（不是按"文件"或"类"拆，而是按"这块东西负责做什么事"拆）
2. ：如果一句话说不清楚，说明这个模块的边界还不够清晰，需要重新划分