2025年9月17日·1 分
フレームワークの慣習がドキュメントの必要性を減らす方法
フレームワークの慣習により長いドキュメントなしでアプリを理解しやすくなる仕組みを解説します。慣習が何をカバーするか、どこで限界があるか、そして例外だけをどのように文書化するかを学びましょう。
フレームワークの慣習により長いドキュメントなしでアプリを理解しやすくなる仕組みを解説します。慣習が何をカバーするか、どこで限界があるか、そして例外だけをどのように文書化するかを学びましょう。
フレームワークの慣習は、フレームワークが静かに推奨する—あるいは明確に期待する—「物事のデフォルトのやり方」です。チームごとにフォルダレイアウト、命名スキーム、リクエスト/レスポンスのフローをゼロから決める代わりに、フレームワークが共通のパターンを提供します。従えば他の開発者は、長い説明を読まなくてもどこに何があるか、どう振る舞うかを予測できます。
ほとんどのドキュメントはドキュメントを書くのが好きだから書かれているわけではありません。ドキュメントは次のような繰り返し起きる問題を解くために存在します：
慣習は特に最初の二つをよく解決します。どこにXを置くかやYを何と名付けるかがフレームワークで既に決まっていれば、説明する量も議論する量も減ります。
「慣習がドキュメントを置き換える」とは、プロジェクトがドキュメント不要になるという意味ではありません。むしろ基本的なガイダンスの大部分が散文から予測可能な構造へ移る、ということです。コントローラの置き場所を学ぶためにウィキを読む代わりに、フレームワークがコントローラをある場所に置くことを期待しているので（ツールやジェネレータ、例もそれを強化します）推測できます。
結果として明らかなことについてのドキュメントは減り、よりフォーカスすべきはプロジェクト固有のもの：ビジネスルール、変わったアーキテクチャの選択、意図的な例外の文書化です。
この記事は、過剰に広がったドキュメントサイトを維持せずに、より明確なコードベースと迅速なオンボーディングを実現したい開発者、テックリード、プロダクト志向のチーム向けです。
フレームワークの慣習がどのように「暗黙のドキュメント」を生み出すか、慣習が通常どのようなことを標準化するか、どこで慣習が役に立たなくなるか、そして何を明示的に文書化すべきかを学べます—つまりドキュメントを減らしつつも明瞭さを高める方法です。
「Convention over configuration（設定より規約）」とは、フレームワークが合理的な選択を代わりに行ってくれるという考え方です—フレームワークの合意されたルールに従う限り。セットアップ手順を何ページも書いたり読む代わりに、チームは誰もが認識する共有されたデフォルトに頼ります。
例えばすべての人が右側通行で赤信号で止まり標準の標識に従う国で運転することを想像してください。
交差点ごとに詳細なマニュアルを書くこともできます（「赤い八角形を見たら止まる、緑なら行く…」など）が、必要ありません—なぜならその慣習が既に知られ一貫して適用されているからです。
フレームワークの慣習も同じです：それが「ここでのやり方」を予測可能な振る舞いに変えます。
フレームワークにデフォルトがあれば、すべての細かい決定を文書化する必要はありません。フレームワーク（とチーム）は次のようなパターンを前提にできます：
User モデルは users データにマップされる等）その共有基盤により、ドキュメントは「Xを設定する全手順」から「フレームワークのデフォルトに従う、例外があれば注記する」へと縮小します。オンボーディング中の認知負荷も下がります：新しい開発者は他のプロジェクトで見たことに合致しているので、推測が当たりやすくなります。
慣習にもコストはあります。時には特殊なフォルダ構成やカスタム命名、非常に独自のワークフローを諦める必要が出てきます。
しかし利点は一貫性です：議論が減り、驚きが減り、長くいる人だけが覚えている「部族知識」が減ります。チームは説明に費やす時間が減り、構築に集中できるようになります。
慣習がドキュメントを節約するのは、人々がその慣習を既に知っているか、1回学べばどこでも再利用できるときだけです。
だから人気のあるフレームワークは強力です：その慣習は広く教えられ、使われ、数多くのコードベースで繰り返されています。プロジェクトがその共有デフォルトに近ければ近いほど、コードは「デフォルトで」理解しやすくなり、書かれた説明は少なくて済みます。
フレームワークの慣習は共有されたショートカットです。新しいチームメイトが1日目に尋ねる典型的な質問、つまり「これをどこに置く？」と「これに何と名付ける？」に答えを標準化します。その答えが予測可能なら、何ページものドキュメントをいくつかの一貫したデフォルトに置き換えられます。
ほとんどのフレームワークは認識しやすいプロジェクト構造を促します：UIの場所、ルートの場所、データアクセスの場所、テストの場所など。これが重要なのは、「ページをレンダリングする部分」と「データベースと話す部分」がどこにあるかをガイドを読まずに見つけられるからです。
良い慣習は、一般的な作業を筋肉の記憶のように感じさせます：新しい画面を追加するとき、どのフォルダに入れるかは既に分かっています。
命名ルールは「わたしたちのコントローラはXにあってYでワイヤーする必要がある」といった説明の必要性を減らします。名前自体が役割を示唆します。
一般的な例：
多くのウェブフレームワークはファイルとルートを対応させる（またはルートを推測しやすくする）ので、ファイル名からURLを推測できれば各機能ごとに別個のルーティングドキュメントは不要になります。
この慣習は動的ルート、ネストルート、404の扱いにも期待を設定するので、「新しいエンドポイントを追加するにはどうする？」は標準的な答えになります。
慣習はしばしば「データコード」の置き場所を定義します：モデル、リポジトリ、サービス、マイグレーション、スキーマファイルなど。アプリが小さくても、データアクセスの標準の居場所があるとUIコードに対するアドホックなデータベース呼び出しを防げます。
run、test、build、lint、format といった標準コマンドはあいまいさを取り除きます。新しい開発者はウィキを見てどうやってプロジェクトを起動するか調べるべきではありません—npm test（や同等）で始めるのが明白であるべきです。
これら5つの領域が一貫していると、コードベース自体が「ここではどうするか？」という多くの質問に答えるようになります。
「すべてがどう動くか」を説明するウィキは、全体を散文で記述しようとします。最初は役に立っても、フォルダが移動し、名前が変わり、新機能が加わると古くなりがちです。慣習はその考えを反転させます：長い説明を読む代わりに、構造を読むのです。
フレームワーク（とチーム）が物の置き場に合意すると、リポジトリは都市の碁盤目のようにナビゲートしやすくなります。
UIコンポーネントが components/ に、ページレベルのビューが pages/ に、APIハンドラが api/ にあるとわかっていれば「Xはどこ？」と問う必要はほとんどありません。間違っている場合でも検索は限定されます：どこでもではなく、期待される少数の場所のいずれかです。
慣習はファイル名やシンボルに意味を持たせます。新しい人は場所と名前から振る舞いを推測できます：
user.controller というファイルはリクエストロジックを扱うだろうUserService クラスはビジネスルールを持つだろうmigrations/ フォルダは順序付きで一度実行するデータベース変更を含むだろうこの推測は「アーキテクチャを説明して」的な大きな質問を、「このサービスは直接DBを呼んでいいのか？」のような小さく答えやすい質問に分解します。
地図を強化する最速の方法はスキャフォールディングです。スターターテンプレートやジェネレータは新しい機能を「正しい」形でデフォルト作成します—フォルダ、ファイル名、ボイラープレートの配線、そしてしばしばテストまで。
慣習は一貫して適用されるときにのみ助けになります。テンプレートはガードレールです：新しいルートやコンポーネント、モジュールを期待される構造に押し込むので、コードベースは余分なウィキページなしに読みやすさを保てます。
内部のスキャフォールドを維持しているなら、短いオンボーディングページ（例えば /docs/getting-started）からリンクして、フォルダツリーに残りを任せてください。
フレームワークの慣習は静かな組み込み指示のように機能します。「どこに置くか」や「どうワイヤーするか」を説明するページを書く代わりに、フレームワークが既に決めています。
Railsは Convention over Configuration で有名です。単純な例として、OrdersController というコントローラを作ると、Railsは対応するビューフォルダが app/views/orders/ にあると仮定します。
この単一の慣習は次のようなドキュメントの塊を置き換えます：
結果：新人はフォルダパターンに従ってページを追加でき、「このファイルはどこに置く？」と尋ねる必要がなくなります。
Djangoは一貫した「app」構造を推奨します。Djangoアプリを見ると、models.py にデータ形状、views.py にリクエスト処理、templates/ にHTMLがあると期待されます。
プロジェクトの構造を長々と説明する代わりに、Djangoのデフォルトがそれを教えてくれます。ページの見た目を変えたいときは templates/ を見る、データの保存方法を調整したいときは models.py を見る、という具合です。
結果：修正が早く終わり、どのファイルが何を制御するかの探索時間が減ります。
Next.jsはフォルダ構造をルーティングの直接的な反映にすることでドキュメントを減らします。app/about/page.tsx（古いセットアップでは pages/about.tsx）にファイルを作れば、自動的に /about ページができます。
これにより次のようなドキュメントは不要になります：
結果：ディレクトリを眺めるだけでサイトの形が発見でき、オンボーディングが単純になります。
Rails、Django、Next.js は見た目は違いますが、原則は同じです：共有されたデフォルトがプロジェクト構造を説明に変える。みんなが同じ慣習を信頼すれば、コードベース自体が多くの「ここではどうする？」という質問に答えるようになります—追加の文書を維持する必要はほとんどありません。
慣習はうまく働いていると目立ちません。ファイルの場所や名前、リクエストの流れを推測できます。混乱が戻るのはコードベースがその共有デフォルトから逸脱し始めたときです。
早期に現れるパターンは：
UserService、別の部分では UsersManager、また別は user_serviceこれらが自動的に間違いというわけではありませんが、新しいメンバーはフレームワークの「地図」に頼れなくなります。
ほとんどの慣習崩壊は合理的なローカル最適から始まります：「この機能は特別だからここに置こう」「この命名の方が読みやすい」など。しかし例外は伝染します。最初の例外が出ると、次の開発者がそれを前例としてコピーし、その次が少し変えて…というように広がります。
すると慣習はもはや慣習ではなく、長くいる人だけが知る部族知識になります。
慣習がぼやけるとオンボーディングは遅くなります。どこを探せばよいかわからないので日常作業に余計時間がかかり、ミスも増えます（間違ったモジュールを配線する、誤った命名を使う、ロジックを重複させる等）。チームはより多くの同期や長いPR説明、急場しのぎの「クイックドキュメント」で補うことになります。
明確な理由があるときだけカスタマイズし、書き残すこと。
そのメモは軽くて良い：特異な構造の近くに短いコメント、フォルダ内の README.md、あるいは /docs/decisions に簡単なエントリを残すだけで十分です。
フレームワークの慣習とは、フレームワークが黙って推奨する（あるいは明確に期待する）“物事のデフォルトのやり方”です。チームごとにフォルダ構成や命名規則、リクエスト/レスポンスの流れをすべて決める代わりに、フレームワークが共通のパターンを提供します。これに従えば、他の開発者は長い説明を読まなくても、ファイルの場所や挙動を予測できます。
多くのドキュメントは執筆が好きで書かれているわけではありません。ドキュメントは繰り返し起きるいくつかの問題を解決するために存在します：
慣習は特に最初の二つをよく解決します。どこにXを置くかやYに何と名付けるかがフレームワークによって既に決まっていれば、説明する量も議論する量も減ります。
いいえ。慣習に従えば明らかな部分（ファイルの場所やルーティングの配線など）についてのドキュメントは減りますが、プロジェクト固有の事項（ビジネスルール、意図的な逸脱、重要な意思決定）は引き続き文書化する必要があります。要するに「ドキュメントは減るが、価値の高いドキュメントは残る」という考え方です。
慣習は日常よく出る疑問に対する標準を定めます。典型的な例としては：
これらが予測可能なら、リポジトリ自体が自己説明的になります。
コードが既知のパターンに従っているとき、ディレクトリ構造やファイル名が案内標識になります。新人は templates/ にテンプレートがある、migrations/ に順序ありのデータベース変更がある、など期待して探すことで、長いアーキテクチャの説明を読む必要が減ります。
スターターやジェネレータは慣習をデフォルトに落とし込むので、人々は記憶に頼らずに済みます。良いスキャフォールドは：
これにより、慣習がドリフトしてドキュメント負債になるのを防ぎます。
慣習が効いているときは、ファイルの置き場や名前付け、リクエストの流れを推測できます。混乱が戻ってくるのは、コードベースがそれらの共通デフォルトから逸脱し始めたときです。例えば：
UserService と UsersManager と user_service の混在）そうなると新人はどこを探せば良いか予測できなくなり、会話やPR説明、ミーティングが増えます。
逸脱は合理的な局所最適から始まることが多いです：ある機能だけ特別なので別の場所に置く、という判断です。問題は例外が伝染することです。一度例外が通れば次の開発者がそれを前例として真似し、少しずつ変形していきます。結果として複数の“許容される”やり方が生まれ、本来の慣習が機能しなくなります。
カスタマイズは明確な理由があるときだけ行い、その理由を軽く残してください。
短いメモで十分です：
README.md を置く「何が違うのか、なぜ違うのか、次にどうすべきか」を短く書いておくと、混乱を未然に防げます。
慣習が強くても、ドキュメントで残す価値があるものがあります。実用的なものの例：
軽くし、コードレビューで例外が導入されたら対応するノートの追加を必須にすることで鮮度を保ちます。
自動化によって慣習を実行可能にすることで、“覚えておいてください”という文章を減らします。典型的なチェック：
CIやローカルで失敗することで、開発者はルールをすぐに学び、レビューアはスタイルの監視に時間をとられなくなります。