--- name: architecture description: 当用户要求为新系统或现有系统设计、评估、记录或审查软件架构时使用，包括架构方案比较、ADR、组件或集成边界、分层或模块化单体、服务拆分、可扩展性、可用性、质量属性、运行时或部署视图、架构风险和迁移计划。可用时检查代码仓库证据，比较明确的权衡，区分事实与假设，并产出可用于决策的文档。不要用于简单的架构定义、泛化头脑风暴、单独的错误修复、功能实现或保持行为不变的重构，除非任务明确要求做架构决策。 --- # Architecture ## 目的 让软件架构决策可追溯、与问题规模相称，并以证据为基础。把架构视为系统的边界、职责、依赖、数据流、运行时行为、部署拓扑和质量属性，而不是流行模式的清单。 使用此 Skill 编写或审查架构 brief、决策记录、目标状态设计、架构审查或渐进式迁移计划。优先选择满足约束和质量目标的最简单设计。没有具体理由时，不要默认选择微服务、事件驱动集成或新框架。 ## 路由 如果用户明确要求在决策前进行对抗式提问，使用 `ultra-grill-me`。如果主要请求是实现、修复或保持行为不变的清理，使用 `feature-dev`、`bugfix` 或 `refactoring`。即使后续可能实现，只要主要任务是做出或记录架构决策，就继续使用此 Skill。 ## 工作规则 - 先调查再提出方案。对于现有代码库，检查项目规则、入口、模块/包布局、依赖清单、持久化、集成客户端、测试、构建与部署配置、可观测性和相关历史。 - 将重要陈述标记为事实、假设、推断或未解决问题。可用时为重要发现标注仓库路径和行号。 - 让质量属性可测试。把“可扩展”或“高可用”转换为包含 stimulus、environment、response 和可测量 target 的场景。 - 使用相同标准比较方案。包含当前状态或最简单的 baseline，不要把单一偏好的模式伪装成分析。 - 明确所有权和故障行为：组件职责、数据所有权、事务边界、通信方式、重试/幂等、超时、背压、一致性、恢复和可观测性。 - 区分目标架构和迁移架构。说明如何通过兼容性、回滚和数据迁移安全地分步移动。 - 记录会改变决策的条件：假设、决策触发器、护栏以及复审日期或时间范围。 - 不要编造吞吐量数字、团队结构、成本、合规要求或基础设施能力。标记缺失证据，并建议如何测量。 ## 工作流 ### 1. 界定决策 用一句话描述决策。记录系统边界、用户或参与者、业务能力、期望结果、范围、约束、非目标、兼容性要求、风险时间范围和决策负责人。在比较设计前定义什么算“好”。 如果请求不完整，做低风险假设并列出。只有当缺失选择会显著影响安全、隐私、数据丢失、监管暴露、公共契约、成本或不可逆的设计方向时，才请求澄清。 ### 2. 建立证据基础 对于代码仓库任务，先检查最小有用集合： - 项目规则和架构文档 - 包/依赖清单、入口、配置和构建脚本 - 顶层模块或服务目录及其公共接口 - 数据模型、迁移、队列、缓存、外部集成和认证边界 - 测试、CI/CD、部署清单、运行时配置、日志、指标和 tracing 设置 沿当前系统追踪代表性的用户或业务流程。必要时使用仓库搜索和版本历史。不要仅凭目录名称推断边界；确认 import、调用、数据访问、所有权和部署耦合。 ### 3. 定义质量场景 选择能够改变决策的三到五个质量属性。通常考虑可用性、延迟、吞吐量、可扩展性、一致性、持久性、可恢复性、安全、隐私、可运维性、可部署性、可测试性和成本。使用以下格式： `When [stimulus] occurs in [environment], the system shall [response] within/with [measure].` 按用户或业务影响排序，区分硬约束与偏好。如果目标未知，声明临时目标，并说明需要什么测量来替换它。 ### 4. 建模当前状态和目标状态 只描述有助于决策的视图： - context view：参与者、外部系统、信任边界和系统职责 - container/component view：可部署单元、模块、接口、依赖方向和所有权 - data view：权威存储、schema 所有权、一致性、生命周期和迁移路径 - runtime view：同步/异步调用、队列、并发、重试、超时和故障传播 - deployment view：环境、放置位置、扩缩容单元、发布、恢复和运维依赖 只有在能使关系更清楚时才使用紧凑表格或 Mermaid 图。代码库审查要找出边界违规、循环依赖、共享可变数据、隐藏耦合、分布式事务假设，以及无法独立测试或部署的组件。 ### 5. 生成并比较方案 生成包括 baseline 在内的两到四个有实质差异的选项。选择适合问题的选项，不要只罗列模式名称。对每个选项说明： - 职责和所有权边界 - 同步/异步通信及契约形状 - 数据所有权、一致性、事务和迁移策略 - 扩缩容单元、性能瓶颈和容量假设 - 故障隔离、恢复、安全和可观测性 - 部署、团队认知负担、测试、成本和运维负担 - 迁移增量、兼容策略和回滚路径 使用相同标准比较所有选项。没有精确测量时可以使用定性矩阵，但要解释最重要的权衡。推荐方案必须说明为什么现在适合约束、主动放弃了什么，以及何时重新审视。 ### 6. 分析风险并做出选择 检查以下方面： - 单点故障和相关故障域 - 过载或含义不清的边界 - 通过共享数据库、schema、库或部署流水线产生的隐藏耦合 - 一致性、顺序、重复、重放、重试和幂等风险 - 安全与隐私边界、最小权限、密钥和数据暴露 - 可观测性缺口和难以测试的路径 - 迁移、回滚、兼容性和运维准备风险 将风险分类为 accepted、mitigated、deferred 或 blocking。证据不足或决策难以逆转时，优先选择更小且可逆的步骤。 ### 7. 产出请求的文档 根据请求选择输出： - **Architecture brief/design：** context、目标、约束、质量场景、当前状态、目标状态、方案、推荐、风险和迁移切片。 - **ADR：** 使用 `references/adr-template.md`，记录 context、decision、status、alternatives、consequences、assumptions 和 revisit triggers。 - **Architecture review：** 使用 `references/review-checklist.md`，报告证据、优势、边界发现、风险、优先行动和开放问题。 - **Runtime/deployment view：** 展示请求路径、异步路径、故障与恢复行为、扩缩容、发布和运维依赖。 - **Codebase architecture assessment：** 引用具体文件和符号，映射依赖方向与数据所有权，按影响排序发现，并提出能改善目标质量属性的最小结构变化。 清楚分开事实、假设、决策、被拒方案、风险和开放问题。不要把示意图或示例指标当成系统已验证的属性。 ## References 只读取任务所需的资料： - `references/architecture-methods.md` — 质量场景、视图、比较矩阵、边界启发式和迁移指导 - `references/adr-template.md` — 可复用的 ADR 结构和填写提示 - `references/review-checklist.md` — 边界、数据、运行时、韧性、安全、运维和迁移检查 ## 输出质量标准 结果应以证据为基础，明确不确定性，内部一致，与决策规模相称且可执行。评审者应能回答：决定什么、为什么现在决定、拒绝了哪些方案、什么可能失败、如何验证选择，以及以后如何改变系统。 ## 停止条件 当请求的文档完成、推荐方案得到约束和质量场景支持、重要风险与假设已记录，并且下一步验证或实现清晰时停止。如果证据不足，则停在有界评估，并准确说明下一步必须测量、检查或决定什么。