Polis Protocol

Polis Protocol

コーディングエージェント向けのローカルファーストなコントロールプレーンです。1つのリポジトリで Claude、Codex、Gemini、Cursor を実行できます。各担当契約にはオーナーが記録され、エージェントは証拠を記録でき、共有された教訓によって同じ失敗の繰り返しを減らせます。プレーンな Markdown を Git で管理し、あらゆるベンダーで利用できます。

🌐 ウェブサイト → polis-protocol.ymlsora.chatgpt.site  ·  インストール  ·  実証  ·  エージェントに接続（MCP）

合成シミュレーション：反復エラー 65% → 7%  ·  助言的な作業重複の競合を検出  ·  5秒で再現：polis bench --mode learning
_{合成タスクとシード 0 を使ったモデル化実行です — 前提と制限を以下に公開しています。}

uvx polis-protocol init      # one command · no server · no database · just markdown in your repo

Claude · Codex · Gemini · Cursor が共有し、すべてが同じ _polis/ フォルダーを読み取ります。MIT ライセンスです。
⭐ 以下の仕組みが気に入ったら、スターを付けると、ほかのマルチエージェント開発者にも見つけてもらいやすくなります。

---

10秒でわかる説明

3つのAIエージェントが1つのプロジェクトを共有しています：Claude（調査）、Codex（フロントエンド）、Gemini（翻訳）。

スペイン語翻訳のタスクが来ました。誰が担当するでしょうか？

初期のころは、Claudeが担当しました。自分の能力を高く評価していたためです。しかし、2件の契約が完了し、1つの教訓（「企業用語の『líder』はこの場面ではしっくりこない。運動体で使われる借用語の『madrij』を使うこと」）が記録された後、ルーターはその作業をひそかにGeminiへ振り分けるようになりました。誰も担当を変えていません。チームが学び、その学びに合わせてルーティングが変わったのです。

実績に基づいて作業を振り分け、結果に応じて実績を更新する — それがこの仕組みの核心です。インストールもAPIキーも不要で、コマンドを1つ実行するだけで試せます。

git clone https://github.com/ymxlx/polis-protocol.git
cd polis-protocol && bash scripts/demo.sh

Score breakdown (sorted by total):
  gemini-translator-pesaj   total=0.688  hist=0.25  self=1.00  cost=1.00  avail=1.00  lessons=+0.10
                              ↳ lessons applied: 2026-04-18-madrij-not-lider
  claude-research-pesaj     total=0.453  hist=0.15  self=0.60  cost=1.00  avail=1.00  lessons=+0.00
  codex-frontend-pesaj      total=0.290  hist=0.00  self=0.20  cost=1.00  avail=1.00  lessons=+0.00

Recommendation: gemini-translator-pesaj   ← won on history + an applied lesson, not self-rating

この仕組みに興味を持っていただけたら、⭐を付けていただくことで、ほかのマルチエージェント開発者にも見つけてもらいやすくなります。

---

Polis とは

AI エージェント向けの Git と Markdown を使ったタスクボードが次々と登場しています。タスクを引き受け、実行し、完了としてマークする仕組みです。これらは優れており、Polis も書き込みに対応しています。しかし、ボードは受動的です。何が起きたかを記録するだけで、賢くなることはありません。プロトコルはリリースされたその日に固定されます。

Polis は共有記録にアクティブな調整レイヤーを追加します。

1. コミュニケーション — 意味のあるすべてのアクションが、追記専用の chronicle.md に記録されます。（すべてのボードがこれを行います。）
2. 最適化 — タスクは構造化された契約であり、マルチアームドバンディットポリシーに基づき、必要な能力タグで最も高い実績を持つ市民に割り当てられます。（ボードにはできません。誰が最適かを把握する仕組みがないからです。）
3. 自己開発 — 決着した契約から構造化された教訓を作成できます。教訓はルーターにフィードバックされ、記録を一貫して維持することで、同じ失敗の繰り返しを減らすのに役立ちます。
4. 憲法の進化 — ルールが機能しなくなったとき、市民はプロトコル自体の改正を提案し、投票し、批准できます。

ボードは書き込むものです。Polis は成長するチームです。 誰が最適かを学び、自らのルールを書き換えることができます。

すべてがフォルダー内に収まります。中央サーバーも、必須のランタイムも、独自形式もありません。Markdown の読み書きができるツールなら、どれでも参加できます。

Polis と AGENTS.md、CrewAI、LangGraph、hcom、 SwarmClaw、またはエージェントメモリーシステムとの比較については、docs/comparisons.md をご覧ください。

---

「polis」の由来

polis とは、古代ギリシャの小さな都市のことです。数千人ほどの人々が互いを知り、自分たちで物事を運営します。この比喩は次のように対応します。

Polis	Polis プロトコル
市民	あらゆるベンダーの AI エージェント
能力カード	エージェントが実行できることを記した、コンテンツハッシュ付きの YAML マニフェスト
契約	意図、割り当て、決着を含む構造化されたタスク
クロニクル	各市民がセッション開始時に読む、追記専用のイベントログ
教訓	能力タグごとに記録された振り返り
ハブルータ	重要なアクションの前に、異なるベンダーの市民が行うペアでの批評
改正案	投票で批准される憲法の変更

意図的に明確な方針を設けています。名称は覚えやすく、ファイル形式は厳密で、クロニクルの行形式には一切の変更の余地がありません。プロトコルレイヤーを厳密にすることで、異なる4社のモデルが同じフォルダーを読み、何を見ているのかについて合意できます。

---

クイックスタート

インストール

任意のプロジェクトのルートから実行します。

# zero-install, one command
uvx polis-protocol init

# or install the CLI
pipx install polis-protocol      # isolated
pip install polis-protocol       # into the current env

init は _polis/ を作成し、Claude／Codex／Gemini 用のブリッジファイルを書き込み、あなたを市民として登録します。ID を指定する場合は、次のように渡します。

uvx polis-protocol init \
  --agent-id claude-research-yourproject \
  --vendor anthropic --model claude-opus-4-7 --tool "claude code"

ファイルを書き込まずに作成内容を確認するには、--dry-run を使います。再実行しても既存のファイルは変更されません。polis init --repair を実行すると、管理対象の不足ファイルが復元されます。 （プロトコル自体をハックしていますか？ git clone と python scripts/init_polis.py も引き続き利用できます。）

これで、次のものが用意されます。

your-project/
├── CLAUDE.md / AGENTS.md / GEMINI.md / AIDER.md ← cross-tool entry pointers
├── .agents/skills/polis-protocol/SKILL.md ← skill mirror (Codex and Antigravity both read this)
└── _polis/
    ├── CONSTITUTION.md                    ← canonical protocol
    ├── README.md
    ├── index.md                           ← "where things stand"
    ├── chronicle.md                       ← append-only event log
    ├── citizens/<you>/                    ← capability_card, status, inbox, journal
    └── contracts/
        ├── open/                          ← active tasks
        ├── settled/                       ← closed tasks with lessons
        └── routing_stats.yml              ← learned routing policy

契約を作成する

polis contract open --title "Literature review" \
  --tags long-context-reading,source-checking --by claude-research-yourproject

または、_polis/contracts/open/ にファイルを手動で追加します。単なる Markdown ファイルです。

---
contract_id: literature-review
opened_by: claude-research-yourproject
status: proposed
stakes: medium
required_tags: [long-context-reading, source-checking]
cost_ceiling: medium
---

# Literature review of multi-agent coordination protocols
...

ルーティングする

polis route --polis-root _polis \
  --contract _polis/contracts/open/literature-review.md --explain

出力：

Score breakdown:
  claude-research-yourproject  total=0.430  hist=0.00  self=0.90  cost=1.00  avail=1.00  lessons=+0.00
  codex-frontend-yourproject   total=0.350  hist=0.00  self=0.50  cost=1.00  avail=1.00  lessons=+0.00

Recommendation: claude-research-yourproject

決着させて学習する

polis contract settle literature-review --quality 5 --minutes 90
polis reconcile --polis-root _polis

バンディットの routing_stats.yml が更新されます。また、所有者が _polis/lessons/<tag>/ に記録した教訓には、制限付きの routing_effect を含められます。ルーターは次に類似の契約が作成されたときにこれを読み取り、--explain にその名称を表示します。失敗は polis guardrail add … のエントリーにでき、以後そのタグを持つ契約では、必須の合格基準として引き継がれます。

衝突を避ける

polis reserve src/auth --as claude-research-yourproject --note "refactoring login"
# another cooperating Polis client receives a conflict warning with the holder named
polis release src/auth --as claude-research-yourproject

予約は、共有状態に記録される助言的な調整機能です。ファイルシステムのロックやセキュリティ境界ではなく、Polis に参加しないツールとの競合を防ぐ保証もありません。

MCP 経由でエージェントに接続する

すべての polis は MCP サーバーでもあります。polis mcp は追加の依存関係なしで、stdio を通じて MCP と通信します。ライフサイクル全体をツール（status、open / route / claim / settle / abandon、コンテキストパケット、reserve / release、ガードレール）として公開し、読み取り専用のリソース（polis://state、polis://replay、polis://replay/redacted、polis://constitution）も提供します。

# Claude Code
claude mcp add polis -- uvx --from polis-protocol polis mcp

# any other MCP client: command `uvx`, args `--from polis-protocol polis mcp`
# (run it from inside the project, or add `--polis-root /path/to/_polis`)

CLI を実行できないエージェントでも、契約の作成、説明可能なルーティングの推奨事項の取得、ファイルの予約、証拠を添えた精算ができるようになりました。CLI やダッシュボードと同じ共有アプリケーション層を通じて行います。_polis/ ファイルが直接編集されることはありません。

---

正直な評価による実証

polis bench は標準で付属しています。主張を述べるだけでなく、自らの主張をベンチマークで検証しました。

• エラーの再発：−89%。 教訓とガードレールが、条件に一致する将来のタスクに自動的に注入されると、エラーの再発率は約65%（記憶を持たないエージェント、または管理されていないスウォーム）から約7%に低下します。各エラーの種類は最大1回再発した後、恒久的なチェックになります。再現するには、polis bench --mode learning を実行します。
• 決定論的な助言ベースの競合検出。 ベンチマークでは、すべての参加者が同じ共有状態を使う場合、polis reserve は重複する要求を拒否し、予約者を示します。予約はファイルシステムロックでも競合状態の防止策でもありません。
• そして、ほとんどのプロジェクトが明かさない点です。 学習によるルーティングは、スキルなしのベースライン（ランダム、ラウンドロビン）を上回り、結果だけからオラクルの品質向上分の約35〜55%を回復します。ただし、正確な静的な自己評価も品質面で競争力があり、ベンチマークレポートにはそのことが明記されています（polis bench）。Polis の強みは、カードを信頼する必要なく学習できること、選択ごとに透明性の高い理由を示すこと、そしてベースラインにはない調整レイヤーです。

---

4つの制度

登録簿

各市民が公開するファイルは1つです：_polis/citizens/<agent-id>/capability_card.yml。ベンダー、モデル、言語、自己評価付きの能力タグ、コストの上限範囲、レイテンシの上限範囲、継続的な指示、署名を記載します。このカードは「誰が何をできるか」に対する polis の回答です。中央ディレクトリはなく、参加に許可も必要ありません。登録簿は設計上、誰にでも公開されています。

契約

タスクは3つのセクションからなる Markdown ファイルです。

• 意図 — 目標、受け入れ基準、必須タグ、期限、コスト上限、重要度
• 割り当て — 担当者、計画、推定作業量（担当者の決定時に記入）
• 精算 — 結果、品質の自己評価、うまくいったこと、問題になったこと（終了時に記入）

未完了の契約は contracts/open/ にあります。精算済みの契約は contracts/settled/ に移され、削除されることはありません。契約の形式は固定されているため、どの市民も、ルーターも、スキーマを推測することなくすべての契約を読み取れます。

年代記

_polis/chronicle.md は追記専用のイベントログです。意味のあるアクションごとに1行記録します。

- 2026-05-14 09:12 | claude-research-pesaj | drafted outline | [[contracts/open/literature-review]] | covers 2019-2025, 14 papers
- 2026-05-14 09:15 | codex-frontend-pesaj  | settled contract | [[contracts/settled/auth-refactor]] | tests passing, lesson filed
- 2026-05-14 09:18 | gemini-translator-es  | requested review | [[reviews/2026-05-14-0918-spanish-rollout]] | high-stakes, needs chavruta

予約済みの動詞（opened contract、claimed contract、settled contract、filed lesson、requested review、proposed amendment、blocked on <thing>、…）には意味上の重みがあり、ルーターや他の市民が解析します。

教訓は _polis/lessons/<capability-tag>/ に別途保存されます。年代記には何が起きたかを記録し、教訓には何が学ばれたかを記録します。ほとんどのイベントは教訓ではなく、ほとんどの教訓は多くのイベントから要点をまとめたものです。

改正

ルールが機能しなくなったときは、どの市民でも変更を提案できます。提案は _polis/amendments/proposed/<id>.md に記載します。他の市民は、応答ブロック（agree | disagree | abstain | request_changes）を追記します。活動中の市民（直近14日以内に年代記に記録がある市民）の単純過半数が同意すると、ファイルは amendments/ratified/ に移され、憲章が編集されます。

プロトコルは自ら変化します。このスキルのデフォルトルールは種であり、時間とともに、各 polis はプロジェクトに合った小さな形で変化していきます。その変化こそが目的です。

---

Chavruta レビュー

ベイト・ミドラーシュのペア学習モデルに着想を得た chavruta レビュー は、単一モデルの失敗を防ぐポリスの安全策です。stakes: high としてフラグ付けされた契約では、実行前に別ベンダーの市民が計画を批評する必要があります。批評では、次の3つの質問に答えます。

オーナーが正しく理解しているのはどの点ですか？見落としている可能性があるのはどの点ですか？判断：signed_off、requested_changes、または rejected。

同じベンダーの市民同士でレビューすることも認められていますが、効果は弱まります。chavruta の価値は、モデル間に構造的な違いがあることそのものだからです。これは必要な場合に限って使ってください。ほとんどの契約は低リスクです。

---

ルーターの学習方法

デフォルトのルーターは、マルチアームド・バンディットです。

• 活用（85%）：必須タグについて、合計スコアが最も高い市民にルーティングします。スコアは、過去の品質（55%）、自己評価（20%）、コスト適合性（15%）、現在の対応状況（10%）を重み付けします。
• 探索（15%）：スコアに応じて、トップではない市民にルーティングし、現在のリーダーが本当に最適かどうかをポリシーが正しく判断し続けられるようにします。
• コールドスタート：タグの履歴がない場合は、自己評価が優先されます。タグごとの契約が数件進むと、自己評価は履歴データに置き換わります。

契約が確定すると、routing_stats.yml が新しい品質スコアと所要時間で更新されます。記録が蓄積されるにつれて、このデータを今後の推奨の改善に活用できます。計算の詳細は references/routing.md を参照してください。

ルーターは次のように実行できます。

• 60行の Python スクリプト（scripts/route_contract.py）として実行する
• 任意のエージェントのセッション内で、短い推論ステップとして実行する（計算はコンテキスト内で行えるほど簡単です）

どちらの方法でも同じ推奨結果が得られます。市民はいつでもその推奨を上書きできます。

---

リポジトリの内容

パス	内容
polis/	polis CLI を支えるインストール可能なパッケージ。ルーティング、契約、予約、ガードレール、コンテキストパケット、ベンチ、doctor、verify、migrate が含まれます
SKILL.md	Claude Code スキル：有効化するタイミングと、ワークフロー全体
scripts/init_polis.py	新しいポリスをブートストラップします（冪等、コンテンツハッシュ付きカード、ブリッジポインター）。polis/initializer.py を呼び出す薄いシムです
scripts/route_contract.py	バンディットルーターと --reconcile ジョブ。polis/routing.py を呼び出す薄いシムです
scripts/benchmark.py	Polis Bench。ルーティングとベースラインの比較、および繰り返しエラーの学習曲線
templates/POLIS_CONSTITUTION.md	新しいポリスそれぞれに書き込まれる正式な憲章
templates/bridge_pointer.md	各ツールから憲章を参照する、短い CLAUDE.md／AGENTS.md／GEMINI.md
references/protocol-spec.md	すべてのファイル（カード、契約、教訓、改正、レビュー、ステータス、受信箱）の完全なスキーマ
references/templates.md	プロトコルで使用するすべてのファイルのコピー＆ペースト用テンプレート
references/routing.md	バンディットの計算、コールドスタート、探索率の調整、統計更新の手順
references/amendments.md	改正と教訓の記録を使い分ける基準、定足数ルール、実例
references/troubleshooting.md	障害モード、復旧、スケーリング、および agent-vault からの移行手順

---

ベンダーをまたいだ連携

このプロトコルはベンダーに依存しません。同じ polis を Claude、Codex、Gemini CLI、Google Antigravity、Aider、GPT ベースのツールなど、Markdown を読み取れるあらゆるツールで共有できます。Bootstrap は、以下の検出用ポインターを書き込みます。

• CLAUDE.md — Claude Code のエントリーポイント
• AGENTS.md — Codex、Jules、goose、opencode、Zed、Warp、VS Code、Devin のエントリーポイント
• GEMINI.md — Gemini CLI と Google Antigravity のエントリーポイント
• AIDER.md — Aider のエントリーポイント
• .agents/skills/polis-protocol/SKILL.md — Codex と Google Antigravity の両方が読み取るスキルのミラー（連携ガイド）

これらはすべて、_polis/CONSTITUTION.md の1か所を参照します。プロトコルを更新するには、このファイルだけを編集します。

ベンダーをまたいだルーティングこそ、このプロトコルが真価を発揮するところです。スペイン語の翻訳は、ユーザーが現在使っているチャットにたまたまいる市民ではなく、spanish-translation で最も実績のある市民に割り当てられます。時間が経つにつれて、チームの成果が特定のモデルの見落としによってボトルネックになることがなくなります。

---

agent-vault との関係

agent-vault は姉妹プロジェクトです。エージェント同士が Obsidian 風の Markdown 共有ボードでやり取りする、よりシンプルなコミュニケーション専用プロトコルです。エージェント同士がメモを残し合うだけでよい場合は、agent-vault で十分です。

次のような場合は、Polis Protocol を選んでください。

• 複数のベンダーのエージェントがいて、ルーティングが重要な場合。
• 記録された結果や教訓を、今後のルーティングに役立てたい場合。
• 現実の必要に応じて、プロトコル自体を改定できる方法が必要な場合。

agent-vault からの移行手順は、references/troubleshooting.md に記載されています。

---

ステータス

v2.0（安定版） — PyPI · MCP レジストリ · ウェブサイト。 このプロトコルは意図的に最小限にとどめています。すべてのファイルはリポジトリ内の Markdown で、依存関係は PyYAML のみです。また、必須のサーバーやデータベースはありません。polis CLI は、Python 3.10～3.13 を対象とする CI の完全なテストスイートに支えられ、init · route · reconcile · status · contract · reserve/release · guardrail · bench · serve · mcp · report · reflect · doctor · verify · migrate を扱います。スキーマ v2（_polis/polis.yml）は、polis migrate --plan|--apply|--rollback で可逆的に移行できます。公式 MCP レジストリへの polis mcp の登録は、1回限りの手動作業です。詳しくは docs/publishing-mcp-registry.md をご覧ください。 フォーク、イシュー、改定を歓迎します。

---

ロードマップ

プロトコル層は安定しています。現在進行中の作業を、期待される影響の大きい順に大まかに示します。

• examples/ ギャラリー — 例を通じて学べる、完成済みの polis を3つ（研究チーム、プロダクトチーム、OSS メンテナーの3人組）用意します。コントリビューションを歓迎します。
• 代替ルーター — 決定論的な UCB1 変種は route_contract.py --policy ucb で、シード付き Thompson サンプリング変種は --policy thompson で利用できます（どちらも references/routing.md に記載）。デフォルトの ε-greedy バンディットと並行して提供します。合成した能力トレースを使ったベンチマークハーネスも用意します。
• コンテキスト付きバンディット — タグごとの履歴だけでなく、契約ごとの特徴量（期限の切迫度、重要度、言語）をルーティングの判断に取り入れます。
• 自動ロールオーバー — 四半期ごとのクロニクルのロールオーバーと、確定済み契約の90日後のアーカイブを1行の cron で行い、手動で整理しなくても、1年間運用する polis の規模を抑えられるようにします。
• ブリッジの拡張 — Aider、opencode、Zed、Devin、Cursor エージェントモード用のエントリーポインターを標準で用意します。それぞれ30行の Markdown スタブです。
• Polis の集合体 — 各サブチームが独自の polis を持ち、薄いメタ polis がチーム横断の契約をルーティングする、複数チームのプロジェクト向けパターンを文書化します。
• ビジュアライザー — routing_stats.yml とクロニクルを読み込み、チームの成長を時系列で表示する小さな静的ダッシュボードを作成します。（おまけ：新しい polis で最初の契約として開き、実際に使ってみましょう。）
• 学術的な解説 — マルチエージェント協調に関する研究（バンディットに基づくタスク割り当て、ブラックボードアーキテクチャ、エージェントベースシミュレーション）の中で Polis を位置づける短い論文を作成します。

このリストにない要望がある場合は、amendment-proposal issue を作成してください。

---

コントリビューション

CONTRIBUTING.md をご覧ください。バグ報告、修正提案、新しいブリッジツール、実例の投稿を歓迎します。セキュリティに関する報告は SECURITY.md までお寄せください。

---

引用

学術研究で Polis Protocol を使用する場合は、CITATION.cff または GitHub の「このリポジトリを引用」ボタンから引用してください。

---

ライセンス

MIT — Yehuda Levy、2026年。