| name | arc-design |
| description | 架构设计 — 模块划分、接口定义、数据模型、系统架构建模。当 PRD 完成、需要做架构风格选型、模块划分、接口契约或数据模型设计时使用此 skill。本 skill 不做需求分析（req-analysis）与 UI 设计（ui-design）。 |
| argument-hint | <PRD文档路径或功能需求描述> |
| suggested-tools | file_read, file_write, file_edit, file_glob, file_grep, shell_exec |
| depends | ["context","tech-eval","research","design-grill"] |
| disable-model-invocation | false |
| user-invocable | true |
架构设计 (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一一对应，减少模板填充时的二次整理
