エージェントフレームワークビルダー

このスキルは、新規プロジェクト用の完全な openCode エージェントフレームワークの構築をガイドします。

---

ステップ1 - プロジェクトを理解する

何かを作成する前に、ユーザーに以下の質問をしてください:

1. エージェントは何をすべきですか? (1～2文でタスクを説明)
2. どの外部ツール/APIが必要ですか? (MCP、REST API、データベース)
3. エージェントはどの程度自律的に動作すべきですか? (完全自律/確認付き/計画のみ)
4. どのサブエージェントが必要ですか? (例: 専門ビルダー、ライター、テスター)
5. 予算制限がありますか? (プレミアムリクエスト、フリーモデルを優先?)
6. メモリをセッション間で永続化させるべきですか? (はい/いいえ)

---

ステップ2 - ファイル構造を計画する

常にこの基本構造を作成してください:

project-name/
+-- AGENTS.md <- メインルール、自動読み込み
+-- memory/
+-- memory.md <- プロジェクトステータス & インサイト
+-- variables.md <- すべての設定値
+-- progress.md <- 進捗チェックリスト
+-- .opencode/
+-- agents/ <- サブエージェント Markdown定義
+-- commands/ <- カスタム /commands
+-- prompts/ <- システムプロンプト(.txt ファイル)
+-- skills/ <- プロジェクト固有のスキル
+-- opencode.json <- エージェント & MCP設定 (ルート OR .opencode/)

---

ステップ3 - opencode.json を構築する

エージェントごとの必須フィールド

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "skill": { "*": "allow" }
  },
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-package"],
      "environment": {
        "API_KEY": "xxx"
      }
    }
  },
  "agent": {
    "main-agent": {
      "description": "...",
      "mode": "primary",
      "temperature": 0.1,
      "max_steps": 20,
      "prompt": "{file:./prompts/main-agent-system.txt}",
      "permissions": {
        "file": "allow",
        "bash": "allow",
        "web": "allow"
      }
    }
  }
}

opencode.json の重要なルール

• model を省略 -> 現在選択されているモデルを自動的に使用
• 特定のモデルを強制する必要がある場合のみ model を設定 (例: フリーサブエージェント)
• prompt を {file:./prompts/name.txt} で参照 - ファイルが存在する必要があります。存在しないとエラーになります
• MCP の command は常に配列で、文字列と別の args にしない
• MCP には常に type: "local" を指定
• opencode.json は .opencode/ OR ルート内に配置可能 - どちらも動作

予算戦略

プレミアムリクエストが制限されている場合:

• メインエージェント: モデルを設定しない (ユーザーが選択)
• サブエージェント: "model": "github/gpt-4.1" (Copilot サブスクリプション付きで無料)
• メインエージェントの max_steps を低く保つ (15～25)
• フリーサブエージェントはより高い max_steps (30～50)

---

ステップ4 - AGENTS.md を構築する

AGENTS.md は最も重要なファイル - 毎セッション自動読み込みされます。

必須セクション

# プロジェクト名 - openCode エージェントルール

## プロジェクト
[エージェントが何をするか 1～2文]

## スタートアップ - 常に最初に実行
1. memory/memory.md を読む
2. memory/variables.md を読む
3. memory/progress.md を読む
[ユーザーに簡潔に説明してから続行]

## コアルール
- [最も重要な動作ルール]
- [2番目に重要なルール]
- 推測しない - 不足している値についてはユーザーに確認
- 毎ステップ後に memory/ を更新

## エージェント使用方法
- メイン作業: `main-agent` (Tab で切り替え)
- [サブエージェント]: [タスク] については `@subagent-name` を呼び出す

## スキル
[表: 状況 -> 読み込むスキル]

## 制約
[表: 何が -> ルール]

AGENTS.md のルール

• 150行以下に保つ - 毎セッションコンテキストに読み込まれる
• ウムラウトなし (ae/oe/ue の代わりに ä/ö/ü) - エンコーディング問題を防止
• em ダッシュなし (—) - 通常のハイフンのみ (-)
• 最も重要な情報が最初 - エージェントは上から下へ読む

---

ステップ5 - システムプロンプトを構築する

すべてのプライマリエージェントは .opencode/prompts/ 内に .txt ファイルを取得します。

システムプロンプトの必須セクション

## スタートアップ (毎セッション)
1. memory/memory.md、memory/variables.md、memory/progress.md を読む
2. 2～3文でユーザーに通知
3. 最後に開いていたステップで続行


## タスク
[エージェントが何をするかの正確な説明]

## フェーズ
[具体的なステップを含むフェーズ 1、フェーズ 2 など]

## スキルを使用
[どのスキルをいつ読み込むか]

## 重要なルール
[プロジェクト固有のルール]

## サブエージェントは慎重に使用
- 本当に必要な場合のみサブエージェントを呼び出す
- セッション終了時のみメモリを更新

---

ステップ6 - メモリファイルを作成する

memory.md 基本構造

# memory.md - プロジェクトステータス
_最終更新: まだ開始されていません_

## ステータス
フェーズ: 0 - 未開始
次のステップ: フェーズ 1 を開始

## インサイト
(入力予定)

## エラーログ
| 日付 | エラー | ソリューション |

variables.md 基本構造

# variables.md - 設定
_MISSING = まだ入力される必要があります_

## [サービス 1]
VAR_1=    # MISSING
VAR_2=    # MISSING

## ステータス
| 変数 | ステータス |
|------|----------|
| VAR_1 | MISSING |

variables.md での参照 (常に含める)

すべてのフレームワークは variables.md に参照ブロックを持つ必要があります。 エージェントはスタートアップ時にこれらを自動的にコンテキストとして読み込みます。

## 参照
# エージェントが使用する必要があるリンク、ワークフロー ID、記事またはドキュメント。
# スタートアップ時に自動読み込み。

REF_1= # MISSING (URL、n8n-workflow-id:XXXXX、または ./local/file.json)
REF_2= # オプション
REF_3= # オプション

サポートされている参照形式

形式	例	読み込み方法
HTTP/HTTPS URL	https://docs.n8n.io/...	web_fetch
n8n ワークフロー	n8n-workflow-id:12345	n8n MCP
ローカルファイル	./examples/template.json	読み込みツール
GitHub	https://github.com/user/repo	web_fetch
記事	https://medium.com/...	web_fetch

エージェントのシステムプロンプトに常にこのロジックを含めてください:

## スタートアップ
1. variables.md の REF_1 から REF_5 を確認
2. URL -> web_fetch で読み込む
3. n8n-workflow-id:XXX -> MCP でテンプレートとして読み込む
4. ローカルファイル -> 読み込みツールで読み込む
5. 参照をコンテキストとして使用 - 盲目的にコピーしない

progress.md 基本構造

# progress.md - 進捗

## フェーズ 1 - [名前]
- [ ] ステップ 1
- [ ] ステップ 2

## 現在のフォーカス
次のアクション: フェーズ 1 を開始

---

ステップ7 - コマンドを作成する

すべてのエージェント向けの最小限のコマンド:

/start (必須)

***
description: エージェントを開始 - メモリを読み、ステータスを表示、続行
agent: main-agent
***
memory/memory.md、memory/variables.md、memory/progress.md を読む。
ステータスを 2～3 文で要約してから、次に開いているステップで続行してください。

/status (推奨)

***
description: 何もしないでプロジェクトステータスを表示
agent: main-agent
***
メモリファイルを読んでコンパクトな概要を表示してください。
その後何もしない - 指示を待つ。

---

ステップ8 - MCP 設定

MCP の一般的な問題と解決策

問題	原因	解決策
MCP が赤色/起動しない	type: "local" がない	追加してください
MCP が赤色	command が文字列の代わりに配列でない	配列を使用
MCP が赤色	トークンにダブルスペース	トークンを確認
読み取り専用ツールのみ	MCP サーバーが間違っている	正しい MCP を確認
stdio MCP が起動しない	環境変数がない	MCP_MODE=stdio、LOG_LEVEL=error、DISABLE_CONSOLE_OUTPUT=true
ローカル URL がブロック	セキュリティモード	WEBHOOK_SECURITY_MODE=moderate

MCP タイプリファレンス

ローカル (stdio):

{
  "type": "local",
  "command": ["npx", "-y", "package-name"],
  "environment": { "KEY": "value" }
}

リモート (HTTP/SSE via supergateway):

{
  "type": "local",
  "command": [
    "npx", "-y", "supergateway",
    "--streamableHttp", "http://host:port/mcp/http",
    "--header", "authorization:Bearer TOKEN"
  ]
}

---

ステップ9 - 完了前チェックリスト

• opencode.json のすべての {file:...} 参照 - ファイルが実際に存在するか?
• AGENTS.md とシステムプロンプトにウムラウトなし
• memory/、variables.md、progress.md が作成されている
• /start コマンドが作成されている
• MCP に type: "local" が設定されている
• MCP の command が配列である
• 存在しないファイルへの prompt 参照なし
• フリーサブエージェント向けに model を明示的に設定

---

典型的なエージェントアーキタイプ

アーキタイプ	プライマリエージェント	サブエージェント	特別な機能
ワークフロービルダー	main-agent	builder、memory-writer	外部ツール向け MCP
リサーチエージェント	researcher	summarizer、memory-writer	Web アクセスが必要
コードジェネレータ	coder	reviewer、tester	bash アクセスが重要
データパイプライン	pipeline-agent	fetcher、transformer	API 認証情報を variables.md に記載
コンテンツ作成者	writer	editor、memory-writer	bash は不要

---

自律レベル (常に variables.md に含める)

すべてのエージェントフレームワークは variables.md に AUTONOMY_LEVEL を持つべきです:

AUTONOMY_LEVEL=3
1 = 各ステップで確認
2 = フェーズ内は自律的、フェーズ間は確認
3 = 完全自律、問題がある場合のみ確認

メインエージェントのシステムプロンプト内で:

## 自律レベル (variables.md から読み込む)

AUTONOMY_LEVEL=1: すべてのステップを通知し、確認を待つ
AUTONOMY_LEVEL=2: フェーズ内は自律的、フェーズ間にステータスを表示
AUTONOMY_LEVEL=3: 完全に自律的に作業、以下の場合のみ確認:
- variables.md に記載されていない不足している値
- 自動的に修正できないエラー
- 取り返しのつかない決定

変数チェックルール (すべてのシステムプロンプトで必須)

## 変数 - 最も重要なルール
常に最初に memory/variables.md を完全に読んでください。
「MISSING」とマークされた変数のみを確認してください。
値を持つ変数 -> 二度と確認しない。
質問する前に常に確認: 「すでに variables.md にありますか?」