Skip to content

SKILL.md

Latest commit

 

History

History
151 lines (121 loc) · 9.01 KB

SKILL.md

File metadata and controls

151 lines (121 loc) · 9.01 KB
name moe-design
description 一个混合专家设计审查技能，在代码编写之前对架构提案和设计文档进行多维度专家级审查，与现有知识库交叉验证一致性。

MoE-Design 目标 (MoE-Design Goal)

将审查左移 (Shift-Left) 到设计阶段。在一行代码都没有写之前，通过多维度专家审查架构提案、RFC 或设计文档，尽早发现潜在的架构风险、可行性问题和与现有系统的冲突。

操作指令 (Instructions)

第 1 步：路由器 — 提案收集与范式检测 (Router — Proposal Collection & Paradigm Detection)

  1. 收集设计文档：获取用户提供的设计提案（RFC 文档、架构文档、口头描述、聊天内容均可）。
  2. 检测项目范式：检查项目的清单文件和目录结构，确定项目类型（REST API、CLI 工具、编译器、数据管道等）。
  3. 检查 KB 存在性：确定是否存在由 kb-build 构建的知识库。
  4. 激活专家：
    • 始终执行：第 1 层（5 个设计审查专家）。
    • 始终执行：第 2 层（1 个领域专家，动态生成）。
    • 有条件执行：第 3 层（KB 一致性专家）— 仅当 KB 存在时。

第 2 步：第 1 层 — 设计审查专家组（并行执行 / Layer 1 — Design Review Experts）

并行执行所有 5 个专家。每个专家接收相同的设计提案，但被约束为只从其指定维度审查。如果没有发现问题，则返回空。

专家 1：可行性 (Feasibility)

  • 关注点：技术选型是否成熟可靠、团队能力是否匹配、依赖项是否存在风险、时间估算是否合理。
  • 约束：不要评论性能或安全性。仅判断"这个方案能不能落地"。

专家 2：可扩展性 (Scalability)

  • 关注点：当负载增长 10x 时方案是否仍然成立、是否存在单点瓶颈、水平扩展路径是否清晰、数据模型是否支持未来演进。
  • 约束：不要评论实现细节。仅关注架构的弹性天花板。

专家 3：复杂度风险 (Complexity Risk)

  • 关注点：方案是否引入了不必要的抽象层、是否存在过度工程 (over-engineering)、新增概念数/交互路径数是否可控、对新人的认知负荷。
  • 约束：不要评论可行性或安全性。仅关注"这个方案是不是把简单的事情搞复杂了"。

专家 4：安全与合规 (Security & Compliance)

  • 关注点：数据流中的敏感信息暴露风险、认证/授权设计是否完整、是否符合相关合规要求（如 GDPR、SOC2）、第三方服务的信任边界。
  • 约束：不要评论性能或可扩展性。仅关注攻击面和合规风险。

专家 5：运维成本 (Operational Cost)

  • 关注点：部署复杂度、监控和告警的可观测性设计、故障恢复路径（RTO/RPO）、是否需要新的基础设施或运维技能。
  • 约束：不要评论代码实现。仅关注"这个方案上线后好不好养活"。

统一输出格式（所有专家适用）

[Risk/风险: Critical|High|Medium|Low] [Dimension/维度: <专家名称>]
Finding/发现: <简明描述>
Recommendation/建议: <可执行的改进建议或替代方案>

第 3 步：第 2 层 — 领域专家（动态生成 / Layer 2 — Domain Expert）

  1. 基于检测到的项目范式，路由器动态生成一个聚焦的审查提示词。
  2. 各范式的提示词示例：
    • REST API："作为 API 设计专家，请审查资源建模合理性、API 版本控制策略、幂等性保证和速率限制方案。"
    • 编译器/解释器："作为语言实现专家，请审查语法设计的可解析性、类型系统的健壮性和向后兼容策略。"
    • 数据管道："作为数据架构专家，请审查 Schema 演进策略、数据一致性保证和失败重试/死信队列机制的设计。"
    • 微服务系统："作为分布式系统专家，请审查服务拆分粒度、跨服务事务一致性方案和服务发现/熔断机制。"
  3. 领域专家使用与第 1 层相同的统一输出格式。

第 4 步：第 3 层 — KB 一致性专家（按条件执行 / Layer 3 — KB Consistency Expert）

如果项目不存在 KB，请完全跳过此步骤。

4.0 KB 新鲜度门控 (KB Freshness Gate)

在执行一致性审查之前，先验证 KB 的新鲜度：

  1. 读取与设计提案相关的 KB 文件的 fingerprint Commit ID，与当前 Git 记录对比。
  2. 如果存在过期 (Stale) 的 KB 文件：直接跳过 Layer 3。在最终报告中输出警告： 
    ⚠️ KB 一致性专家已跳过：相关知识库文档的源码指纹已过期，一致性审查结果不可信。
建议先运行 kb-update 刷新知识库后再重新审查。

4.1 现有架构提取与一致性审查

(仅在通过新鲜度门控后执行)

  1. 现有架构提取：从 KB 中读取与设计提案相关的模块文档，理解现有系统的架构模式和设计约定。
  2. 一致性审查：
    • 新设计的接口风格是否与现有模块一致（如命名规范、参数传递模式、错误处理风格）？
    • 新设计是否与 KB 中记录的已有设计决策产生冲突（如之前选择同步处理已有明确的 Why 文档，而新提案要引入异步）？
    • 新设计是否会破坏 KB 中记录的现有模块间的交互契约？
  3. 输出格式： 
    [Risk: Medium] [Dimension: KB 一致性]
Finding: 新提案中的异步事件模型与 KB 记录的同步请求链路设计冲突。
KB Reference: .agent/kb/core/request-pipeline.md
Recommendation: 评估是否要重构现有管道或在新模块中提供同步适配器。

第 5 步：聚合器 — 合并与风险评估 (Aggregator — Merge & Risk Assessment)

  1. 收集所有专家的输出。

  2. 去重：如果多个专家发现了同一个根因问题，合并为一个 finding。

  3. 冲突解决：优先级排序：

    安全与合规 > 可行性 > 复杂度风险 > 可扩展性 > 运维成本

  4. 设计就绪评级 (Design Readiness Rating)：

    最高级发现 评级 建议
    Critical / 致命 🔴 Blocked 方案存在根本性缺陷，需要返工重新设计
    High / 高风险 🟠 Major Revisions 需要在动工前解决关键问题
    Medium / 中风险 🟡 Minor Revisions 可以开始开发，但需要补充设计细节
    Low / 低风险 🟢 Ready 方案成熟，可以进入实施阶段
    None / 无发现 ✅ Excellent 方案完善，建议立刻开工

  5. 最终报告结构：

    # 设计审查报告 (Design Review Report)
## 设计就绪度 (Readiness): [🔴|🟠|🟡|🟢|✅] [级别]
## 概要 (Summary)
<1-2 句对设计方案的总体评价>
## 致命与高风险发现 (Critical & High Risk)
<分组列出发现>
## 中风险与低风险发现 (Medium & Low Risk)
<分组列出发现>
## KB 一致性分析 (KB Consistency) (如果适用)
<与现有架构的冲突或一致性确认>
## 已解决冲突 (Conflicts Resolved)
<专家分歧及解决方案>

示例 (Examples)

示例：审查一份"为订单系统引入事件驱动架构"的设计提案

  1. 路由器 (Router)：检测到 Node.js 微服务项目，确认存在 KB。
  2. 第 1 层 (Layer 1) (并行执行)：
    • Feasibility (可行性)："团队目前没有消息队列运维经验，引入 Kafka 的学习曲线可能导致延期。" [High]
    • Scalability (可扩展性)：没有发现（事件驱动本身对扩展性有利）。
    • Complexity Risk (复杂度)："引入了 Event Store、Saga 协调器、死信队列三个新概念，认知负荷较高。" [Medium]
    • Security (安全)："事件负载 (payload) 中可能携带 PII 数据，需要加密或脱敏策略。" [Medium]
    • Operational Cost (运维)："需要新增 Kafka 集群的监控、日志清理和分区管理。" [Medium]
  3. 第 2 层 (Layer 2) (领域专家 — 微服务)："未说明跨服务事件的幂等性保证和消费者 offset 管理策略。" [High]
  4. 第 3 层 (Layer 3) (KB 一致性)：KB 记录了现有的订单流程是 API → OrderService → DB 的同步调用链。新的事件驱动异步模型需要保证与现有同步的退款接口兼容。[Medium]
  5. 聚合器 (Aggregator)：设计就绪度 = 🟠 Major Revisions。2 个高风险发现（团队经验 + 幂等性缺失），3 个中风险发现。建议在开发前先做 Kafka PoC 和团队培训。

联动触发 (Cross-Skill Triggers)

以下建议在对应技能已安装时可选触发。调用时使用技能名称，Agent 会自动查找对应的 SKILL.md。如果技能未安装，在结果中告知用户并建议手动执行对应操作。

触发条件 建议调用技能 目的
设计就绪度为 🟢 Ready 或 ✅ Excellent，且后续代码已提交 moe-cr 验证实现是否忠实于审查通过的设计方案