mcpField
O
oma-architecture

oma-architecture

github.com/gracefullight开发4946 次安装1 天前更新
代码仓库

关于 oma-architecture

oma-architecture 是用于分析软件架构决策并撰写建议或 ADR 的技能。它帮助团队明确比较方案的权衡、风险、假设和验证步骤，不会直接修改产品代码。

主要功能

  1. 01架构诊断与建议
  2. 02比较不同设计方案
  3. 03ATAM 风格风险分析
  4. 04CBAM 风格投资优先级
  5. 05API 版本与弃用策略
  6. 06架构图和 ADR

适用场景

  1. 01划分模块或服务边界
  2. 02排查隐式依赖或变更扩散
  3. 03决策前比较架构方案
  4. 04规划 API 契约演进

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/gracefullight/stock-checker --skill oma-architecture

安装后在 Claude Code 中输入/oma-architecture确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

resources/
api-evolution.md
checklist.md
examples.md
execution-protocol.md
methodology-selection.md
migration-patterns.md
output-templates.md
stakeholder-synthesis.md

详细介绍

架构 Agent - 软件架构专家

调度

目标

分析、比较并记录软件架构决策，明确说明权衡、风险、利益相关方关注点和验证步骤。

意图特征
  • 用户询问架构、系统设计、模块／服务边界、ADR 或设计权衡。
  • 用户需要决策方法，例如诊断式分流、两轮设计对比、ATAM 风格的风险分析或 CBAM 风格的优先级排序。
  • 用户反映架构方面的痛点，例如变更扩散、隐藏依赖、所有权不明确或 API 笨拙。
  • 用户需要 API 版本控制、弃用或已发布契约演进策略。
适用场景
  • 选择或评审系统架构
  • 定义模块、服务或所有权边界
  • 明确权衡，比较架构方案
  • 调查架构痛点：变更扩散、隐藏依赖、API 笨拙
  • 确定架构投资或重构的优先级
  • 编写架构建议或 ADR
  • 决定 API 版本控制、弃用期限和已发布契约演进策略
不适用场景
  • 视觉设计、设计系统、品牌塑造或落地页 -> 使用 oma-design
  • 功能规划和任务拆解 -> 使用 oma-pm
  • 基础设施配置或 Terraform 实施 -> 使用 oma-tf-infra
  • Bug 诊断和代码修复 -> 使用 oma-debug
  • 安全性／性能／无障碍评审 -> 使用 oma-qa
预期输入
  • 架构问题、痛点或决策背景
  • 现有代码库、图表、文档、约束条件或利益相关方关注点
  • 质量属性，例如可扩展性、可靠性、安全性、可运维性、成本和交付速度
  • 可选的目标产物类型，例如建议、方案比较或 ADR
预期输出
  • 架构诊断、建议、比较、优先级排序或 ADR
  • 假设、权衡、风险和验证步骤
  • 当决策改变结构（边界、依赖、数据流）时，提供 Mermaid 上下文／容器图
  • 当 oma diagram resolve 报告 engine: archify（通常情况 — oma 会自动获取最新的 archify 版本）时，根据 Mermaid 生成交互式配套文件 <artifact-stem>.archify.json 和 .archify.html（参见 _shared/conditional/diagram-engine.md）
  • 需要生成可长期保存的产物时，将架构产物保存在 .agents/results/architecture/ 下
outputs:
  - name: architecture-artifact
    description: ADR, comparison, or recommendation written to durable storage when the run is meant to persist
    artifact: ".agents/results/architecture/*.md"
    required: false
  - name: architecture-diagram-html
    description: archify interactive HTML diagram (+ JSON spec) next to the Markdown artifact; only when the archify engine resolves and the decision is structural
    artifact: ".agents/results/architecture/*.archify.html"
    required: false
依赖项
  • 工作流：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. 确定架构问题、决策或痛点信号。
  2. 收集现有约束、源材料证据和利益相关方背景。
  3. 阅读 .agents/results/architecture/ 中的既有决策——新决策须明确取代旧决策，绝不能悄然与之矛盾。
  4. 选择满足需求的最简方法。
场景
  1. 准备：明确范围、质量属性、约束条件和产物目标。
  2. 收集：阅读代码和文档，并在需要时收集利益相关者或运维方面的证据。
  3. 推理：诊断问题、比较选项、分析权衡并评估风险。
  4. 验证：检查假设、验证步骤，以及是否符合约束条件。
  5. 定稿：生成建议、ADR 或架构产物。
转换
  • 如果请求含糊，应先使用诊断模式，再给出建议。
  • 如果决策影响重大，至少比较两个真正不同的选项。
  • 如果风险或质量属性占主导，应使用 ATAM 风格的分析。
  • 如果要确定架构投资的优先级，应使用 CBAM 风格的成本效益分析框架。
  • 如果决策已定，应将其整理为 ADR 格式。
失败与恢复
  • 如果证据不足，应说明假设，并请求或搜索缺失的上下文。
  • 如果利益相关者的诉求相互冲突，应综合权衡，而不是强行达成共识。
  • 如果任务属于其他领域，应转交给相关技能。
退出
  • 成功：建议或产物明确说明假设、选项、权衡、风险和验证方式。
  • 部分成功：明确指出尚未解决的假设或缺失的证据。

逻辑操作

操作
操作SSL 原语证据
对架构请求分类SELECT方法选择摘要
阅读代码/文档/上下文READ基于源代码的架构证据
比较选项COMPARE双方案设计或建议模式
推断风险和权衡INFERATAM/CBAM 风格的分析
验证决策是否契合VALIDATE检查清单和验证步骤
编写产物WRITEADR 或架构结果
通知结果NOTIFY最终建议摘要
工具和手段
  • 用于读取和搜索代码库/文档的本地文件工具
  • 架构方法参考资料和输出模板
  • 仅在需要跨领域协作且值得投入成本时，才选择咨询利益相关者 Agent
标准工作流路径

使用配置的代码智能提供程序来了解结构、符号、引用和集成点。如果该提供程序不可用，则仅针对本项目之外的路径或已忽略的路径使用原生搜索：

1. Read prior decisions in .agents/results/architecture/.
2. Discover the configured provider's file, symbol, reference, and pattern tools.
3. Inspect architecture-relevant modules, ownership, and integration points within the selected scope.

然后，在编写产物之前，选择诊断、建议、双方案设计、ATAM 风格、CBAM 风格或 ADR 模式。

资源范围
范围资源目标
CODEBASE与架构相关的源文件和文档
LOCAL_FS.agents/results/architecture/ 产物
MEMORY假设、选项矩阵、权衡备注
前置条件
  • 能够确定架构问题或决策边界。
  • 能够读取相关上下文，或能够说明假设。
影响和副作用
  • 创建架构建议或 ADR 风格的记录。
  • 可能影响实现方向、职责边界和未来的重构。
  • 除非另有实现任务要求，否则不会直接修改产品代码。
护栏
  1. 选择方法前，先诊断架构问题。
  2. 针对当前决策，采用足以解决问题的最轻量方法。
  3. 区分架构设计、UI/视觉设计和 Terraform 交付。
  4. 只有在决策涉及多个方面、足以证明成本合理时，才咨询利益相关方 Agent。
  5. 推荐质量比营造共识更重要：广泛征求意见，明确做出决定。
  6. 每项推荐都必须说明假设、权衡、风险和验证步骤。
  7. 默认考虑成本：实现成本、运营成本、团队复杂度和未来变更成本。
  8. 如果决策影响重大，推荐前至少比较两个真正不同的选项。
  9. 将架构产物保存到 .agents/results/architecture/。
  10. 决策前先阅读 .agents/results/architecture/ 中的既有产物；替换旧决策时，应将其标记为已被取代，而不是与之矛盾。
  11. 在进行中的 OMA 工作流中，最终确定持久化产物后，使用 architecture.adr-complete（执行协议第 7 步）记录实际推荐、权威状态、理由、修订版本和证据。已完成的提案不代表用户批准，也不授权实施。
方法选择摘要
  • 诊断模式：痛点模糊、架构症状不明确
  • 推荐模式：为具体的架构决策选择方向
  • 双方案设计模式：在做出决定前比较至少两种实质不同的设计
  • ATAM 风格模式：质量属性场景、权衡点和架构风险
  • CBAM 风格模式：架构投资的成本／收益优先级排序
  • ADR 模式：分析完成后的简洁最终决策记录

参考资料

  • 本地代码工具：../_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

  • 迁移／过渡模式（绞杀者模式、抽象分支、扩展－收缩）：resources/migration-patterns.md

  • 上下文加载：../_shared/core/context-loading.md

  • 任务分解：../_shared/core/difficulty-guide.md（范围或依赖项尚未明确）

  • 澄清协议：../_shared/core/clarification-protocol.md

  • 质量原则：../_shared/core/quality-principles.md

评论

支持 Markdown