adk-unit-guide

ADK コードユニットガイド

ユニットガイドは、1つのコードユニットの使い方を詳しく説明するドキュメントです。adk.dev に掲載されている内容よりも踏み込んだ情報を扱い、公開ドキュメントに含めると膨らみすぎる詳細を記載します。読者はアプリケーションからそのユニットを呼び出そうとしているため、まず動作するコードを示します。

ユニットガイドでは、公開 API と呼び出し側から見える動作に焦点を当てます。内部実装の詳細、たとえばプライベートメソッド、内部状態の仕組み、エクスポートされていないヘルパーについては説明しないでください。

文体

上から指示するのではなく、読者の理解を助けるように書いてください。

• ルールだけでなく、その理由も示します。 制約、デフォルト、推奨事項を記載するときは、そうなっている理由も説明してください。理由がわかれば、ガイドで想定されていないケースにも読者が対処できます。
• 読者に代わって判断しないでください。 「ほとんどのアプリケーションでは必要ありません」や「使うことはほとんどないでしょう」といった表現は、読者の意向を決めつけます。トレードオフを示し、選択は読者に委ねてください。
• 呼び出し側の視点で説明してください。 何が起きるかの説明は必要ですが、それを実現する仕組みの説明は必要ありません。説明にプライベートなシンボルが必要なら、説明のレイヤーが適切ではありません。
• 理解に必要な長さにします。 簡潔さを目的にしないでください。読者が次に疑問を持つ箇所には答え、説明が十分な箇所には付け加えないでください。
• 構文より先に問題を説明します。 読者が何をしようとしているかを述べてから、コードを示してください。
• すべての見出しの下に、次の見出しが来る前に少なくとも1文を記載してください。また、すべてのコードブロックについて、その内容を紹介する文を添えてください。

文レベルのルールは、Google の開発者向けドキュメントのスタイルガイドに従います。現在形を使い、短縮形や括弧書きを避けます。括弧書きの代わりに読点を使い、主語が単独の「This」になる表現、「e.g.」や「etc.」、最上級表現を使いません。見出しは文頭のみ大文字にし、H3 より深い見出しは使いません。

違いの例

BaseNode ガイドから。変更前：

ほとんどのアプリケーションでは BaseNode をサブクラス化しないため、以降のセクションではまず設定について説明します。

これは読者に代わって判断しており、自分のケースを判断する材料も示していません。変更後：

通常はノードをサブクラス化するのではなく設定します。以下の設定で、ほとんどのグラフに必要な内容を指定できるためです。設定で表現できない動作が必要な場合はサブクラス化が有効で、そのケースについては最後に説明します。

長さも事実も同じです。後者では理由を示しているため、読者はどちらの状況に当てはまるかを判断できます。

2つ目は、JoinNode ガイドからの例です。変更前：

ここでは、同じ入力に対して3つのタスクを並列に実行し、JoinNode がその結果を集めます。

これはドキュメントというより話し言葉で始まり、読者が検索するパターンの名前も示していません。変更後：

この例では、ファンアウト／ファンインのワークフローを構築します。3つのタスクが同じ入力に対して並列に実行され、JoinNode が結果を集約するため、最後のノードですべての結果をまとめて提示できます。

入力

ソースファイル、またはその中で名前が挙げられているクラスやメソッドを必ず確認してください。また、存在する場合は、ユニットテストと設計ドキュメント docs/design/{topic}/{unit}/index.md も確認してください。ユニットテストは、応用できる例を示してくれます。

執筆前の分析

• ユニットの目的と想定される用途。
• そのユニットに依存するクラスと、そのユニットが依存するクラス。
• 継承したものを除き、そのユニット自体が導入する設定オプション。
• 既知の制限事項。
• プライベートメソッドや属性、内部ヘルパー関数、プライベートな実行状態、内部データ構造などの内部実装の詳細は除外します。

ガイドの配置先

docs/guides/ の下にソースのパスを反映し、単位ごとにディレクトリを作成し、ガイドのファイル名は index.md にします。非公開モジュールの先頭のアンダースコアは取り除きます。

ソース	ガイド
src/google/adk/workflow/_function_node.py	docs/guides/workflow/function_node/index.md
src/google/adk/plugins/reflect_retry_tool_plugin.py	docs/guides/plugins/reflect_retry_tool_plugin/index.md

1 つのソースファイルに、実質的に別々の使用方法がある場合に限り、index.md ではなく名前付きファイルを使います。docs/guides/agents/llm_agent/ に single_turn.md と task.md があるのはこのためです。

既存のガイドはその場で更新し、コードに変更がない部分の既存の文言は維持してください。そうすることで、差分には実際に変更された箇所だけが表示されます。

次に、ガイドを docs/guides/README.md の適切なカテゴリ見出しの下に、* [タイトル](path/index.md) - 1 行の概要。 の形式で追加します。このインデックスが唯一の目次です。インデックスにないガイドにはたどり着けません。

ガイドが不要な場合

scripts/check_new_py_files.py は、変更で src/google/adk/ の下に追加される Python ファイルにこの規則を適用します。一部のファイルは確認なしに対象外となり、残りは免除できます。規則で求められていないガイドを書く前に、自分がどのケースに当てはまるかを確認してください。

次の 3 つのサブツリーは、公開されるものがないため規則の対象外です。 src/google/adk/internal/、src/google/adk/platform/internal/、src/google/adk/v1/。

それ以外のファイルは、2 つの理由のいずれかで免除されます。1 つ目は、そのファイル自体に単位がない場合です。これには __init__.py と、パスに cli/ または utils/ が含まれるファイルが該当します。2 つ目は、そのファイルに含まれる宣言が独立したガイドではなく、それを使う側のガイドに記載されるべき場合です。これには、ファイル名が _utils.py、_helper.py、_helpers.py、_types.py、_errors.py、_exceptions.py、_constants.py のいずれかで終わるファイルが該当します。

パッケージの __init__.py からインポートも参照もされていないモジュールも免除されます。その場合、ガイドで説明する公開インターフェースがないためです。このチェックでは、src/google/adk/ の下にあるすべての __init__.py を読み込み、遅延再エクスポートも対象にします。if TYPE_CHECKING: の下や __getattr__ 内にあるインポート、遅延インポートのテーブル内でモジュール名を示す文字列も該当します。先頭の _ の有無は関係ありません。そのため、新しいモジュールから名前をエクスポートすると、そのモジュールにはガイドが必要になります。

これ以外のものには、ガイドまたは免除指定が必要です。免除指定には理由を添えた NO_UNIT_GUIDE= または SKIP_UNIT_GUIDE= タグを使います。この 2 つのタグは同じように機能します。免除されるのは単位ガイドの要件だけです。_ 接頭辞の規則も同じ仕組みと同じエラー報告を使いますが、免除する方法はありません。1 つのタグは、理由に記載されたファイルだけでなく、変更で追加されるすべてのファイルを免除します。そのため、複数のファイルを追加する変更では、それらすべてを網羅する理由が必要です。

タグは、ガイドがない理由を示す唯一の記録になります。理由は、レビュー担当者がコードを確認して判断できるように記述してください。

NO_UNIT_GUIDE=InvocationNotFoundError is covered by docs/guides/errors/index.md.

免除タグの記載場所

タグは、コミットメッセージまたは環境変数を通じてチェックに渡します。どちらを使うかは、コミットがすでに存在するかどうかによって決まります。

コミットが存在する場合は、そのメッセージにタグを記載します。継続的インテグレーションは、プルリクエストに含まれるコミットのメッセージを読み取るため、コントリビューターがそこに記載した免除タグによって、プルリクエストをブロックするチェックを満たせます。チェックは行頭で一致するため、= の前にスペースを入れず、行頭からタグを記載してください。インデントされたタグやリスト項目内のタグは見つからず、見つからなかったことも報告されません。

まだコミットが存在しない場合は、環境変数を通じてタグを渡します。

NO_UNIT_GUIDE='covered by docs/guides/errors/index.md' git commit ...

この形式は、プリコミットフックによって処理が止められた場合に使います。プリコミットフックは git がメッセージをどこかに記録する前に実行されます。また、チェックは前のコミットのメッセージを代わりに読み取らないため、使える経路は環境変数だけです。理由は引用符で囲んでください。引用符で囲まないと、理由は最初のスペースで切られ、シェルは次の単語を実行するコマンドとして扱うため、コミットがまったく行われません。理由がシェル内だけに残らず履歴に記録されるよう、メッセージにもタグを記載してください。

どちらの経路でも、理由のないタグでは免除されません。理由だけが判断の記録となるため、理由のない免除にはレビューできる情報が残りません。

コード例

• 「Get started」の下に、呼び出しをどこに置くかが分かる程度の周辺クラスを含めた、最小限の例を1つ記載してください。ユニットテストがある場合は、そこから始めてください。
• google.adk のインポート行は残してください。読者がコピーする際に最も間違えやすいのはインポートパスだからです。関係のない標準ライブラリのインポートや、内容の理解に役立たない asyncio.run(main()) の実行用ボイラープレートは省略してください。
• 開発者が実際に書くコードを示してください。インターフェースの形だけを示す例や、読者が通常 Runner 経由で使うサービスを直接操作する例は、ガイドには適しません。
• サンプルエージェントに model= を設定しないでください。ガイドでは特定のモデルに依存しないようにし、現在 docs/guides/ にあるガイドではモデルを固定していません。
• ワークフローノードでは、ユースケース上サブクラスが本当に必要な場合を除き、BaseNode のサブクラスではなく、通常の Python 関数としてロジックを示してください。
• 関数をノードとして使うには、FunctionNode を直接使うのではなく、@node デコレーターでラップしてください。ただし、FunctionNode 自体の設定方法を示す場合は除きます。

関連サンプルへのリンク

GitHub の URL ではなく、ガイドからのリポジトリ相対パスでサンプルにリンクしてください。 [Node Output](../../../../contributing/samples/workflows/node_output/agent.py)。 リンクする前に、そのファイルが存在することを確認してください。

構成

references/guide-template.md に、セクションごとに従ってください。