| name | architect-doc |
| description | 技术架构设计 Skill。根据产品需求文档（PRD）设计完整的技术架构方案，输出结构化的架构设计文档。覆盖技术栈选型、系统架构、数据模型、API 设计、部署方案、非功能需求、安全设计等。触发条件：(1) 设计技术架构，(2) 从 PRD 推导技术方案，(3) 系统设计/技术选型，(4) 数据库设计，(5) API 设计，(6) 部署架构设计。 |
技术架构设计 Skill
根据 PRD 或产品需求描述，生成结构化的技术架构设计文档。
参考文件
按需加载 references/ 目录下的模板文件：
外部 Skill 依赖
架构设计过程中可能需要加载以下 Skill 的参考资料：
| Skill | 路径 | 何时加载 |
|---|
microservices | .agents/skills/microservices/ | 当架构选择微服务风格时，加载 references/development.md 获取服务拆分和通信规范 |
feishu-docs | .agents/skills/feishu-docs/ | 用户要求将架构文档同步到飞书时 |
github-publish | .agents/skills/github-publish/ | 用户要求提交架构文档到 GitHub 时 |
requirement-to-issues | .agents/skills/requirement-to-issues/ | 用户要求将架构模块拆分为 GitHub Issues 时 |
工作流
架构设计（主流程）
-
加载主模板 — 读取 references/architecture-template.md
-
判断 PRD 是否模块化：
- 检查 PRD 同级目录下是否存在
modules/ 目录
- 检查
modules/ 下是否存在 prd-{module_en_slug}.md
- 若存在，则进入模块化架构模式：主架构文档 + 模块级架构文档是默认产物
- 若不存在，则进入单文档架构模式：仅输出主架构文档
-
判断主架构文档模式：
- 分文档模式触发条件（满足任一）：用户明确说"拆分文档"、"分文档"、"前端架构文档"、"后端服务文档"、"数据库设计文档"；或项目规模为中大型（功能模块 ≥5 个 或 API 端点 ≥15 个）
- 单文档模式：默认模式，所有主架构内容写入主架构文档
- 若为分文档模式，额外加载
references/frontend-architecture-template.md、references/backend-services-template.md、references/database-design-template.md
- 即使启用分文档模式，模块级架构仍保持“一模块一文档”，不继续拆成模块前端/后端/数据库子文档
-
解读 PRD：
- 提取业务目标、用户画像、功能需求（P0/P1/P2）、非功能需求、技术约束
- 记录 PRD 文档头的精确版本号（如
v1.0.0），用于填充架构文档头
- 同时搜索
docs/ 目录下已有的 architecture-*.md，如存在则作为迭代基线
- 若为模块化模式，逐个读取 Module PRD，提取模块边界、依赖关系、用户故事、验收标准
-
分析原型图（如存在） — 在 PRD 同级目录查找 wireframes/ 和 hifi-wireframes/，按类型区分分析深度：
- 低保真 wireframes/：提取页面清单、导航结构、信息架构、基础交互流程
- 高保真 hifi-wireframes/：在低保真基础上额外提取设计系统（CSS 变量/主题色/组件库）、交互动效（动画/过渡）、响应式断点、数据展示需求（图表/数据表格/搜索筛选）
- 输出前端复杂度评级（低/中/高）和核心交互模式清单
- 若为模块化模式，将页面与交互按
module_en_slug 归类，为模块级架构提供输入
-
MVP 规模校准 — 根据 PRD 目标用户量和业务定位，确定架构复杂度等级，避免过度设计：
| 规模等级 | 判定条件 | 推荐架构风格 | 约束 |
|---|
| L1（轻量级） | 目标 DAU ≤ 1K 或 MVP 验证阶段 或 功能模块 ≤ 3 | 单体应用（Monolith） | 禁用微服务、K8s；优先 SQLite/PostgreSQL 单库；部署用单容器或 PaaS |
| L2（标准级） | 目标 DAU 1K-50K 且功能模块 4-8 | 模块化单体（Modular Monolith） | 可用消息队列但不拆服务；单库或读写分离；部署用 Docker Compose 或托管服务 |
| L3（复杂级） | 目标 DAU > 50K 或 功能模块 > 8 或 有明确的多团队并行开发需求 | 微服务（Microservices） | 可使用 K8s、服务网格、分库分表；需论证拆分必要性 |
校准规则：
- 从 PRD §1（项目背景）和 §8（里程碑）提取目标用户量和阶段定位
- 若 PRD 未明确目标用户量，主动向用户追问，不默认选择 L3
- 若选择的架构风格超出规模等级推荐，必须在 §11.2（架构决策记录 / ADR）中记录「超规模选型理由」
- 在架构文档头新增
规模等级: L1/L2/L3 字段，供 Gate 2 评审核验
-
评估架构风格 — 根据规模校准结果和业务需求选择单体 / 微服务 / Serverless / 混合架构
-
技术栈选型 — 前端、后端、数据库、缓存、消息队列、搜索、AI/ML、DevOps，每项附选型理由
-
设计主架构总纲：
- 系统架构图（Mermaid）
- 跨模块路由/状态管理/服务通信/公共能力
- 模块职责与依赖总览
- 共享数据模型、部署架构、非功能和安全设计
-
设计模块级架构（仅模块化模式）：
- 读取
references/module-architecture-template.md
- 遍历每个 Module PRD，为每个模块设计数据模型、API、前端组件、服务职责、模块间接口
- 模块级文档只覆盖该模块边界内的详细设计，跨模块约束引用主架构
- 输出文档：
- 始终写入
projects/prd-{项目名}/architecture-{项目名}.md
- 若为模块化模式，额外写入
projects/prd-{项目名}/architecture-{项目名}-{module_en_slug}.md
- 文档头必须包含精确版本号
- 若目标路径已存在文档，则根据变更范围递增版本（Patch: 措辞/格式；Minor: 新增模块/API/调整部署；Major: 架构风格变更/核心技术栈替换）
- 模块级架构文档独立维护版本；首次创建为
v1.0.0
- 若本次新增或重建模块级架构文档，主架构版本至少 Minor 递增
- 分文档模式额外输出：
projects/prd-{项目名}/frontend-architecture-{项目名}.mdprojects/prd-{项目名}/backend-services-{项目名}.mdprojects/prd-{项目名}/database-design-{项目名}.md
- 主文档 §0 文档索引自动填充各子文档和模块级架构文档路径
- 回填模块 PRD（仅模块化模式）：
- 更新模块 PRD 文档头中的「关联架构文档」字段
- 回填 Module PRD §6.3 技术参考中的数据模型、API 端点、前端组件摘要
- 若批量生成时某个模块失败，继续处理其他模块，并在最终汇总中列出失败模块和原因
manifest 接入（v2 必做）
启动前执行：
node scripts/workflow-manifest.js check {项目} architecture
校验通过后产出主架构 / 模块级架构文档，落盘后写入：
echo '{
"agent": "architect",
"doc": "projects/prd-{项目}/architecture-{项目}.md",
"version": "v{X.Y.Z}",
"linked_prd": "v{X.Y.Z}",
"module_arch_count": {N}
}' | node scripts/workflow-manifest.js set {项目} architecture
规范见 docs/workflow-manifest-spec.md。
后续操作
架构文档生成后，可触发后续流程：
- 提交 GitHub: 加载
github-publish Skill
- 同步飞书: 加载
feishu-docs Skill
- 拆分 Issues: 加载
requirement-to-issues Skill；若存在模块级架构文档，优先让下游消费模块级架构
- 部署详设: 加载
microservices Skill 的 references/deployment.md
模块化模式细则
当检测到 projects/prd-{项目名}/modules/ 目录时，以下规则默认生效：
- 输出结构固定：
- 主架构：
projects/prd-{项目名}/architecture-{项目名}.md
- 模块架构：
projects/prd-{项目名}/architecture-{项目名}-{module_en_slug}.md
- 主从职责分离：
- 主架构负责跨模块技术栈、公共能力、共享数据、部署、安全、运维
- 模块架构负责模块数据模型、API、前端组件、服务职责、上下游接口
- 批量生成顺序：
- 先生成或更新主架构
- 再按模块遍历生成模块级架构
- 若模块存在显式依赖，优先生成被依赖模块；无法判断时按文件名排序遍历
- 错误处理：
- 单个模块失败不阻断其他模块生成
- 结束时输出成功模块、失败模块和待人工补充项
- 回填要求：
- Module PRD 文档头的「关联架构文档」必须指向实际模块架构文件
- Module PRD §6.3 必须回填数据模型、API 端点、前端组件摘要
- 模块架构 §5.2 集成与契约测试设计为必填
- 版本管理：
- 模块文档独立版本化，首次为
v1.0.0
- 主架构新增模块级架构时至少 Minor 递增
- 模块文档头必须包含「关联 Module PRD」和「关联主架构文档」
快速参考
架构风格选择矩阵
| 评估维度 | 权重 | 单体架构 | 微服务架构 | Serverless | 混合架构 |
|---|
| 团队规模 | 20% | ≤5人 ✅ | >10人 ✅ | 不限 | 5-15人 ✅ |
| 交付时间 | 15% | 快 ✅ | 慢 | 中 | 中 |
| 弹性需求 | 15% | 低 | 中 | 高 ✅ | 中 |
| 运维复杂度 | 15% | 低 ✅ | 高 | 中 | 中 |
| 独立部署 | 15% | 不支持 | 支持 ✅ | 支持 ✅ | 部分支持 |
| 技术异构性 | 10% | 不支持 | 支持 ✅ | 支持 | 部分支持 |
| 成本（初期） | 10% | 低 ✅ | 高 | 按用量 | 中 |
快速判断：MVP/小团队→单体 | 多团队/独立部署→微服务 | 事件驱动/高弹性→Serverless | 渐进演进→混合
文档质量检查清单
必检项（所有项目必须通过）：
条件检项（满足条件时必须通过）：
