chimera-reproduce-before-diagnosing
診断とは、自分が動かしていないマシンについての主張です。まず短いコマンド一つで失敗を再現してください——とりわけ、その診断が他人から届いたものである場合には。
カードを読んだレビュアーが与えるものであり、ファイルが自分について主張するものではありません。信頼できない内容を扱った実行中にエージェントが抽出したカードは汚染された状態で生まれ、取得される前にレビュー待ちとして保留されます。
どんなときに思い出すか
- バグ報告が届いた
- 別のエージェントが原因を説明した
- トレースバックがファイルを指している
- 失敗を見ないまま直そうとしている
価値はたいてい「回避」と「確認」にあります。「実施」は誰でも書ける節です。
上のカード本文は翻訳です。CLI が取り込み、エージェントが実行時に読み、下のハッシュが証明するのは英語の原文です。
トリガー
自分では起きるところを見ていない失敗を理由に、コードを変更しようとしている場合に当てはまる。赤い CI ジョブ、issue に貼られたログの抜粋、ユーザーの説明、そして——このカードが本当に対象としているのは——レビュアーやサブエージェント、静的解析ツールから、ファイル名と行番号付きで渡された自信たっぷりの診断だ。
失敗がすでにコマンド1つになっている場合には当てはまらない。ローカルで実行して失敗するテストは、それ自体が再現である。2つ目を作らないこと。また、失敗を含まない作業——新機能、リファクタリング、設計上の問い——にも当てはまらない。そこには再現すべきものがない。
実施
- 単体で実行できる、最短の失敗するものを書く。スクリプト1つ、pytest のノード ID 1つ、CLI 呼び出し1つだ。「スイートを実行して3つ目のエラーを見る」ではだめだ——毎回そのエラーを読み飛ばすことになる。
- それを実行する。実際の出力をメモにコピーする。例外の型、期待値の隣に並べた誤った値、終了コードだ。自分の要約ではなく。
- そこで初めて診断を述べ、そして直ちにそれを潰しにかかる。診断が名指しした関数の先頭に
raise RuntimeError("here")を置き、再現を実行し直す。元の失敗が変わらず現れるなら、その関数は失敗の経路上になく、どれだけよく論じられていようとその診断は誤りである。 - 修正し、同じコマンドを実行し直し、その再現を同じ変更の中にテストとして残す。修正後に削除された再現は、その修正が巻き戻されたときに何も教えてくれない。
回避
トレースバックのうち、見覚えのあるフレームを編集すること。見覚えのあるフレームとは、以前読んだことのあるフレームであって、間違っているフレームではない。そこにもっともらしい編集を加えると、症状はしばしば別の場所へ移動する——そしてそれが進捗のように読めてしまう。
診断を事実として引き継ぐことを避けること。渡された説明はテキストであり、流暢で誤った説明を生む過程は、流暢で正しい説明を生む過程と同じである。したがって流暢さは、どちらを受け取ったのかについて何の情報も持たない。名前の付いた仮説として扱うこと。何から試すかの順序付けには役立つが、証拠としては無価値だ。
# reviewer says the cache key is missing the tenant id
key = f"{tenant.id}:{user.id}"
# yes — first make the failure appear on demand
# repro.py: two tenants, same user id, assert the second read misses
そして断続的な失敗に対して、緑になるまで再実行するという反射も避けること。再実行は競合状態を診断しない、隠すだけだ。そしてそれは、一度は再現できたバグを、誰にも再現できないバグへと変えてしまう。
確認
修正を書く前に、はいかいいえで答えること。この失敗を、今すぐ、コマンド1つでもう一度起こせるか。 いいえなら、それはデバッグではなく、エディタを開いたまま推測しているだけだ。
修正の後: 同じコマンドは今度は通るか、そしてその前に失敗するところを自分の目で見たか。スイートが緑になったことだけで検証された修正が証明するのは、スイートが緑だということだけであり——失敗していたケースがそもそもスイートに入っていなかったのなら、それは誤った理由で緑だったのかもしれない。
リスク
再現が本当に高くつく失敗もある。1日に一度しか現れない競合、本番にしか存在しない状態、長時間ジョブの6時間後のクラッシュなどだ。そこで安価な再現に固執すると、そのバグのコストを上回るものを燃やすことになる。時間を区切り、その時間を使い切ったら、確認済みだと表現するのではなく、その修正は未検証だとはっきり述べること。
より微妙な罠は、切り詰めすぎることだ。削ぎ落としたスクリプトは、元とは別の理由で失敗し始めることがあり、そうなるとおもちゃの方を直すことになる。元の失敗経路にも修正を適用し、そこで元の症状が消えることを確認して備えること——最小化されたケースは原因を見つけるための道具であって、それが原因だったことの証明では決してない。
使い方
カードはデータです。リポジトリをクローンし、パスで取り込んでください。ネットワーク経由で届いたものは汚染扱いとなり、承認されるまで保留されます。それが望ましい挙動であり、ここにワンライナーのインストーラーがない理由です。
git clone https://github.com/brcampidelli/chimera-agent.gitchimera skills-import chimera-agent/skills/chimera-reproduce-before-diagnosing/SKILL.md完全性
公開された状態のファイルの SHA-256。取り込む側は、受け取ったものがこのページに表示されたものと同じか確認できます。
9d70fa5a61992e3b79a2d0ab2afb592c41a7b63274efbdca0afec1724a5b8338