adk-dev-guide

ADK 開発ワークフローとガイドライン

セッションの継続性

セッションが長時間に及ぶ場合は、各フェーズの前に関連するスキルを再読してください。 コードを書く前に /adk-cheatsheet、評価を実行する前に /adk-eval-guide、 デプロイする前に /adk-deploy-guide、スキャフォールディングの前に /adk-scaffold を確認してください。 コンテキストの圧縮によって、以前のスキルの内容が失われている可能性があります。

---

DESIGN_SPEC.md — 最優先のリファレンス

重要：このプロジェクトに DESIGN_SPEC.md がある場合、それが最優先の信頼できる情報源です。

まずこれを読み、以下を把握してください。

• 機能要件と機能
• 成功基準と品質しきい値
• エージェントの動作上の制約
• 想定されるツールと統合

仕様は契約です。 実装に関するすべての判断は、仕様に沿っている必要があります。判断に迷ったら、DESIGN_SPEC.md を再確認してください。

---

フェーズ 1：仕様を理解する

コードを書く前に、次の手順を実行してください。

1. DESIGN_SPEC.md を隅々まで読む
2. 必要となる中核機能を特定する
3. 制約や、エージェントがしてはならないことを確認する
4. 評価の成功基準を理解する

フェーズ 2：構築と実装

エージェントのロジックを実装します。

1. エージェントのディレクトリ内でコードを記述・変更します（ディレクトリ名は、GEMINI.md や CLAUDE.md などのエージェント向けガイダンスファイルを確認してください）
2. 開発中の対話的なテストには make playground（または adk web .）を使用します
3. ユーザーからのフィードバックに基づいて実装を反復改善します

ADK API のパターンやコード例については、/adk-cheatsheet を使用してください。

フェーズ 3：評価

最も重要なフェーズです。 評価では、evalset とスコアリング指標を使用して、エージェントの動作をエンドツーエンドで検証します。

必須： 評価を実行する前に /adk-eval-guide を有効にしてください。evalset のスキーマ、設定形式、重要な注意事項が記載されています。省略しないでください。

テスト（pytest）は評価ではありません。 テストで検証できるのはコードの正しさであり、エージェントが正しく動作するかどうかは分かりません。必ず adk eval を実行してください。

1. 小さく始める：スイート全体ではなく、サンプル評価ケースを 1～2 件から始めます
2. 評価を実行します：adk eval（またはプロジェクトに Makefile がある場合は make eval）
3. 結果についてユーザーと話し合います
4. 問題を修正し、まず中核ケースを反復改善します
5. 中核ケースに合格してから、エッジケースや新しいシナリオを追加します
6. 品質しきい値を満たすまで繰り返します

ここでは 5～10 回以上の反復を想定してください。

フェーズ 4：デプロイ

評価のしきい値を満たしたら：

1. 準備ができたらデプロイします。デプロイ方法については /adk-deploy-guide を参照してください

重要：人間から明示的な承認を得ずにデプロイしてはいけません。

---

コーディングエージェント向け運用ガイドライン

原則 1：コードの保持と分離

コードを変更する際に最優先すべきことは、変更範囲を厳密に限定することです。ユーザーの依頼で直接指定されたコード部分のみを変更し、それ以外の周辺コードや無関係なコードは必ずそのまま保持してください。

実行前の必須確認：

コードの置き換えを確定する前に、次の点を確認してください。

1. 対象の特定： ユーザーの明示的な指示だけを根拠として、変更する行または式を正確に定めます。
2. 保持の確認： 特定した対象の外にあるすべてのコード、設定値（例：model、version、api_key）、コメント、書式が変更されていないことを確認します。

例：

• ユーザーの依頼：「エージェントの指示をレシピ提案者に変更してください。」
• 誤り（違反）：

  root_agent = Agent(
      name="recipe_suggester",
      model="gemini-1.5-flash",  # 意図しない変更 - モデルの変更は依頼されていない
      instruction="You are a recipe suggester."
  )
  

• 正しい（準拠）：

  root_agent = Agent(
      name="recipe_suggester",  # OK、新しい目的に関連
      model="gemini-3-flash-preview",  # 保持
      instruction="You are a recipe suggester."  # OK、直接の変更対象
  )
  

原則 2：実行のベストプラクティス

• モデルの選択 — 重要：

  • 明示的に依頼されない限り、モデルは絶対に変更しないでください。 コードで gemini-3-flash-preview が使われている場合は、gemini-3-flash-preview のままにしてください。モデル名を「アップグレード」したり「修正」したりしないでください。
  • 新しいエージェントを作成する場合（既存のエージェントを変更する場合を除く）は、Gemini 3 シリーズを使用してください：gemini-3-flash-preview、gemini-3-pro-preview。
  • ユーザーが明示的に指定しない限り、古いモデル（gemini-2.0-flash、gemini-1.5-flash など）は使用しないでください。

• モデルよりロケーションが重要です：

  • モデルが 404 を返す場合、ほとんどの場合は GOOGLE_CLOUD_LOCATION の問題です（例：us-central1 ではなく global が必要）。
  • 404 を「修正」するためにモデル名を変更するのは違反です。代わりにロケーションを修正してください。
  • 一部のモデル（gemini-3-flash-preview など）には特定のロケーションが必要です。エラーメッセージに手掛かりがないか確認してください。

• ADK 組み込みツールのインポート（正確さが必要）：

  # 正しい - ツールのインスタンスをインポート
  from google.adk.tools.load_web_page import load_web_page
  
  # 間違い - ツールではなくモジュールをインポート
  from google.adk.tools import load_web_page
  

  インポートしたツールは tools=[load_web_page] に直接渡してください。tools=[load_web_page.load_web_page] ではありません。

• Python コマンドの実行：

  • Python コマンドの実行には、必ず uv を使用してください（例：uv run python script.py）。
  • スクリプトを実行する前に、make install（または uv sync）を実行してください。
  • 利用可能なコマンドがある場合は、Makefile と README.md を確認してください。

• 無限ループの停止：

  • 同じエラーが 3 回以上連続して発生した場合は、直ちに停止してください。
  • 失敗した操作を再試行しないでください。まず根本原因を修正してください。
  • 危険信号： ロック ID が増加する、名前が v5→v6→v7 のように追加される、「もう一度だけ試します」と何度も繰り返す。
  • 状態の競合（エラー 409：リソースがすでに存在します）：作成を再試行する代わりに、terraform import で既存のリソースをインポートしてください。
  • ツールのバグ： 続行する前にソースコードのバグを修正してください。回避策で済ませないでください。
  • 行き詰まった場合： 問題のあるツールを呼び出すのではなく、基盤となるコマンドを直接実行してください（例：terraform CLI）。

• トラブルシューティング：

  • まず /adk-cheatsheet を確認してください。よくあるパターンのほとんどが説明されています。
  • Glob/Grep/Read を使ってインストール済みの ADK パッケージを検索してください（python -c "import google.adk; print(google.adk.__path__[0])" で場所を確認します。uv を使う場合は uv run python を使用してください）。
  • ADK ドキュメントのインデックスには、curl https://adk.dev/llms.txt を使用してください。
  • フレームワークに関する質問や GCP 製品については、公式ドキュメントを確認してください。
  • エラーが解消されない場合は、対象を絞った Google 検索を行うと、より早く解決策が見つかることがよくあります。

---

ひな形を参考にする

特定のインフラストラクチャファイルが必要でも、現在のプロジェクトに直接ひな形を作成したくない場合は、/adk-scaffold スキルを使って /tmp/ に一時的な参考プロジェクトを作成し、必要なものをコピーしてください。

CLI コマンドとオプションの詳細については、/adk-scaffold を参照してください。

---

開発コマンド

Agent Starter Pack CLI で作成したプロジェクトには、以下のコマンドを含む Makefile が用意されています。 プロジェクトの作成や拡張については、詳しい手順が記載された /adk-scaffold スキルを参照してください。 ひな形を使わずに作成したプロジェクトでは、ADK CLI の同等のコマンドを使用してください。

Make（ひな形を使用）	ADK CLI の同等コマンド	用途
make playground	adk web .	対話形式でローカルテストを実行
make test	pytest	単体テストと統合テストを実行
make eval	adk eval <agent_dir> <evalset>	evalset に対して評価を実行
make lint	ruff check .	コード品質をチェック
make setup-dev-env	—（ひな形を使用した場合のみ）	開発用インフラストラクチャをセットアップ（Terraform）
make deploy	—（ひな形を使用した場合のみ）	開発環境にデプロイ（人間の承認が必要）

---

スキルのバージョン

トラブルシューティングのヒント： 繰り返しエラーが発生する場合、ツールが予期せず失敗する場合、またはスキル内の説明が不完全に思える場合や、見つからない機能に言及している場合は、スキルが古くなっている可能性があります。次を実行してください：

npx skills check -g

古くなったスキルが報告された場合は、ユーザーに更新するよう伝えてください：

npx skills update -g

スキルが古くなっていることが問題の原因だと思われる場合に限り、このチェックを実行してください。毎回のセッションで実行する必要はありません。