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}，字段表格(字段 | 类型 | 约束 | 说明)

Step 5: 非功能架构 (对应ARCH §5)

• §5.1 性能方案: 缓存策略 / 异步处理 / 分页方案
• §5.2 安全方案: 认证机制 / 授权模型 / 数据加密
• §5.3 错误处理: 错误码体系 / 重试策略 / 降级方案
• §5.4 配置管理: 环境变量清单 / 配置文件格式与加载策略 / 敏感信息(secrets)处理方式。所有可变参数须外部化，禁止硬编码在文档或代码中。本节定义配置形态决策；实际 CI/CD 配置文件生成由 deploy-config 负责
• 对应PRD§3非功能需求逐项给出架构级方案

Step 6: 目录结构与开发约定 (对应ARCH §6-§7)

• §6 目录结构: 按模块划分目录树(text格式)
• §7.1 命名规范: 文件/变量/接口命名规则
• §7.2 代码风格: Lint/格式化工具配置
• §7.3 Git约定: 分支策略/Commit格式
• 经 context generate 分支 authoring 落图后 finalize 交付 ARCH（操作细节见 context skill）

Anti-Patterns

• 禁止: 在 ARCH 主卷塞入实现细节代码 —— ARCH 写接口契约 / 数据流 / 模块边界；实现归 implementer 的 src/，越界让两层职责粘连
• 禁止: 跳过 §5.4 配置管理章节 —— 没有配置形态决策（环境变量清单 / 加载策略 / secrets 处理）的 ARCH 让 deploy-config 与 devops 无据可依，下游断链
• 禁止: 模块划分循环依赖 —— ARCH 阶段的依赖图必须是 DAG；循环会让 tech-lead 任务拆解无起点
• 避免: 把多个候选方案并列写在 ARCH 正文 —— 终态决策入 ARCH，候选讨论进 research-note 或 decision-log

效率策略

• 功能→模块映射确保无遗漏
• 接口先于实现，契约驱动
• 执行流程各Step与ARCH模板§1-§7一一对应，减少模板填充时的二次整理