SuperAPI AI 工具集

adr-audit

智能体与模型

查看项目

更新于 10-16 09:57

技能介绍

adr-audit 是一个架构合规检查技能,用于审计项目是否遵守既有架构规范。它不做新决策发现(由 adr-discover 负责),也不负责文档化决策(由 adr-manage 负责),而是以现有规则为“应然”,与仓库“实然”进行比对,输出差距报告。

规范来源包括:docs/adr/ 下所有 ADR,优先 Accepted 状态;AGENTS.md 及其子目录的嵌套文件中的每条显式规则;.agents/MEMORY.md 仅作技术栈与语言上下文,本身不产生规则。证据来自代码、目录结构与依赖清单。方法为静态检查加适应度函数:基础手段是用 find、grep 和清单文件读取仓库;若某 ADR 配有自动化架构检查(适应度函数),则执行它,其结果作为该 ADR 的首要依据。不运行完整构建或测试套件,只跑检测到的架构检查。无法通过检查或适应度函数确认的规则,标记为“不可验证”并说明所需证据,不臆造结论。

输出为单一报告 docs/adr/audits/audit-YYYY-MM-DD.md,按高/中/低优先级分组,每条发现引用被违反的 ADR 或 AGENTS.md 规则,列出证据与违规文件,提出行动并标注状态。报告还包含适应度函数章节:已有检查及其执行结果、缺失检查(ADR 合格但无适应度函数)及创建建议。报告首次生成后不再改动;后续复检仅在文末 ## Revalidaciones 添加新条目,记录时间、结论与有证据的变更。报告模板见 assets/audit-template.md。

用法上,先检查是否存在既往报告(ls docs/adr/audits/audit-*.md),据最新报告询问用户是复检还是重新审计。复检时读取既往报告及其复检记录,以“原始报告经历次复检调整后的状态”为基准,重新采集并对比,仅记录有证据的变更(已解决、证据更新、新违规或回归、依赖变化),无变化则明确标注“与上次验证相比无变化”。每次复检在文末追加一条记录,并更新头部结论为“原结论 (revalidado YYYY-MM-DD HH:MM)”。全新审计则忽略历史,新建当日报告。

审计流程分阶段:阶段 1 采集规则并分类是否适合适应度函数;阶段 2 逐条对照仓库取证,包括执行适应度函数(阶段 2B)。验证技术依规则类型而定,如技术选型用 grep 统计、结构层次用 find、依赖清单读 manifest、代码禁用项用 grep 反模式、模块边界检查导入。可量化时尽量量化,收集违规文件精确路径;不运行完整构建或测试,仅运行检测到的适应度函数。规则状态包括已满足、部分满足、未满足、不可验证;发现优先级按影响分为高、中、低。若项目存在 scripts/arch/verify-architecture.sh 聚合器,优先单次运行;否则逐个检测执行,并建议创建聚合器。语言选择顺序为:会话中的用户偏好、项目记忆中的偏好、用户消息语言(并询问是否持久化)、最后询问用户;文件路径、ADR 名称与命令输出不翻译。

适用场景为需要检查代码库是否符合架构决策记录与 AGENTS.md 规则的维护与评审工作。限制:不发现新决策、不编写决策文档、不运行完整测试套件;对依赖人工判断或外部环境的规则只能标记不可验证;具体命令可能因项目而异,资料中未提供本项目实际依赖与平台细节。