Agent Skills
返回列表
架构治理检查

架构治理检查

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中:

请根据 https://skillhub.cn/install/skillhub.md,安装 @user_c0c2196f/metago-arch

技能介绍

要解决的问题

分层项目最容易失控的不是目录命名,而是依赖方向。看上去分成 domain、application、adapters、infrastructure 四层,实际代码里 dom 层直接 import sqlalchemy 或 prisma、应用层顺手调 requests、数据库行对象一路透传到内层,架构很快退化成一锅粥。另一个常见问题是一刀切:小脚本、原型项目也强制四层+组合根,带来不必要的模板代码;而使用 services、models、api、core 这类传统目录的项目,规则不做层映射就会覆盖率为 0,看似检查了实际什么都没查。

技能如何工作

@user_c0c2196f/metago-arch 把架构规则固化成 Agent 可读的约束,而非替开发者改代码。它先按项目规模选档:A 档核心产品强制四层、依赖向内、组合根;B 档中小项目/内部工具守 SOLID 的 S+D+OCP 加简单分层;C 档脚本/原型不强制检查。trim 参数非法时回退到 B 档并说明原因。

工作流分三步:

  1. 装载规则:计算包从内置的 rules/架构治理规则v1.md 读取完整约束,无需外部文件;
  2. 静态判依赖:依据依赖规则检查 import 方向与禁入清单。核心规则包括:domain 禁止引用 application/adapters/infrastructure;application 禁止引用 adapters/infrastructure;内层禁止 import 框架/数据访问库,覆盖 Python 的 sqlalchemy/asyncpg/httpx/requests/redis/fastapi,以及 TS 的 express/sequelize/prisma/pg/axios;
  3. 交付决策与报告:A/B 档项目必须通过检查才能宣告完成,违规未修复不允许通过;检查结果写入 arch-report.md。检查目录不存在时提示确认路径而非静默通过。

实际上层是否合规,看的是依赖能不能朝一个方向流动,而不是目录叫什么名字。

适用边界与注意点

  • 只检查,不自动修复。需要批量改代码、替代 CI/CD 原生质量门禁的场景不适合本技能;
  • 传统目录必须配置 arch.config.json 的 check.layers 映射,否则覆盖率为 0 等于没检查;
  • strict 模式下分层覆盖率为 0 直接判 FAIL,不得宣告通过;
  • 配置、DI 类导入先加 check.allowImports 白名单再判定,避免把合理 import 误伤为违规;
  • 用例名要写成人类动作(如 PlaceOrder),禁止用 insert/update/delete/remove 开头;
  • 跨层只用简单 DTO,禁止把数据库行/ORM 实体传进内层;
  • 小项目直接上 A 档属于过度设计,按规模选档才是正解。

使用场景

  • 新建项目或模块时,初始化分层结构并选定 A/B/C 档位
  • 编写或修改业务代码后,检查依赖是否违反向内规则
  • 重构前运行 metago-arch check,确认没有引入反向依赖
  • 审查使用 services/models 传统目录的仓库,配置层映射后验证覆盖率而非误判

适合人员

  • 需要给新项目定下分层与依赖规则的后端工程师
  • 在遗留单体上推行整洁架构的技术负责人
  • 编写 AI Agent 技能并需要触发条件与规则文件的开发者
  • 重构前想用静态规则替代口头约定的架构评审成员