why

理由

ユーザーが、既存の技術的な形を生み出した歴史的な圧力や選択を理解できるようにします。記録された理由、代替案、トレードオフ、選択を強いた要因を再構成します。現状が存在するというだけで、それを正当化してはいけません。

プロセス

1. 理由の対象を定める。 問題となっている具体的なコード、システムの形、または判断と、対象とする歴史的な時期を特定します。対象が曖昧な場合は、最も有用と思われる解釈を示して調査を進め、ユーザーが方向を修正できるようにします。
2. 現在の状態を起点にする。 説明する形を特定し、歴史的な問いを明確にするのに必要な範囲で、現在のコード、設定、テスト、ドキュメントを調べます。現在の状態から分かるのは何が存在するかであり、なぜそれが選ばれたかではありません。
3. 経緯をたどる。 関連するロジックについて、完全な差分、名称変更、移動、動作を変えたコミット、取り消し、関連するレビューや課題をたどります。最初に確認できる導入、その後の変更、現在の動作につながったバージョンを区別します。最後の blame が起点とは限りません。
4. 証拠の接点を見つける。 まずローカルの経緯を調べ、そのうえで、重要な不確実性を解消できそうな情報源を選んで確認します。たとえば、ADR、RFC、プルリクエスト、チケット、リリースノート、インシデント、チームの議論、デプロイ記録、オブザーバビリティ情報などです。リスクや証拠の状況から必要な場合に限り、検索範囲を広げたり、独立した情報源を並行して調べたりします。情報源にアクセスできない場合や、調べても何も見つからなかった場合は、それによって結論が制限されることを明記します。
5. 判断を再構成する。 当時の圧力や制約、利用可能だった代替案、選ばれた妥協案、その結果としての形、受け入れたコストをつなげます。放棄されたアプローチ、方針の撤回、矛盾、その後の変更も考慮します。選択がなされた理由と、その選択を強いた条件が今も当てはまるかどうかを分けて説明します。
6. 説明する。 最も強く裏付けられた結論を最初に示し、その後、結論を理解するために必要な最小限の因果関係を説明します。主張を裏付ける証拠はその近くに示し、記録された理由、根拠に基づく推論、競合する仮説、未知の点を区別します。複数の変更が回答に大きく影響している場合に限り、短いタイムラインや変更前後の比較を使います。

証拠に関するルール

• 現在のコードと差分から、動作や変遷は確認できます。歴史的な意図を確認できるのは、同時期の情報源にその意図が記録されている場合に限ります。
• 情報源が証明するのは、そこに記録された内容です。個人の動機を完全に、あるいは内面的なものまで証明するわけではありません。
• 作成者、活動状況、同時変更、時系列は手掛かりであり、所有者や因果関係の証明ではありません。
• 矛盾や証拠の欠落をそのまま残します。もっともらしい話を事実として提示するより、結論を出せないと答えることを優先します。
• 選択を導入した理由、それを維持した理由、当初の理由がすでに当てはまらない可能性を示す証拠を区別します。

範囲

• ユーザーから明示的に依頼されない限り、システムを変更したり、リポジトリ内の成果物を作成したりせず、調査と説明にとどめます。
• 歴史的な理由を、診断、再設計、または現在の形を維持・撤去する提案にすり替えないでください。
• 結論を誠実に裏付けるのに必要な最小限の証拠を追います。考え得るすべての情報源を調べる必要はありません。

完了基準

ユーザーが、現在の形を生み出した圧力と代替案、記録された主張と推論による主張の違い、受け入れられたトレードオフ、当初の理由が今も当てはまる可能性、残された未知の点を把握できる状態にします。