zcode-delegate

ZCode 委任

あなたはオーケストレーターです。このスキルを使うと、範囲を限定したコーディングタスクを別の実装担当である Z.AI ZCode CLI に任せ、その成果をレビューして自分で取り込めます。ブリーフを作成し、判断の責任を持つのはあなたです。ZCode がコードを書き、あなたが検証してコミットします。

ここに記載する内容は、特定のオーケストレーターに限定されません。この一連の手順に必要なのは、シェルコマンドを実行し、ファイルを読み取る機能だけです。（Claude Code 向けに設計され、そこで実行されています。他のオーケストレーターについては、設計上は対応していますが、まだ実証されていないものとして扱ってください。）

使用しない場合

• タスクがその場で済ませられるほど小さい場合。委任のオーバーヘッドに見合いません。
• ZCode がインストールされていない場合、または CLI にモデルプロバイダーが設定されていない場合。
• 自分でコードを書きたい場合、またはレビューだけが必要な場合。

前提条件（一度だけ確認）

1. ZCode がインストールされていること。 CLI はデスクトップアプリ内に含まれており、PATH 上にも npm にもありません。リレーは、まず --zcode-path <file> または ZCODE_CLI を確認し、次に PATH、最後にインストール済みアプリのバンドルの順に解決します。Linux ではアプリは AppImage で、固定のインストールパスがないため、フラグまたは環境変数が必須です。リレーが推測することはありません。
2. CLI にモデルプロバイダーが設定されており、実際に接続できるキーがあること。 デスクトップアプリにサインインしているだけでは不十分です。詳しくは以下を参照してください。
3. 対象の Git リポジトリ内にいること（または --cd でそのリポジトリを指定すること）。

リレーは CLI のバージョンと解決方法を result.json に記録するため、予期しないインストール状態も後から確認できます。

ヘッドレス CLI の認証

ZCode デスクトップアプリにサインインしても、このリレーが操作する CLI は認証されません。 CLI はデスクトップアプリとは別に、独自の設定を ~/.zcode/cli/config.json に保持しており、両者をつなぐものはありません。想定されている方法は zcode login ですが、OAuth response is not valid JSON というエラーが発生する場合は、Z.AI API キーを使います。

必要なものは2つあり、それぞれ別個に設定します。

1. プロバイダーブロックを ~/.zcode/cli/config.json に設定する必要があります。これはプロバイダー、そのエンドポイント、モデルを定義するもので、環境変数では設定できません。

   {
     "provider": {
       "zai": {
         "kind": "anthropic",
         "options": { "apiKeyRequired": true, "baseURL": "https://api.z.ai/api/anthropic" },
         "models": { "glm-5.1": { "name": "GLM-5.1" } }
       }
     },
     "model": { "main": "zai/glm-5.1" }
   }
   

2. キーは、そのファイル内の provider.zai.options.apiKey に設定するか、ZAI_API_KEY、ZCODE_API_KEY、ANTHROPIC_API_KEY のいずれかの環境変数に設定できます。秘密情報をディスクに保存せずに済むため、環境変数の使用を推奨します。

実行時に Model provider is missing an API key: <provider> というエラーが発生した場合、プロバイダーブロックは解決されていますが、キーが見つかりません。これらの変数のいずれかを設定して再実行してください。

自律性 — ディスパッチ前にお読みください

ZCode ではモードという用語を使います。モードは4種類ありますが、ヘッドレスで使用できるのは2種類だけです。

mode	動作
yolo	書き込みます。 ZCode で --prompt を指定した場合の既定値であり、このリレーの書き込み可能な既定モードです。
plan	編集を拒否します。 --read-only で選択されます。
build	このリレーでは拒否されます。 ヘッドレスでは権限クライアントが存在しないため、ツールはブロックされ、何もせずに実行が終了コード 0 で終了します。
edit	同じ理由で拒否されます。

ZCode では保証できないため、2つの制限を明記します。

• テストでは plan モードで編集が拒否されましたが、リレーはそれを保証として扱いません。 実行前に Git のフィンガープリントを取得し、実行後に3状態の readOnlyViolation を報告します。編集されていないと思い込まず、touchedFiles が空で返されたことを確認してください。
• ZCode に --allowed-tools はありません。 存在するのは拒否リストの --disallowed-tools だけで、こちらは実際に適用されます。そのため、ツールを明示的に許可リストで制限することはできません。そうした制限があると思い込まないでください。

一連の手順

タスクごとに、以下の5つのステップを実行します。ステップ1、4、5ではあなたが判断し、2と3は機械的に処理されます。

1. 依頼内容を作成する

ZCode が参照できるのは、送信した内容だけです。リポジトリの記憶もチャット履歴もありません。タスクに必要な情報をすべて依頼内容に含めてください。目標、現在の状態、変更する内容、変更せずに残す内容、プロジェクトで実際に使われているゲートコマンド（リポジトリの CLAUDE.md／AGENTS.md／Makefile から確認してください。推測してはいけません）、そして報告の形式です。ZCode はコミットしないと伝えてください。依頼内容 1 件につきタスクは 1 つです。リレーは依頼内容を添付ファイルとして渡すため、コマンドラインの長さ制限には収まりません。ただし、モデルのコンテキストウィンドウには上限があります。詳しいガイダンスとテンプレート： references/writing-the-brief.md。

2. ディスパッチする

Codex でバックグラウンド作業をオーケストレーションする場合は、まず別のサポートユーティリティであるcodex-backgroundをインストールして設定してください。MCP ツールまたはレジストリがない場合は停止し、セットアップが必要であることを報告してください。モデル主導のポーリングに黙って切り替えてはいけません。その後、以下のシェルの例に代えて、登録済みの delegate_run MCP ツールを 1 回呼び出してください。 構造化された共通引数、変更しないプロバイダーフラグ、runId による再接続については、そのスキルの指示に従ってください。完了するまでリクエストを保留状態にしてから、このスキルのレビューと取り込みの手順を続けてください。その他のオーケストレーターでは、以下のシェルのワークフローを使用してください。

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# read-only (review/diagnosis, no edits):   add --read-only
# continue a specific session:              add --session <sess_...>  (from result.json; send only the delta brief)
# continue the latest session for --cd:     add --resume-last
# withhold tools (denylist):                add --disallowed-tools "Write,Edit,Bash"
# point at the CLI explicitly:              add --zcode-path /path/to/zcode.cjs
# hard time limit (watchdog):               add --timeout 2h  (default: off)
# see all options:                          node .../relay.mjs --help

(<skill-dir> は、このスキルがインストールされているディレクトリ、つまりこの SKILL.md を含むフォルダーです。)

リレーは成果物を一時ディレクトリに書き込むため、レビュー対象のリポジトリはクリーンな状態に保たれます。リレーがコミットすることはありません。手順 5 を参照してください。仕組み、フラグ、result.json の形式については、こちらを参照してください： references/dispatch-and-poll.md。

3. 完了を待つ

codex-background を使う Codex では、元の MCP リクエストが保留状態のままになります。モデル主導でスリープ、ステータス、ログのポーリングを行わないでください。中断されたリクエストに再接続する場合に限り、delegate_wait を使用してください。

リレーは ZCode が完了するまで処理をブロックするため、オーケストレーターが提供する方法で待機させてください。

• Claude Code： run_in_background: true を指定して Bash 呼び出しを実行します。完了すると通知されます。
• 通常のシェル／その他のエージェント： 短いタスクはフォアグラウンドで実行し、それ以外はバックグラウンドで実行して結果ファイルをポーリングします。result.json が存在し、status が含まれていれば実行は完了です。実行前の使用方法エラーでは終了コード 2 が返され、結果ファイルは書き込まれません。そのため、終了コードも確認してください。CLI が見つからない場合は終了コード 127 が返されますが、status が zcode_unavailable の result.json は書き込まれます。

進捗トラッカーを実際の状態より信用しないでください。ステータス行ではなく、作業ツリーを確認してください。

4. レビュー — 自己報告を鵜呑みにしない

• プロジェクトのゲートを自分で再実行してください。「ゲートを通過した」という報告を決して鵜呑みにしないでください。
• 依頼内容と照らし合わせて差分を確認します。 ZCode は依頼どおりに、過不足なく作業しましたか？最初に touchedFiles を確認してください。
• --read-only で実行した場合は、readOnlyViolation を確認し、touchedFiles が空であることを確かめてください。
• インストール済みであれば、差分に関連するガードスキルを実行してください。

チェックリストの全文：references/review-and-land.md。

5. 取り込む

コミットするのはオーケストレーターです。 ゲートを通過し、差分に問題がないことを確認してから、次の手順に進んでください。

• 検証済みの作業を、明確なメッセージを付けて自分でコミットします。
• 変更が必要な場合は、前回の result.json にある sessionId を使って --session <sessionId> を指定し、差分依頼を送信してから再度レビューします。

読み取り専用でのセカンドオピニオン

リレーを使えば、書き込みリスクなしで批判的なセカンドオピニオンを得ることもできます。合意済みの点と、争点ごとに双方の見解を列挙した依頼内容を添えて、--read-only をディスパッチします。そして、各争点について ZCode に立場を擁護するか、譲歩するかを尋ねてください。ここではプランモードの保証は強制ではなく計測にとどまるため、編集がないと思い込まず、返された touchedFiles が空であることを確認してください。

認可モデル

委任するかどうかは、人間が選択します。委任した後は、検証済みでゲートを通過した作業をコミットすることが、合意された契約です。制限は 2 つあります。表に出し、抱え込まない（ZCode の設計上の判断や、求められてはいないものの正当化できる対応を、黙って抱え込まずに報告します）ことと、スコープの変更時には停止する（正しく完了するために依頼の範囲を超える必要がある場合は、確認を求めます）ことです。詳しくはreferences/review-and-land.mdを参照してください。

参考資料

• references/writing-the-brief.md — ZCode が指示を受けずに実行できるブリーフの書き方：構成、レポートの契約、実際のゲートコマンドの埋め込み方法。
• references/dispatch-and-poll.md — relay.mjs のフラグ、result.json の契約、CLI の解決方法、バックグラウンド実行、復旧方法。
• references/review-and-land.md — レビューチェックリスト、コミットの境界、同一セッションでの正確な手戻りサイクル。
• references/multi-task-queues.md — 順次キューの実行方法：制約の引き継ぎ、進捗の追跡、実行終了時の整合性チェック。