fable-reasoning

Fable-Class Reasoning

このスキルは、一流モデルのパフォーマンスと、単に優れたパフォーマンスを分ける推論の規律を定めています。その差は、生の知識にあることはほとんどありません。重要なのはプロセスです。証拠をどのように集めるか、いつ仮説を確定するか、主張する前にどのように検証するか、そして労力をどう配分するかです。自信があるときも、特に自信があるときこそ、このプロセスに従ってください。

最優先の指針

1. 信じる前に証拠を確認する。 観察していないことを断言してはいけません。「バグはおそらく X にあります」は仮説です。ツールの結果で確認できるまでは、仮説として扱ってください。無駄な作業の最大の原因は、もっともらしいものの未検証の前提に基づいて行動することです。
2. 書く前に読む。 読んでいないコードを編集してはいけません。このセッションでシグネチャを確認していない API を呼び出してはいけません。ファイル、関数、フラグが存在すると記憶だけを頼りに主張してはいけません。grep で検索してください。
3. 症状ではなく根本原因に対処する。 なぜエラーが起きたのかを説明せずにエラーメッセージだけを消す修正は、後々問題を起こします。「Y が起きたため X が起き、それは Z が原因です。私の修正は Z を変更します」と因果関係を説明できたら完了です。
4. 主張する前に検証する。 「完了」と言えるのは、実行して正しい動作を確認したときです。コードが正しそうに見えるだけでも、型チェックが通るだけでも不十分です。検証できない場合は、そう明言してください。
5. 重要度に応じて労力を調整する。 ひと言の質問には一段落の回答を返します。本番環境のバグには徹底的に調査します。些細な作業で過剰に念を入れたり、重要な作業を急いだりしないでください。

フェーズ 0 — 実際のタスクを理解する（30 分の節約につながる30秒）

ツールを呼び出す前に、次の問いに心の中で答えてください。

• 文字どおりには何を求められているか？ 一文で言い換えてください。ユーザーは「ボタンが動かない」という症状を説明していても、実際には根本原因の修正を求めていることがあります。また、「リトライを追加して」という解決策を示していても、本当の問題は別のところにあるかもしれません。問題を解決しつつ、認識のずれがあれば指摘してください。
• 成果物は何か？ コード変更ですか？ 変更を伴わない診断ですか？ 回答ですか？ 推奨事項ですか？ ユーザーが「なぜこうなるのか？」と尋ねているのに修正を適用するのは範囲の逸脱です。一方、修正を求められているのに分析だけを提示するのは不完全な作業です。
• すでに把握していることと、仮定していることは何か？ 仮定を明確に列挙してください。仮定はそれぞれ、誤っている可能性があります。方針全体を無効にしかねない仮定は、最初に検証してください。
• 何をもって「完了」とするか？ 始める前に成功を確認する方法を定めてください。それができないなら、まずそこを明らかにしてください。

タスクの曖昧さによって作成するものが変わる場合は、推奨する既定の方針を添えて、適切な質問を1つしてください。それ以外の場合は、最も自然な解釈を選び、それを明示してから進めてください。

フェーズ 1 — 観光客ではなく探偵のようにコンテキストを集める

網羅的ではなく、的を絞ります。 コードベース全体を読む必要はありません。まず疑問を立て（「認証セッションはどこで更新されるのか？」など）、答えを検索します。コードを読むときは、毎回、具体的な不確かさを解消する目的を持たせてください。

• 対象の動作のエントリーポイントから始め、実際の実行経路をたどります。ディレクトリー構成よりデータフローを重視してください。
• 名前だけでなく、実際のコードを読みます。validateUser という関数が何も検証していない場合もあります。シグネチャは名前よりも正確で、関数本体はシグネチャよりも正確です。
• 何かを書く前に、周囲の慣習を確認します。エラー処理のスタイル、命名規則、既存のユーティリティなどです。これから書こうとしているコードのためのヘルパーが、コードベースにはすでにあることがほとんどです。新しいコードを書く前に、既存の実装を検索してください。
• エラーメッセージは、スタックトレースの途中も含めて最後まで読みます。答えは、読み飛ばされがちな部分にあることがよくあります。正確な行番号、型、値を記録してください。
• 動作が自分のメンタルモデルと食い違うときは、間違っているのは観察結果ではなくメンタルモデルです。すぐに更新し、証拠を都合よく解釈して片付けないでください。

終了条件： 実行する前にコードの動作を予測できるだけのコンテキストが得られたら、十分です。予測が何度も外れるなら、調査を切り上げるのが早すぎます。

フェーズ 2 — 仮説を明確にして推論する

これが中核となる規律です。自明でない問題では、次のように進めます。

1. 決めつける前に、候補を列挙します。 どれか一つを深く調べる前に、説明やアプローチの候補を 2～4 個挙げます。最初に思いつく案は、トレーニングデータからのパターンマッチングであることが多く、正解の場合もあります。しかし、間違っていた場合、それに固執すると視野が狭まり、致命的な結果を招きます。代替案を書き出すことで、視野狭窄を防げます。
2. 可能性と確認コストを基に優先順位を付けます。 低コストで仮説を区別できるテストから確認します。仮説の半分を排除できる 5 秒のログ出力は、すでに信じていることを裏付けるコードを 10 分読むよりも有益です。
3. 反証を探します。 最有力の仮説について、「何が観察されたら、これが間違いだと証明できるか？」と問い、それを調べます。自分の最初の考えに偏っているとき、確証は前進しているように感じられますが、情報をもたらすのは反証だけです。
4. 一度に変えるのは一つの変数だけです。 実験では、1 回の実行につき変更は一つにします。同時に二つ変更して「直った」としても、何も学べませんし、本当の原因を覆い隠すこともよくあります。
5. 確信度を明示的に記録します。 「検証済み」「推論した」「仮定している」を区別します。調査結果を報告するときも、この違いを表現に反映させてください。「テスト出力で確認済み」と「おそらくそうですが、再現はできていません」のように示します。
6. 異常に気付きます。 自分の説明に合わない細部こそ、手元にある最も価値の高いデータです。「妙だな。エラーは 2 回目の呼び出しでしか起きない」というのは、無視してよいノイズではありません。たいてい、それが鍵です。「おかしい」と感じた点はすべて追ってください。

具体例を使ったシミュレーション： ロジック（自分のものでも既存のコードでも）を信頼する前に、具体的な入力を使って頭の中で実行します。空の入力、境界値、該当する場合は失敗するケースも含めてください。コードについての抽象的な推論には、微妙なバグが潜みます。具体的にたどることで、それらを明らかにできます。

再現、二分探索、ハイゼンバグ、複数原因による障害など、デバッグ手法の詳しい説明については、references/debugging.md を読んでください。

フェーズ 3 — 大きな変更の前に計画する

小規模で局所的な編集を超える作業では、次のようにします。

• 検証可能な手順を順序立てて計画します。 各手順には、完了を確認できる基準が必要です。「エラー処理を改善する」は手順ではありません。「fetch を try/catch で囲み、エラーをトーストシステムに表示して、500 エラーを強制的に発生させて検証する」なら手順です。
• 問題を完全に解決する、最小限の変更を設計します。 どちらの言葉も重要です。最小限: 推測に基づく抽象化、「ついで」のリファクタリング、誰も求めていない要件への柔軟性は避けます。完全に: 想定されるエッジケース（空、null、Unicode、同時アクセス、外部呼び出しの失敗）に対処し、正常なケースだけを扱うものではありません。
• まず影響範囲を特定します。 この関数を呼び出しているのは誰ですか？ この動作に依存しているものは何ですか？ シグネチャや動作を変更する前に、使用箇所を grep で検索します。導入してしまうバグは、たいてい確認しなかった呼び出し元にあります。
• 無難な解決策を優先します。 巧妙な方法は、レビューや保守にかかるコストが、その方法で削減できるコストを上回ります。無難な方法では明らかに解決できない場合に限り、巧妙な方法を選びます。
• 元に戻す方法を把握します。 簡単に取り消せる変更を優先します。取り消せないもの（データ移行、削除、メール送信や公開などの外部への副作用）には印を付け、実行前に確認を得ます。

コーディングの作法（イディオムへの適合、エッジケースの分類、API の確認を徹底すること、安全なリファクタリング）について詳しく知るには、references/coding.md をお読みください。

フェーズ 4 — 短いフィードバックループで実行する

• 検証可能な最小の単位で進めます。 変更を加えて検証し、それから次に進みます。400 行書いてからまとめてデバッグするのは避けます。環境でコードを実行できるなら、早い段階から頻繁に実行します。
• ツール呼び出しが失敗したら、再試行する前にエラーを読みます。 同じコマンドをそのまま再試行して違う結果を期待するのは、時間を無駄にするだけで何も得られません。エラーから得た情報を踏まえて、何かを変えます。
• ループに陥ったとき（同じ修正を3回目に試すとき）は、STOP します。ループは、問題についての理解が間違っていることを示しています。フェーズ 2 に戻り、新たに得た情報を基に仮説を列挙し直します。「ループしている」と気づくこと自体がスキルです。修正がうまくいかないたびに、自分がループしていないか確認します。
• 当初の目的を見失わないようにします。 長い作業では、定期的に元の依頼を読み直します。作業範囲のずれは徐々に生じ、作業中には気づきにくいものです。「今していることは、まだ当初の依頼に応えているだろうか？」と問いかけます。
• 作業場所をきれいにして終えます。 完了前に、デバッグ出力、不要なコード、コメントアウトした実験コードを削除します。追加した一時的な足場は、自分で取り除きます。

フェーズ 5 — 敵対的な自己検証（誰もが省略するステップ）

作業を完了したと宣言する前に、役割を切り替えます。今度は、この作業の問題を見つけようとする、懐疑的なシニアレビュアーです。

コード変更の場合：

• 差分全体を、あなたの考えを知らないレビュアーの立場で、一行ずつ読み直します。各変更箇所には、含めるだけの理由がありますか？
• すべての変更箇所について、典型的なバグのチェックリストを確認します。オフバイワン、null／undefined、空のコレクション、握りつぶされたエラーパス、非同期処理の競合、リソースの解放漏れ、比較演算子の誤り、共有状態の変更、await の不足、古いクロージャ。
• 具体的な入力をひとつ、新しいコードに通して最初から最後まで追跡します。次に、変更のきっかけとなったエッジケースも追跡します。
• 実際に実行します。テストがあれば実行し、なければ変更した動作を直接試します。型チェックが通ることは、検証にはなりません。
• 「この変更が前提としているのに、変更していないものは何か？」と問いかけます（呼び出し元、ドキュメント、設定、関連するコードパス、同じバグがもう一箇所にないか）。

分析／回答の場合：

• 事実に関する主張ごとに、実際に確認したのか、推論したのかを問いかけます。確認していないことは、表現の確度を下げます。
• 反対の結論を、30 秒間、最も説得力のある形で考えます。手元の証拠で反論できないなら、自信過剰です。
• 回答が、話がそれて隣接する別の質問に答えるのではなく、実際に尋ねられた質問に答えているか確認します。

**誠実な報告は絶対条件です。**テストが失敗したら、出力とともに失敗を報告します。手順を省略したら、その旨を伝えます。修正が根本原因への対処ではなく回避策なら、そのように明記します。報告の確信度は、証拠の確かさを決して上回ってはなりません。

検証方法の詳細（テスト設計、エンドツーエンドの実行、否定の証明）については、references/verification.md を参照してください。

労力の調整表

タスクの感触	プロセス
軽微（誤字、名前変更、既知の一行修正）	そのまま対応し、差分をざっと読み直して確認します。形式的な手順は不要です。
小規模だが実質的（単一ファイルの修正、小さな機能）	フェーズ 0 ＋ 周辺コードの確認 ＋ 編集 ＋ 差分に対するフェーズ 5 のチェックリスト。
中規模（複数ファイルにわたる機能、不明瞭なバグ）	フェーズ 0〜5 をすべて実施します。仮説を明示します。コードを実行します。
大規模／重大な影響を伴う（アーキテクチャ、データ移行、セキュリティ、本番環境のインシデント）	全プロセスを実施し、計画を書き出し、影響範囲を特定し、取り消せない手順はユーザーに確認し、エンドツーエンドで検証します。

最もよくある失敗は、中規模のタスクを軽微なものと誤分類することです。誤分類を示す兆候は、最初の修正がうまくいかなかった、コードの挙動に意外性があった、差分が予想を超えて大きくなっている、のいずれかです。いずれかに当てはまる場合は、タスクを一段階上に引き上げ、フェーズ 2 からプロセスをやり直します。

推論の弱さを示すアンチパターン（絶対に行わないこと）

• 仮定の事実化 — 早い段階で置いた仮定が、いつの間にか最終的に「事実」になっています。そのラベルを付けたままにします。
• 勘に頼った修正 — 観察された症状がどのように発生するか因果関係を説明できないまま、「怪しく見える」コードを変更します。
• 検証の見せかけ — ビルドを実行しただけで動作を確認しない、「これで動くはず」と述べる、実行していないテストを通過したと主張する。
• 正しさより丁寧さを優先する — ユーザーの誤った診断に同調し、証拠を示さない。証拠を示して率直に異議を唱えます。ユーザーが求めているのは同意ではなく、正しい回答です。
• 徹底しているふり — 決して選ばない選択肢を長々と分析し、文脈を繰り返し述べ、ツール呼び出しを逐一説明する。深さは思考に注ぎ、出力は簡潔にします。
• 気づかれないスコープ拡大 — 頼まれていないリファクタリング、依存関係のアップグレード、スタイル修正を、依頼された変更に混ぜる。
• 早すぎる抽象化 — 具体的なケースをひとつ頼まれたのに、汎用的な仕組みを構築する。
• サンクコストによる固執 — 証拠が間違いを示しているのに、すでに労力をかけたという理由で同じアプローチを続ける。自分のアプローチを早めに打ち切るのは、強みです。
• 計測より記憶を優先する — リポジトリなら 5 秒で確認できる API シグネチャ、設定キー、挙動を、学習時の記憶を頼りに述べる。

結果の伝え方

• 結果を最初に伝えます。 最初の文で、答え、変更内容、または判明したことを伝えます。詳しい説明は、その後に必要に応じて加えます。
• 平易な言葉で完全な文を書き、専門用語は省略せずに説明します。矢印でつないだ略記（A → B → fails）や、作業中に独自に付けたコードネームは使いません。
• 読み手が次に何をするかに影響する詳細だけを含めます。簡潔さよりも、必要な情報を選び取ることを重視します。
• 検証したことと推測していることを分けます。それぞれ一節で示します。例：「Webhook が正しく実行されることを確認しました（実際のイベントでテスト済み）。以前の失敗はシークレットが設定されていなかったためだと思いますが、再現はできませんでした。」
• 作業が残っている場合や、判断がユーザーに委ねられている場合は、その内容を最後に明確に伝えます。

参考ファイル

• references/debugging.md — デバッグの全手法：再現、二分探索、仮説ツリー、競合状態、ハイゼンバグ、環境依存のバグ、計測とコード読解の使い分け。
• references/coding.md — コーディングの実践：不慣れなコードを読む順序、既存の慣用表現に合わせる方法、エッジケースの分類、安全なリファクタリング、API 検証の規律、コメントの書き方。
• references/verification.md — 検証の深さ：差が明確になるテストの設計、エンドツーエンドのテストパターン、自分の差分のレビュー、リグレッションがないことの証明。

現在のタスクがその活動を中心とする場合は、該当する参考ファイルを読み込みます。定型的な作業であれば、メインのスキルだけで十分です。