OpenCode Agents ガイド：Subagents と AGENTS.md の7項目チェック

結論：AGENTS.md はリポジトリ共通ルールに使い、OpenCode agents は専用プロンプト、モデル、ツール、境界を持つ専門ロールに使います。

AGENTS.md にはテストコマンド、スタイル、生成フォルダ、注意点など長く有効なルールを書きます。agent には reviewer や docs-editor のような役割ごとの動作を書きます。

両方に同じルールを書くと、将来の修正でずれや衝突が起きやすくなります。

subagent は大きなフォルダ確認、危険な差分レビュー、API 調査など、分離できる関心があるときに有効です。

出力形式は明確にし、ファイル参照、修正計画、リスク一覧などを指定します。

モデルは役割のリスクで選びます。レビューや設計判断は強い推論を、要約や簡単な文書化は軽いモデルを選べます。

ツールとパスは必要最小限にして、予期しない変更を減らします。

共有設定は Git で確認できる形にし、秘密情報は環境変数やプロバイダーの認証手順に置きます。

reviewer や docs-editor のような安定した名前はログとプロンプトを読みやすくします。

最初は書き込みなしで検証します。範囲、口調、出力形式が合っているかを確認します。

次に小さな変更だけを許可し、Git diff を確認します。

1. 役割名を決めるreviewer、planner、docs-editor などを使います。
2. 出力を定義する返す内容と禁止事項を書きます。
3. モデルを選ぶリスクに推論力とコストを合わせます。
4. ツールを絞る最小限から始めます。
5. 読み取りで検証するまず説明やレビューを依頼します。
6. 小さな差分を見る問題ない場合だけ拡大します。
7. 規則を記録するいつ agent を使うかを書きます。

agents を増やしすぎると、どの役割を使うべきか迷います。まず繰り返し発生する一つの課題から始めます。

AGENTS.md と agent に同じ規則を重複させないでください。

MCP、hooks、skills は役割を強化しますが、リスク面も広げます。

prompt、tool、write path を一層ずつ検証します。

{
  "agents": {
    "reviewer": {
      "model": "provider/reasoning-model",
      "description": "Review diffs and return concrete findings only",
      "tools": ["read", "grep"]
    },
    "docs-editor": {
      "model": "provider/fast-model",
      "description": "Update documentation after source changes",
      "tools": ["read", "edit"]
    }
  }
}

共有設定は Git で確認できる形にし、秘密情報は環境変数やプロバイダーの認証手順に置きます。