arc-design

架构设计 (arc-design)

能力边界

• 能做: 架构风格选型、模块划分、接口契约定义、数据模型设计、系统上下文建模
• 不做: 需求分析（req-analysis）、UI 设计（ui-design）、代码实现（implementer/TDD）

输入规范

• PRD功能需求(F-{NNN}列表)
• PRD非功能需求
• 技术选型结果(来自tech-eval)

输出规范

• 架构概览(风格 + 系统上下文图)
• 模块划分(M-{NNN})，每个模块映射PRD功能点
• 接口契约(API-{NNN})，完整request/response定义
• 数据模型(E-{NNN})，字段含类型和约束
• 目录结构 + 开发约定

执行流程

语言细则: 根据 framework.json project.languages，按需载入本 skill references/lang-<lang>.md（仅 active 语言，逐个 Read），获取对应语言的技术选型细则（包/依赖管理、框架选项、并发模型、构建产物形态）。project.languages 为空或未配置时跳过 lang-detail 载入，按语言无关原则做架构决策。

可选前置: Grill 深度澄清

触发与启用协议见 design-grill §启用门（项目偏好或阶段入口一次询问；询问不等于启用，用户明确接受后调用 design-grill arch [范围]）。未启用即以 research user-interview 做普通澄清。Grill 发现会改变系统边界、数据含义、权限模型或核心流程的 PRD 缺口时，交回 req-analysis 澄清，不以技术假设填补；总结返回后再进入 Step 1。

Step 1: 需求分析与架构决策 (对应ARCH §1)

• 通过 cataforge context read prd#§2（功能需求）/ prd#§3（非功能需求）按需分章节加载
• §1.1 确定项目类型: fullstack | backend-only | CLI | API-only (此决定影响orchestrator是否跳过Phase 3 UI设计)
• §1.2 架构风格选型: 结合tech-eval调研结果 决策标准: 团队规模 / 性能要求 / 部署环境 / 可维护性 不确定时必须通过research skill的user-interview指令向用户确认，不得直接标注[ASSUMPTION]跳过 决策记录: 三要素见 COMMON-RULES §决策记录要求
• §1.3 系统上下文图: Mermaid C4Context 格式(系统边界、外部依赖、用户交互)
• §1.4 技术栈: 每项技术填写(层次 | 技术 | 版本 | 选型理由 | 调研来源)表

Step 2: 模块划分 (对应ARCH §2)

• 从PRD功能点(F-{NNN})推导模块(M-{NNN})
• 每个模块包含:
  • 职责: 单一职责描述
  • 映射功能: F-{NNN}列表(引用PRD)
  • 对外接口: API-{NNN}列表(引用 §3 接口契约)
  • 依赖模块: M-{NNN}列表
  • 内部关键组件: 类/组件列表
• 验证: 所有F-{NNN}至少被一个M-{NNN}覆盖(无遗漏)
• 模块间依赖应为有向无环

Step 3: 接口契约 (对应ARCH §3)

• 为每个对外接口定义API-{NNN}
• 格式使用YAML:

  path: /api/v1/{resource}
  method: POST
  module: M-{NNN}
  request:
    headers: { Authorization: "Bearer {token}" }
    body:
      field1: { type: string, required: true, desc: "{说明}" }
  response:
    200: { schema: "{ResponseType}" }
    400: { schema: "ErrorResponse" }
  

• 必填: request headers + body字段(type + required + desc)
• 必填: response成功码 + 错误码schema

Step 4: 数据模型 (对应ARCH §4)

• 描述实体关系(1:N / M:N / 继承等，Mermaid erDiagram 格式)
• 定义实体E-{NNN}，字段表格(字段 | 类型 | 约束 | 说明)