架构设计技能

何时使用

• •新建项目时：根据需求文档进行正向架构设计
• •变更开发时：在代码理解输出的逆向设计书基础上做增量架构设计
• •需要进行模块划分、接口定义、技术选型时

输出格式

• •架构文档：按 process_templates/architecture.md 模板（必须包含 Mermaid/PlantUML 图表）
• •接口定义：按 process_templates/interfaces.json 格式
• •设计评审：按 process_templates/design_review.md 模板

输出规范

架构文档必须包含以下章节，缺少任何必填章节则视为不完整：

设计步骤

1. 约束分析

• •技术约束（语言、框架、平台）
• •性能约束（响应时间、吞吐量）
• •安全约束（认证、加密、合规）
• •部署约束（单机、容器、云原生）

2. 模块划分

• •按职责单一原则划分模块
• •每个模块包含：名称、职责、对外接口
• •模块间低耦合、模块内高内聚
• •明确模块间的依赖方向（禁止循环依赖）

3. 接口定义

按以下格式输出到 interfaces.json：

{
  "from": "模块A",
  "to": "模块B",
  "contract": "接口名称",
  "method": "GET/POST/调用方式",
  "input": "输入格式",
  "output": "输出格式",
  "error": "错误响应格式"
}

4. 技术选型

• •列出候选方案与对比（至少 2 个候选）
• •从性能、生态、团队熟悉度、维护成本 4 个维度评估
• •给出推荐方案与理由

5. 架构图表

根据项目特征选择需要的图表类型，使用 Mermaid 语法嵌入到 architecture.md 中。

5.1 架构块图（所有项目必选）

展示系统整体结构和模块关系：

graph TB
    A[客户端] --> B[API层]
    B --> C[服务层]
    C --> D[数据层]

5.2 时序图（有异步/多模块协作时必选）

展示关键业务流程的模块间交互：

sequenceDiagram
    participant C as 客户端
    participant A as API层
    participant S as 服务层
    C->>A: 请求
    A->>S: 处理
    S-->>A: 响应
    A-->>C: 返回

5.3 类图（面向对象设计时必选）

展示核心类及关系：

classDiagram
    class Service {
        +method()
    }
    class Repository {
        +query()
    }
    Service --> Repository

5.4 流程图（复杂业务逻辑时必选）

展示决策分支和处理流程：

flowchart TD
    A[开始] --> B{条件判断}
    B -->|是| C[处理A]
    B -->|否| D[处理B]
    C --> E[结束]
    D --> E

5.5 数据流图（数据管道场景推荐）

graph LR
    A[数据源] -->|读取| B[处理模块]
    B -->|转换| C[存储模块]
    C -->|输出| D[消费者]

5.6 部署图（多服务部署推荐）

graph TB
    subgraph 生产环境
        A[负载均衡] --> B[应用服务器]
        B --> C[数据库]
    end

6. 图表选择矩阵

根据项目类型快速判断需要哪些图：

7. 设计自评审

输出设计前，按以下清单自检：

• • 所有需求的功能点均有对应模块承载
• • 模块间无循环依赖
• • 接口定义完整（输入、输出、错误）
• • 架构块图已包含所有模块
• • 按需图表已补充（时序图、类图、流程图等）
• • 非功能需求有对应的技术方案
• • 技术风险已标注

评审通过后输出 design_review.md，设置 workflow_state.json 的 status: approved。 评审不通过时，记录问题并重新修改设计，不得跳过。

逆向模式指导（change-project）

当接收到 code-understanding 技能输出的逆向分析结果时：

1. •将逆向分析的模块清单作为架构设计的基线
2. •在基线架构上标注需要变更的模块（新增/修改/删除）
3. •评估变更对现有模块的影响范围
4. •更新架构图中受影响的部分
5. •在 architecture.md 中标注 mode: update，说明变更前后的差异