grounding-before-coding

コーディング前に実態を把握する

必須の事前知識： principal-engineering スキル。

概要

仕様書や修正、最初の一行を書く前に、実際のコードとデータをマッピングします。根拠にする数値ごとに file:line を引用し、その数値の裏付けとなるクエリを実行します。

この規律

1. 名前ではなく実装を読みます。 validate という名前のメソッドが検証しない場合、それを標準的な前提とします。名前から機能を決めつけず、何をするのかを確かめてから利用します。
2. 根拠を引用します。 計画の根幹をなす主張にはすべて、file:line、正確なクエリ結果、またはコマンド出力を添えます。主張の裏付けがない場合は、推測せず、その旨を明確に伝えます。
3. 慣習を推測しません。 このリポジトリでの命名、依存関係の接続、エラー処理、テストの実行方法は、数分で調べられます。
4. 状況報告よりコードを信頼します。 ドキュメントやチケットの自己申告による状態は、実行状態の根拠にはなりません。コードと履歴（git log -S <symbol>、ツリー全体の grep）で判断してから、その上に作業を積み重ねます。
5. 修正前に再現します。 バグの場合は、何かを変更する前に実際に失敗することを確認します。
6. 呼び出し元が合流する箇所で修正します。 バグ報告に記載されているのは、ある経路での一つの症状です。編集する前に、変更対象のコードに至るすべての経路を見つけます。不具合が共有部分にある場合、ガードも共有部分に置きます。差分が小さくなり、チケットに記載されていない関連経路も修正できます。報告された経路だけにパッチを当てても、報告への対処にとどまり、バグ自体は直りません。
7. 変更によって壊してはならない不変条件をマッピングします。 調査結果はマップです。変更箇所、引用した現在の動作、そして不変条件を記録します。以前のバグにちなんだテスト名、説明コメント付きのガード、苦労して見極めたしきい値を表す定数は、過去の問題の痕跡です。

調査の範囲

• すべてを読む必要はありません。変更箇所とその周辺を一段階分、リスクに応じた深さでマッピングします。
• 質問することの代わりにはなりません。コードから意図に関する疑問（このしきい値が 7 なのはなぜか？）に答えられない場合は、履歴や担当者が答えられます。答えの出ない疑問は、黙って前提にせず、明示的な仮定として扱います。
• このセッションですでに確認した内容を、再度調査する必要はありません。一度調査し、その後は根拠を引用します。

よくある間違い

• フレームワークのドキュメントから、プロジェクトのコードの動作を推測すること。プロジェクト側でフォーク、ラップ、または誤用している可能性があります。実際の状況はコードツリーを見れば分かります。
• 正常系だけを調査すること。不変条件はエラー経路やエッジケースのガードにもあります。
• コードそのものより、以前のセッションによるコードの要約を信頼すること。その要約に記載されたファイルを開いてから作業を進めます。
• タスクが以前のものに「似ている」という理由で、調査を省くこと。既知のケースにパターンマッチする兆候でも、原因が異なる場合があります。根拠が今回のケースを裏付けているか確認します。