convention-over-configuration

設定より規約

適用する前に

.agents/stack-context.md が存在する場合は、まずそれを読んでください。検出されたスタックに適した慣用的なパターンを使って、この原則を適用してください。フレームワーク固有の詳細については、context7 MCP またはウェブ検索を利用し、推測しないでください。

原則

妥当なデフォルトと一貫したパターンを採用し、決定は一度だけ行って全体に適用します。明示的な設定は、デフォルトと本当に異なる必要がある場合に限ります。

本番環境で重要な理由

設定項目はすべて、誰かが決定し、文書化し、理解し、保守する必要があります。設定ミスは本番環境のインシデントの主な原因です。誤った環境変数、YAML のタイプミス、サービス間の設定の競合などが該当します。

規約に基づくシステムは予測しやすいものです。新しいチームメンバーは、1 つのモジュールを見れば、他のすべてのモジュールがどう動作するか把握できます。「18 か月前に誰かがそう設定したから、このサービスだけ違うやり方をしている」という状況はありません。

設定はデフォルトではなく、例外にすべきです。すべてが設定可能なら、何も標準化されません。

ルール

1. プロジェクトの規約を早期に定め、文書化します。 ファイル構成、命名パターン、エラー処理のスタイル、テストの構成などを一度決めたら、全体で従います。CLAUDE.md や CONTRIBUTING.md のような、継続的に更新するドキュメントに記載してください。
2. フレームワークの規約をそのまま使います。 フレームワークでルートを routes/ に、モデルを models/ に、テストを tests/ に置くなら、それに従ってください。フレームワークの規約が本当に合わない場合を除き、独自の構成を考案しないでください。
3. 予測しやすい名前を付けます。 users テーブルのハンドラーが users.rs なら、テストは users_test.rs に置き、マイグレーションでは users を参照し、API エンドポイントは /users にします。予測しやすい命名は、探す手間を省く規約です。
4. 一般的なケースをデフォルトにします。 設定オプションには、ユースケースの 90% で機能する妥当なデフォルトを設定してください。本当に異なる 10% のケースでのみ、明示的な設定を必須にします。
5. 環境固有の設定を最小限にします。 開発、ステージング、本番環境の差は、可能な限り小さくしてください。環境固有の設定は、「自分の環境では動く」というバグの主な原因です。
6. 設定をコードとして扱います。 設定ファイルはコードと同様に、バージョン管理し、レビューし、テストしてください。設定値の変更で障害が起きる可能性があるなら、コード変更と同じ厳密さで確認する必要があります。

反パターン

• 設定主導のアーキテクチャ： 誰も全容を把握していない YAML ファイル内の何百もの設定項目によって動作が決まるシステム
• 一貫性のないプロジェクト構成： 「開発者がその構成を好んだから」という理由で、モジュールごとに構成が異なること
• 車輪の再発明： 標準的で十分なツールがあるのに、独自のビルドスクリプト、テストランナー、デプロイツールを作ること
• あらゆるものへのフィーチャーフラグ： すでに決定済みのことを「後で変更できるように」と、すべてフィーチャーフラグで囲むこと
• 文書化されていない規約： コードベース内に存在するものの、文書化されていないパターン。新しいチームメンバーが知らずに違反してしまいます

例

-- Over-configured: every handler specifies its own middleware stack
app.route("/users", handler=users, middleware=[auth, logging, rate_limit, cors])
app.route("/orders", handler=orders, middleware=[auth, logging, rate_limit, cors])
app.route("/products", handler=products, middleware=[logging, cors])  # oops, forgot auth

-- Convention: default middleware applied globally, exceptions are explicit
app.use([auth, logging, rate_limit, cors])   # convention: all routes get this
app.route("/users", handler=users)
app.route("/orders", handler=orders)
app.route("/health", handler=health, skip=[auth])  # explicit exception

-- Over-configured: every test specifies database setup
def test_create_user():
    db = connect("postgres://localhost:5432/test")
    db.migrate()
    db.seed("users.sql")
    ...

-- Convention: test framework handles setup, tests just test
def test_create_user(db):   # db fixture provided by convention
    user = create_user(db, name="Alice")
    assert user.name == "Alice"

境界

• 規約は柔軟性がないという意味ではありません。 チームやプロジェクトの成長に応じて、規約も進化させる必要があります。定期的に見直し、更新してください。
• 設定が必要なものもあります。 データベース URL、API キー、段階的なロールアウトのためのフィーチャーフラグ、環境固有の設定などは、実際に設定が必要です。この原則の目的は、不要な設定を最小限にすることであり、設定をすべてなくすことではありません。
• 規約は見つけられるようにする必要があります。 ある開発者の頭の中にしかないものは規約ではなく、落とし穴です。文書に記載してください。
• 柔軟性との兼ね合い： 多様なユースケースを想定したライブラリやフレームワークでは、より多くの設定が適切です。アプリケーションコードでは、設定は少ないほうが望ましいです。

コードレビューのチェックリスト

• この変更は、プロジェクトで確立されたパターンや規約に従っていますか？
• 新しいパターンを導入する場合、そのパターンは文書化され、妥当性が説明されていますか？
• 適切なデフォルト値に置き換えられる設定オプションはありませんか？
• ファイル／モジュールの構成は、プロジェクトの他の部分と一貫していますか？
• 新しいチームメンバーは、プロジェクトの規約に基づいて、このコードの場所や構成を予測できますか？

関連するスキル

• boy-scout-rule：規約を段階的に維持するため
• separation-of-concerns：構造上の規約そのもののため
• kiss：規約ではよりシンプルな選択肢をデフォルトにすべき場合