エージェント利用ガイド
[TOC]
エージェントの仕組み
AI モデルは単一の呼び出しです——プロンプトを送ると、レスポンスが返ってきます。エージェントは、その同じモデルがループで動作しているものです。すなわち、あなたのリクエストを受け取り、アクション（ファイルの読み取り、コマンドの実行、コードの編集）を決定し、結果を観察し、タスクが完了するまでこれを繰り返します。
より深く知るには、Anthropic の building effective agents の解説を参照してください。
MCP の仕組み
MCP (Model Context Protocol) サーバーは、エージェントを外部のツールやデータソース——Snowflake、GitLab、dbt、Slack などを思い浮かべてください——に接続することで、エージェントができることを拡張します。アクティブな各 MCP はエージェントのコンテキストウィンドウに加わるため、目の前のタスクで実際に必要なものだけを有効にしてください。
設定
OpenCode は、実行時にマージされる 2 つの設定ファイルを使います——グローバル設定 (~/.opencode/config.json) と、プロジェクトレベルの設定（リポジトリのルートにある .opencode/config.json）です。プロジェクトの設定は、衝突したときにグローバルの設定を上書きします。
グローバル設定は最小限に保ってください。そこに置く価値がある主なものは、何に取り組んでいるかにかかわらずあらゆるセッションで必要となる MCP です。それ以外のすべて——特に dbt-mcp のようなリポジトリ固有の MCP——はプロジェクトの設定に属します。たとえば、dbt-mcp は analytics リポジトリでのみ関連するため、そのリポジトリの設定にのみ存在します。
良い目安: どのプロジェクトの外で OpenCode を開いたときでもその MCP をアクティブにしておきたいなら、それはグローバルに入れます。そうでなければ、ローカルに留めます。
ベストプラクティス
コンテキストはスリムに保ってください。焦点を切り替えるとき——新しい機能、別のバグ、無関係なレビュー——はいつでも新しい会話を始めてください。迷ったら、新しいウィンドウにします。OpenCode では、/new コマンドを使ってそれを行います。これは、レスポンスの品質を向上させるとともに、コストも改善します。
あなたが行っていることに対応するスキルが存在するなら、それを使ってください——スキルは、そうでなければ得られないドメイン固有のコンテキストをエージェントに与えます。
Analytics Engineer
AE チームは、dbt モデルの構築と変更、MR レビューフィードバックへの対応、パイプライン障害のトラブルシューティング、データのテストと検証、データセットの探索、Slack スレッドやレビューコメントなどのコンテキストからの Issue 作成まで、開発ライフサイクル全体で OpenCode を使用します。
推奨ワークフロー
- 新規または不慣れなタスクでは、まず Plan モードで開始します。変更を加える前に提案されたアプローチをレビューしてください
- 十分に理解しているタスクでは、直接 Build または AE エージェントに進みます
- プロンプトは「I want to…」で始め、取り組んでいる変更、レビューコメント、または質問を説明します
- MR レビューでは、そのレビューにスコープを限定した新しいセッションを開きます
- 2 つのモードの詳細は、以下の Plan モードと Build モードのどちらを使うか を参照してください
セッション管理、モデル選択、コスト効率
- MR、トピック、または日ごとに新しいセッションを開始します。前のコンテキストが次のタスクに実際に必要かを判断し、不要なら新しく開始します
- Sonnet 4.6 のような中規模モデルが推奨されるデフォルトモデルです。品質、速度、コストのバランスがよく、ほとんどの AE タスクでは大規模モデルほど遅く高価になっても、それに見合う向上はありません
- 入力トークンはセッションで最も高価な要素のようです。コンテキストをスリムに保ち、大きくなったら
/compactを使い、200K トークンのしきい値に達する前に新しいセッションを開始してください - 現在のタスクに必要な MCP だけを有効にします。
/mcpsコマンドを使用し、spaceを押して MCP のオンとオフを切り替えます
MCP のセットアップ
ほとんどの AE 開発作業では Snowflake MCP が必要です。設定で問題が発生した場合は、セットアップとトラブルシューティングの動画を参照してください: [プレースホルダー — Snowflake MCP セットアップ動画へのリンクは近日公開]
Plan モードと Build モードのどちらを使うか
OpenCode には 2 つの主要なモードがあります。
- Plan — あなたのリクエストと関連するコードをレビューし、変更を加える 前に 詳細なアプローチを提案します
- Build — 変更を直接実行します
些細でないものについては、常にまず Plan を実行してください。すでに実装の途中にいる前にデザインの問題を捉えることに、驚くほど長けています。
plan をデフォルトのエージェントとして設定している場合（セットアップガイドで推奨）、デフォルトで Plan モードになります。実行する準備ができたら、明示的に Build モードに切り替えてください。
スキル
スキルは、再利用可能でチーム固有の知識——慣習、ワークフロー、そして、そうでなければ毎セッション説明し直す必要があるベストプラクティス——をエンコードします。ゼロからプロンプトを書くのではなく、スキルを呼び出すことで、エージェントに正しいコンテキストを即座に与えられます。
スキルの使い方
スキルは、あなたのプロンプトで説明されたタスクがスキルのフロントマターのメタデータと一致したときに、OpenCode のような AI コーディングツールによって自動的に呼び出されます。よく書かれたフロントマター（特に name と description のフィールド）は、自動的な発見を可能にします。スキルが存在することを知っている場合は、プロンプト内で名前を挙げて明示的に言及することもできます。
利用可能なスキル
Data Team によって開発されたスキルの一覧は、Agentic Tool Development ガイドの Available Skills セクションを参照してください。
セットアップ
OpenCode の環境でスキルを有効にするには、Agent Setup ガイドの Skills Setup の手順に従ってください。
c955a93f)