adk-verify-snippets

Markdown スニペットを検証する

Markdown ファイルからすべての ```python ブロックを抽出し、同梱の run.py ハーネスを介してそれぞれを個別のサブプロセスで実行し、各スニペットの読み込み状況、実行状況、行カバレッジをまとめたレポートを書き出します。

読み取り専用の取り決め

ドキュメントの検証によって、ドキュメントが変更されることがあってはなりません。検証対象の Markdown、そのコードブロック、SKILL.md を含め、リポジトリ内のファイルを作成、変更、削除しないでください。失敗を報告し、修正したりパッチを提示したりしないでください。

スクリプトが行う書き込みは次の2つだけです。一時的な .py ファイルをリポジトリ外のシステム一時ディレクトリに作成します（終了時に削除されます）。もう1つは、ソースの Markdown ファイルと同じ場所にレポートを書き出します。

前提条件

1. ADK 開発環境が必要です。リポジトリのルートから uv 仮想環境を有効にして実行してください（adk-setup スキルを参照）。

2. coverage は任意です。プロジェクトの依存関係として宣言されていないため、明示的にインストールしてください。インストールされていない場合、Coverage 列には — が表示されます。

   uv pip install coverage
   

3. Gemini API キーが必要です。ただし、Agent、App、Workflow を構築するスニペットに限ります。これらは実際の API を使用して実行されます。

   export GEMINI_API_KEY="{your_key}"
   # or
   export GOOGLE_API_KEY="{your_key}"
   

   両方が設定されている場合、ハーネスは GOOGLE_API_KEY を破棄するため、GEMINI_API_KEY が優先されます。

使い方

uv run --no-sync python .agents/skills/adk-verify-snippets/scripts/verify_md.py {path_to_markdown_file}

スクリプトはスニペットごとの進行状況を表示してから、ソースファイルと同じ場所にレポートを書き出し、その完全なパスを表示します。

レポートのファイル名は、ソースファイルの拡張子を除いた名前を小文字に変換し、[a-z0-9_] 以外の文字をすべて削除したものに _REPORT.md を付けたものです。したがって、Workflow-Guide.md の場合、Workflow-Guide_REPORT.md ではなく workflowguide_REPORT.md が生成されます。自分でパスを組み立てるのではなく、スクリプトが表示するパスを確認してください。

レポートには、スニペットごとに1行を含む Executive Summary テーブルがあり、続いて各スニペットの詳細セクションが含まれます。詳細セクションには、コードブロック、実行ログ（標準出力と標準エラー／トレースバック）、カバレッジの出力が記載されます。

各スニペットの分類方法

実行可能 — モジュールレベルの ADK コンポーネントがある

スニペットが Workflow、Agent、App のいずれかをモジュールレベル変数に割り当てている場合、ハーネスは Gemini API を使用して実行します。

• 変数名は関係ありません。ハーネスは vars(module) をスキャンします。
• 優先順位は Workflow、ルート Agent、App の順です。スニペット内のどこかに Workflow があれば、どのエージェントよりも優先されます。
• ルートエージェントは、ほかのエージェントの sub_agents に含まれていない、最初に見つかったエージェントです。そのため、複数のエージェントを含むスニペットは、エージェントの定義順にかかわらず正しく解決されます。
• App は root_agent を指定して構築されている必要があります。指定されていない場合、実行は失敗します。
• 送信されるプロンプトは "Test input topic" です。スニペット内でモジュールレベルの test_input 文字列を定義すると、上書きできます。

読み込みのみ — ADK コンポーネントがない

ハーネスはスニペットの構文とインポートを確認し、API 呼び出しは行いません。レポートには ➖ NO ADK COMPONENT と表示されます。

スキップ — ignore が指定されている

ブロックを除外するには、開始の ```python フェンスの直前の行に `` を単独で記述します。擬似コード、説明用の断片、外部のセットアップが必要なスニペットに使用してください。レポートには ⏭️ SKIPPED と表示されます。

```python
# pseudo-code — not runnable as-is
my_agent = Agent(model="gemini-ultra-hypothetical", ...)
```

正しいスニペットが壊れていると報告される原因となる制限事項

これらを回避するため、ドキュメントを編集するのではなく、`` で注釈を付けてください。

• スニペット間で状態は共有されません。 各スニペットは新しいサブプロセスで実行されるため、前のブロックでインポートしたものや定義した変数に依存するスニペットは、NameError または ImportError で失敗します。
• スニペットごとに120秒のタイムアウトがあります。 タイムアウト後にプロセスが強制終了され、スニペットは実行失敗として報告されます。
• 注釈の配置。 注釈は次の ```python フェンスに適用されます。間に空行があっても問題ありませんが、文章や見出しがあると適用されません。
• 単独の ``` はブロックを閉じます。 パーサーは言語タグのない最初のフェンスで Python ブロックを閉じるため、スニペット内のコンテンツとして使われた単独のフェンスがあると、そこで切り詰められます。タグ付きのフェンス（たとえば ```bash）はリテラルなコンテンツとして保持されるため、安全です。
• モジュールレベルの asyncio.run() はハーネス独自のイベントループと競合し、実行失敗として報告されます。スニペットでは、トップレベルの非同期呼び出しを if __name__ == "__main__": の後ろに置いてください。

ユーザーへの報告

生成されたレポートを読み、エグゼクティブサマリーの表を記載どおりにそのままコピーしてください。6列、同じ順序で、列名の変更や削除はしないでください。 Snippet | Preceding Heading | Load Phase | Run Phase | Coverage | Details 表を提示したら、そこで終了してください。