READMEの設計判断は、技術名の一覧ではなく、解決したかった問題、比較した案、採用理由、制約、再評価条件を短く残す説明です。 「React、Node.js、PostgreSQLを使用」と書くだけでは、なぜ必要だったか、どこまで理解して選んだかは伝わりません。
なぜ必要か
依存一覧は設定ファイルから分かりますが、当時の制約や採用しなかった案はコードから復元しにくい情報です。判断を残すと、閲覧者は成果物の特徴を理解でき、将来の保守担当は前提が変わった時に再評価できます。ただしREADMEは詳細な設計書ではないため、重要な判断への入口として使います。
判断の価値は「正解を選んだ」と主張することではなく、その条件で何を優先したかを検証可能にすることです。
登場人物と対象
初めて見る利用者、開発参加者、レビュー・採用担当、将来の保守担当が読みます。対象は認証、データ保存、レンダリング、外部サービス、アクセシビリティ、デプロイなど、利用者価値や運用リスクに関わる判断です。
書く流れ
- 読者が理解すべき重要な判断を2〜4件選ぶ。
- 解決したかった問題と制約を書く。
- 現実に検討した選択肢だけを並べる。
- 評価軸と採用理由を書く。
- 残るリスクと再評価条件を書く。
- 詳細なADR、Issue、公式資料へリンクする。
設計判断の型
## 認証方式
### 解決したかったこと
ブラウザから安全にログイン状態を維持する。
### 比較した案
- localStorageにトークンを保存
- HttpOnly Cookieでセッションを管理
### 採用した案
HttpOnly Cookieを採用した。
### 理由
JavaScriptから認証情報を直接読ませず、既存構成にも合うため。
### 残る課題
CSRF対策とセッション失効を確認する必要がある。
全判断を書かない
ポートフォリオの特徴、難しかった境界、利用者価値に関わる2〜4件へ絞ります。
記録場所の比較
| 場所 | 向く内容 | 粒度 |
|---|---|---|
| README | 初見で重要な判断 | 要約 |
| ADR | 選択肢・経緯・帰結 | 詳細 |
| Issue | 未決事項と実装範囲 | 作業単位 |
| コードコメント | 近くに必要な制約理由 | 局所 |
READMEへ長い議論を複製せず、結論と理由を要約して正本へリンクします。技術を変更したら一覧だけでなく、判断説明も更新します。
「高速だから」「安全だから」のような比較条件のない形容詞は避け、どの要件・脅威・運用条件を優先したかを書きます。
後付けで美化しない
当時の制約と迷いも書きます。結果が悪かった場合も、次にどう直すかが学びになります。
たとえば認証方式では、HttpOnly属性だけで安全を断定できません。CookieのSecure、SameSite、CSRF対策、セッション失効など関連条件があります。READMEでは採用理由と残る課題を短く書き、詳細は設計記録と実装へ結びます。
よくある誤解
採用技術すべてに理由を作る必要はありません。既存構成や課題指定で決まったものは、その事実を書きます。比較していない案を後から列挙すると判断の記録ではなく創作になります。「有名だから」も文脈次第では制約ですが、保守性やチーム経験など具体的な意味へ分解します。
注意とベストプラクティス
- 実際に比較・確認した内容だけを書く。
- バージョン依存の説明は対象バージョンを明記する。
- 秘密情報、内部URL、個人情報を載せない。
- 採用案の欠点と残課題も書く。
- 前提が変わる条件を示し、永続的な正解として断定しない。
デバッグ・確認方法
READMEの記述を依存設定、コード、Issue、テストと照合します。リンク切れ、古い技術名、既に解消済みの課題を確認します。第三者に「何を解決し、何と比較し、なぜ選んだか」を説明してもらい、本文から読み取れるか試します。
実践演習：技術一覧を判断へ変える
READMEの使用技術から一つ選び、「何を解決したかったか」「既存構成を使う案を含め何を比較したか」「どの制約を優先したか」を書きます。調査していない選択肢は加えず、課題指定で決まっていたならその事実を記します。
次に、採用案が不適切になる条件を一つ考えます。利用者数、更新頻度、チーム経験、対応ブラウザなど前提が変わった時、どの証拠を見て再評価するかを示します。READMEでは数段落に要約し、詳細な比較表や検証ログはADRやIssueへリンクします。
最後に依存設定とコードを照合し、既に使っていない技術、古い方式、解消済みの残課題が書かれていないか確認します。判断記録もコードと同様に保守対象です。
ケーススタディ：投稿画像の保存方式
学習記録アプリへ投稿画像を追加する場面を考えます。候補は、画像本体をデータベースへ保存する方法と、オブジェクトストレージへ保存してデータベースには参照先だけを持つ方法です。「クラウドストレージを採用。拡張しやすいから」だけでは、何を測り、どの制約を優先したのか分かりません。
判断の前提は、個人開発で運用人数は一人、投稿は一日数十件を想定し、一画像の上限は五メガバイト、既に利用中のホスティングから同じ事業者のストレージを使える、という条件です。画像表示の失敗が本文投稿まで失わせないこと、バックアップ時に巨大なデータベースを扱わないこと、公開範囲を投稿の権限と一致させることを評価軸にします。無料枠だけを理由にすると料金改定で判断が崩れるため、上限超過時の費用と移行可能性も残します。
判断手順では、まず画像なしの投稿、上限付近の画像、不正な形式、保存途中の通信切断を試します。次に、二案でバックアップ対象、権限設定、削除時の整合性、開発の複雑さを比較します。オブジェクトストレージ案では、画像保存に成功して投稿保存に失敗すると孤立ファイルが残ります。この失敗条件を隠さず、定期削除処理をまだ実装していないなら残課題へ書きます。非公開画像のURLを知るだけで閲覧できる、削除済み投稿の画像が残り続ける、上限超過時に利用者へ理由を示せない状態も採用案の失敗です。
観測結果を根拠にする
READMEへすべての測定ログを貼る必要はありませんが、判断に使った観測は要約できます。たとえば「五メガバイトの画像を十件登録した試験で、データベースのバックアップ容量へ画像本体を含めない構成を優先した」「未認証状態と別利用者で非公開画像を取得できないことを結合テストで確認した」と書けば、拡張性や安全性という形容詞を検証可能な事実へ変えられます。
観測方法は再評価条件と対にします。保存失敗率、月間転送量、孤立ファイル数、画像取得の応答時間、ストレージ費用を月次で確認し、失敗率が基準を超える、費用が予算を超える、別地域配信が必要になる、といった時点で構成を見直します。まだ運用していない段階なら実測値を装わず、「リリース後にこの指標を取得する」と書きます。
良い例と悪い例
悪い例は「画像保存には最新で高速なサービスを採用した。データベース保存より安全で、将来も問題ない」です。比較条件がなく、安全性を何で確かめたかも、どんな時に再検討するかも示していません。「最新」という表現はすぐ古くなり、永続的な正解という誤解も生みます。
良い例は「投稿本文のバックアップ容量と画像配信を分離するため、画像本体はオブジェクトストレージ、投稿にはオブジェクト識別子を保存する。データベースへ本体を保存する案は実装が単純だが、一画像五メガバイトの上限ではバックアップ肥大化の影響が大きいと判断した。非公開画像は認可後に期限付き参照を発行する。投稿保存失敗時の孤立ファイル削除は未実装で、定期処理を追加するIssueへ記録した。月間費用が予算を超える場合は保存上限と事業者を再評価する」です。問題、比較、採用理由、欠点、再評価が一続きになっています。
READMEへ載せる判断の選別手順
候補を見つけたら、利用者の体験、データの寿命、セキュリティ、運用費、将来の変更範囲のいずれかへ影響するかを確認します。影響がなく、設定ファイルを見れば明らかな選択は技術一覧だけで十分です。影響があり、初見の参加者が前提を知らずに変更すると事故につながるものはREADMEの要約候補です。
次に、問題、制約、実際に比較した案、評価軸、採用案、欠点を順に書きます。一つでも事実を確認できない項目があれば、後からもっともらしい理由を作らず、課題指定や既存構成による選択だったと明記します。詳細が長くなったらADRへ移し、READMEには現在の結論とリンクだけを残します。実装変更時には依存名だけでなく、この結論と残課題が現在も正しいかを確認します。
設計判断のレビュー観点
説明を読んだ人が、採用案の名称だけでなく、優先した評価軸を答えられるか確認します。「学習のため」は正当な制約になり得ますが、本番利用の要件を満たす根拠とは分けます。ポートフォリオでは、学習目的と利用者向け設計を混同しないようにします。
セキュリティ判断は、単一機能を採用しただけで安全と断定しません。守る対象、想定する脅威、残るリスク、運用上の対策を必要な範囲で示し、OWASPや利用製品の公式資料へリンクします。詳細を公開すると悪用につながる未修正脆弱性はREADMEへ書かず、非公開の報告手順を使います。
設計判断を削除する時も、単に古い文章を消すのではなく、現在の判断へ置き換えるか、詳細な履歴へ誘導します。READMEは現在の入口、履歴はADRやPRという役割を保ちます。
まとめ
READMEの設計判断は、問題、実在した選択肢、評価軸、採用理由、残課題を短く結び、詳細資料への入口にします。 技術を立派に見せる文章ではなく、当時の制約と再評価条件を正直に残す文章です。
