Communityコーディング&開発github.com

エージェント文書監査

既存の AGENTS.md または CLAUDE.md の指示を、プロジェクトの証拠やポリシーと照合してチェックします。定期的なレビュー、変更後のドリフトチェック、または Git 監査記録の確立・継続に使用します。欠陥と検証限界を報告し、未解決の所見を保持し、チェックポイントメッセージを作成します。修正の適用またはチェックポイントの作成は、許可がある場合のみ行います。

エージェント文書監査 とは?

これは、AI エージェント(Claude Code、Codex など)が使用する AGENTS.md や CLAUDE.md といった指示ファイルを、プロジェクトの実際の状態や確立されたポリシーに対して監査するスキルです。主な目的は、エージェントを誤った方向に導く可能性のある虚偽の主張を特定することです。監査はデフォルトで読み取り専用で行われ、修正やチェックポイント(監査結果を記録した 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に質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

AGENTS.md 監査

プロジェクトの状態と確立されたポリシーに対して指示を監査します。エージェントを誤解させる可能性のある主張を優先します。文書の形状や編集頻度だけでは欠陥とは見なされません。チェックで欠陥が示されない場合は欠陥なしと報告します。簡単なブートストラップ文書や変更のない正確な指示でも十分な場合があります。

デフォルトでは、インデックスや Git 履歴を含め、監査を読み取り専用に保ちます。修正とチェックポイントメッセージをレビュー用に準備します。そのアクションがリクエストで許可されている場合にのみ、修正の適用またはチェックポイントの作成を行います。既存の権限を再度要求することなく使用します。自動修正やその他のソース書き込みオプションなしでチェックを実行し、利用できない実行前提条件を報告します。

カバレッジ

実際に調査したファイル、主張、履歴、およびチェックをカバレッジとして記録します。

  1. リポジトリのリビジョンとワーキングツリーの状態を記録します。リポジトリ内の指示ファイル、関連する祖先ルール、オーバーライド、インポート、リンク、およびモジュールマップを棚卸しします。AGENTS.md がアクティブなエントリポイントであると仮定するのではなく、既存の CLAUDE.md システムを含めます。
  2. 意図されたハーネスがどのファイルを発見し、どのファイルが明示的な読み取りを必要とするかを確認します。利用可能な構成または現在のハーネスのドキュメントに対して、関連するロードパスとサイズ予算をチェックします。不明な配信は未検証としてマークします。ファイル名とディレクトリ配置だけではロードを証明できません。
  3. 検証するファイルと主張、サンプリング、コマンドの前提条件、および利用可能な履歴を明記します。リポジトリがダーティである、履歴が浅いまたは利用できない、またはチェックを実行できない場合、判定を制限します。ローカルの変更はコミットされたスナップショットとは別に監査します。それらをその SHA に帰属させないでください。ワーキングツリーにローカル変更があるなど、チェックがコミットされたスナップショットと異なるファイルで実行される場合は、どこで実行され、どのパスが異なっていたかを明記します。

履歴と以前の所見

Git リポジトリの場合、介入する変更をチェックする前にベースラインを選択します。Git 履歴がない場合は、現在の状態をチェックし、履歴の検証が利用できないことを報告します。

完了した監査は、リポジトリ全体に対して宣言されたチェックを終了しています。明示的な制限付きで、欠陥、サンプリング、および利用できないチェックを報告できます。クリーンな結果は、完了したチェック内で欠陥が実証されなかったことを意味します。完了できない監査はレポートを生成しますが、チェックポイントは生成しません。

チェックポイントは、空の単一親の Git コミットであり、そのメッセージには完了した監査のレポートと チェックポイントメッセージ テンプレートのトレーラーが格納されています。その唯一の親は 監査されたリビジョン、つまりその監査によって調査されたコミットされたスナップショットです。ローカル変更はそのスナップショットとは別のものです。コミットが ベースライン選択 のすべての条件を満たす場合にのみチェックポイントとなります。それ以外のコミットは、メッセージの内容に関わらず、通常のコミットです。

ベースラインは、ターゲットブランチの first-parent 履歴上の最も近いチェックポイントです。これは 履歴境界 を設定し、監査が監査されたリビジョンまでの変更を検査するリビジョンです。その New および Carried の所見は、未解決の以前の所見の完全なセットです。チェックポイントを生成しない監査は、ベースラインを変更しません。

ブートストラップ出力は、検証されるまで暫定的な文書のままとなり、それ自体でベースラインを提供することはできません。

ベースライン選択

ターゲットブランチの first-parent 履歴を 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 オブジェクトが以下のすべての条件を満たす場合にのみチェックポイントです。

  • メッセージテンプレート内のすべてのトレーラーが競合しない値を 1 つ持ち、バージョンがサポートされ、スキルリビジョンまたはコンテンツハッシュが識別可能である。
  • コミットの親は 1 つだけである。その親の完全な SHA が Agents-Audit-Commit と等しく、親とコミットの両方のツリーが Agents-Audit-Tree と等しい。ツリーの等価性だけでは、たまたま同じファイルを生成する異なる履歴への再生を検出できません。
  • コミットはターゲットの first-parent 履歴上にある。
  • Agents-Audit-Previous は、監査されたリビジョンの first-parent 履歴上の最も近い以前のチェックポイントを指定するか、明示的に確立された初期履歴境界の場合は none を指定する。指定されたコミット自体がチェックポイントでなければなりません。
  • メッセージには、テンプレートのすべてのレポートセクションが含まれ、宣言されたカバレッジが含まれている。Agents-Audit-Previous が none でない限り、指定されたチェックポイント内の New 所見または Carried 所見の各 ID が、Carried 所見または Closed 所見の下に表示されます。

各先行はそれ自体がチェックポイントでなければならないため、最も古いものから順に候補をチェックし、各結果を再利用します。これにより、すべてのコミットが 1 回チェックされます。これらの条件を満たす最も近い候補をベースラインとして選択します。他の候補は履歴ウィンドウ内の通常のコミットとして扱います。そのメッセージから所見やクロージャーを読み取らず、レポートやチェックポイントメッセージから除外します。 先行者が利用できないか、浅い履歴によってこれらのチェックが妨げられる場合は、そのギャップを明記します。既知の履歴境界を最後の数回のコミットで静かに置き換えたり、その作業を最初の監査と宣言したりしないでください。ベースラインを確立できない場合は、明示的な制限内で現在の状態をチェックし、履歴カバレッジは未検証のままにします。以前のチェックポイントがない真の最初の監査の場合は、現在の状態を検証し、明示的な初期履歴境界を明記します。

リベース、チェリーピック、およびスカッシュはコミットに新しい親を与えるため、履歴を書き換えた後は条件を再度確認します。機能履歴がスカッシュされた場合は、統合後に耐久性のあるチェックポイントを確立します。

チェック

正確性とポリシー

  • プロジェクト構成とその前提条件に対してコマンドを検証します。適切な環境で実行可能なチェックを実行します。失敗を、古い呼び出し、実装の欠陥、利用できない前提条件、または不完全なチェックに帰属させます。回帰を発見する有効なテストコマンドは古くなっていません。
  • 名前付き参照、パス、インポート、およびモジュールマップエントリを解決します。指示が欠落していると呼ぶ前に、名前の変更、共有所有権、および該当する祖先ルールを検査します。欠陥を実証し、次に、欠落したシンボルだけではなく、指示に従うエージェントにとっての可能性の高い結果によってその重大度を判断します。
  • 実装とテストに対して重要な不変条件を検証し、docstring とコメントを証拠ではなく主張として扱います。条件の両方の入力で条件付きの主張をチェックします。説明とポリシーを区別します。意図的なコードでも確立された境界に違反する可能性があります。タスクの権限と記録された決定を使用して競合を解決します。それに違反するコードに単に一致するようにポリシーを書き換えないでください。
  • 具体的な障害または回帰パスに対して警告を検査します。古くなった詳細や浅い詳細を削除し、バイパスしても現実的なリスクが残る場合は有用なガードレールを保持し、テストや強制によって既に適切に伝達されている説明をトリミングします。修正された障害の履歴よりも現在のガイダンスを優先します。

実証された欠陥を、古い、矛盾している、欠落している、ポリシーの競合、または古くなった警告として報告します。不確かな主張は未検証のチェックのままにします。影響を受ける指示、リポジトリの証拠、結果、および提案された修正を含めます。

メンテナンス

履歴境界以降のコード、構成、依存関係、および指示の変更を検査します。関連する各変更を、それが無効にする可能性のある主張(変更されていない指示ファイルを含む)にマッピングします。コミットメッセージのキーワードと、コードと指示を一緒に変更したコミットのオプションのカウントを使用して、検査する変更を選択します。ドキュメントの品質を判断するためではありません。

メンテナンスの欠陥は、変更が文書化された主張を無効にしたか、必要な指示を省略した場合にのみ報告します。精密な不変条件が多くの変更に触れられずに残ることを許可します。独立した修正、ブートストラップコミット、監査修復、およびチェックポイントコミットを正当な作業として扱います。クロスモジュールリファクタリングは、その主張が真のままである指示を編集する必要はありません。

決定と警告

バグ発見とは独立してアーキテクチャ上の決定を検査します。将来の変更を制限するはずの結果をもたらし、その理由がコードから明らかでない、受け入れられた選択肢を探します。記録された説明または意思決定者による確認を使用します。diff は変更を証明しますが、その意図は証明しません。証拠があり、まだ有用な場合にのみ、ルール、理由、および再検討の条件を作成します。言及する価値のある拒否された代替案は、それが影響を与えるソース内のコメントに残し、そのコードを変更するエージェントが見つけられるようにします。ブートストラップ中は、現在のソースのみを引き続き使用します。Git の履歴から理由をマイニングしたり、根拠を発明したりしないでください。

重要な診断済みバグについては、その教訓が依然としてコストのかかる、または繰り返される間違いを防ぐかどうかを確認します。有用なガイダンスを追加する場合にのみ、症状、メカニズム、および認識または回避を記録した簡潔なエントリを提案します。抽象化をバイパスすると障害が再導入される可能性がある場合は、警告を簡潔なガードレールに書き換え、その理由を説明します。メカニズムがなくなった場合、間違いが浅い場合、または強制がすでに教訓を適切に伝えている場合は、削除を提案します。不確かなメカニズムは、確認のための提案として保持します。

形式

正確性を確認した後で形式をチェックします。リポジトリ全体のルールはルートファイルに、モジュール間で共有されるルールはソースルートまたはパッケージファイル(ハブ)に、個別のモジュールルールはローカルファイル(リーフ)に配置します。個別のガイダンスが必要なスコープのみを使用します。1 ファイルのプロジェクト、複数のハブ、および空のセクションの省略を許可します。正規の説明を 1 つ保持し、発見性を向上させる場合は、リンク付きの簡潔なスコープ指定リマインダーを許可します。該当するバージョン、検証日、プラットフォーム、および測定条件を保持します。古くなった進行状況のナレーション、発明された根拠、不要な重複、および変更に役立たなくなった指示を削除します。具体性は、テキストが変更される頻度ではなく、有用な決定によって判断します。

レポート

チェックされた指示が正確であるかどうかを述べ、その結論を調査された主張に限定します。リビジョン、調査されたダーティまたは無視されたコンテンツ、指示の棚卸し、検証またはサンプリングされた主張、履歴境界、コマンドの結果、関連する環境とバージョン、および未解決のチェックを記録します。リポジトリからの相対パスと Git リビジョンを証拠として使用して、レポートをリポジトリ自体から解釈可能に保ちます。

レポートを確定する前に、ベースラインからのすべての未解決の所見を再チェックし、Carried 所見または Closed 所見の下に配置します。

所見を次のセクションに分類します。空のセクションには None と記述します。

  • 新しい安定した ID、影響を受ける指示、証拠、結果、および必要な修正とともに、新しい所見を記録します。
  • ベースラインからの未解決の所見(ベースラインが新しいものとしてリストしたものを含む)を、その ID、ソースチェックポイント(それを最初に記録したチェックポイント)、およびその証拠、結果、および必要な修正の完全な説明とともに、引き継ぎます。解決を検証できない場合は所見を開いたままにし、検証できない証拠を開示します。
  • 検証された解決または差し替えとそれを裏付ける証拠をもって所見をクローズします。各クロージャーを 1 回記録し、その後は後のレポートから省略します。その履歴は、各レポートでアーカイブを増やすのではなく、以前のチェックポイントに保持します。

ID は、廃止されたものを再利用せずに割り当てます。たとえば、監査固有の UTC タイムスタンプとカウンターを使用し、その ID をその後も保持します。監査が完了したかどうかをレポートに記載します。中断または未完了の監査はレポートで終了します。クリーンな結果は、それを実証するチェック内でのみ主張します。

チェックポイントメッセージ

完了した監査の成果物の一部として、次のメッセージを準備します。外部の課題トラッカー、ローカルレポート、またはその他の外部ソースへのポインタではなく、監査レポート自体を含めます。件名なしの件名とトレーラーを図示されたとおりに正確に使用し、レポートセクションには ## 見出しと空白行を使用します。インストールされたパスに依存するのではなく、完全なオブジェクト ID と識別可能なスキルリビジョンまたはハッシュを記録します。

chore: record agent documentation audit

## Coverage

Examined <repository-relative instruction files or directories>.
Verified <claims and checks performed, including any sampling>.
Inspected history from <history boundary> to the audited revision.
Used <relevant environment and tool versions, and where checks ran>.

## Unverified checks

<Checks not completed and their reasons, or None.>

## New findings

<Stable ID, affected instruction and section, finding, evidence,
consequence, and required correction for each new finding; or None.>

## Carried findings

<Stable ID, source checkpoint, and a self-contained account of each
unresolved finding, including evidence, consequence, and required
correction; or None.>

## Closed findings

<Stable ID, resolution or supersession, and supporting evidence
for each finding this audit closes; or None.>

Agents-Audit-Version: 1
Agents-Audit-Commit: <full audited parent commit SHA>
Agents-Audit-Tree: <audited tree SHA>
Agents-Audit-Skill-Revision: <skill revision or content hash>
Agents-Audit-Previous: <baseline checkpoint SHA or none>

チェックポイントの作成

完了した監査に対してのみ、かつその書き込みの許可がある場合にのみチェックポイントを作成します。監査されたリビジョンが依然として HEAD であり、監査された指示とコードがそのツリーに表現されていることを要求します。最初に許可された修正をコミットし、その結果のスナップショットを記録する前に検証します。修正によって監査されたリビジョンが変更された場合は、その検証されたスナップショットを説明するようにレポートとトレーラーを更新します。コミットされていない、または無視されたコンテンツをコミットされたスナップショットに関する主張から除外し、結果として生じるカバレッジ制限を記録します。ダーティな状態のチェックポイントを記録することを拒否します。あたかも…

[...truncated for translation...]

関連スキル