設計判断を記録する

ファイルには現在の状態を書き、採用・変更の経緯と判断理由はコミットに残す。読み手が必要とする情報に合わせて記録先を選ぶ。

記録先と想定読者

記録先	想定読者	記録する内容
ドキュメント	今日参加して作業を始める開発者。その領域を初めて担当する人	現在使う技術、仕様、規約、責務、変更できる範囲、方針、作業手順
コミットメッセージ	変更を評価するレビュアー。後から判断理由を調べる保守担当者	問題、変更内容、判断の根拠、実際に比較した案、採用・不採用の理由、検証の実績
コードコメント	コードを読んで、改善案や別の実装を思いついた人	その別案を採用できない事情・制約と、変更すると起きる問題。Why notを説明する
コード	処理を理解し、修正・拡張・レビューする開発者	現在の処理、状態、業務ルール、責務、依存関係を、命名・型・構造で簡潔に表す
テスト	期待する振る舞いを理解し、変更が契約を守るか確認する人	条件と期待する観測可能な結果、境界条件、必要な副作用、維持する性質

基本的な開発知識はあっても、このリポジトリの前提を知らない人が作業を始められる内容にする。採用した時期、以前の方針、変更の経緯は書かない。配置や文書名はリポジトリに合わせ、特定の docs/ 以下の構成を要求しない。

架空のプロジェクトなら「WebアプリにはフレームワークAを使う。画面は src/pages/ に配置する」と書く。Aを選んだ理由やBとの比較は、選択した変更のコミットに残す。過去の判断が必要になったら、対象ファイルのGit履歴から変更コミットを読む。

PRタイトル・本文を、マージ時のコミット件名・本文としてそのまま使う。レビュアーが変更を判断でき、後から読んだ人が当時の前提と理由を理解できる内容にする。

コミット件名とPRタイトルにはConventional Commitsを強く推奨する。件名で変更の種類を示し、破壊的変更を明示して、Semantic Versioningによるバージョン更新にも使える記録にする。採用したコミット規約に従い、互換性を壊す変更の影響と必要な移行方法を説明する。

問題と実際の変更、変更後の振る舞いを説明する。
判断に使った事実と制約、実際に比較した案、採用・不採用の理由、受け入れた不利な点を必要な範囲で書く。検討していない案や不明な理由を補わない。
リンクを取り除いても判断を理解できる本文にする。Issue、レビュー、外部資料へのリンクだけで理由を残すことを禁止する。リンクは補足に使い、議論の結論と必要な根拠は本文へ取り込む。
検証した範囲と結果、失敗や未確認の範囲を書く。未実施なら Not run と記載する。検証の実行は別途必須とされたものを除いて任意とし、必須CIや合意済みの受入条件は守る。

架空の判断記録なら「サーバー側の描画が必要なためAを採用する。Bでは拡張を独自実装する負担があるため見送った」と、選択を説明するための事実を書く。

読み手が考えそうな別案、実際の制約、その別案で起きる問題を、該当するコードのそばに書く。過去の試行の一覧や、理由のない「変更しないこと」は残さない。確認できない事情は推測で補わない。

受信順に同じレコードを更新するAPIへ二つの変更を送る場合は、次のように制約を書く。

// Do not send these updates in parallel.
// The receiver applies them in arrival order; reversed delivery leaves the older value.

制約が変わったら、実装とともにコメントを更新する。公開APIのdocstringには、利用者が呼び出すために必要な目的、入出力、エラー、契約を書く。

コードの読み手には言語と業務の基本知識を想定し、この実装を知っていることは前提にしない。名前と単純な処理で規則を表し、説明をなくすためだけに難しい型や抽象化を増やさない。

テストは内部の実装を知らなくても期待する振る舞いが読めるようにする。内部メソッドの呼出し順や実装の計算を写して期待値にしない。外部とのやり取り自体が契約の場合は、そのやり取りを検証する。

例えば、コードでは cancelOrder という名前と状態の分岐で注文の取消しを表す。テストでは「発送済みの注文の取消し要求は拒否され、注文の状態は変わらない」という契約を表す。テストの定義と、実行した結果を残すPR・コミットの記録は区別する。

目的と判断理由をまとめて説明できる単位で変更する。
判断した時点で、根拠と比較内容をPR本文やその下書きへ記録する。
議論やレビューで判断が変わったら、最終的な結論と根拠を本文へ反映する。
影響する文書・コード・コメント・テストを同じ変更で揃える。必要な記録先だけを更新し、毎回五つすべての成果物を作ることは求めない。
PRタイトル・本文を最終的な変更内容に合わせ、案内用のHTMLコメントをすべて除去する。タイトルと本文の言語は導入先の規約に従う。
リポジトリのレビュー・必須チェックなどのマージ条件を満たした後、スカッシュマージまたはマージコミットで統合する。リベースマージは禁止する。最終PRタイトル・本文を取得し、翻訳や要約をせずマージ時の件名・本文に指定して、保存されたコミットを確認する。

既存の文書、PRテンプレート、開発者向け指示、CI、マージ設定を確認する。同等の仕組みがある場合は活かし、不足する部分について変更箇所と内容を示す。導入が依頼された範囲で適用し、文書の配置や言語は既存の規約に合わせる。

形式の検査とは別に、本文だけで判断理由が分かるかをレビューする。