产品架构构建器

把不完整的产品输入转化为有证据、有边界、有权衡且可交付的系统架构。默认生成架构文档，不在未经授权时部署、购买服务或更改生产环境。

工作原则

• 先理解产品和约束，再选择技术；不要从框架偏好倒推需求。
• 将结论标记为 已确认、从证据推断、建议 或 待确认。绝不把 Demo 中看不到的后端实现描述成事实。
• 保持需求、架构决策、风险、验证方式之间的可追溯关系。
• 优先形成可演进的模块化单体；只有在团队、规模、隔离或独立扩缩容证据充分时才拆分微服务。
• 给出具体默认方案，同时记录替代方案、触发切换的条件和代价。
• 区分 MVP、近期目标和远期演进，避免用远期规模为当前制造无效复杂度。

1. 建立输入基线

识别输入模式，并读取 input-analysis.md：

• 想法模式：从目标用户、问题、核心场景、价值、约束和成功指标开始。
• 文档模式：提取显式需求、冲突、缺口、术语和验收条件；保留来源位置。
• Demo 模式：在用户授权范围内遍历界面、状态和关键流程；记录可观察证据，不臆测内部实现。
• 代码模式：先检查仓库结构、依赖、入口、数据模型、接口、部署配置和测试，再形成现状架构。
• 混合模式：交叉验证来源；遇到冲突时列出冲突，而不是静默选择一个版本。

建立简短的输入清单，包括来源、可访问性、可信度和更新时间。不要因缺少完美材料而停滞；用明确假设继续。只有会显著改变产品边界、合规要求、数据隔离或核心技术路线的问题才必须先询问。

2. 定义产品和架构驱动因素

明确以下内容：

1. 用户角色、核心任务、主流程和异常流程。
2. 范围内、范围外、依赖项与业务规则。
3. 功能需求及优先级：MVP、Next、Later。
4. 可度量的非功能指标：可用性、延迟、吞吐、数据量、恢复目标、安全、隐私、成本和可维护性。
5. 团队技能、预算、时间、部署环境、既有技术和供应商限制。
6. 未决问题、假设及其验证方式。

为需求分配稳定 ID，例如 FR-001、NFR-001、CON-001。无法量化的指标要标为待确认，不能伪造精确数字。

3. 审计现状

存在 Demo 或代码时，输出当前能力地图：页面/入口、用户动作、状态、业务实体、外部集成、权限边界、已知技术组件和明显缺口。使用证据表记录结论来源。

不得仅凭 URL、页面外观或网络请求名称断言数据库、云厂商、内部服务划分或安全实现。可提出候选实现，但必须标为 建议。

4. 形成候选架构并决策

对影响大的选择至少比较两个合理方案，例如：模块化单体与微服务、关系数据库与文档数据库、同步与异步集成、自建与托管服务。按需求适配度、交付速度、复杂度、成本、运维、风险和可逆性比较。

使用 ADR 记录最终选择：背景、约束、方案、决定、理由、后果、替换触发条件。不要为了展示技术广度而堆叠组件。

5. 设计完整架构

读取 architecture-package.md，按与项目规模相称的深度覆盖：

• 产品上下文、角色、领域边界和关键旅程。
• 系统上下文、容器/部署单元、模块或组件职责及依赖方向。
• 核心领域模型、数据所有权、生命周期、保留、迁移、备份和一致性策略。
• API、事件、错误模型、幂等、版本、认证和外部集成契约。
• 身份、授权、租户隔离、密钥、审计、威胁与隐私控制。
• 可用性、容错、容量、缓存、限流、降级、RTO/RPO 和灾难恢复。
• 日志、指标、追踪、告警、SLO 和运维手册。
• 环境、CI/CD、基础设施、发布、回滚、配置和成本边界。
• 测试策略、迁移/上线计划、交付切片、依赖、风险和退出标准。

优先使用 Mermaid 表达上下文、容器、序列、状态和部署关系。每张图附一段文字说明边界、关键决策和失效路径；图不能替代契约细节。

6. 生成交付包

默认在目标项目的 docs/architecture/ 中生成架构包。先从本技能目录运行：

python scripts/scaffold_architecture.py --output <目标项目>/docs/architecture --title "<产品名称>"

脚本默认不覆盖已有文件。用 --dry-run 预览，用 --force 仅覆盖已明确允许覆盖的模板文件。随后用调查结果填充每个文件，删除无意义占位符；如果用户只要求对话内建议，则直接输出紧凑版架构，无需创建文件。

架构包应至少包含：摘要、产品上下文、需求与假设、系统架构、数据架构、接口与集成、安全/可靠性/可观测性、部署运维、交付路线、决策风险和追溯矩阵。小型产品可以合并文件，但不能遗漏适用的关注点。

7. 质量门禁

完成前读取 quality-gates.md，逐项检查并报告：

• 关键主张是否有证据或明确标签。
• 每个 MVP 需求是否映射到组件、数据、接口和验证方式。
• 每个 NFR 是否有设计响应和验证方案。
• 信任边界、敏感数据、失败模式、恢复和运维是否完整。
• 架构是否能由当前团队按阶段交付。
• 高风险决策是否有替代方案和演进触发条件。
• 图、表、术语、ID 和文件之间是否一致。

运行脚本的检查模式验证交付文件：

python scripts/scaffold_architecture.py --output <目标项目>/docs/architecture --check

最后给出：推荐架构摘要、最重要的三到五个决策、仍需用户确认的问题、最高风险，以及下一阶段可立即执行的工作。不要声称架构“完整”却隐藏未知项。

参考资料路由

• 分析想法、文档、Demo 或代码时：读取 input-analysis.md。
• 创建详细架构交付物和图表时：读取 architecture-package.md。
• 评审完整性、可实施性和一致性时：读取 quality-gates.md。