delegation-spec

Files (1)

• SKILL.md

SKILL.md (first lines)

# Delegation Spec — 委任仕様テンプレ

司令塔が worker（Codex / Claude）へ渡す task spec の必須構成。worker は literal に実行し、曖昧さを意図で補完しない前提で書く。

## 必須7節

1. **背景** — 前提事実と実測済み事項。worker に再調査させない範囲を明示する
2. **実施内容（literal）** — ファイルパス・変更単位まで具体化。「〜の趣旨で」を使う場合は範囲を限定する。数値・時間オプションは単位・境界値・不正値の扱いまで書く（下記）
3. **スコープ外** — 触ってはいけないファイル・やってはいけない操作を列挙する。禁止は手段でなく意図で書く（例: 「ファイルの作成・編集、コミット、設定の変更はしない」）。手段で書くと、worker が仕事に使う道具まで塞ぐ（実例: 「シェルコマンドの実行」と「ほかのツールの呼び出し」を禁じた確認の指示で、Codex の worker が MCP のツールを呼べずに止まった。Codex は MCP のツールを `exec` ツールの中から呼ぶ → brain `URISK-251`）
4. **検証（rubric）** — 下記チェックリストを満たすこと。結果は worker_done の body に実測値で含めさせる
5. **レビューサイクル** — 実施者（委譲先で完結）を明記。レンズ選定は brain `ref-work-archetypes-bcherny` の対応表、収束規律は standards `AI_FIRST.md` §3 の値で（スキル既定値を上書き）。**最大ラウンド数を明記する**（下記）。**レビューの実行手段も書く**（下記）
6. **完了条件** — PR 作成まで。main へのマージは human-gate。PR 本文の要件（変更概要・検証結果・レビュー記録・実装担当識別子）。レビューで受容した指摘（ACCEPTED_RISKS）は、レビュー記録と PR 本文だけでなく、対象リポの `.docs/risk-registry.md` にも記録させる（集約先と書式（accepted・受容の理由・anchor）の正本は standards `DOCS_OPS.md` §3）。記録先を書かないと、worker は仕様が挙げた置き場にだけ書く。対象リポに `.docs/risk-registry.md` が無いときは、どこに記録させるかを仕様に書く。既存の PR・文書へ積む委任では、**既存本文の扱い**も書く（下記）
7. **制約** — 「指示と実態が矛盾したら止めて ask で報告」（MUST）＋裁量範囲と変更申告義務。**逆委任は受けない**——環境制約（thread / turn 上限・ツール不在等）で担当範囲を遂行できないときは、司令塔へ範囲を戻さず ask で報告して判断を待つ。事前合意済みの代行に別作業を同梱しない（司令塔側の規律は `~/.claude/CLAUDE.md`「エージェント役割分担」）

## 検証節の事前チェックリスト（書く前に司令塔が確認する）

失敗パターンの正本は `~/.claude/references/verification-pitfalls.md`。

- [ ] 検証コマンドは**書く前に実行してベースラインを取った**か（「PASS するはず」を期待値にしない）。仕様に貼る文字列は**実測した文字列そのまま**か（パスの書き方を変えたら測り直す——実例: `npm pack` を絶対パスで測り、仕様には相対パス `apps/cli` で書いたところ、npm が GitHub の `owner/repo` の略記と解釈して exit 128 になった）
- [ ] テスト先行の「失敗を確かめる」Step の期待を、件数でなく**落ち方**で書いたか。assertion で落ちる／未実装の export を静的 import するファイルは読み込みで丸ごと落ちる（同じファイルの既存テストも走らない）／「404 を返す」だけを見るテストはルートが無くても通る、の 3 つを区別する（実例: 「追加した N 件が FAIL・既存は PASS」と書いた計画で、2 つの Task は「404 だけを見るテストがルート無しで通る」、1 つの Task は「読み込みで丸ごと落ちる」ために件数が合わず、worker が 3 Task 続けて止まった）
- [ ] 応答・出力の**形を変える**委任で、形を完全一致で固定している既存テスト（`Object.keys(...)` の `toEqual`・スナップショット）を grep して対象ファイルに入れたか（実例: API の応答に 1 項目足したら、内部の項目を漏らさないためのキーの完全一致テスト 2 件が落ち、対象外のファイルなので worker が止まった）
- [ ] 入力の扱い（省略・空文字・型違い）を仕様や計画のコードで具体化したとき、**設計書の文と同じ言葉**になっているか（実例: 設計は「`true` / `false` 以外は 400」、計画のコードは既存の正規化で空文字を省略扱い → どちらが契約か worker が決められず止まった）
- [ ] 本番に対して流す手順（デプロイ後のスモーク等）の入力が、**本番の設定値でも通るか**をコードで追ったか。テスト環境の既定値で通っても、本番の設定との組み合わせで拒否されることがある（実例: スモークが作る対象の種類が、本番のワークスペース設定（テスト環境の既定値とは違う値）との組み合わせでは作成を 400 で拒否されるものだった。レビューの optional で見つかり、既存のスモークと同じ種類に変えてマージ前に直した）
- [ ] probe に使う値（クラス名・文字列・パス）の**実在を確認した**か
- [ ] 負の検査（禁止語 0 件等）は**出現位置まで指定した**か（部分文字列の偽陽性——実例:「ッピ」probe が「マッピング」に命中）。さらにその probe を**仕様に書いた置換後文言そのものに対して実行し 0 件**を確認したか（実例: 置換後文言に訂正履歴として置換前の語を引用したため、同じ語の負の検査が置換後に必ず命中した）
- [ ] 検証コマンドに pipe・`&&` 連結・`|| true` を**含めていない**か（個々の exit code を確認する形か）
- [ ] 検証コマンドを**表のセルに書いていない**か。Markdown のセル内 `|` はエスケープが要り、`grep -E 'A\|B'` の `\|` は ERE では**リテラルのパイプ**になって交替として解釈されず、意図した候補群にマッチせず、「0 件＝準拠」の偽の通過を作る（実例: 中立性検査の probe が沈黙し、worker も司令塔も気づけなかった）。コマンドは**コードフェンスに置き、表からは参照する** → brain `URISK-116`
- [ ] 背景に、**worker が着手時に自分で観測できる事実**（ブランチ名・作業ツリーが clean か・ファイルの行数・依存やディレクトリの有無）を書いていないか。司令塔は main checkout で測るため、worktree とは別ディレクトリ・別ブランチ・別ファイル集合になり、書けば食い違って `ask` の往復を生む（実例: 1 セッションで 4 回の ask のうち 3 回がこれ）。背景に書くのは**観測しにくい事実**（設計の意図・過去の裁定とその理由・別リポの規定・ライブラリの内部実装・ベースラインの実測値）に限り、観測できる事実は rubric に**測る手順**として置く
- [ ] 同じ対象を変える**ほかの open PR が無いこと**を、背景に司令塔の測定値として書いて済ませていないか。並行セッションは数分の差で同じ変更の PR を出すことがあり、司令塔が dispatch の前に測った「0 件」は、worker が PR を作るときには古くなっている。worker に **PR を作る直前に** `gh pr list --state open --json number,title,files` で同じファイルを変える PR を測らせ、あれば PR を作らずに ask で止まらせる。環境が自分以外の手で変わっていた（使うはずの道具がもう無い、など）ときは、同じテーマで動いているセッションがいる兆しなので、dispatch の前に `orca worktree ps` でその範囲を確かめる（実例: 司令塔が open PR 0 件を測った 2 分後に、別のセッションが同じ変更の PR を出し、その 2 分後に司令塔が委任した。配布物が 1 バイトも違わない PR が 2 つ並び、片方を閉じた。司令塔は、委任の前提にした道具がすでに環境から外れているのを見ていたが、誰が外したかを確かめなかった）
- [ ] 検証報告に**実測の範囲**（可視 / 存在 / 実行 / 動作のどこまで測ったか）を要求したか
- [ ] 独立検証は**情報源まで分けた**か（間接証拠でなく実体への直接照会を1本混ぜる——実例: ディレクトリ一覧で「未配布」と誤判定、ランタイム照会で覆った）
- [ ] worker の完了判定は worker_done の受領でなく**成果物の実体との突合**にしたか
- [ ] 挿入・置換の**位置指定は基準語を 1 つ**にしたか（「X の直前」と「Y の後ろ」を併記すると、どちらに係るか worker が読めない——実例:「`…Rev3…)` の直前」と括弧内の「Rev3 の後ろ」の併記で ask が発生）
- [ ] 仕様本文に**司令塔側のチャット規律**（語尾の指定など）を書いていないか。仕様を成果物（plan ファイル）として保存させると、禁止文字列を含む仕様自身が規律に違反する（実例: 語尾の禁止行を含む仕様を `.docs/plans/` へそのまま保存させて ask が発生）
- [ ] レビュアーに課す制約（ツールを渡さない等）を、**委譲先の harness で実現できる手段まで**書いたか。スキルが要求する制約と、worker を起動した harness が表現できる引数は一致しないことがある
- [ ] 既存の PR・文書へ積む委任で、**既存本文のどの節を置換し・どの節へ追記し・どの節を維持するか**を書いたか
- [ ] worker に、**検査の結果（exit code と出力）を見てからコミットする**よう書いたか。検査とコミットを 1 回の呼び出しにまとめると、落ちた検査のままコミットが残る（実例: 振る舞いを固定するテストのコミットが、型検査の失敗を見る前に作られ、凍結したコミットを作り直す許可を求める ask が発生）
- [ ] 「最後のコミットのあとに検証する」と「検査の結果を見てからコミットする」を両方書くなら、**コミットの前に見る検査と、コミットのあとに測る検査を分けて**、順序まで書いたか。ファイルの中身の検査とテストはコミットの前に見られるが、ブランチの差分（`origin/main...HEAD`）の範囲と行数はコミットのあとでないと測れず、open PR は PR を作る直前、CI は PR を作ったあとでないと測れない。分けずに 2 つの文を並べると、literal に読む worker はどちらの順に従えばよいかを決められない（実例: 同じ 2 文を 3 つの委任仕様に続けて書き、3 つ目で worker が、差分の範囲と行数の検査はコミットのあとでないと測れないと ask で止まった。司令塔は 2 つの文を残したまま、「コミットの前に中身の検査とテスト → コミット → 全項目 → PR を作る直前に open PR → PR を作ったあとに CI」の順序を補足として返した）
- [ ] 中身と関係なく落ちる**環境起因の既知の失敗**（フレーク）があるなら、再実行してよい条件（どのエラーのときか）・回数・証跡の残し方・再実行でも落ちたときの止まり方を、**その検査を実行するすべての段**について書いたか。書かないと literal に実行する worker は「期待値と違う」として毎回止まる（実例: E2E が WebKit だけ開発サーバーへの接続を拒まれて落ちる環境で、再実行の条件を最後の検証にだけ書いた委任が、途中の段の同じ失敗で当てはめてよいかを ask した）
- [ ] UI を持つコードを変える委任では、**振る舞いを変えない書き直しでも** standards `AI_FIRST.md` §3 の収束の対 ②（§2 の検証マトリクス）を rubric に最初から入れたか。worker が PR へ画像を添付できないなら、light / dark の写真は司令塔が完了ゲートで添付すると書く。対象 route の欄のうち既存のテストで確かめていないもの（ある画面の dark・keyboard など）は、テストに足すか、一時のスクリプトで実測して既存のテストと区別して書くかを指定する（実例: rubric を E2E だけにした書き直しの委任で、worker が AI_FIRST §3 との食い違いを ask で止めた。別の委任では、ある画面の keyboard を確かめる既存のテストが無いことを worker が ask した）

## レビューの実行手段まで書く

レビューの規律（レビュアーの人数・レンズ・ツール制限）を定めるのはスキルだが、それを**実行できるかは worker を起動した harness が決める**。スキルの要求と harness の表現力が食い違うと、worker は自分で埋めてよいか判断できず止まる。仕様には「誰が・どのレンズを・何ラウンド」に加えて、**その制約を満たす実行手段**（どのコマンド・どのコンテキストで走らせるか、記録をどこへ残すか）を書く。委譲先の harness に手段が無いなら、司令塔が先に代替手段を決めて仕様へ書く。

**実例**: `lens-review-cycle` はレビュアーへ書き込みツールを渡さないことを求めたが、worker を起動した Orca の `worker-start` にはレビュアーのツールを制限する引数がなく、3 worker 中 2 名が独立に同じ ask を出した。司令塔は、別コンテキストの `claude -p` にツールを渡さず、差分と対象全文を stdin で渡してレビューする方式を裁定した。**レビューの規律はスキルが決めるが、実行可能性は harness が決める。**

**入力の量と打ち切り時間も書く。** 「変更したファイルの全文を渡す」とだけ書くと、仕様書のような大きな既存ファイルまで入って入力が膨らむ。大きな既存ファイルは diff（`git diff -U20` など。新規ファイルは diff に全文が入る）だけを渡し、入力の上限（`wc -c` で測るバイト数）と打ち切り時間を添える。macOS には `timeout` が無いので、`perl -e 'alarm shift @ARGV; exec @ARGV' <秒> <コマンド>`（打ち切ると終了コード 142）のように手段まで書く。

**実例**: 変更ファイルの全文を渡す指示で、レビューの入力が約 694KB（仕様書と 1,900 行の route ファイルの全文を含む）になり、1 回のレビューに 1 時間 40 分かかった。

**起動の形も書く。** `claude -p` の可変長のオプション（`claude --help` で `<tools...>` のように `...` が付くもの。`--tools`・`--allowed-tools`・`--add-dir` など）は、後ろに続く位置引数まで値として吸い込む。`claude -p --tools "" "<指示>"` と書くと、指示文がツールの名前として読まれ、レビュアーは指示を受け取らないまま応答する。指示は入力ファイルに含めて stdin だけで渡すか、`--tools "" -- "<指示>"` のように値の後ろを `--` で区切る。部品として呼ぶ `claude -p` には、設定の読み込みと advisor を止める `--safe-mode` と `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1` も付ける（brain `URISK-238`。agent-env の hook が、付いていない呼び出しを止める）。仕様には次の形で書く。

```bash
CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 perl -e 'alarm shift @ARGV; exec @ARGV' <秒> claude -p --safe-mode --tools "" < <入力ファイル>
```

**実例**: 2026-10-29、委任仕様にレビュアーの起動を `claude -p --safe-mode --tools "" "<レビューの指示>" < <diff>` と書いた。指示文が `--tools` の値として吸い込まれ、stderr に `--tools entry "! grep" was read as "!grep"` と出た。exit 0 で返った応答は、指示した 3 つのレンズも flag の件数の書式も守らず、diff に無いものに言及していた。worker が stderr を読んで止まり、司令塔が `--tools "" --` の形で短い指示と diff を渡して確かめてから、仕様を差し替えた。**exit 0 は、レビュアーが指示を受け取った証拠ではない。**

**記録の残し先は、消えない場所を指定する。** `lens-review-cycle` の作業用ディレクトリ（`/tmp/review-cycle-<worktree 名>`）は、サイクルの記録（対象リポの `.docs/reviews/cycles/<cycle-id>.md`）を書いたあとに消す作業場で、残っていても PC の再起動で消える。変更してよいファイルを絞った委任では、サイクルの記録のファイルも対象外になるので、記録をどこに残すかを仕様に書く（例: PR 本文の「レビュー記録」節に、ラウンドごとのレンズ・指摘・対応を書く）。PR 本文には、`/tmp` やセッションの一時フォルダのパスを証跡として書かせない。書かせるなら「一時的で、いずれ消える」と添えさせる。司令塔が完了ゲートで PR に足す証跡（スクリーンショット・確認のスクリプトの結果）も同じで、添付しないものを「手元に保存してある」と書かない。

**実例**: 変更してよいファイルを 6 つに絞り、レビューの作業用ディレクトリを `/tmp/review-cycle-…` に置かせた委任で、worker は PR 本文のレビュー記録に「レンズ別原文と検証ログ: /tmp/review-cycle-…/」と書いた。司令塔も、添付できなかったスクリーンショットを「司令塔の手元に保存してある」と書いた。8 日後にセッションを再開すると、PC の再起動で `/tmp` とセッションの一時フォルダが消えていて、PR 本文の 3 か所が事実でなくなっていた（brain `URISK-244`）。**PR に残らない証跡は、無いものとして書く。**

## 既存の成果物へ積む委任は、既存本文の扱いを書く

未マージ PR のブランチや既存の文書へ追加コミットを積む委任では、**既存本文が今回の変更と矛盾しうる**。「追記する」とだけ書くと、worker は矛盾を残すか、勝手に書き換えるか、止まって聞くかの三択になる。節ごとに **置換 / 追記 / 維持** のどれかを指定する。目安は、変更後の状態を説明する節（PR の変更概要など）は矛盾箇所を最小置換、履歴として積み上がる節（検証結果・レビュー記録）は既存を残して末尾へ追記、司令塔や他者が書いた節は維持。

**実例**: 未マージ PR へ追加コミットを積む委任で「PR 本文の変更概要に 1〜2 行追記する」とだけ指定したところ、worker は今回の変更と矛盾する旧記述を 3 箇所見つけ、追記だけでは矛盾が残ると ask した。司令塔は「矛盾箇所は最小置換、他節は維持」と裁定した。**PR 本文の変更概要は変更の履歴ではなく、マージ後に残る最終状態の説明である。**

## レビューサイクルの上限をタスクごとに決める

**最大ラウンド数を委任仕様に明記する。** 書かなければスキル既定値（`lens-review-cycle` が正本）が使われ、
タスクの規模に対して過大／過小なことがある。

- 仕様が確定していて範囲が限定的（数ファイルの修正・ドキュメント整合） → **2〜3 ラウンド**
- 新機能・設計変更を含む → **5 ラウンド程度**
- 上限に達しても flag が残る場合は、打ち切って現状を報告させる（自律実行原則の例外）。打ち切るときも、残った flag ごとに「直す」か「理由と anchor を付けて明示的に受容する」かを決めさせ、どちらにしたかを指摘ごとに記録させる（打ち切りで残った指摘の扱いの正本は standards `AI_FIRST.md` §3、受容の書式と anchor の定義は同 `DOCS_OPS.md` §3。実例: 打ち切りの手順を「上限で新しい flag が出たら直さずにレビュー記録に書いて進む」とだけ書いた委任で、受容の判断が抜けているとレビューで指摘された）

**実例**: 仕様が確定した中規模タスク（MCP の診断改善＋設定生成）で上限を書かずに委任した結果、
既定のまま 9 ラウンド・4 時間走り、テストが 200→304 件に増えた。成果物自体は健全だったが、
上限を書いていれば同じ品質へ短時間で到達できた。**上限の指定は品質でなく所要時間を決める。**

## 数値・時間オプションは単位・境界・不正値まで書く

`--timeout <sec>` のように名前と単位だけ書くと、0・負数・小数・上限・丸め方法の扱いが未定義のまま実装へ渡り、
レビューで同じ領域が繰り返し指摘される。仕様に書くのは次の 4 点。

- **単位**（秒かミリ秒か。内部で変換するなら丸め方法も）
- **境界値**（下限・上限。ランタイム固有の上限があるならその値）
- **不正値の扱い**（0・負数・非数を受けたときエラーか既定値か）
- **適用範囲**（そのオプションがどのコマンド・どの通信に効くか）

**実例**: 配送表現の導入タスクで「CLI に `--timeout <sec>` を追加する」とだけ書いた結果、
レビュー R2〜R5 の 4 ラウンドが timeout の境界だけに費やされた
（境界値 → Node timer の実効上限 → 丸め前の入力境界 → 秒からミリ秒への変換で生じる浮動小数点誤差）。
同じ委任の他項目（型の shape・アドレス規則・除外するフィールド）は literal に書いたため 1 ラウンドで収束している。
**レビューのラウンド数は実装の難しさではなく仕様の解像度を映す。**

## 所要時間の目安を渡し、無進捗の判定基準を決めておく

**ラウンド数の上限だけでは「遅い」の基準にならない。** 司令塔は待つ側なので、目安が無いと沈黙を異常と誤認して不要な割り込みをかける。委任時に次を伝える。

- **想定所要時間**（例: このタスクは 30〜60 分。その間 commit が無くても正常）
- **無進捗と判断する基準**（何を、どれだけ観測できなかったら確認するか）

司令塔側の観測は **commit と PR の有無**を基本にする。ファイル更新時刻のような細かい観測はクエリを誤ると偽の異常を生む（→ brain `risk-negative-result-unverified-query`）。amend を使う worker もいるので、commit は件数ではなく**ハッシュの同一性**で見る。

**実例**: 大規模な撤去タスク（21 ファイル）で時間の目安を渡さずに委任した結果、「10 分 commit が無い」を異常と誤認し、正常に作業していた worker を割り込みで停止させた。実際には未コミットのまま数分おきにファイルが更新されており、レビュー往復中だった。**中断のコストは実作業より、司令塔と worker の双方が状況説明に費やす往復のほうが大きい。**

**「止まっている」と判断する前に、その道具の出力の仕方を確かめる。** `claude -p` のような LLM の CLI は応答を最後にまとめて書くので、実行中は出力ファイルが 0 バイトのままで CPU もほぼ使わない。0 バイトと CPU の低さは停止の証拠にならない。

**実例**: worker が回していたレビュアー（`claude -p`）を、1 時間 37 分・出力 0 バイト・CPU 0.1% を根拠に停止と判断し、「入力を分け直す」追い送りを送った。実際はその 2 分後に正常に完了しており、追い送りを取り消す訂正を送る往復が増えた。

## 追い送りは元仕様のどこを上書きするか名指しする

dispatch 後に司令塔が送る追加指示（先回りの裁定・方針変更）は、**元仕様と同じ重みで literal に読まれる**。どの節を上書きするのか・補足なのかを書かないと、worker は元仕様と新しい指示の競合として検出し、止まって聞く。追い送りには「元仕様 §N の〈該当文〉を〈新しい文〉に置き換える」「元仕様 §N はそのままで、これは追加の条件」のどちらかを明記する。短い指示ほど、元仕様のどこに当たるかを書き落としやすい。

**実例**: 司令塔が先回りの裁定として「レビュー記録の節は触らない」と追い送りしたところ、元仕様 §5 の「残った指摘はレビュー記録に追記する」と競合し、worker が ask で止まった。司令塔は、既存記述の書き換えを避ける意図だったと説明し、「既存記述は維持し、末尾に今回分を小見出し付きで追記」と訂正した。**追い送りは元仕様の差分であり、差分は適用先を指して初めて適用できる。**

From elchika-inc/agent-toolkit, MIT.

More from elchika-inc/agent-toolkit