---
name: architecture-design
description: 将需求、原型或明确技术问题转为完整的系统设计，默认交付含可见图示的 HTML。比较可行方案并由用户决定关键取舍，再完成整体与必要专项设计、风险验证和一致性复核；复杂专项可委派子 agent。适用于系统设计、技术方案、接口或数据模型设计及方案评审；不实施生产代码或部署，不做全仓架构机会扫描。
user-invocable: true
---

# 统一架构设计

## 职责与输入

承担本次范围内系统设计的完整性责任，确定跨模块规则、关键技术路线及可行性，使使用者不必重新补定共享契约和数据语义；普通函数组织等局部实现不预先限定。

独立使用需求、PRD、原型、已有方案或工程事实，不要求固定前置文档／技能，也不指定或调用下一技能。单端任务不凭空增加另一端；评审已有方案时聚焦相关问题，不重做无关设计。

只交付设计，可给契约、Schema、迁移草案和关键伪代码；不写生产实现、执行数据库变更、调整版本或发布。单纯解释概念、绘制已有架构或按已定方案编码不启动完整流程。

## 1. 建立依据与约束

按需读取项目指令、相关需求、原型、契约、ADR、规范和受影响实现／测试；使用 Wiki 时按项目约定检查新鲜度。关键字段、兼容性与约束核对真实来源，不把文档或代码现状自动当成正确需求。

区分事实、设计建议和假设；数据库设计比较可取得的迁移与实际 Schema，没有连接则标明环境未核实。按 [质量目标与风险验证](references/quality-validation.md) 识别决定架构的关键场景，不编造性能、容量或部署事实。

只追问会影响业务规则、边界、兼容性或关键取舍的缺口，可继续独立部分；材料充分不等于用户已经选择技术路线。

## 2. 比较方案，与用户确定方向

按 [方案比较与决策](references/decisions.md) 展示真实可行方案的优缺点、成本、风险与推荐依据，由用户决定重大取舍。用户选择前只推进独立取证或候选探索，不沿推荐项定稿或深化依赖部分；已有明确选择／限定授权直接沿用，不重复确认。

## 3. 形成整体方案并验证风险

在已确认或授权的方向内，按 [整体方案要点](references/overall-design.md) 建立统一基线，说明目标范围、模块边界、关键流程、数据归属、共享契约、主要取舍与依赖。整体初稿不代表设计完成。

有原型时建立“页面／操作／状态 → 技术支撑”对应，区分服务端数据、输入、派生值和纯展示状态，不机械把全部字段放入 API；核对所有受影响消费者的兼容性。没有网络接口时用真实模块或文件边界，不强造 REST API。

按 [图示方法](references/diagrams.md) 提供适用的架构、流程、ER 等图；用户指定的图不能无说明省略。按质量验证方法消减“不成立就会推翻路线”的假设，必要时修订整体方案或重新讨论选择，不能只标“未验证”就承诺可实施。

## 4. 深化与委派

按 [专项设计要点](references/specialist-design.md) 完成本次涉及的前端、后端或其他设计；裁剪无关内容，不把关键契约、数据或一致性决策留给使用者临场决定。

小型／单端任务自行完成。复杂且相对独立的专项按 [设计委派协议](references/delegation.md) 实际派发并等待子 agent；主 Agent 持有整体基线和共享契约。未解决依赖、同文件写入或共享产物冲突时不并行；无工具则自行处理，无名额可串行委派并说明。

## 5. 集成与完整性复核

主 Agent 核对证据并整合专项，检查需求、契约、图示、质量／失败场景、用户决策和验收相容，不能只拼接报告。专项提出契约变化时核对影响，触及重大取舍先与用户讨论，再同步基线及受影响结果。

按 [方案完整度与使用说明](references/handoff.md) 完成准备检查，区分草案、可实施、局部可实施与受阻；设计状态、用户选择和实施授权分别记录。未解决冲突或部分完成不能称为完整可实施。

## 6. HTML 交付与修订

按 [HTML 设计文档](references/html-delivery.md) 默认生成实际的 `spec.html`，完整保留方案、可见图示、适用范围和开放问题；专题较多时由统一入口导航，不重复维护 Markdown 正本。正式候选材料同样用 HTML，状态保持待决定；对话只给链接和关键摘要。

优先用户位置或项目约定，已有需求目录时可同目录保存；无约定用目标项目 `docs/design/YYYY-MM-DD-主题/spec.html`。项目未定时用本任务可写产物目录，不写技能安装目录。用户明确格式／对话草稿要求及既有正本约定优先，不擅自搬迁。

交付后结束，由用户决定如何使用。后续要求修订时核对新证据，同步受影响的决定、契约、图示和状态；重大取舍仍与用户讨论，不要求经由固定流程返回。