--- title: "エージェントをチームのように動かす" description: "「エージェントをチームのように動かす」：yokoten ガイドの一章。" canonical: https://yokoten.app/ja/docs/guide/managing-agents-like-a-team lang: ja source: https://github.com/yokoten-labs/yokoten/blob/v0.1.2/docs/i18n/ja/guide.md ref: "v0.1.2" --- > For AI agents: the documentation index is at https://yokoten.app/llms.txt. To set up yokoten in a project, follow https://yokoten.app/agents.md. # エージェントをチームのように動かす この仕組みは、エージェントをラインの作業者として扱います。それぞれに明確な役割と、限られた権限があります。 - **オーナー**（あなた）が、何を作り、いつ出すかを決めます。プルリクエストを承認し、リリースのタグを作り、リポジトリの設定を変えるのはあなただけです。 - **リード**は、あなたが話すセッションです。計画を立て、作業を分け、レビューし、**ボット**を通してプルリクエストを開きます。あなたのアカウントでは決して開きません。 - **ワーカー**は、リードがタスク一つずつために始めるセッションです。`.worktrees/` の下の自分のワークツリーで、`YOKOTEN_ROLE=worker` を持ちます。コードを変え、報告します。決して push しません。修正タスクは `YOKOTEN_FIX_TASK=1` も受け取ります。すると番人とコミットチェックが、テストのファイルへの変更を止めます。停止フックがブリーフの done-when のコマンドを走らせます。三回拒否されたあと、ワーカーは止まってよいことになります。リードへのメッセージは「NOT DONE: checks failing」で始まります。リンクしたワークツリーでは、`.yokoten-agent.json` が `checks` を記録します。リードがそのファイルを読みます。カンバンの `/api/state` は `checks` をコミットチェックとして示します。 - **ボット**は、リポジトリにインストールした GitHub App です。プルリクエストを開きます。Workflows の権限があっても、CODEOWNERS がすべての CI の変更をあなたに送り、リリースは保護された `release` 環境であなたを待ちます。ルールセットがあなたのレビューを求めるので、それが開くものがあなたなしでマージされることはありません。 ワーカーは番人のもとでコマンドを走らせます。だからブリーフは次のルールに合わせて書きます。 - コマンドは `cd && cmd && cmd` の形で書きます。`cd` は単独で置き、`&&` か `;` でつなぎます。サブシェル、パイプ、バックグラウンドの中には置けません。`cd` のあとにパイプは使いません。 - `git -C` は使いません。先に `cd` でワークツリーに入ります。 - コマンドの前に `VAR=value` は付けません。例外は `TZ`、`CI`、`NODE_ENV`、`NO_COLOR`、`FORCE_COLOR`、`DEBUG`、`LANG`、`LC_ALL` と、`yokoten.json` の `worker.settings` に書いた名前だけです。 - タスクにほかの設定が要るとき（たとえばテストの出力ファイル）は、リードが自分で用意し、ファイルとしてワーカーに渡します。 七つのスキルがこの方法を運びます。`dispatch` はワーカーにブリーフを渡します。`inspect` は一つの正確なコミットを三つの段階でレビューします。`rca` は原因を見つけ、チェックを足し、それを広めます。`record` は決断を書き留めます。`release` は次の版を選び、変更履歴を用意します。タグを打つのはオーナーです。`merge` はボットを通してマージし、新しいコミットが UTC でないときに止まります。`yokoten` は実践を導入します。三つのエージェントが作業します。`worker`、`reviewer`（読むだけ）、`verifier`（走らせるだけで、決して直さない）です。 ## 誰が何をレビューするか レビューはリスクに従います。プルリクエストの 1 行目のティアが、ミスを取り消す難しさを言います（記録 0004）。 | ティア | 変更の種類 | レビューする人 | |------|----------------|-------------| | C | 標準: 文書、言葉、スタイル | リード | | B | 普通: テストのあるほかのコード | リード | | A | 取り消しにくい: 秘密情報、データ、インストール、リリース、所有するファイル | オーナー。ハードラインでもルールを緩める変更でもないパスは、別のモデルのエリアリードも承認できます（記録 0047） | `.github/CODEOWNERS` は所有するファイルを並べます。ルール、キット、エージェントの設定、CI、記録です。すべてのファイルを並べるのではありません。新しいプロジェクトでは、`init` がリード専用のパスのために一つ書きます。「require review from code owners」がオンのとき、ホストはそれらの一つを変えるプルリクエストをオーナーにレビューさせます。 `check --pr` は二つを結びます。所有するファイルを変えるプルリクエストは、1 行目が `tier: A` でないと失敗します。パスが一番低いティアを決めます。著者はティアを上げられますが、決して下げられません。チェックは基底ブランチから CODEOWNERS を読むので、プルリクエストがファイルを編集して自分のティアを下げることはできません。基底のコミットがないローカルの実行では、作業ツリーを読みます。メッセージはどちらを読んだかを言います。CODEOWNERS のファイルがなければ、チェックもありません。 承認は一つのコミットに対するもので、プルリクエストの変更ファイルのコードオーナーから来なければなりません。オーナーのログインはコラボレーターとして承認するので、アカウントは決して数えず、CODEOWNERS の所属だけが数えます。変更ファイルがオーナーを名指ししないときは、CODEOWNERS のどこかで名指しされたオーナーなら誰でも数えます。`yokoten bot` は、最新のコードオーナーのレビューが head への Approve でないティア A のプルリクエストの `gh pr merge` を拒否します。より新しい changes-requested や dismissed のレビューも拒否し、ほかのレビューは決して数えません。head が新しいときは、基底ブランチのきれいなマージのときだけマージが進みます。プルリクエスト自身の差分が Approve のときと同じでなければなりません。そうでなければ拒否します。the Approve is on ; commits with changes came after it; ask the owner to approve again です。ボットを通した `gh pr status` は、ティア A のプルリクエストに同じチェックを示します。GitHub の古い承認を dismissed にする設定もオンのままにしてください。ただし yokoten は、プロジェクトが持たないかもしれないホストの設定に決して依存しません。 レビュアーはラベルを通してティアを見つけるので、`check --pr` もラベルを読みます。プルリクエストにはタイプのラベル一つとティアのラベル一つが要ります。タイプのラベルはタイトルのタイプ（`feat`、`fix`、`docs`、`refactor`、`ci` など）か、その一般的な名前です。`fix` には `bug`、`hotfix`、`incident`、`feat` には `feature`、`enhancement`、`docs` には `documentation` です。ティアのラベルは `tier A`、`tier B`、`tier C` です（`tier: B` も数えます）。本文の `tier:` の行と一致しなければなりません。足りないラベルや間違ったラベルは、それぞれ自分のメッセージを受け取ります。 サーバーの設定を、一歩ずつ: [`docs/server.md`](https://github.com/yokoten-labs/yokoten/blob/v0.1.2/docs/server.md)。 ## デスク デスクは一つの AI が一つのタスクをするための囲われた場所で、どのベンダーでも同じです（#637）。 issue 番号か、引用符で囲んだタスクを渡すと始まります。 ```sh yokoten desk 42 yokoten desk "fix the login bug" --agent codex ``` `yokoten desk` はデスク `../-desks//`（専用のクローン、ブランチ `desk/`）を作り、 指示書を書いて、囲いの中で AI を始めます。push はしません。`--pr` を付けたときだけ、ブランチを push して プルリクエストを開きます。AI が終わると、囲いの中でチェックとテストを走らせ、証拠を見せます。 引数なしだと、あなたのデスクを一覧にします。 スクリプト向けの古い形では、自分で作った囲い用のクローンで任意のコマンドを始められます。 ```sh git clone ../yokoten ../desks/42 yokoten desk claude-code ../desks/42 -- claude -p "$(cat brief.md)" ``` 囲いは一つの契約です。各システムが自分のやり方で作ります。 | ルール | デスクの中 | |---|---| | 書き込み | デスクのフォルダ（`.git` も。ワーカーがコミットできるように）と、エージェントのためのデスク自身の状態フォルダだけ。`.git/config` と `.git/hooks` は読み取り専用のまま | | 読み取り | エージェントが見られるほかのすべては読み取り専用 | | ほかのプロジェクト | 見えない。あなたのホームと、デスクの親フォルダは隠れる。Linux では `/run` も隠れる。そのソケットが外へ通じ、WSL2 ではその一つが Windows のプログラムを始めるからだ。Node、エージェントのプログラム、yokoten は読み取り専用で再び見える | | あなたのエージェントの状態 | 見えない。あなたの `~/.claude`、`~/.codex`、`~/.grok`、Muse のフォルダは隠れたまま。設定、フック、記憶、MCP の設定、履歴、セッションはない | | 子プロセス | 動く。パイプつきなので、テストがプログラムを始められる | | ネットワーク | コマンドは自分のネットワークを持たない。外のプロキシはエージェントの API のホストだけを通す。中のどのコマンドもプロキシを使えるので、コマンドはそれらのホストに届きうる | | 環境 | `YOKOTEN_ROLE=worker` と `TZ=UTC`。あなたのシェルのトークンも鍵もない（[エージェントの環境が持つもの](https://yokoten.app/ja/docs/guide/privacy.md#エージェントの環境が持つもの)を見てください） | | チーム | チームのフォルダは読み取り専用。その中のエージェント自身の outbox だけが書き込み可能（[エージェント同士のメッセージ](https://yokoten.app/ja/docs/guide/managing-agents-like-a-team.md#エージェント同士のメッセージ)を見てください） | デスクは自分の `git clone` でなければなりません。ワークツリーの git フォルダは別のチェックアウトにあり、デスクはそれを隠すので、ワークツリーは拒否されます。 **デスクの状態フォルダ。** 各デスクは、エージェントのための自分の状態フォルダを、すぐ横に持ちます。`.state/` です。デスクはエージェント自身の変数で、エージェントをそこに向けます。あなたのものからコピーするのはログインのファイルだけです。あなたの新しいログインは、次の開始でまたコピーされます。状態フォルダはデスクと一緒に消してください。 | エージェント | `` | 状態を指すもの | コピーするログインのファイル | API のホスト | デスクの中のコマンド | |---|---|---|---|---|---| | Claude Code | `claude-code` | `CLAUDE_CONFIG_DIR` | `.credentials.json` | `api.anthropic.com`、ログインの更新には `platform.claude.com` | `claude -p ""` | | Codex、および Codex を通した DeepSeek | `codex` | `CODEX_HOME` | `auth.json` | `api.openai.com`、`api.deepseek.com` | `codex exec --sandbox danger-full-access ""` | | Grok | `grok` | `GROK_HOME` | `auth.json` | `api.x.ai` | `grok -p ""` | | Muse Code | `muse` | `XDG_CONFIG_HOME`、`XDG_DATA_HOME` | `muse/auth.json` | `api.meta.ai` | `muse exec ""` | - **Claude Code** は `platform.claude.com` でログインを更新します。`claude setup-token` のトークンを `CLAUDE_CODE_OAUTH_TOKEN` に入れるか、API 鍵なら更新は要らず、ログインとして通ります。 - **Codex** はデスクの中で `--sandbox danger-full-access` で走ります。Codex 自身の `workspace-write` のサンドボックスは `.git` を読み取り専用にし、テストが使うパイプを止めるからです。代わりにデスクが囲いです。あなたの `config.toml` は入りません。プロバイダーはコマンドの `-c` で与えてください。ChatGPT のログインには `--host chatgpt.com,auth.openai.com` も要ります。 - **Grok**: コミットやテストを止めるなら、デスクの中で `--sandbox` を切ってください。 - **もっとホスト**: `--host ` は、エージェントがポート 443 で別の API のホストに届くようにします。複数はカンマで区切ります。 - **もっとファイル**: `--read ` は別のパスを読み取り専用で見せます。あなたのホーム、隠しフォルダ、あなた自身のエージェントの状態を開くパスは拒否されます。 **プロキシ。** 四つのエージェントはどれも自分のプログラムで `HTTPS_PROXY` を名指しし、デスクは `HTTPS_PROXY`、`HTTP_PROXY`、`ALL_PROXY` をどちらの場合にも設定します。`NODE_USE_ENV_PROXY=1` も設定するので、Node 自身の `fetch` もプロキシを使います。プロキシは `CONNECT` だけを、一覧のホストへ受け取り、通信を決して読みません。開くトンネルは多くても 64 で、10 分たっても残るトンネルは閉じます。ホストを拒否するときは、デスクが最後にそのホストを名指しします。 **外からのレビュー。** ワーカーはデスクの中で書くので、デスクを信頼できないものとして扱ってください。作業を確かめる前に、デスクの中で git やほかのコマンドを走らせないでください。ブランチを自分のチェックアウトに取り込み、そこでレビューします。 ```sh git fetch ../desks/42 HEAD:refs/desks/42 git diff main refs/desks/42 ``` `.git/config` と `.git/hooks` はデスクの中で読み取り専用なので、ワーカーはそこにフックやエイリアスを仕込めません。上流やほかの設定は、デスクを始める前に外から設定してください。 **コミットチェックとあなたの非公開の印。** コミットチェックはあなたの非公開の印のファイルを読みます。そのファイルを読めるエージェントは、それを出力もできます。だからデスクは既定でそれを隠し、デスクの中のチェックはあなたの印を見ません。印がハッシュとして保たれるまで（#665）、チェックはあなた自身で、デスクの外で走らせてください。取り込んだブランチを自分のチェックアウトにチェックアウトし、そこで `yokoten check` を走らせます。ツリー全体をチェックします。`--marks` はそのファイルをデスクの中で読み取り専用で見せます。その言葉を信頼するエージェントにだけ使ってください。 **システム。** - **Linux と WSL2**: `bwrap`（bubblewrap）。`sudo apt install bubblewrap` で入れます。デスクは自分の空のネットワークを持ちます。中の小さなブリッジが、エージェントのプロキシの接続を外のプロキシへ渡します。 - **macOS**: 組み込みの `sandbox-exec` に、デスクごとに書いたプロファイルを使います。プロファイルは「すべてを拒否」から始まり、デスクが必要とする読み取り、書き込み、Mach サービス、プロキシのポートだけを許します。`open`、`osascript`、Launch Services、Apple のイベントを止めます。Mac ではまだ走らせていません。そこで一度 `node --test test/agents/desk/start.test.ts` を走らせ、契約を確かめてください。 - **ネイティブの Windows**: 実験的で、まだ準備できていません（#669）。制限付きトークンの補助プログラム、デスクの ACL、ファイアウォールのルールが要ります。本物の Windows 11 で #637 の契約のテストが通るまで、ワーカーを始めません。それまでは WSL2 で yokoten を走らせてください。Linux のデスクがそこでは動きます。ネイティブの Windows では、番人だけがルールを保ちます。 ## エージェント同士のメッセージ どのベンダーのエージェントも、互いにメッセージを送れます（#674）。このマシンのファイルです。サーバーもネットワークもありません。 ```sh yokoten msg send lead "tests pass; ready for review" yokoten msg inbox yokoten msg who yokoten msg log ``` - **どこ**: あなたのチェックアウトの横のチームフォルダ、`.team/` です。各エージェントはそこに自分の outbox だけを書きます。`yokoten desk` はエージェントを `--name` で、またはデスクのフォルダ名を小文字にしたもので足します。名前にできないフォルダ名は、どのチームにも入りません。 - **あなたが誰か**: デスクの中ではデスクが言います。外では、あなたが `lead` なのはメインのチェックアウトでだけです。ワークツリーや、デスクの中のチェックアウトでは違います。 - **デスクは送信者を偽れない**: デスクの中ではチームのフォルダが読み取り専用で、エージェント自身の outbox だけが書き込み可能です。`msg send` はデスクの外のワーカーを拒否し、番人はチームフォルダへのその編集を止めます。 - **デスクの外では送信者を偽れる**: デスクの外のプログラムはあなたのユーザーとして走るので、どの outbox にも、リードのものにも書けます。普通のワークツリーのワーカーも、たとえば自分のフォルダを出るインラインのコードからそれができます。yokoten はそのような書き込みをあなたのものと見分けられません。メッセージを送るワーカーはデスクで走らせてください。 - **配送**: フックが読んでいないメッセージをエージェントのコンテキストに足します。Claude Code と Grok はツール呼び出しの前に受け取ります。どのエージェントもターンの終わりに、チェックのあとで受け取ります。チェックに失敗したターンは、メッセージと一緒に送り返されます。`msg inbox` はいつでもそれらを見せます。Muse Code のフックは変数を受け取らないので、デスクの Muse は `msg inbox` で読みます。 - **メッセージはデータ**: どの配送も、メッセージは別のエージェントからのもので、承認や許可を与えられないと言います。この注意が防衛です。各メッセージは送信者のベンダーとモデルを名指しします。オーナーの承認という主張のいくつかには印が付きますが、その印は別の言葉での主張を見落とします。 - **プライバシー**: メッセージは投稿されるテキストと同じ走査を受けます。非公開の印、秘密情報、メールと IP アドレス、秘密の変数です。失敗したメッセージは送られず、あなたが理由を受け取ります。走査は素のテキストを読むので、符号化されたり分割されたりした秘密情報は通ります。デスクがあなたの非公開の印を見るのは `--marks` のときだけなので、あるデスクから別のデスクへのメッセージは、そのときだけ印と照らされます。リードが読むものは常にチェックされます。 - **誰が読むか**: チームのどのデスクも、自分のものだけでなく、すべてのメッセージを読めます。 - **上限**: メッセージ一つ 2,000 文字、エージェント一つ 10 分に 20 通、outbox 一つ 256 KB です。 - **ログ**: `msg log` はすべてのメッセージを見せます。走らせるのはリードだけです。 ## カンバン `yokoten kanban` はチームを一目で見せます。プレビュー版なので、今後変わるかもしれません。 読み取り専用で、ここから仕事を始めたり止めたり変えたりはできません。理由は記録 0044 にあります。 （v0.1.2 より前は `yokoten board` という名前でした。古い名前でも動きます。） 見せるものは三つです。 - **セッション。**このリポジトリ、その worktree、そのデスクにある AI のセッションごとに、 エージェント、モデル、タスク、そして作業中・止まっている・待っている・終わった、のどれか。 15 分間出力がないセッションは「止まっている」と数えます。 - **証拠。**セッションごとに、システムのサンドボックスで囲まれていたか、番人だけだったか。 コミットチェックが通ったか。Linux、Windows、macOS でのテストの結果。ステータスファイルがプラットフォームを記録するまで、この三つは「未証明」と出ます。 - **プルリクエストと Actions。**あなたを待っているプルリクエスト、最近マージされたもの、 GitHub Actions の状態。各エージェントが使ったトークン数も一緒に出ます。 `yokoten kanban --text` は、セッションを状態別に、続けてプルリクエストと Actions を素のテキストで出力して終わります。これは今すぐ使えます。 証拠とトークン数は、いまは `GET /api/state` にあります。 `--text` なしだと、このマシンでだけ動くページを `http://.localhost:/` に出します。 `` はフォルダ名を、ホスト名に使える形にしたものです。ポートはこのリポジトリでは変わりません。 ブラウザーでページを開き、サインイン済みの状態で、Ctrl-C で止めるまで動き続けます。 `--no-open` を付けるとアドレスだけを出力します。サインイン用の鍵はブラウザーにだけ渡り、出力されません。 ホスト名が違うリクエストは断ります。 ページは独立したウェブパッケージとして作り直し中です（記録 0044）。できあがるまでは、`/` を開くと 一行の説明が出るだけですが、`GET /api/state` は使えます。セッション、プルリクエスト、Actions の スナップショットを JSON で返します。`GET /api/sessions//stream` は一つのセッションの出力を サーバー送信イベントで流します。id はセッションのフォルダのハッシュで、パスではありません。 GET と HEAD 以外のリクエストは 405 を返します。 カンバンは `gh` で GitHub をバックグラウンドで一度に一つずつ読みます。読めなかったときは、前の一覧を残します。 どのエージェントも番人を通り、push とマージは bot だけが行います。 エージェントは自分から現れます。このリポジトリ、その worktree、またはデスク（`yokoten desk`）で エージェントを始めると、yokoten のフックがそのチェックアウトの根の `.yokoten-agent.json` に状態を書きます。 どのベンダーでも同じです。 - セッションの開始で、`vendor`、`model`、`role`（メインのチェックアウトでは `lead`、ワーカーでは `engineer`。番人と同じ規則で決まります）、`worktree`、`state: working`、`started` を書きます。 `started` は一度だけ書きます。Grok には開始フックがないので、最初の呼び出しが書きます。 - 許可されたツール呼び出しごとに `doing` と `updated` を更新します。5 秒に一度までです。 - 拒否された呼び出しは `blocked` を書きます。次に許可された呼び出しがそれを消します。 - 停止で `state` を書きます。ワーカーは `checks` 付きの `done`、リードは `waiting` です。 フックがこのファイルを書くのは、`yokoten.json` があるリポジトリだけです。ワーカーはメインのチェックアウトの ファイルには書きません。それはリードのものです。最初に書くとき、リポジトリ自身の `.git/info/exclude` に このファイルを足すので、`git status` には出ません。デスクは普通のクローンなので `git worktree list` には 出ません。そこで `yokoten desk` がリポジトリの git フォルダに記録し、カンバンもそれを表示します。 エージェントが `task` のようにこのファイルを自分で書いてもかまいません。フックは自分が設定しない フィールドには触れません。ファイルを消せば抜けたことになります。形式は公開されていて、ほかの ツールも読めます。worktree ごとに一つです。 | フィールド | 意味 | |-------|-------| | `name` | エージェントの名前。なければ worktree のフォルダ名 | | `vendor` | どのベンダーで動くか。`claude-code`、`codex`、`grok` など | | `model`, `effort` | モデルと力の入れ具合。`opus` と `medium` など | | `role` | `lead`、`engineer`、`reviewer`、`verifier`、`helper` | | `task` | 取り組んでいること。例：`PR #615 Run rules locally` | | `worktree` | 作業している worktree | | `doing` | いまやっていること。数語で | | `state` | `working`、`waiting`（あなたを待っている）、`done` | | `checks` | 直近のテスト実行の結果。`passing` か `failing`。`/api/state` ではコミットチェックとして出ます | | `updated` | 最後に書いた時刻。例：`2026-10-22T10:00:00Z`。15 分静かだと「止まっている」と出ます | | `started` | この作業を始めた時刻。例：`2026-10-22T08:00:00Z`。なければファイルの作成時刻、それもなければ `updated` | | `blocked` | 決定が要る番人の停止。一行で | どのフィールドも文字列で、どれもなくてかまいません。JSON オブジェクトでないファイルは読み飛ばします。 `state` と `checks` は上の言葉以外なら無視します。 エージェントが書いたものは文字としてだけ表示し、ページのコードとしては扱いません。セッションと同じく 先に伏せ字にします。カンバンはインターネットから何も読み込みません。インターフェースは `/api/state` で、 ページはその見せ方の一つにすぎません。 --- 前の章: [命名](https://yokoten.app/ja/docs/guide/naming.md) 次の章: [プライバシー](https://yokoten.app/ja/docs/guide/privacy.md)