infrahub-auditing-repo

Infrahub Repo Auditor

概要

infrahub-skills プラグインのすべてのルールとベストプラクティスに照らして、Infrahub リポジトリを包括的に監査します。スキーマ、オブジェクト、チェック、ジェネレーター、トランスフォーム、メニュー、.infrahub.yml 設定、およびデプロイ準備状況を網羅する構造化されたレポートを生成します。

この監査は読み取り専用です。 書き込むファイルは、自身のレポートである AUDIT_REPORT.md ただ 1 つだけです。作業ツリーやインデックス内のそれ以外のものは一切変更されず、監査自身の副作用を元に戻す場合も含めて、それらに対して破壊的な git コマンドが実行されることはありません。監査は、コミットされていない作業を保持するツリーでこそ最も有用であり、それはまさに書き込みを元に戻せないツリーです。

rules/audit-is-read-only.md には、正規のリストが記載されています。どの git コマンドが禁止されているか、そしてどの git コマンドがツリーに触れずに別のリビジョンを読み取るかです。Phase 1 の前に、このファイルと手順の Phase 0 をお読みください。Bash ツールは読み取り専用の調査のために付与されており、状態を変更するためではありません。Write はレポートファイル専用に付与されています。

プロジェクトコンテキスト

プロジェクト構造: !find . -maxdepth 2 -type f \( -name "*.yml" -o -name "*.yaml" -o -name "*.py" -o -name "*.gql" -o -name "*.j2" \) 2>/dev/null | head -40

Infrahub 設定: !cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"

使用する場面

• リポジトリを Infrahub にデプロイする前
• 既存の Infrahub プロジェクトにオンボーディングするとき
• 大規模なリファクタリングの後に、リグレッションを検出するため
• 開発ワークフローにおける定期的な品質ゲートとして
• スキーマの読み込み、オブジェクト同期、またはパイプラインの障害をトラブルシューティングするとき

仕組み

呼び出されると、監査ツールは次のことを行います:

1. プロジェクト構造を検出します (.infrahub.yml、スキーマ、オブジェクト、チェック、 ジェネレーター、トランスフォーム、メニュー)
2. 各コンポーネントを infrahub-skills プラグインで 定義されたルールに照らして検証します
3. コンポーネント間を相互参照します(例: クエリ名が Python ファイルと .infrahub.yml の間で一致するか)
4. 重要度別に整理された検出事項を含む Markdown レポートを生成します

これらのステップをまとめる段階的な手順は audit-procedure.md にあります — 監査を実行するときはそのファイルをお読みください。これは Phase 0(他のすべてのフェーズが従う読み取り専用の制約)で始まり、 その後 9 つのフェーズ(プロジェクト構造 → スキーマ → オブジェクト → Python コンポーネント → 相互参照 → 登録 → ベストプラクティス → デプロイ → YAGNI / 修正コスト)と、最終レポートで使用される 検出事項ごとの重要度レベルを定義しています。

最初の検出事項を出力する前に、 rules/audit-cites-all-reference-sites.md と rules/audit-verifies-proposed-syntax.md をお読みください。検出事項は、どのように検証されたかを述べるか、 検証できなかった場合は verified_against でその旨を述べます — 重要度を下げることで済ませてはならず、重要度はルールに属します。 検出事項は、変更を求めるすべての参照箇所を列挙し、提案する フィルター、フィールド、または設定キーを、公開されているドキュメント ではなく監査対象のバージョンに照らして解決します。どちらもすべての フェーズに適用され、どちらも検出事項の形式にフィールドを追加します。

Phase 7 が .infrahub.yml に到達したときは、watch ブロックを 判断する前に rules/practices-watch-dependencies.md をお読みください。欠落したキー、不完全なリスト、および追跡されて いないファイルを指定するエントリは、いずれもサイレントに失敗し、 キーは提案する前に監査対象のバージョンに照らして確認する必要が あります。

監査カテゴリ

優先度	カテゴリ	チェック内容
CRITICAL	行動規範	監査はレポート以外を何も書き込まず、すべての指摘はその根拠となる証拠を開示します。これは監査者を制約するものであり、リポジトリを制約するものではありません
CRITICAL	プロジェクト構造	.infrahub.yml が存在し、パスが有効であること
CRITICAL	スキーマ検証	命名、リレーションシップ、非推奨フィールド
CRITICAL	オブジェクト検証	YAML 構造、値の型、参照
CRITICAL	Python コンポーネント	クラスの継承、必須メソッド
HIGH	相互参照	クエリ名の一致、ターゲットグループ
HIGH	リレーションシップ	双方向 ID、カーディナリティ
HIGH	登録	すべてのファイルが登録され、孤立したファイルがないこと
MEDIUM	ベストプラクティス	human_friendly_id、display_label、watch 依存関係
MEDIUM–LOW	YAGNI / 修正コスト	スキーマ、GraphQL、Jinja2、または組み込みの IPAM/VLAN で実現できることを Python で行っている場合、非正規化されたデータ、抽出されていない重複形状、マーケットプレイスが出荷しているのに一から手作りされたドメイン全体。重要度は修正コストのはしごに沿って決まります。ステップ 1〜3 は MEDIUM、ステップ 4〜7 は LOW
MEDIUM	デプロイ	Git ステータス、ブートストラップの配置
LOW	パターンとスタイル	コード構成、命名

監査の実行

Claude に次のように伝えてください: 「Audit this Infrahub repo」 または 「Run the Infrahub repo auditor」

監査者は現在の作業ディレクトリをスキャンし、 audit-procedure.md で定義されたフェーズを順にたどり、 以下で説明するレポートを生成します。

レポート形式

レポートはプロジェクトルートの AUDIT_REPORT.md に次の構造で書き込まれます:

# Infrahub Repository Audit Report

## Summary

- Total findings: N
- Critical: N | High: N | Medium: N | Low: N | Info: N
- Working tree at audit time: clean | N uncommitted files
- Tree modified by this audit: no | yes, listing paths
  (the report file itself does not count)

## Project Structure

...

## Schema Audit

...

## Object Data Audit

...

## Checks Audit

...

## Generators Audit

...

## Transforms Audit

...

## Menus Audit

...

## Cross-Reference Integrity

...

## Deployment Readiness

...

## YAGNI / Cost-to-Fix Findings

Findings sorted by `ladder_step` ascending (cheapest
fix first), then by file path. Each entry names the
rule, the ladder step, the file:line, and the
suggested replacement (schema feature, GraphQL query,
Jinja2 template, `Builtin*`/`Ipam*` inheritance, or
inverse relationship declaration).

A finding also renders the evidence it carries: a
**Sites** line listing every reference the fix must
touch, a **Verified against** line naming what the
proposed syntax was resolved against, and, on a
generic-extraction finding, a **Feasibility** verdict.

...

監査ルールリファレンス

監査者はすべてのスキルのルールをチェックします:

• ../infrahub-managing-schemas/ -- 命名、 リレーションシップ、属性、階層、表示、 拡張、一意性、マイグレーション
• ../infrahub-managing-objects/ -- フォーマット、 値、子、範囲、構成
• ../infrahub-managing-checks/ -- アーキテクチャ、Python クラス、API、登録
• ../infrahub-managing-generators/ -- アーキテクチャ、Python クラス、トラッキング、API
• ../infrahub-managing-transforms/ -- 型、Python/Jinja2、ハイブリッド、アーティファクト、API
• ../infrahub-managing-menus/ -- フォーマット、 アイテムのプロパティ、階層、アイコン
• ../infrahub-common/ -- Git 連携、 キャッシュ、.infrahub.yml リファレンス、GraphQL
• ../infrahub-common/rules/workflow-information-priority.md -- スキルの内容を優先し、真に不足がある場合（例: ノードの削除）に docs.infrahub.app を参照する方法

ルールと手順

• audit-procedure.md — すべての監査実行を 駆動する、フェーズ 0 の制約と 9 フェーズのウォークスルー
• rules/ — 各フェーズから参照される 詳細な監査ルール定義
• examples.md — 監査レポートの サンプルと指摘パターン