エージェント利用ガイド

[TOC]

エージェントの仕組み

AI モデルは単一の呼び出しです——プロンプトを送ると、レスポンスが返ってきます。エージェントは、その同じモデルがループで動作しているものです。すなわち、あなたのリクエストを受け取り、アクション（ファイルの読み取り、コマンドの実行、コードの編集）を決定し、結果を観察し、タスクが完了するまでこれを繰り返します。

より深く知るには、Anthropic の building effective agents の解説を参照してください。

MCP の仕組み

MCP (Model Context Protocol) サーバーは、エージェントを外部のツールやデータソース——GitLab、dbt、Slack などを思い浮かべてください——に接続することで、エージェントができることを拡張します。アクティブな各 MCP はエージェントのコンテキストウィンドウに加わるため、目の前のタスクで実際に必要なものだけを有効にしてください。

すべての連携が MCP サーバーというわけではありません。Snowflake MCP サーバーは保守されなくなったため、Snowflake へのアクセスには Snowflake CLI（snow）を使用します。エージェントはこれをほかのコマンドラインツールと同様に呼び出します。

設定

どちらのツールもグローバル設定とプロジェクトレベルの設定をマージし、衝突したときにはプロジェクトの設定がグローバルの設定を上書きします。

グローバル設定は最小限に保ってください。そこに置く価値がある主なものは、何に取り組んでいるかにかかわらずあらゆるセッションで必要となる MCP です。それ以外のすべて——特に dbt-mcp のようなリポジトリ固有の MCP——はプロジェクトの設定に属します。たとえば、dbt-mcp は analytics リポジトリでのみ関連するため、そのリポジトリの設定にのみ存在します。

良い目安: どのプロジェクトの外でエージェントを開いたときでもその MCP をアクティブにしておきたいなら、それはグローバルに入れます。そうでなければ、ローカルに留めます。

Claude Code では手動で編集するよりも /config を使用してください。設定ファイルへの書き込みを代行します。

ベストプラクティス

コンテキストはスリムに保ってください。焦点を切り替えるとき——新しい機能、別のバグ、無関係なレビュー——はいつでも新しい会話を始めてください。迷ったら、新しいウィンドウにします。Claude Code では /clear、OpenCode では /new を使ってそれを行います。これは、レスポンスの品質を向上させるとともに、コストも改善します。

あなたが行っていることに対応するスキルが存在するなら、それを使ってください——スキルは、そうでなければ得られないドメイン固有のコンテキストをエージェントに与えます。

Analytics Engineer

AE チームは、dbt モデルの構築と変更、MR レビューフィードバックへの対応、パイプライン障害のトラブルシューティング、データのテストと検証、データセットの探索、Slack スレッドやレビューコメントなどのコンテキストからの Issue 作成まで、開発ライフサイクル全体で OpenCode を使用します。

推奨ワークフロー

• 新規または不慣れなタスクでは、まず Plan モードで開始します。変更を加える前に提案されたアプローチをレビューしてください
• 十分に理解しているタスクでは、直接 Build または AE エージェントに進みます
• プロンプトは「I want to…」で始め、取り組んでいる変更、レビューコメント、または質問を説明します
• MR レビューでは、そのレビューにスコープを限定した新しいセッションを開きます
• 2 つのモードの詳細は、以下の Plan モードを使うタイミングを参照してください

セッション管理、モデル選択、コスト効率

• MR、トピック、または日ごとに新しいセッションを開始します。前のコンテキストが次のタスクに実際に必要かを判断し、不要なら新しく開始します
• Sonnet 4.6 のような中規模モデルが推奨されるデフォルトモデルです。品質、速度、コストのバランスがよく、ほとんどの AE タスクでは大規模モデルほど遅く高価になっても、それに見合う向上はありません
• 入力トークンはセッションで最も高価な要素のようです。コンテキストをスリムに保ち、大きくなったら /compact を使い、200K トークンのしきい値に達する前に新しいセッションを開始してください
• 現在のタスクに必要な MCP だけを有効にします。OpenCode では /mcps で space を押してサーバーのオンとオフを切り替えます。Claude Code では /mcp で接続済みのサーバーを一覧表示し、読み込むサーバーは設定で指定します

データアクセスのセットアップ

ほとんどの AE 開発作業では Snowflake CLIが必要です。エージェントはこれを使ってセッション中に Snowflake にクエリを実行します。dbt のモデル構造、リネージュ、ノード詳細を把握するために、さらに dbt MCP サーバーを追加するとよいでしょう。

Plan モードを使うタイミング

どちらのツールも計画と実行を分離しています。

• Plan モード — あなたのリクエストと関連するコードをレビューし、変更を加える 前に 詳細なアプローチを提案します
• 実行 — OpenCode の Build モード、Claude Code のデフォルトモードまたは編集を許可するモードでは、変更を直接実行します

些細でないものについては、常にまず Plan モードを実行してください。すでに実装の途中にいる前にデザインの問題を捉えることに、驚くほど長けています。

セットアップガイドでは、どちらのツールでも Plan をデフォルトにすることを推奨しています。defaultMode については Claude Code のセットアップ、デフォルトエージェントについては OpenCode のセットアップを参照してください。そのうえで、実行する準備ができたら、明示的に Plan モードを終了します。

スキル

スキルは、再利用可能でチーム固有の知識——慣習、ワークフロー、そして、そうでなければ毎セッション説明し直す必要があるベストプラクティス——をエンコードします。ゼロからプロンプトを書くのではなく、スキルを呼び出すことで、エージェントに正しいコンテキストを即座に与えられます。

スキルの使い方

スキルは、あなたのプロンプトで説明されたタスクがスキルのフロントマターのメタデータと一致したときに、Claude Code や OpenCode のような AI コーディングツールによって自動的に呼び出されます。よく書かれたフロントマター（特に name と description のフィールド）は、自動的な発見を可能にします。スキルが存在することを知っている場合は、プロンプト内で名前を挙げて明示的に言及することもできます。

利用可能なスキル

Data Team によって開発されたスキルの一覧は、Agentic Tool Development ガイドの Available Skills セクションを参照してください。

セットアップ

Claude Code または OpenCode でスキルを有効にするには、エージェントセットアップガイドのスキルのセットアップの手順に従ってください。

ページのソースコードを見る - ページの編集 - please contribute.