# Arc Design

> 架构设计 — 模块划分、接口定义、数据模型、系统架构建模。当 PRD 完成、需要做架构风格选型、模块划分、接口契约或数据模型设计时使用此 skill。本 skill 不做需求分析（req-analysis）与 UI 设计（ui-design）。

- Skill: `lync-cyber/arc-design` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add lync-cyber/arc-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lync-cyber/arc-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: lync-cyber (https://skillmd.com/u/lync-cyber)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lync-cyber/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:
  ```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一一对应，减少模板填充时的二次整理