agentleFS
sasuketoriisasuketorii/rev_harness_public/.agents/skills/root-cause-first-discipline/SKILL.md

root-cause-first-discipline

Skill0 starsChanged 3 months agoApache-2.0View on GitHub

バグ修正・障害対応・レビュー指摘への対応で使う。修正が次の問題を生む連鎖(対症療法ループ)に入っていないかを検出し、根本原因の特定→根本からの修正→再発防止の記憶、という順序を強制する。あわせてTDDの網羅性を「テストが甘い→デバッグの引き出しが少ない→組んでからエラーばかり」という因果で捉え直し、デバッグ手法とテスト設計そのものを継続的に充実させ、同じ種類の見落としが二度起きないようにする。1つの修正が新しい欠陥を生んだ時点で必ず起動する。

The file

Files
SKILL.md

Root Cause First Discipline

開発の基本ループはこれ以外にない。

根本原因の調査 → 特定 → 根本から修正 → 二度と起きないように記憶する

対症療法は、このループの「特定」を飛ばして「修正」に入ったときに発生する。

対症療法ループの検出(最重要)

次のどれかに当てはまったら、手を止めて根本原因の特定へ戻る。

  1. 直近の修正が、新しい欠陥を生んだ。 1回でも起きたら黄信号、2回連続なら確定
  2. 修正のたびに守りのコード(ガード・分岐・チェック)が増えている
  3. 「Aを直したらBが壊れた、Bを直したらCが壊れた」と説明できてしまう
  4. レビュー指摘を潰すたびに新しい指摘が出る周回が3周を超えた
  5. 修正の説明が「〜の場合に備えて」「〜されないように」ばかりで、 「なぜその状態が存在しうるのか」を答えていない

検出したときにやること

次の1手を実装しない。 代わりに:

  • 連鎖を時系列で並べる。 「何を直したら何が壊れたか」を表にする
  • 連鎖の起点を1つの文で言う。 言えないなら、まだ特定できていない

根本原因の見分け方(行数では測らない)

コード量の増減で根本原因かどうかを判定してはならない。根本原因の修正でも コードは増える——新しい永続化層、新しい状態機械、新しいサブシステムを 足せば当然行数は増える。「削除行数で評価する」という基準は誤りで、 これを機械的に適用すると、正しい根本修正を「対症療法」と誤判定する。

見るべきは量ではなく性質。次の問いに答える。

  • この修正は「なぜその悪い状態が存在しうるか」を潰しているか、 それとも「その悪い状態が起きたときにどう振る舞うか」を足しているだけか。 前者が根本原因の修正、後者は症状対応(足すこと自体は必要な場合もある)
  • この修正の後、同じ原因から生まれる別の症状を予見できるか。 予見できてしまうなら、まだ原因の1つ手前(症状)を直している
  • 既存の守りのコードのうち、この修正によって「もう要らない」と 言えるものが1つでもあるか。 無くてもよい(初出の問題なら守りは そもそも存在しない)。ただし「前回足した守りを、今回また別の守りで 補っている」なら、それは対症療法が続いている確実な兆候
  • 新しく足したコードは、原因そのものを表現しているか、 それとも症状ごとの場合分けを増やしているか。 「状態Xのときは特別扱いする」という分岐が積み重なっているなら対症療法。 「Xという状態自体が起こらない設計にした」なら根本原因の修正

行数はこの判定の結果であって基準ではない。増えても減ってもよい。 問うべきは「同じ原因から生まれる次の症状を、この修正は止めるか」だけ。

状態設計の典型的な根本原因

以下は「守りを増やし続ける」状況の典型で、実際に踏んだもの:

  • 失うと困るものが、失われる場所(メモリ・画面のライフサイクル)に置いてある。 だから「離れさせない」「他の操作を止める」というガードが必要になる。 → 失われない場所(永続化 + バックグラウンド再開)へ移すと、ガードが全部消える。 この修正はコード量としては増える(永続化層・再開ロジックが新設される)が、 「なぜ画面から離れると困るか」という原因そのものを消しているので根本原因の修正
  • 1つの未完了が、無関係な操作まで止めている。 「なぜこれを止める必要があるのか」に答えられないガードは、 設計の欠陥を補っているだけである
  • 安全装置に脱出口が無い。 止めるところまでは正しくても、 止まった利用者が抜け出す道が無ければ、それは袋小路という新しい欠陥である

TDDの規律:デバッグとテストの充実は片方だけでは終わらない

テストの甘さは、そのままデバッグ能力の低さになる。

テストが甘い / 少ない(網羅性がない)
  → デバッグの引き出しが少ない
  → 組んでからエラーばかり出る

エラーが後工程で噴出するのは能力の問題ではなく、テスト設計の網羅性が足りていない結果である。 この節は「デバッグを充実させる」と「二度と同じ見落としが起きないようテストに刻む」の両輪を扱う。片方だけでは再発を止められない。

デバッグの引き出しを増やす(検出フェーズ)

デバッグが弱いのは「経験が足りない」からではなく、手順が言語化されていないからである。

  1. 障害調査は生ログ・実データ優先。 推測より先に実際の出力・実際のデータを見る。 今回の教訓: 「太字化した最後の1行」を停止位置だと誤認した (実際は子プロセスの出力バッファリングで、真の停止位置はもっと先だった)。 ログの欠落・遅延・バッファリングの可能性を常に疑うこと
  2. 仮説は実験で証明してから採用する。 「たぶんこれが原因」で修正しない。 疑わしい機序を再現条件を反転させて確かめる (例: タスクの生成順を意図的に逆にしたら、狙った通り100%再現した)
  3. 複数の独立した調査者に同じ一次資料を渡し、合流させる。 1人の推論には必ず死角がある。異なる系統(モデル・視点)に同じ生データを 読ませ、両者が一致した点は信頼度が高く、食い違った点はそこに答えがある
  4. 自分の直前の説明を鵜呑みにしない。 自分が数分前に立てた仮説であっても、 新しい証拠と矛盾したら即座に取り下げる。「さっき自分がそう言ったから」を 理由に押し通さない

デバッグ手法そのものを記録・蓄積する(引き出しを増やす本体)

個別の障害の記録だけでは引き出しは増えない。 「このやり方で見つかった」 という手法を、障害の中身と切り離して積み上げること。

  • 障害を1件解決するたびに、その障害固有の内容(何が原因だったか) と 転用可能な手法(どうやって見つけたか) を分けて書く
  • 手法の例: 「ログの最後の行を鵜呑みにせず、単独実行で再現率を測ってから 疑う」「時刻・数値のズレが疑わしいときは、健全な過去データと並べて 差分だけを見る」「否定したい仮説は、条件を反転させて実験する」
  • これらの手法が一定数溜まったら、このスキルの本節に昇格させる。 個別障害の記録は各リポジトリの handoff に残し、手法はここに集約する

テストに刻む(再発防止フェーズ)

  1. 期待値を実装の式から導出しない。 expected == implementation(input) は 何も検証していない。仕様はリテラルで書く。実装を変えたら落ちること
  2. 意図的破壊テスト(mutation)を必ず行う。 テストが通ることは、 テストが機能していることを意味しない。わざと壊して落ちるかを確かめる
  3. 落ちない変異があったら、そのテストは無力である。 実装ではなくテストを書き直す
  4. 両方向の変異を当てる。 「機能しなくなる方向」と「行き過ぎる方向」の両方。 片方だけでは、安全側に倒しすぎた退行を検出できない
  5. 実データの形でテストする。 合成した小さな入力だけでは実機の形を再現できない。 実機で起きた欠陥は、その実データをfixture化して固定する
  6. テストが無期限に待つ形にしない。 実時間の予算を主張するテストは負荷で落ちる。 仮想クロックか、待ちが返ってきた事実そのものを証拠にする

見落としが起きたときの手当て(検出とテストを繋ぐ)

同じ種類の見落としが二度起きないよう、デバッグ手法とテスト設計の両方を更新する。

  • 「このテストがあれば検出できた」を特定し、そのテストを追加する
  • さらに「なぜそのテストを書いていなかったか」を言語化する。 多くの場合、テストの入力が実機の形と乖離している
  • 「どうやってこの原因にたどり着いたか」も言語化し、上の「デバッグ手法の蓄積」へ回す。 次に似た症状が出たとき、同じ道のりを毎回ゼロから歩かないため
  • 網羅の軸(役割・状態・エラー種別)を洗い出し、直積で回す。 片方の役割でしか試していない故障注入は、もう片方の欠陥を見逃す

記憶する

同じ問題を二度起こさないための記録を、修正と同時に残す。

  • 何が根本原因だったか(症状ではなく)
  • なぜ検出できなかったか(テストのどの軸が欠けていたか)
  • どうやって見つけたか(デバッグ手法。上の節へ集約)
  • 誤った仮説を立てたならそれも残す。次に同じ推論をしないため
  • 記録先: 該当リポジトリの handoff/ADR、および再発防止が横断的ならこのスキル群

「直した」だけを記録しても再発は防げない。「なぜ気づけなかったか」と 「どうやって見つけたか」が本体である。

実機E2Eで露見する欠陥の5類型(2026-08-17、rev_meet実機E2Eの実例から)

単体・統合テストが全緑でも実機で露見した4バグの根本原因は、いずれも 以下の類型に落ちた。実機E2E前後のチェックリストとして使う。

  1. デプロイ版数ずれ: 実機が向くバックエンドが検証したいHEADと別版 だった(5日前の版に対して「最新のE2E」を繰り返していた)。 → 実機E2Eの開始前に、実機の接続先のデプロイ版数(version ID)と HEADの一致を確認する手順を必ず踏む。 「どの版に対して検証したか」を E2E記録に残す。逆に、新版を初めてデプロイした直後のE2Eは 「今日初めて実機に載った差分」を疑いの先頭に置く — ただしそれは 仮説であって結論ではない(下記5を参照)。
  2. 設計変更の残骸(dead/stale UI): 設計変更コミットが旧設計のUI・ ハンドラ・文言を消し忘れると、「動くけど嘘をつくUI」が残り、 表示条件が偶然(例: UUIDのソート順)に依存して再現性なく露見する。 → 設計変更のコミットは、旧設計のUI・ハンドラ・文言の削除を同一 コミットに含める。 消せない場合は理由をコミットメッセージに書く。 大きな設計変更の後は、旧概念の語彙でgrep棚卸しをする。
  3. catch-all分類が具体的な文言を騙る: エラー分類のdefault armに 特定原因を示唆する文言(例:「共通開始時刻を確定できませんでした」)を 置くと、無関係な失敗が全部その文言を名乗り、利用者と調査者の両方を 誤誘導する。→ catch-allは「原因不明(コード付き)」と正直に言う。 個別原因には個別の分類を足す。アラートには同一内容の再提示抑制を 置く(ただし「内容が異なるアラートへの即差し替え」は壊さない — 抑制と差し替えは別の軸)。
  4. サーバー側恒久ロックとUIアフォーダンスの不整合: サーバーが 構造的に受け付けない操作(例: 校正成功後の再提出が恒久409)の ボタンをUIが出し続け、しかもエラー文言が「操作をやり直せば直る」と 誤誘導する。→ 状態機械に「戻る遷移」が無い操作は、UIから導線を 消すか、遷移を設計する。エラー文言は原因に忠実に。
  5. 収束経路の未配線: 「即時に間に合わない分は後段の収束処理が拾う」 という設計(例: late merge)は、トリガーが実際に配線され、 実経路のテストで固定されて初めて設計である。存在するだけの収束 コードは動かない。収束経路には「発火しなかったら検出できる」計装 (outcome記録)を必ず付ける。

付随する規律: 並列調査で仮説を配るときは、調査員が一次証拠で仮説を 棄却できる形で渡す(仮説を検証対象として明示する)。実例では オーケストレーターの最有力仮説2件が診断ログとコード配線の一次証拠で 棄却され、真因への到達が早まった。計装(診断イベント)の欠落は 調査の確度を「確定」に上げられない直接原因になる — 修正には 再発時の調査を可能にする計装追加を含める。

テストとデバッグの充実(2026-08-19追記、同セッションの実例から)

  1. テストが仕様ではなくバグを固定していないか: 実例では 「120ms押して離し、5秒後に届いたトークンを証拠採用する」テストが 存在し、押している間だけ集めるという契約の違反(タップすり抜け校正)を 回帰テストとして守っていた。テストを書くとき・レビューするときは 「このテストが固定しているのは契約か、それとも現実装の偶然の挙動か」を 問う。実装から逆算して書いたテストはこの罠に落ちやすい。
  2. 計装は調査の速度を桁で変える: 同セッションで計装(イベント種別+ 数値values)を追加した後は、実機の障害がタイムスタンプ付きの時系列 1回の回収で7秒単位まで再構成できた(追加前は再現+ライブconsole捕捉が 必要だった)。障害修正には必ず「次に同種が起きたとき、ログだけで 確定診断できるか」を問う計装を同梱する。
  3. 手作業のデバッグ手順は3回目にはツール化する: 実機からの診断回収→ 要約は毎回同じ手作業(devicectl copy+JSON解析)だった。定型化した 調査手順はrepoのscripts/へ落とし、--self-test付きで保守する。
  4. 決定的な同期点なしの実時間テストは負債: 400msスリープ・実時間観測の テストは負荷で偽陽性/偽陰性を出し、レビューで「受入証拠に数えない」と 判定される。signal-or-waitゲート(continuation handshake)等の決定的 シームを最初から用意する。フレーク発生時は失敗テスト名とログを 必ず保存する(帰属を独立確認できない開示は証拠にならない)。

起動条件

  • バグ修正・障害対応に入るとき
  • レビュー指摘への対応が3周を超えたとき
  • 自分の修正が新しい欠陥を生んだとき(必ず)
  • テストが通っているのに実機で壊れたとき
  • 実機E2Eを計画・実施するとき(上の5類型をチェックリストとして使う)

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.