Community编程与开发github.com

agents-md-审计

对照项目证据和既定策略检查现有的 AGENTS.md 或 CLAUDE.md 指令。可用于定期审查、变更后的漂移检查,或建立/延续 Git 审计记录。报告缺陷与验证限制,保留未解决的发现,并准备检查点消息。仅在获得授权时应用修正或创建检查点。

agents-md-审计 是什么?

该技能用于自动化审计项目中的 AGENTS.md 或 CLAUDE.md 指令,确保其与代码库的实际状态和既定策略保持一致。它通过检查指令的准确性、策略遵从性、维护情况、决策记录和警告有效性,识别可能误导 AI 代理的过时或不准确声明。审计默认以只读模式运行,生成详细的报告和修正建议,但仅在获得明确授权后才会应用修复或创建 Git 检查点提交。支持对 Git 历史进行基线选择,以跟踪发现项的演变,并通过检查点消息记录审计结果,从而在项目文档中建立可追溯和可验证的审计链。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/has2k1/agents-grimoire/tree/HEAD/skills/agents-md-audit

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

AGENTS.md 审计

对照项目状态和既定策略审计指令。优先处理可能误导代理的声明。仅凭文档结构和编辑频率不能确定缺陷。当检查未发现任何缺陷时,报告无缺陷;简单的引导文档和未变更的准确指令可能已足够。

默认保持审计为只读,包括索引和 Git 历史。准备修正和检查点消息以供审查。当请求授权该操作时,应用修复或创建检查点;使用现有权限而不再次请求。在无自动修复或其他源码写入选项的情况下运行检查,并报告不可用的执行前提。

覆盖范围

记录实际检查的文件、声明、历史和检查。

  1. 记录仓库修订版本和工作树状态。盘点仓库中的指令文件、相关祖先规则、覆盖项、导入、链接和模块映射。包括现有的 CLAUDE.md 系统,而不是假定 AGENTS.md 是其活动入口点。
  2. 确认预期工具链发现哪些文件,以及哪些文件需要显式读取。根据可用配置或当前工具链文档检查相关加载路径和大小预算。将未知的交付标记为未验证;文件名和目录位置本身并不能证明加载。
  3. 说明要验证的文件和声明、任何抽样、命令先决条件和可用历史。当仓库不干净、历史记录浅或不可用,或检查无法运行时,限制判定。将本地更改与已提交的快照分开审计;不要将其归因于其 SHA。当检查在不同于已提交快照的文件上运行(例如,具有本地更改的工作树)时,说明检查运行的位置以及哪些路径不同。

历史记录和先前发现

对于 Git 仓库,在检查中间更改之前选择基线。如果没有 Git 历史,检查当前状态并报告历史验证不可用。

已完成的审计已完成其对整个仓库的声明检查;它可以在完成的检查范围内报告缺陷、抽样和不可用的检查,并附有明确限制。干净的结果意味着在已完成的检查范围内未发现缺陷。无法完成的审计会生成报告,但不会生成检查点。

检查点是一个空的、单亲 Git 提交,其消息存储已完成审计的报告和检查点消息模板的尾部。其唯一父级是审计修订版本,即该审计检查的已提交快照。本地更改与该快照分开。只有当提交满足基线选择下的每个条件时,它才是检查点;任何其他提交都是普通提交,无论其消息内容如何。

基线是目标分支第一个父历史中最近的检查点。它设置历史边界,即审计检查从该边界之后到审计修订版本之间的更改。其“新发现”和“结转发现”是完整的未解决先前发现集合。不产生检查点的审计不会更改基线。

引导输出在验证之前仍是候选文档,并且本身不能提供基线。

基线选择

从 HEAD 遍历目标分支的第一个父历史。将带有 Agents-Audit-Version 尾部的提交视为候选;通过尾部而不是主题来识别它们。例如:

git log --first-parent --format='%H' --grep='^Agents-Audit-Version: 1$' HEAD
git show -s --format=%B <candidate> | git interpret-trailers --parse

这些命令用于查找候选。仅当候选提交的消息和 Git 对象满足以下所有条件时,它才是检查点:

  • 消息模板中的每个尾部都有一个非冲突的值,版本受支持,并且技能版本或内容哈希可识别。
  • 该提交恰好有一个父级。该父级的完整 SHA 等于 Agents-Audit-Commit,并且父级和提交的树都等于 Agents-Audit-Tree。仅凭树相等性无法检测到重放到恰好产生相同文件的不同历史记录上。
  • 该提交位于目标的第一个父历史记录上。
  • Agents-Audit-Previous 指定审计修订版本第一个父历史记录上最近的早期检查点,如果已明确建立初始历史边界,则为 none。指定的提交本身必须是一个检查点。
  • 消息包含模板的每个报告部分,并具有声明的覆盖范围。除非 Agents-Audit-Previous 为 none,否则指定检查点中新发现或结转发现下的每个 ID 都必须出现在结转发现或已关闭发现下。

因为每个前身本身必须是一个检查点,所以从最旧的开始检查候选对象并重复使用每个结果;然后每个提交只检查一次。选择满足这些条件的最近候选对象作为基线。将任何其他候选对象视为历史窗口中的普通提交:不从其消息中读取任何发现或关闭信息,并将其排除在报告和检查点消息之外。

当前身不可用或浅层历史记录阻止这些检查时,说明差异。不要用最后几个提交静默替换已知的历史边界,或将当前工作声明为首次审计。如果无法建立基线,则在明确限制内检查当前状态,并将历史覆盖范围标记为未验证。对于没有早期检查点的真正首次审计,请验证当前状态并说明明确的初始历史边界。

变基、挑选和压缩会为提交提供新的父级,因此在重写历史记录后再次检查条件。在合并后建立持久的检查点,特别是在功能历史记录被压缩时。

检查

准确性和策略

  • 根据项目配置及其先决条件验证命令。在合适的环境中运行可行的检查。将失败归因于过时的调用、实现缺陷、不可用的先决条件或不完整的检查;测试命令有效并发现回归不是过时的。
  • 解析命名引用、路径、导入和模块映射条目。在调用指令丢失之前,检查重命名、共享所有权和适用的祖先规则。演示缺陷,然后根据代理遵循指令的可能后果来判断其严重性,而不仅仅是因为缺少符号。
  • 对照实现和测试验证重要的不变量,将文档字符串和注释视为声明而非证据。检查条件声明时,使用条件两侧的输入。区分描述与策略:有意的代码仍然可能违反已建立的边界。使用任务的权威和记录的决定来解决冲突;不要仅仅为了匹配违反它的代码而重写策略。
  • 针对具体的失败或回归路径检查警告。删除过时或肤浅的细节,当绕过它仍然是一个现实风险时保留有用的防护栏,并精简已经由测试或执行充分承担的解释。优先提供当前指导,而不是固定的失败历史记录。

将演示的缺陷报告为过时、冲突、缺失、策略冲突或过时的警告。将不确定的声明保留在未验证的检查下。包括受影响的指令、仓库证据、后果和提议的修正。

维护

检查自历史边界以来的代码、配置、依赖关系和指令变更。将每个相关变更映射到它可能失效的声明,包括未更改的指令文件。使用提交消息关键字和同时更改代码和指令的可选提交计数来选择要检查的变更,而不是判断文档质量。

仅当变更使已记录的声明失效或遗漏了必要的指令时,才报告维护缺陷。允许精确的不变量在多次变更中保持不变。将独立的修正、引导提交、审计修复和检查点提交视为合法工作。跨模块重构无需编辑其声明仍然正确的指令。

决策和警告

独立于错误修复发现来检查架构决策。寻找已被接受的、其后果应约束未来变更且其原因无法从代码中看出的选择。使用决策者的记录解释或确认;差异证明的是变更,而非意图。仅在有证据且仍然有用时,才起草规则、原因和重新考虑的条件。将被认为值得提及的被拒绝的替代方案留在受其影响的源代码的注释中,这样更改该代码的代理会找到它。在引导期间,继续仅使用当前源代码;不要挖掘 Git 历史来寻找原因或编造理由。

对于已诊断的重大错误,检查经验教训是否仍能防止代价高昂或重复的错误。仅当增加了有用的指导时,才提出一个记录症状、机制和识别或避免的简洁条目。当绕过抽象可能重新引入失败时,将警告重新表述为简洁的防护栏并解释原因。当机制已消失、错误很浅或执行已充分承载经验教训时,提议删除。将不确定的机制保留为建议以供确认。

形式

在准确性之后检查形式。将仓库范围的规则放在根文件中,模块共享的规则放在源根或包文件(中心)中,不同的模块规则放在本地文件(叶子)中。仅使用需要单独指导的范围;允许单文件项目、多个中心和省略的空部分。保留一个规范的解释,并允许在改进可发现性时提供一个简短的限定范围提醒及链接。保留适用的版本、验证日期、平台和测量条件。删除过时的进度叙述、编造的理由、不必要的重复以及不再有助于变更的指令。根据有用的决策来判断具体性,而不是根据文本更改的频率。

报告

说明检查的指令是否准确,并将该结论限制在所检查的声明范围内。记录修订版本、检查过的脏内容或忽略的内容、指令清单、已验证或抽样的声明、历史边界、命令结果、相关环境和版本以及未解决的检查。使报告可从仓库本身解释,使用仓库相对路径和 Git 修订版作为证据。

在最终确定报告之前,重新检查基线中的每个未解决的发现,并将其放入“结转发现”或“已关闭发现”下。

将发现分为以下几个部分;如果某部分为空,则写入 None:

  • 使用新的稳定 ID、受影响的指令、证据、后果和所需的修正来记录新发现。
  • 结转基线中每个未解决的发现,包括其列出的新发现,附带其 ID、其来源检查点(首次记录该发现的检查点)以及其证据、后果和所需修正的完整说明。当其解决方案无法验证时,保持发现处于打开状态,并披露无法验证的证据。
  • 使用已验证的解决方案或替代方案及支持证据关闭发现。记录一次关闭,然后在以后的报告中省略它。将其历史记录保存在较早的检查点中,而不是在每个报告中累积档案。

分配 ID,不要重复使用已退役的 ID;例如,使用审计特定的 UTC 时间戳加上计数器,并在此后保留该 ID。在报告中说明审计是否完成;中断或未完成的审计在报告之后结束。仅在证明其有效的检查范围内声明结果干净。

检查点消息

准备以下消息作为已完成审计交付物的一部分。包括审计报告本身,而不是指向外部问题跟踪器、本地报告或其他外部源的指针。完全按所示使用无标题主题和尾部,报告部分使用 ## 标题和空行。记录完整的对象 ID 和可识别的技能版本或哈希,而不是依赖已安装的路径。

chore: 记录代理文档审计

## 覆盖范围

检查了 <仓库相对路径的指令文件或目录>。
验证了 <声明和执行的检查,包括任何抽样>。
检查了从 <历史边界> 到审计修订版本的历史。
使用了 <相关环境和工具版本,以及检查运行的位置>。

## 未验证的检查

<未完成的检查及其原因,或 None。>

## 新发现

<每个新发现的稳定 ID、受影响的指令和部分、发现、证据、后果和所需修正;或 None。>

## 结转发现

<每个未解决发现的稳定 ID、来源检查点以及自包含的说明,包括证据、后果和所需修正;或 None。>

## 已关闭发现

<每个本次审计关闭的发现的稳定 ID、解决方案或替代方案以及支持证据;或 None。>

Agents-Audit-Version: 1
Agents-Audit-Commit: <完整的审计父级提交 SHA>
Agents-Audit-Tree: <审计的树 SHA>
Agents-Audit-Skill-Revision: <技能版本或内容哈希>
Agents-Audit-Previous: <基线检查点 SHA 或 none>

检查点创建

仅针对已完成的审计且获得该写入操作的授权时,才创建检查点。要求审计的修订版本仍然是 HEAD,并且审计的指令和代码在其树中表示。首先提交经授权的修正,并在记录其检查点之前验证该快照。如果修正更改了审计修订版本,则刷新报告和尾部以描述该已验证快照。排除未提交或忽略的内容在关于已提交快照的声明之外,并记录任何由此产生的覆盖范围限制。拒绝为观察到的脏状态记录检查点。

相关技能