SuperAPI AI 工具集

architecture-guardian

编程与开发

查看项目

更新于 10-24 16:15

技能介绍

Architecture Guardian 是 Agent Kernel 的本地一致性工作流,用于 AI 辅助的代码变更,防止架构漂移。它通过分离现有债务与新回归、要求复用证据、限定任务边界来管理架构一致性。

用途

Architecture Guardian 旨在防止 AI 编码代理在修改代码时引入架构漂移。它适用于以下场景:功能跨越多个模块或层、重构更改依赖或公共接口、提议新服务/仓库/适配器/钩子/验证器/状态存储/工具、包/模式/迁移/提供商集成/部署边界变更、存在变更契约、用户要求防止架构漂移/循环/重复事实来源/范围外编辑、CI 报告 Architecture Guardian 发现。对于琐碎的拼写错误或孤立的文档更正,除非项目策略明确要求,否则不需要完整契约。

主要能力

  • 项目治理读取:读取 AGENTS.md、相关代理指令和 .agent-kernel/architecture/policy.json(如果存在),不从路线图或旧报告推断策略。
  • 当前状态验证:通过 agent-kernel architecture doctor . --json 和 agent-kernel architecture policy validate . --json 检查策略或存储的架构状态是否格式错误,若错误则停止并修复。
  • 结构发现:使用 agent-kernel architecture discover . --json 发现源根、层、内部边、外部包、循环和导入者证据。发现过程读取有界源文件,不执行仓库代码。
  • 复用候选搜索:在创建能力前,运行 agent-kernel architecture reuse "<business capability>" . --json,审查具有相邻职责的符号和文件,避免因现有抽象名称不同而创建并行事实来源。
  • 任务边界建立:对于非平凡工作,使用 agent-kernel architecture contract init 初始化契约,指定任务、所有者、允许路径、预期文件、新依赖和测试,然后验证契约。
  • 范围内实现:将业务规则保留在审查的领域层,使用公共接口而非直接访问基础设施内部,保持每个规则单一事实来源。Claude PreToolUse 钩子可强制 Write、Edit 和 MultiEdit 范围,审查模式报告,严格模式拒绝。
  • 提交前检查:运行 agent-kernel architecture check . --json(严格模式加 --strict),分类每个发现:新确定性阻塞、现有基线债务、有效范围例外覆盖、语义审查提示、需要策略或检测器纠正的误报。不隐藏关键违规。
  • 关闭或更新审查状态:完成任务后关闭契约 agent-kernel architecture contract close . --json。仅在审查现有发现后更新基线,基线不是忽略文件。
  • 基线管理:通过 agent-kernel architecture baseline . --json 和 agent-kernel architecture diff . --json 创建基线,记录审查的现有发现和包/导入证据,新阻塞与旧债务保持可区分。
  • 例外管理:使用 agent-kernel architecture exception add 添加例外(需规则、文件、原因、所有者、过期时间),并可通过 list 和 revoke 管理。例外必须狭窄、有主、过期。
  • 审查与严格模式:审查模式为采用默认,报告候选阻塞但不阻止工作;严格模式对新阻塞违规返回非零退出码。仅在策略、基线、契约和例外可信后启用。钩子覆盖通过环境变量 AGENT_KERNEL_ARCHITECTURE_MODE 显式设置。
  • 失败处理:当架构检查暴露重复代理错误时,使用 agent-kernel failure capture 捕获失败,记录来源、类型、命令、退出码、文本、根因和修复,通过正常提案和审批流程推广可重用教训。

使用方式

按照所需工作流执行:读取项目治理、验证当前状态、发现结构、搜索复用候选、建立任务边界、在范围内实现、提交前检查、关闭或更新审查状态。使用命令行工具执行各步骤,并根据需要参考相关文档(如 references/workflow.md 等)。

适用场景

适用于非平凡功能开发、重构、跨模块修复、新服务/仓库/适配器/钩子/验证器/状态存储/工具引入、包/模式/迁移/提供商集成/部署边界变更,以及用户明确要求防止架构漂移的场景。

限制

对于琐碎拼写错误或孤立文档更正,除非项目策略要求,不需要完整契约。发现过程不执行仓库代码。严格模式仅在策略、基线、契约和例外可信后启用。例外必须狭窄、有主、过期,不应长期使用。不得在没有证据表明职责不同的情况下创建第二个事实来源,不得将业务规则移入传输、UI、持久化、提供商或框架层,不得绕过现有公共接口直接访问基础设施,不得在审查的层图或活动契约之外添加依赖,不得因实现漂移而扩大契约,不得在没有规则、范围、原因、所有者和过期时间的情况下抑制发现,不得将过期例外视为授权,不得将基线发现归因于当前变更,不得因低置信度语义猜测而阻塞(应报告供审查),不得在未经用户审查的情况下削弱策略以使单个 PR 通过。