SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场oma-architecture

oma-architecture

编程与开发

查看项目

更新于 10-16 02:12

技能介绍

用途

oma-architecture 是一个软件架构专家智能体技能，目标是分析、比较并记录软件架构决策，并明确列出权衡、风险、相关方关注点与验证步骤。它面向需要架构判断的场景，而非直接改动实现代码。

主要能力

  • 选择或评审系统架构
  • 定义模块、服务或所有权边界
  • 对比架构选项并明确权衡
  • 诊断架构痛点：变更放大、隐藏依赖、别扭的 API
  • 对架构投资或重构进行优先级排序
  • 编写架构建议或 ADR
  • 决定 API 版本化、弃用窗口与已发布契约演进策略

使用方式

该技能按请求清晰度、决策重要性、风险级别以及是否需要相关方咨询进行分支，可能先比较多个选项再给出推荐，产出基于来源的文档而非直接修改实现。

结构化流程：

  • 入口：识别架构问题、决策或痛点信号；收集既有约束、来源证据与相关方背景；读取 .agents/results/architecture/ 中的既往决策（新决策显式取代旧决策，绝不静默矛盾）；选择最轻量且足够的方法。
  • 场景：PREPARE（澄清范围、质量属性、约束与产物目标）、ACQUIRE（读取代码/文档，必要时收集相关方或运维证据）、REASON（诊断、比较选项、分析权衡、评估风险）、VERIFY（检查假设、验证步骤与约束契合度）、FINALIZE（产出推荐、ADR 或架构产物）。
  • 转换：请求含糊时先用诊断模式；决策重要时至少比较两个真正不同的选项；风险/质量属性占主导时用 ATAM 风格分析；对架构投资排序时用 CBAM 风格的成本/收益框架；决策最终确定时格式化为 ADR。
  • 失败与恢复：证据不足时说明假设并请求或搜索缺失上下文；相关方利益冲突时综合权衡而非强行达成共识；任务属于其他领域时路由到相应技能。
  • 退出：成功时推荐或产物说明假设、选项、权衡、风险与验证；部分成功时明确未解决的假设或缺失证据。

方法选择：

  • 诊断模式：痛点含糊、架构症状不清晰
  • 推荐模式：为具体架构决策选择方向
  • Design-Twice 模式：在承诺前比较 2 个以上实质不同的设计
  • ATAM 风格模式：质量属性场景、权衡点、架构风险
  • CBAM 风格模式：架构投资的成本/收益优先级排序
  • ADR 模式：分析后形成简洁的最终决策记录

预期输入：架构问题、痛点或决策背景；现有代码库、图表、文档、约束或相关方关注点；可扩展性、可靠性、安全性、可运维性、成本、交付速度等质量属性；可选的产物类型（推荐、选项对比或 ADR）。

预期输出：架构诊断、推荐、对比、优先级排序或 ADR；假设、权衡、风险与验证步骤；当决策改变结构（边界、依赖、数据流）时提供 Mermaid 上下文/容器图；当 oma diagram resolve 报告 engine: archify（常规情况，oma 自动获取最新 archify 版本）时，生成交互式同级 <artifact-stem>.archify.json + .archify.html；在产生持久输出时，将架构产物保存到 .agents/results/architecture/。

产物定义：

  • architecture-artifact：当运行需要持久化时，写入持久存储的 ADR、对比或推荐，路径 ".agents/results/architecture/*.md"，非必需。
  • architecture-diagram-html：Markdown 产物旁的 archify 交互式 HTML 图（+ JSON 规格）；仅当 archify 引擎解析成功且决策属于结构性时生成，路径 ".agents/results/architecture/*.archify.html"，非必需。

依赖资源：resources/execution-protocol.md（工作流）、resources/methodology-selection.md（方法选择）、resources/stakeholder-synthesis.md（跨领域相关方咨询合理时）、resources/output-templates.md（最终产物形态）、resources/api-evolution.md（已发布契约的版本化/弃用决策，MAP 演进模式）、resources/migration-patterns.md（所选架构需要重构在线系统时的过渡计划）、_shared/conditional/diagram-engine.md（+ oma diagram resolve，生成结构图时选择 archify 还是 Mermaid 并负责验证/交付循环）。

规范工作流路径：使用配置的代码智能提供方获取结构、符号、引用与集成点。若不可用，仅对本项目之外的路径或被忽略的路径使用原生搜索：

  1. 读取 .agents/results/architecture/ 中的既往决策。
  2. 发现所配置提供方的文件、符号、引用与模式工具。
  3. 在选定范围内检查与架构相关的模块、所有权与集成点。

然后在写入产物前选择诊断、推荐、Design-Twice、ATAM 风格、CBAM 风格或 ADR 模式。

资源范围：CODEBASE（与架构相关的源文件与文档）、LOCAL_FS（.agents/results/architecture/ 产物）、MEMORY（假设、选项矩阵、权衡笔记）。

前置条件：架构关注点或决策边界可识别；相关上下文可读取或可说明假设。

效果与副作用：创建架构推荐或 ADR 风格记录；可能影响实现方向、所有权边界与未来重构；除非另行请求实现任务，否则不直接修改产品代码。

适用场景

  • 选择或评审系统架构
  • 定义模块、服务或所有权边界
  • 对比架构选项并明确权衡
  • 调查架构痛点：变更放大、隐藏依赖、别扭的 API
  • 对架构投资或重构进行优先级排序
  • 编写架构建议或 ADR
  • 决定 API 版本化、弃用窗口与已发布契约演进策略

限制

以下场景不适用，应路由到其他技能：

  • 视觉设计、设计系统、品牌或落地页 -> 使用 oma-design
  • 功能规划与任务分解 -> 使用 oma-pm
  • 基础设施配置或 Terraform 实现 -> 使用 oma-tf-infra
  • 缺陷诊断与代码修复 -> 使用 oma-debug
  • 安全/性能/无障碍评审 -> 使用 oma-qa

护栏：先诊断架构问题再选择方法；使用当前决策最轻量且足够的方法；区分架构设计与 UI/视觉设计及 Terraform 交付；仅当决策足够跨领域、值得付出成本时才咨询相关方智能体；推荐质量优先于共识表演（广泛咨询、明确决策）；每条推荐必须说明假设、权衡、风险与验证步骤；默认成本意识（实现成本、运维成本、团队复杂度、未来变更成本）；决策重要时至少比较两个真正不同的选项再推荐；将架构产物保存到 .agents/results/architecture/；决定前先读取该目录中的既往产物，替换旧决策时标记为已取代而非矛盾；在活跃 OMA 工作流中最终确定持久产物时，用 architecture.adr-complete 记录其实际推荐、权威状态、理由、修订与证据（执行协议第 7 步），完成的提案不提供用户批准也不授权实现。

工具与手段：本地文件读取与搜索（代码库/文档）；架构方法参考与输出模板；仅在足够跨领域、值得成本时可选咨询相关方智能体。

逻辑操作：分类架构请求（SELECT）、读取代码/文档/上下文（READ）、比较选项（COMPARE）、推断风险与权衡（INFER）、验证决策契合度（VALIDATE）、写入产物（WRITE）、通知结果（NOTIFY）。

参考：本地代码工具 ../_shared/core/code-intelligence.md；执行步骤 resources/execution-protocol.md；检查清单 resources/checklist.md；方法选择 resources/methodology-selection.md；相关方协议 resources/stakeholder-synthesis.md；输出模板 resources/output-templates.md；API 演进模式 resources/api-evolution.md；迁移/过渡模式（strangler fig、branch by abstraction、expand-contract）resources/migration-patterns.md；上下文加载 ../_shared/core/context-loading.md；任务分解 ../_shared/core/difficulty-guide.md；澄清协议 ../_shared/core/clarification-protocol.md；质量原则 ../_shared/core/quality-principles.md。