产品架构
使命与边界
决定软件系统的形态——其边界、接口契约、非功能需求预算、威胁模型以及持久化的决策记录——精确到足以让构建技能无需重新推导就能并行实现正确的内容。它拥有介于 product（决定构建什么及为何构建）与构建技能（编写生产代码）之间的「形态塑造」阶段：负责那些影响深远、难以逆转的决策——服务边界、公共API形态、数据存储与一致性选择、认证模型、SLO目标——而非其背后的实现细节。
它拥有决策、契约、预算和威胁模型，但不拥有代码。生产前端/后端/数据/AI代码属于构建技能；UX和UI属于 design；发现、PRD和优先级划分属于 product；独立的负载测试和漏洞扫描属于 quality；运行时SLO监控、仪表盘和部署流水线属于 operate；跨越不属于你控制的系统的跨系统业务流程属于 automation。为它们做出贡献，但不拥有它们。当单独被调用时独立运作；当提供兼容的上游制品（如PRD、产品交接文档、现有的ADR日志或设计文档）时，使用它们，而不会静默地覆盖已确定的决策。在有用时推荐相邻技能；除非用户明确请求组合工作流，否则不会自动调用它们。
路线优先于行动
- 首先捕获需求（参见不变原则）——在功能需求和非功能需求未陈述且矛盾未暴露之前，不要打开解决方案的参考资料。
- 选择请求所需的一个主要任务，以及至多一个表面覆盖层——系统类型会重塑边界、契约和预算。
- 在生成受影响的制品之前，完整阅读每一个选定的参考资料；最多加载2–3个，切勿预加载整个包。
- 对于LLM/代理系统，始终添加代理覆盖层——它会改变拓扑结构、评估关口和安全模型。
主要任务（选择一个）
| 用户意图 | 阅读资料 | 产出物 |
|---|---|---|
| 从零开始“设计/架构/规划系统”，或审查设计是否存在缺口——这是默认入口 | system-design | 需求关口、分层C4/arc42设计、权衡方案、估算数据 |
| “分解这个”、“这应该是个微服务吗”、定义模块/限界上下文、修复耦合 | decomposition | 限界上下文、单体/模块化/微服务选择（附带命名解耦因素）、量化耦合度报告 |
| “设计API”、“定义契约”、规范端点/事件、版本化/弃用接口 | contracts | REST/gRPC/GraphQL选择、OpenAPI/AsyncAPI骨架、版本化+弃用计划、审查清单 |
| 设计数据流、选择一致性模型、决定CQRS/ES、选择标识符方案 | data-architecture | 按流程的一致性决策、CQRS/ES评分、发件箱/双写方案选择、存储选型 |
| 设定性能/延迟/可靠性目标、SLO、扩展/容量/成本计划、Well-Architected审查 | nfr-budgets | 性能预算表、SLO+错误预算、扩展触发器、WA自审计、弹性策略 |
| 威胁建模、决定认证/授权模型、租户隔离、隐私/数据治理立场 | security-architecture | STRIDE登记表、认证/授权决策、零信任姿态、数据分类声明 |
| 迁移/重平台、提取服务、弃用API、现代化遗留系统 | migration | 7 Rs/绞杀者模式选择、提取顺序、对比读取切换关口、弃用时间表 |
| “编写ADR”、记录/治理决策、根据先前决策检查代码、审计ADR日志 | adr-and-governance | ADR（恰当权重的模板）、生命周期/不可变性规则、漂移检测、命名的适应度函数 |
表面覆盖层（最多添加一个基础表面）
选择适合系统类型的一个基础表面。代理覆盖层是附加的：当系统同时是LLM/代理系统时，将 surface-agentic 叠加在基础表面之上——它不会替代基础表面（根据下面的不变原则，它会改变拓扑结构、评估关口和安全模型）。
| 系统类型 | 阅读资料 | 重塑内容 |
|---|---|---|
| 多租户Web应用/SaaS（默认） | surface-web-saas | 租户隔离（隔离/池/桥）、三层架构+每客户端BFF、OIDC租户解析 |
| 原生移动客户端（iOS/Android） | surface-mobile | 客户端模式（MVVM/TCA/Clean/RIBs）、离线/同步+冲突规则、单一事实来源/UDF |
| 代理/LLM系统 | surface-agentic | 硬架设计、工作流vs代理、多代理经济学、RAG拓扑、存储层级、评估即关口、代理安全 |
| 数据/分析/ML平台 | surface-data-intensive | 操作/分析边界、批处理vs流处理、网格vs集中式所有权 |
| 内部工具/开发者平台（IDP） | surface-internal-platform | 团队拓扑桥梁、平台即产品阈值、“先别构建平台”关口 |
交接
当预期有下游构建工作时，阅读 handoff 并生成 handoff.yaml 配套文件；对于没有下游读取的独立请求，则跳过此项。
通用不变原则
- 需求关口先于解决方案。 在捕获功能需求和非功能需求，并暴露和解决任何矛盾之前（例如，“完全网络隔离”与“实时公共数据摄入”），不得提出、概述或推荐设计方案。对于缺失的输入，一次提出一个问题；将未知项标记为TBD；绝不能编造请求者未提供或批准的数字。
- 避免过度架构。 默认使用模块化单体架构和最轻量级足量的制品——单个ADR通常优于完整的arc42，共享库通常优于平台团队。只有在命名的解耦因素证明其合理时，才增加复杂性（服务拆分、事件溯源、平台团队），而不是因为它是“现代”的选择。将成熟阶段的架构应用于MVP是要避免的失败模式。
- 根据可逆性权衡分析。 将每个决策视为单向门（不可逆：数据存储、公共API形态、组织/团队边界）或双向门。单向门需要更深入的分析和一个ADR；双向门可以快速决定。明确指出可选方案，并陈述“如果满足{触发条件}，会选择X”。
- 每项建议都是一个具体的选项 + 不应该构建的内容 + 明确说明的权衡。 每次通过最多做出3–5个决策；更多内容读起来像是文档转储，而不是一组决策。
- 详尽的清单使用统一的表格 + 自审计计数，而不是叙述性文本。 对于任何“覆盖N项”的任务（Well-Architected支柱、每个元素的STRIDE、API清单），为每个项目填充一行，并在声称完成前对照总数计算已覆盖的行数——一次单一的叙述性遍历会可靠地遗漏行，并在达到全面覆盖之前停止引用发现。
- 区分事实、决策、假设和建议。 保留上游决策和用户约束，否则明确标记冲突；优先使用存储库和制品证据而非通用默认值。
核心工作流程
- 检查请求、证据、约束和现有制品（PRD、ADR日志、设计文档）。
- 需求关口：功能需求 + 非功能需求 + 约束已捕获，矛盾已暴露。
- 选择最小的足够路线：一个主要任务，至多一个表面覆盖层。
- 记录重要的假设和未解决的输入及其负责人。
- 生成请求的制品，以参考文档命名的框架为基础；每次通过最多包含3–5个决策，每个决策附带其权衡。
- 对照请求、约束和验收标准进行验证；说明置信度。
- 当预期有下游构建工作时，生成简洁的
handoff.yaml。
制品契约
每个参考文档定义自己的制品。每个架构制品必须记录：做出的决策和考虑过的选项；接受的权衡；区分事实/决策/假设；以及应用于任何难以逆转的决策的可逆性视角。一次完整的架构通过最多可生成五个下游制品——解决方案架构文档（assets/solution-architecture-doc.md，arc42形状）、API/事件契约、非功能需求预算（assets/nfr-budget-worksheet.md）、ADR（assets/adr-template.md）和STRIDE威胁模型（assets/threat-model-register.md）——加上DDD画布（assets/bounded-context-canvas.md、assets/aggregate-design-canvas.md）和 assets/arc42-skeleton.md，当任务需要它们时提供。每当预期有下游工作时，提供机器可读的 handoff.yaml 配套文件；参见 handoff。
完成与交接
在完成之前：
- 确认每个请求的制品都存在，且其验收标准是可检查的。
- 确认每个详尽清单制品都是一个带有自审计计数的表格，而不是叙述性文本。
- 记录决策、假设、风险和未解决的问题，并注明负责人。
- 区分已执行的验证和剩余的验证；诚实地说明置信度。
- 当预期有下游构建工作时，生成
handoff.yaml配套文件，包含制品路径、约束、决策、风险和推荐的下一步技能——不要重复完整的制品。绝不要静默地调用构建技能；在recommended_next中指明。
资源
仅加载选定路线所需的资源；切勿预加载。
- 主要任务：system-design —— 需求关口入口主干 · decomposition —— 边界、耦合、单体优先 · contracts —— API/事件契约优先 · data-architecture —— 一致性、CQRS/ES、存储 · nfr-budgets —— 将质量属性量化为数字 · security-architecture —— STRIDE、认证、零信任 · migration —— 绞杀者模式、7 Rs、切换 · adr-and-governance —— 决策记录+适应度函数
- 表面覆盖层：surface-web-saas · surface-mobile · surface-agentic · surface-data-intensive · surface-internal-platform
- 流水线：handoff —— 独立与流水线行为，以及由
frontend、backend、data、ai和quality使用的handoff.yaml配套文件。 - 制品：位于 assets/ 中的可填写模板——解决方案架构文档、arc42骨架、ADR模板、非功能需求预算工作表、威胁模型登记表、限界上下文和聚合设计画布，以及
handoff.yaml信封。