adk-review

ADK 変更レビュアー

以下の7つの観点に照らして作業ツリーの差分をレビューし、問題点を報告したら終了してください。その後、ユーザーが依頼したものだけを修正してください。

ワークフロー

1. git status と git diff（ステージ済みの変更の場合は --staged を追加）を使い、追加、変更、削除されたファイルを正確に把握します。
2. チェックリストに照らして、ファイルごとに差分をレビューします。
3. 以下の形式でレポートを出力します。
4. 終了します。ファイルは編集せず、編集の申し出もしないでください。ユーザーからの依頼を待ちます。
5. ユーザーから修正を依頼された場合は修正し、影響を受けるテスト（pytest tests/unittests/{path}）と pre-commit run --files {paths} を再実行します。

手順4は間違えやすい部分です。依頼されていない修正を行うと、ユーザーが求めた指摘が埋もれ、レビュー結果に未レビューの変更が混在してしまいます。

チェックリスト

1. 正確性

• 型：新たな mypy エラーがないこと。CI では mypy の出力をベースブランチと比較し、新たに導入されたエラーだけで失敗するため、変更したファイルに既存のエラーがあっても問題にはなりませんが、新たなエラーは問題です。
• インポート：循環インポートがないこと。モジュール内ですでに絶対インポートが使われている場合は、絶対インポートを使うこと。
• 例外：裸の except: を使わないこと。具体的な型を捕捉し、呼び出し元を特定するのに十分なコンテキストをログに記録すること。
• 型の判別：型固有の属性を読み取る前に、オブジェクトの型を確認すること（たとえば、mode を調べる前にノードが LlmAgent であることを確認する）。これにより、予期しないノード型でも例外が発生しません。
• 境界値：None、空のコレクション、ゼロ、空文字列が、検証またはフォールバックのデフォルト値によって処理されること。
• 事前条件：中核となるロジックの実行前に、状態の不変条件が確認されていること。

2. 設計

• 複雑さ：分割したほうが明確になる関数やクラスがないこと。
• 結合度：凝集度が高く、結合度が低いこと。アンチパターンが新たに導入されていないこと。
• パフォーマンス：不要な計算、ループ内での反復 I/O、または入力に応じて増加する不要なメモリ割り当てがないこと。
• セキュリティ：入力が検証されていること。機密データがログに記録されず、インジェクション、リソース枯渇、内部状態の漏えいがないこと。

3. スタイル

ここでルールを繰り返すのではなく、adk-style スキルを参照して差分を確認してください。可視性と _ 接頭辞、型付け、Pydantic v2 のパターン、遅延ロギング、インポート、非同期処理、ファイル構成を確認します。

変更されたファイルが pre-commit run --files {paths} を通過することを確認してください。

4. アーキテクチャと意図しない結果

• パブリック API の安定性：この変更によって、src/google/adk/ 配下のパブリックインターフェース、クラス、メソッド、引数リスト、CLI の仕様が変更、削除、または縮小されますか？パッケージはセマンティックバージョニングに基づいてリリースされ、ユーザーはマイナーバージョンを固定しているため、後方互換性を損なう変更の前には、まず非推奨化の期間が必要です。
• Session、Artifact、Memory サービスの変更：Session、ArtifactVersion、MemoryEntry、または BaseSessionService、BaseArtifactService、BaseMemoryService とそれらのスキーマに新しいフィールドを追加することは、後方互換性を損なう変更です（オプションやデフォルト値のあるフィールドでも同様です）。既存の下流ストレージサブクラスや外部バックエンドは未知のフィールドを永続化またはデシリアライズしないため、再読み込み時に状態が通知されないまま失われます。
• 実行と再開：ワークフロー、ノード、状態への変更は、イベント実行のライフサイクルおよびセッションの再開（人間が介在するステップとチェックポイント）との互換性を維持する必要があります。adk-architecture スキルを参照してください。
• 並行性とライフタイム：競合状態が発生しないこと。プラグイン、エクスポーター、接続は、エラー時を含むすべての経路でクローズされること。
• データベースとランタイムの DDL 安全性：ランタイムの起動処理（例：DatabaseSessionService.prepare_tables() と _ensure_schema_indexes_exist()）では、DROP INDEX のような破壊的な DDL を決して実行してはいけません（ACCESS EXCLUSIVE ロックを取得し、ローリングデプロイやロールバックを妨げるため）。追加のみのランタイム DDL では、複数コンテナーの起動時の競合に対処する必要があります（プロセス内の asyncio.Lock では、checkfirst=True におけるコンテナー間の TOCTOU 競合を防げません）。作成処理を SAVEPOINT（connection.begin_nested()）で囲み、同時作成を許容してください。
• スコープ：修正に不要な新しいパブリック名、パラメーター、フラグ。バグのある動作をデフォルトのまま維持するフラグ。必要とした呼び出し元が 1 つなのに共有レイヤーで行う修正。新しい動作に合わせて編集された既存のテストアサーション。

5. ドキュメントへの影響

• ユーザー向けドキュメントは別の adk-docs リポジトリにあるため、ユーザーから見える変更には、そちらへの PR も必要です。レポートに記載してください。
• パブリック API やワークフローのパターンが変わる場合は、docs/guides/ 配下のガイドも更新が必要になることがあります。
• 変更によってコード単位の設計上の契約が変わる場合、その単位の設計ドキュメントは adk-unit-design スキルが管理します。

6. サンプル

• contributing/samples/ 配下の既存サンプルは、変更後も実行できますか？
• 新しい機能にサンプルを追加する価値はありますか？追加する場合は、adk-sample-creator の規約に従ってください。

7. テスト

• 新規または変更したすべてのコードパスに対して、tests/unittests/ 配下にテストがあること。
• 新しいテストは、変更名にちなんだファイルではなく、その単位の既存の test_{module}*.py ファイルに追加してください。変更名にちなんだファイルにすると、その単位のテストカバレッジが分散します。
• テストは adk-style のテストリファレンスに記載されたルールに従ってください。1 つのテストにつき 1 つの動作を検証すること、動作を表す名前を付けること、プライベート属性をアサーションしないこと、フィクスチャを最小限にすること、Arrange／Act／Assert の構成にすること。

各指摘の根拠を示す

指摘を報告する前に、基底クラスをたどってシンボルを確認してください（Event は LlmResponse を継承します）。正確性に関する指摘では、失敗を引き起こす入力を示してください。それ以外の指摘では、違反しているルールまたは規約を引用してください。どちらにも該当しない指摘は推測にすぎないため、報告しないでください。

レポート形式

指摘を優先度ごとにまとめ、それぞれにファイルパスと行番号を記載してください。指摘のない項目は報告しないでください。

• 🔴 重大：バグ、型エラー、競合状態、リソースリーク、セキュリティ上の問題。
• 🟠 設計：複雑さ、可読性、パフォーマンス、アーキテクチャとの不整合。
• 🟡 スタイル：リンティング、書式、遅延評価されないログ出力、型の不一致。
• 🔵 ドキュメント、テスト、サンプル：カバレッジ、ガイド、サンプルの不足または古さ。