agentleFS
sasuketoriisasuketorii/rev_harness_public/.agents/skills/delegated-development-discipline/SKILL.md

delegated-development-discipline

Skill0 starsChanged 3 months agoApache-2.0View on GitHub

実装タスクをコーダーサブエージェントに委譲する時、本番/デモ環境の障害(空表示・サイレント失敗等)を調査する時、複数環境(demo/staging/production)にまたがるシステムで修正・機能追加を行う時に使う。オーケストレーター自身が実装・レビューを行わず、敵対的デュアルレビューと環境非依存な修正を徹底し、コーダーの自己申告だけで完了と判断することを防ぐ。委譲プロンプト自体に「推測せず読んで検証してから書け」を明記することで、後工程のレビューで初めて見落としが見つかる構造的コストを事前に減らす。

  • Deletes or force-pushes

The file

Files
SKILL.md

Delegated Development Discipline

オーケストレーター(自分)は実装者でもレビュアーでもない。実装は必ずコーダーサブエージェントに委譲し、独立した2系統のレビューで両方のLGTMが揃うまで完了と認めない。本番/デモ障害調査でも同じ規律(自己申告を信じない・生ログが決定打)を適用する。

絶対ルール

  1. オーケストレーターは自分で実装・レビューをしない。 すべての実装はコーダーサブエージェントに委譲する。
  2. 敵対的デュアルレビューを行い、両方がLGTMを出すまで修正と再レビューを繰り返す。 コーダーの「直しました」という自己申告だけで完了と判断しない。
  3. 本番/デモ障害調査は「データロス確認→ロジック単体検証→実ログ確認」の順序を守る。 UIのスポットチェックだけで「直った」と判断しない(詳細な診断手順はshared-client-wrapper-safetyスキル参照)。
  4. 修正・機能追加は環境非依存(environment-agnostic)に行う。 特定環境だけに効く環境固有パッチではなく、リポジトリ本体のソースコード変更として行い、環境差は環境変数/設定/接続先のみで吸収する。
  5. 複数のサブエージェントが同一の作業ツリー上で並行実行している状況では、破壊的・退避的なgit操作(git stash, git reset --hard, git checkout ., git clean -f, branch -D等)は使わない。 他のエージェントの変更を巻き込むリスクがあるため、サブエージェントにも徹底させる(単独作業時のgit stashのような一時退避は、この前提が成立しない限り対象外)。
  6. デプロイ(コミット/DB書き込み含む)はオーケストレーター自身の責任として、レビューLGTM後に慎重に行う。 コーダーサブエージェントに直接本番/デモDBへの書き込みをさせない。
  7. 委譲プロンプト自体に、毎回「推測で実装せず、既存コードを実際に読んでから検証済みの実装を書け」という指示を明示的に含める。 「動きそうだから」「一般的にはこう書くから」という推測ベースの実装は、後工程の敵対的デュアルレビューで初めて見落としが発覚し、修正・再レビューのサイクルを何周も要する構造的コストを生む。このコストは事後のレビューで検出・是正できるが、事前に防げるならその方が安い。

起動条件

  • 実装タスク(機能追加・バグ修正・リファクタリング)を任された時。
  • 本番/デモ環境で障害(空表示、サイレント失敗、意図しない挙動)が発生し調査を始める時。
  • demo/staging/production等、複数環境にまたがるシステムで修正・機能追加を行う時。
  • サブエージェント(コーダー)からの「修正完了」報告を受け取った時。

適用範囲の限定: 本番/デモに影響しうる実装(機能追加・バグ修正・設定変更・依存関係更新等)には全面適用する。一方、ドキュメントのtypo修正、コメントの追記、コード実行に影響しないファイルの整形など、非常に軽微でリスクのない変更にまでこのプロセス全体を杓子定規に強制する意図ではない。ただし、この例外は「面倒だから省略する」の言い訳に使ってはならない。対象を「本番/デモの挙動・データ・設定に一切影響しないことが明白な変更」に厳密に限定し、少しでも実行時の挙動に影響する可能性がある変更(たとえ1行でも)は全面適用する側に倒す。判断に迷う場合は全面適用する。

なぜ敵対的デュアルレビューが必要か

  • 1人のレビュアーだけでは不十分。 レビュアーが見落とす観点は必ずある。片方が甘くても、独立したもう片方が指摘するという冗長性を確保することで、見落としの確率を構造的に下げる。
  • 「敵対的」とは、相手の主張を無条件に信じず、反証を探す姿勢を指す。 2人のレビュアーが同じ視点・同じプロンプトで動くと、単なる重複チェックになり冗長性が生まれない。視点(例: 正確性重視 vs 保守性/再利用性重視、あるいは異なるモデル)を分けることが重要。
  • コーダーの自己申告(「直しました」「テストが通りました」)は完了の証拠にならない。 単体テストが通ることと、本番相当の非典型的な呼び出しパターンまで含めて安全であることは別問題(shared-client-wrapper-safetyスキル参照)。オーケストレーターは必ず独立したレビューか自身の検証を経てから完了と判断する。
  • 運用手順: (a) コーダーサブエージェントに実装させる → (b) 独立した2つのレビュー(異なるモデル、または異なる観点のレビュアーエージェント)にかける → (c) 両方が指摘した問題を修正し再度両方のレビューにかける → (d) 両方がLGTMを出すまで(b)(c)を繰り返す → (e) オーケストレーターがデプロイする。

なぜ委譲プロンプトへの事前指示が必要か(レビューが後工程で問題を検出する構造的コスト)

敵対的デュアルレビューは見落としを構造的に検出できるが、それは「事後の網」であって「事前の予防」ではない。レビューサイクルを何度も回すこと自体にコストがある(レビュー1回ごとにモデル呼び出し・待ち時間・オーケストレーターの判断コストが発生する)。

観測された実例では、1つの機能実装に対してレビューが3〜7ラウンドかかることがあった。その原因の多くは「コーダーが既存の実装を実際に読まず、推測や一般的なパターンで書いた」ことに起因する見落としだった。委譲プロンプトの時点で「推測せず、既存コードを実際に読んでから検証済みの実装を書け」と明示しておけば、これらのラウンドの一部は最初から避けられた可能性が高い。

具体的にプロンプトへ含めるべき指示の例:

  • 「新しいコンポーネントを配置する前に、それを消費する既存の呼び出し箇所を全てgrepし、実際に渡されている値を確認してから実装せよ」
  • 「このユーティリティ関数の挙動を変更する前に、その関数の全呼び出し箇所を確認し、非典型的な使い方がないか調べよ」
  • 「『一般的にはこうだろう』という推測でコードを書かず、このリポジトリの既存の類似実装を実際に読んでパターンを踏襲せよ」

これは敵対的デュアルレビューの代替ではない。事前指示があってもレビューは必ず実施する。事前指示は「レビューで検出される見落としの母数を減らす」ためのものであり、「レビューを省略してよい」根拠にはならない。

環境非依存な修正の原則と見分け方

  • 原則: バグ修正・機能追加は、リポジトリ本体のソースコードに対する変更として行う。環境ごとの違いは環境変数/設定ファイル/接続先(DB URL、APIキー等)のみで吸収し、コードパス自体はどの環境でも共通にする。
  • 狙い: 「デモでは直ったが本番では直っていない」という事故を構造的に防ぐ。コミットとしてリポジトリ本体に含まれていれば、次にどの環境をこのリポジトリからデプロイしても自動的に修正済みコードが使われる。
  • 具体的な見分け方(修正案をレビューする際に確認する):
    • 修正が特定のホスト名、環境名(if (env === 'demo')等)、ハードコードされた接続先を条件分岐に含んでいないか。
    • 修正がリポジトリ外(デプロイ先サーバー上の設定ファイル、手動パッチ、デプロイスクリプトのみの変更)に閉じていないか。修正はコミットとしてリポジトリに残っているか。
    • 環境ごとに異なる挙動が必要な場合、その差分が環境変数/設定ファイル/フィーチャーフラグとして明示的に分離されているか(コードパスの分岐そのものではなく値の違いになっているか)。
    • 「今この環境で動いた」ことの確認だけで満足せず、「他の環境をこのリポジトリから再デプロイしたら同じ修正が効くか」を自問する。

空表示・サイレント失敗の診断手順(この順序で行う)

「データロス確認→ロジック単体検証→実ログ確認」の3段階を、この順序で必ず行う。詳細な診断手順・コマンド例・ケーススタディはshared-client-wrapper-safetyスキルを参照する(重複記載を避けるためここでは要点のみ)。UIのスポットチェックだけでは原因特定にも修正確認にも至らないことが多く、実ログ確認が最終的な決定打になる。

破壊的git操作の禁止

  • 前提: このルールは「複数のサブエージェントが同一の作業ツリー上で並行実行している」状況を対象とする。この前提が成立しない単独作業(自分1人、または1つのサブエージェントが単独で作業ツリーを占有している状態)でのgit stash等の一時退避は、業界的にも正当なプラクティスであり、本ルールが禁止する対象ではない。
  • 複数のサブエージェントが同一の作業ツリー上で並行実行している状況では、git stash / git stash pop、git reset --hard、git checkout .、git clean -f、branch -D等は、たとえ「一時的に退避するだけのつもり」でも使わない。
  • 理由: 複数のサブエージェントが同時並行で同じ作業ツリーに対して動いている場合、これらの操作は他のエージェントの変更を巻き込んで一時的に危険に晒す(stashの取り違え、pop忘れ、working tree破壊)。実害が出なくても、それはヒヤリハットであり、次は実害が出る前提で運用する。
  • 代替: 並行実行下で変更を退避したい場合は新しいブランチやworktreeを使う、変更を破棄したい場合は対象ファイルを明示してgit restore <file>のように範囲を限定する、等、影響範囲を常に限定する手段を選ぶ。

必須アウトプットのテンプレート

実装担当: <どのコーダーサブエージェントに何を委譲したか>
委譲プロンプトの事前指示: <「推測せず読んで検証してから書け」を含めたか、含めた場合の具体的な文言>
レビュー担当: <独立した2系統のレビュー内容(モデル/視点の違い)>
LGTM状況: <レビューA: LGTM/NG(理由) / レビューB: LGTM/NG(理由)>
修正サイクル: <指摘→修正→再レビューを何周したか>
環境非依存性の確認: <リポジトリ本体への変更かどうか、環境固有分岐がないかの確認結果>
検証方法: <データロス確認/ロジック単体検証/実ログ確認の各結果、UIスポットチェックのみに依存していないことの明記>
破壊的git操作: <使用していないことの確認>
デプロイ判断: <誰が(オーケストレーターが)、いつ、何を根拠にデプロイしたか>

ケーススタディ

  • 本番/デモ空表示障害: postgres.jsクライアントのラッパーが原因で/clients一覧が全ロールで空表示になった事案では、UIスポットチェックだけでは原因を特定できず、実サーバーコンテナの生ログ(docker logs)で構文エラーを発見して初めて根本原因が判明した。修正(ラッパー撤回)はリポジトリ本体のコミットとして行われたため、次にどの環境をこのリポジトリからデプロイしても自動的に修正済みコードが使われる状態になっている。デプロイ判断はオーケストレーターがdual-reviewerのLGTMを得た後に行った。
  • git stashヒヤリハット: 複数のコーダーサブエージェントが同一の作業ツリーで並行実行していた際、あるエージェントが誤ってgit stash/git stash popを使用し、他エージェントの変更を一時的に危険に晒しかけた。実害はなかったが、この経験から破壊的git操作を明示的に禁止する運用に切り替えた。
  • レビュー多ラウンド化の構造的コスト: 別プロジェクトでの実装(scaffold/Alert統一、admin staff画面新規追加、CSPヘッダー追加)で、それぞれレビューが7ラウンド・6ラウンド・3ラウンドかかった事例があった。共通する原因は、コーダー(または実装者自身)が既存コードの実際の呼び出しパターンやコンポーネントのprops override実態を確認せず、代表例やデフォルト値からの推測で実装したことだった(詳細はshared-client-wrapper-safetyのCSPケーススタディ参照)。委譲プロンプトに「推測せず読んで検証してから書け」を毎回明記する運用へ切り替えた根拠となった。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.