0002: 専用エージェントの内包方針とLLM制約の範囲の明確化

背景

これまでAGENTS.md/CODEX.md/OPENCODE.mdは、Claude Code、Codex、OpenCodeなど既存の汎用コーディングエージェントが、このリポジトリを実装するときに従う共通ルールを定めていた。

一方でAGENTS.mdには「法令、統計、文献、ニュースの取得結果は候補であり、解釈や論証として生成しない」「LLM-Wikiの内容は地図であり、根拠は出典リンクへ戻す」という制約があり、 product.mdの対象外にも「LLMによる大学レポート本文、法的解釈、論証の自動生成」がある。これらは大学レポートのようなアウトプット代わりのデータ生成を禁じる意図であり、コーディングエージェントによる本リポジトリの実装作業を制限する意図ではなかったが、文面上その区別が明示されていなかった。

また、今後はリポジトリの実装作業を行うコーディングエージェントとは別に、 paper-civic-kit自体がプロダクト機能として提供するドメイン特化のエージェント（取得、 Wiki生成、ダイジェスト作成などを担当）を内包する方針を追加する。

決定

LLM制約の範囲を明確化する: AGENTS.mdの「解釈や論証を生成しない」およびLLM-Wikiの出典遡上ルールは、Paper-Wiki/Law-Wiki/Data-Wiki/LLM-Wikiが出力する研究データ・文章にのみ適用される。コーディングエージェントおよび専用エージェントによる、本リポジトリの実装・設計作業には適用しない。
コーディングエージェント（Claude Code/Codex/OpenCodeなど、リポジトリの実装に使うツール）と、paper-civic-kitが提供する専用エージェント（プロダクト機能としてのエージェント）を区別する。
本リポジトリの実装作業は、既存のClaude Code CLI・Codex CLIなど汎用コーディングエージェントで行う。専用エージェントは実装作業には使わない。
専用エージェントの用途は、情報収集アシスト（Zotero/RSS/APIなどの候補整理）と LLM-Wiki生成に限定する。
LLM-Wiki生成そのもの（llmwiki compile/llmwiki query、0004）は llm-wiki-compilerが自身のプロバイダ設定でLLM呼び出しを完結させるため、専用エージェントの基盤を経由させる必要はない。専用エージェントの基盤を使うのは、情報収集アシスト側——複数ソース（RSS/DuckDuckGo/e-Gov）を横断して検索し、結果を見て再検索するかingestするかを判断する自律的な探索ループ——に限る。このtool-calling ループを自前実装せずに済ませることが、専用エージェント基盤を採用する理由になる。判断の結果、ingestすべきと決めたソースは、専用エージェントがllmwikiのMCPツール（llmwiki serveが提供するingestツール）またはCLIを呼び出す形でsources/に渡す。
専用エージェントの土台にはGoose（aaif-goose/goose、 Apache-2.0、旧Block発・現在はLinux Foundation傘下のAgentic AI Foundation運営、 contributor 500+・★50,000超）を採用する。opencodeではなくGooseを選んだ理由は「理由」節を参照。
専用エージェントはチャットで人間と対話しない設計とする。goose run --recipe agent/recipes/<name>.yamlに--no-session（セッションファイルを作らない自動実行）、 --output-format json（構造化JSON出力）、--max-turns/--max-tool-repetitions （ループ上限）を指定して、スクリプト・Makefile・cronから一回きりの非対話呼び出しで起動する（TUI・対話セッションは使わない）。定期実行にはgoose schedule addという組み込みのジョブスケジューラを使い、外部cronを新たに組まない。常駐させたい場合は goose serve（ACP over HTTP/WebSocket、既定でGOOSE_SERVER__SECRET_KEY必須）をヘッドレスサーバーとして使う。
「専用エージェントは実装作業に使わない」という制約は、Recipeのextensions定義で強制する: Recipeがextensionsを定義している場合、Gooseはグローバル設定の extension（developer等のbash/edit相当を含む）を読み込まず、Recipe定義のツールだけをエージェントに与える（実測確認済み、下記「検証結果」）。--no-profileは Recipe内extensionsまで無効化してしまうため使わない。
MCPサーバー側の認証は、既存ツールが持つOAuthをそのまま流用できる場合はそれを使い、専用のOAuthクライアントを新たに作らない（DuckDuckGo検索のようにAPIキー・OAuth いずれも不要なMCPサーバーを優先する方針とも両立する）。
専用エージェントはClaude/Anthropicモデル（Fable 5含む）を使わない。Gooseは ChatGPT/Gemini等のサブスクOAuthログインにも対応しているが、それも含めて他社サブスクのOAuth流用は行わない（下記Anthropic規約の理由により、Claudeに限らずこの設計方針を貫く）。実装作業に使うClaude Code CLI（Anthropicのサブスクをそのまま使う正規ルート）とは完全に切り離す。
情報収集アシストの検索ソースは、ログイン不要な nickclyde/duckduckgo-mcp-server （uvx duckduckgo-mcp-serverで起動、APIキー不要）を最初のMCPサーバーとして採用する。 X（Twitter）などAPIキーが必要なソースは、鍵の管理方針を別途決めるまで後回しにし、 MCP接続口だけ空けておく。
専用エージェントのモデルはOpenCode Go（opencode公式の低価格モデルサブスクリプション、$10/月、DeepSeek/Qwen/MiniMax/GLM/Kimiなど非Claude系モデルを束ねる、 OpenAI互換APIエンドポイントを提供）を採用する。Goose 1.41以降はopencode_go ネイティブプロバイダを内蔵しており、goose configureで設定するだけで接続できる（~/.config/goose/config.yamlにactive_provider: opencode_goとモデル名、 secrets.yamlにAPI key。OPENAI_HOST等のOpenAI互換フォールバック設定は不要）。既定モデルは固定せず、config.yamlのproviders.opencode_go.modelまたは goose run --model <model-id>で切り替えながら選定する。
OpenCode Goは、他社サブスクのOAuthトークンを転用するのではなく、opencode運営元への直接課金・専用API keyという通常の商用API利用形態のため、Anthropicの規約変更（下記「理由」参照）のようなサードパーティ利用規約問題を抱えない。
法令（e-Gov）を情報源に含める場合は、 shuji-bonji/houki-egov-mcp （@shuji-bonji/houki-egov-mcp、MIT、npx -y @shuji-bonji/houki-egov-mcpで起動、 APIキー不要）をMCPサーバーとして採用する。e-Gov法令API v2のlaw_title一致検索（略称辞書つき）・条/項/号取得・目次取得・改正履歴取得を提供し、本文中のキーワード一致による全文検索（search_fulltext）はまだフォールバック実装（search_lawと同じタイトル検索）にとどまる。本文キーワードでの発見が必要な場面は、採用済みの DuckDuckGo検索（duckduckgo-mcp-server）で補う。paper-civic-kit独自のe-Gov httpx クライアントは新たに作らない。

理由

制約の対象を明確にしないと、実装作業そのものがLLMによる「解釈・論証」に該当すると誤読され、コーディングエージェントの利用が不必要に萎縮する。
AGENTS.mdの「既存OSSを使える場合は薄い接着層を優先する」という方針を、専用エージェントの基盤選定にも一貫して適用する。
OAuthをはじめとする認証フローを個別実装すると、秘密情報の管理・失効・再認可のコストが増える。既存ツールの認証を再利用すれば、この管理コストと攻撃面を減らせる。
当初は専用エージェントの土台としてopencodeを検証していたが、llm-wiki-compiler の採用（0004）でLLM-Wiki生成側の必要性が下がったのを機に、専用エージェント基盤の用途を「情報収集アシストの自律探索ループ」だけに絞り込み、あらためて候補を比較した。opencodeは小規模組織（anomalyco）の運営で、サブエージェントの権限継承バグ（#12566、 #20549、 #6396）やrun --format json の完了イベント不具合（#26855）など複数の未解決issueが見つかった。
Gooseは2024年8月発足、直近pushedが確認時点の2日前、★50,644、フォークではない本体リポジトリであることをGitHub API（gh api repos/aaif-goose/goose）と公式ドキュメントサイト（goose-docs.ai）の記載内容の両方で確認した。運営もBlock単独ではなくLinux Foundation傘下のAgentic AI Foundationに移管されており、opencodeよりガバナンス面の継続性が高い。
Gooseはこの環境に実際にインストールし（aaif-goose/goose公式リリースのインストールスクリプトより、v1.41.0）、goose run --no-session --output-format json --no-profile --with-extension/--with-streamable-http-extension --max-turns --max-tool-repetitions --provider --modelが想定通り機能することをCLIヘルプ・実行で確認した。--no-profileでデフォルトのextensionを読み込まない設計は、「実装に使わせない」制約を設定ミスの余地なく強制できる点でopencodeの--tools 許可リスト方式より扱いやすい。加えてgoose scheduleという定期実行の組み込み機能もあり、外部cronを別途組む必要が減る。
houki-egov-mcpはDISCLAIMER.mdで「本MCPが返すのは事実情報（根拠テキストと出典 URL）のみ、最終判断は利用者または有資格の専門家に委ねる」という設計思想を明記しており、AGENTS.mdの「解釈や論証として生成しない」「LLM-Wikiは地図であり根拠は出典へ戻す」という制約と方向性が一致する。
デジタル庁/e-Gov公式のMCPサーバーはまだ存在しない。検索で見つかるのは houki-egov-mcpのほか、groundcobra009/hourei-mcp-server、ryoooo/e-gov-law-mcp、 takurot/egov-law-mcpなどいずれも非公式実装で、GovTech Tokyoも「Vibe Codingで作ってみた」という実験記事止まり。公式版が出るまではhouki-egov-mcpが現状の非公式実装の中で最も作り込まれている（略称辞書・テスト・エラーコード契約）ため、これを確定採用とし、「代替手段の検討」は保留の未決定事項としては扱わない。公式版が出た場合、またはhouki-egov-mcpが更新停止した場合にのみ乗り換えを再検討する。
Anthropicは2026年2月20日に利用規約を更新し、「Claude Free/Pro/MaxのOAuthトークンをClaude CodeとClaude.ai以外の製品・ツール・サービスで使うこと」を明示的に禁止し、 4月4日にこれを施行した。OpenCodeは規約上カバー対象外になった代表例として名指しされている（The Register、 MLQ）。この規約は特定のツールに限定されず「Claude Code / Claude.ai以外」全般が対象なので、土台をopencodeからGooseに変えても同じ制約は残る。したがって専用エージェントは引き続きClaude系モデルを使わない方針とし、モデルはOpenCode Go（opencode運営元への直接課金サブスクで、他社OAuthの転用ではない）に固定する。実装作業で使うClaude Code CLI自体は公式クライアントのままなので、この規約変更の影響を受けない。

影響

AGENTS.md、product.mdの該当箇所に、この決定へのリンクと制約範囲の注記を追加した。
専用エージェントの設定・エージェント定義は、paper-civic-kit独自の設定層を作らず、 Goose標準の仕組みにそのまま置く: グローバル設定は~/.config/goose/config.yaml、専用エージェントの構成（使うMCP extension・モデル・プロンプト）はリポジトリ内の agent/recipes/に置くYAML Recipeファイルとして定義し、goose run --recipe agent/recipes/<name>.yamlで呼び出す。agent/はpackages/・templates/・web/・ workers/と並ぶ新規のトップレベルディレクトリとし、repo直下のAGENTS.md/ CLAUDE.md/CODEX.md/OPENCODE.md（全コーディングエージェント共通の指示書）とも、実装エージェント（Claude Code/Codex CLIなど）固有の設定とも混在させない。
情報収集アシストの実行単位はGooseのRecipe（1本のYAMLファイルに、役割・指示（instructions/prompt）、使うMCPサーバー一覧（extensions）、実行時パラメータ（parameters）、必要なら出力を固定するJSON Schema（response）をまとめたもの。 goose run --recipe <path> --params key=valueで呼び出す）として定義する。
専用エージェントの実行profileはvpsとする。architecture.mdでvpsは「Dashboard、metadata DB、RSS/API取得、軽いjob queue」の役割とされており、情報収集アシスト・LLM-Wiki生成はOCR/PDF変換のような重い処理を伴わず、RSS/API/MCP 呼び出し中心の軽量なjob queueとしてvpsにそのまま乗る。mac-mini（Zotero/PDF 保管）やrtx-worker（OCR/画像処理）は用途が異なるため使わない。
専用エージェントのモデル費用はOpenCode Goの定額$10/月（初月$5）で発生する。 Claude/Fable 5を試す場合は、専用エージェントとは別に、Claude Code CLI（実装エージェント側、サブスク込み）またはAnthropic API keyの従量課金を使う必要がある。

未決定事項

なし。この決定の範囲（専用エージェントの基盤・モデル・実行profile・情報収集ソース・実行単位・設定の置き場所）はすべて確定した。

検証結果

Gooseのインストール元は、当初エージェントがaaif-goose/gooseと推測で決め打ちしてインストールスクリプトを実行しようとしたため、auto modeの安全装置に一度ブロックされた。ユーザーが提示したhttps://github.com/aaif-goose/goose.gitと https://goose-docs.ai/docs/quickstartをもとに、gh api repos/aaif-goose/goose （作成日2024-08-23、fork:false、★50,644、直近pushed 2026-07-03）と公式ドキュメントサイトの記載（「goose has moved to the Agentic AI Foundation (AAIF)」、インストールリンクが同じorgを指す）を突き合わせて正当性を確認してからインストールした。
インストール後、goose --version（1.41.0）、goose --help、goose run --help、 goose recipe --help、goose schedule --help、goose serve --help、 goose mcp --helpを実行し、--no-session/--output-format json/--no-profile/ --with-extension/--with-streamable-http-extension/--max-turns/ --max-tool-repetitions/--provider/--model、およびgoose schedule add （組み込みジョブスケジューラ）、goose serve（ACP over HTTP/WebSocket、既定で GOOSE_SERVER__SECRET_KEY必須）が存在することを確認した。
OpenCode Go接続は当初OpenAI互換の環境変数（OPENAI_HOST等）を想定していたが、実際にgoose configureで設定したところ、Goose 1.41にはopencode_goネイティブプロバイダが内蔵されており、環境変数の手動設定なしで接続できた（2026-07-05、モデルdeepseek-v4-proで確認）。
agent/recipes/info-gathering.yamlをend-to-endで実行し（goose run --recipe ... --no-session --output-format json --max-turns 15）、duckduckgo__search/ duckduckgo__fetch_content/houki-egov__search_lawが実際に呼ばれ、JSON Schema どおりのingest候補5件（e-Gov法令・総務省調査・自治体答申・学術論考・日弁連声明）が返ることを確認した（合計11kトークン程度）。
--no-profileを付けるとRecipe内extensionsまで無効化され、エージェントが final_output以外のツールを一切持たなくなることを実測で確認した（初回実行が空の候補リストを返した原因）。逆に、Recipeがextensionsを定義していればグローバル設定のextensionは読み込まれないことも、ツール一覧を返させる監査用 Recipeで確認した（利用可能ツールはduckduckgo__*とrecipe__final_outputのみで、グローバルで有効なdeveloper等は含まれなかった）。
RSS収集は、architecture.mdに既に挙げているPython feedparserで成立する見込み。複数媒体を横断してcandidate化する経路自体に技術的な障害はない。
現在このClaude.aiセッションで使える外部提供のe-Gov MCPコネクタ（search_laws/get_law_data）を実地で試したところ、keyword引数を「情報公開」「個人情報の保護に関する法律」「デジタル社会形成基本法」と変えても返る法令リストとtotal_count（9529件）が変化せず、常に公布日順の同じ先頭件が返ってきた。つまりこの特定のMCPコネクタは、少なくともkeyword検索が機能していない（事実上フィルタなしの一覧しか返せない）不具合がある。
代替としてshuji-bonji/houki-egov-mcpのソースを確認したところ、search_lawは e-Gov API v2の/lawsエンドポイントへlaw_title（タイトル一致）として問い合わせる実装で、上記のような「引数を変えても結果が変わらない」不具合はコード上見当たらない。略称辞書による略称→正式名解決、条/項/号取得、目次取得、改正履歴取得もテスト付き（Vitest 50件）で実装されている。このため、法令情報源はこのMCPサーバーの採用で確定し、paper-civic-kit独自のe-Gov httpxクライアントは作らない。

追記: LLM-Wiki廃止（2026-07-22時点の注記）

本文中のLLM-Wiki生成に関する記述は、0004 「LLM-Wiki生成エンジンにllm-wiki-compilerを採用」の追記（2026-07-15、実運用でほぼ使われなかったため廃止）により廃止済み。以下の記述は廃止前の設計判断の記録として残す。