boy-scout-rule

ボーイスカウトのルール

適用する前に

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

原則

触れたファイルはすべて、見つけたときより少しだけ良い状態にしておきます。大幅にではなく、少しだけです。小さな改善を積み重ねることで、時間とともにコードベースがきれいになります。

本番環境で重要な理由

コードベースは一晩で劣化するわけではありません。ハードコードされた値が一つ、名前の変更を見送った箇所が一つ、3年間残り続ける TODO が一つというように、近道を一つ選ぶたびに劣化していきます。ボーイスカウトのルールは、その解決策です。改善を予定されたイベントではなく、日常の習慣にします。

このルールを実践しているチームでは、「クリーンアップスプリント」は必要ありません。通常の機能開発にメンテナンスが継続的に組み込まれているため、コードの健全性が保たれます。

ただし、これは規律があってこそ機能します。改善は小さく、安全で、範囲を限定したものでなければなりません。40個のファイルに手を入れ、2つの機能を壊す「クリーンアップ」は、問題をそのままにしておくよりも悪い結果になります。

ルール

1. 範囲内で、気づいた問題を直します。 バグを修正するためにファイルを開き、誤解を招く変数名に気づいたら、名前を変更します。使われていないインポートがあれば、削除します。いずれも安全でリスクの低い改善です。
2. クリーンアップは別のコミットに分けます。 機能のコミットには機能を、クリーンアップのコミットにはクリーンアップを含めます。混在させるとコードレビューが難しくなり、変更の取り消しも危険になります。
3. 理解していないものをリファクタリングしないでください。 見慣れないファイルを開いて問題に見える箇所があったら、「修正」する前に調べてください。不要なコードに見えるものが、重要なフォールバックである可能性もあります。誤字に見えるものが、意図的な場合もあります。
4. 改善の範囲を限定してください。 ボーイスカウトのルールが意味するのは、分かりにくい名前を直したり、足りない型注釈を追加したりすることです。たまたま通りかかったモジュールを再設計することではありません。
5. 後から分かるように記録を残します。 通りがかりに直すには大きすぎる問題に気づいたら、イシューを作成するか、TODO(ticket-number) を追加して、忘れられないようにします。

「少しだけ良くする」とは

• 変数名を x から user_count に変更する
• 未使用のインポートや不要なコードを削除する
• 足りない型注釈を追加する
• 誤解を招くコメントを修正する（またはコードを言い換えただけのコメントを削除する）
• マジックナンバーを名前付き定数に置き換える
• 必要以上に複雑な条件式を簡素化する
• コンパイラーやリンターの警告を修正する

該当しないこと

• 機能を変えずに、より「良い」スタイルで関数を書き直す
• コードベース全体を新しいパターンに移行する
• 機能を追加したり、動作を変更したりする
• 別のスタイルに合わせてファイルを整形し直す（その場合は自動フォーマッターを使用してください）
• 十分に理解していない見慣れないコードをリファクタリングする

境界

• 規模の上限： クリーンアップが約20行を超えて変更する場合や、複数のモジュールにまたがる場合は、ボーイスカウトの改善とは言えません。専用のチケットとレビューが必要なリファクタリング作業です。
• 「担当外には手を出さない」との兼ね合い： 共有コードベースでは、小さな改善は一般に歓迎されます。モジュールの境界をまたぐ大規模なリファクタリングには、調整が必要です。その違いを理解してください。
• 差分を最小限にすることとの兼ね合い： 意図した変更だけを含むPRを好むチームもあります。その場合は、ボーイスカウトのクリーンアップを別のPRにしてください。

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

• クリーンアップは本当にリスクが低く、明らかに正しいものですか？
• クリーンアップは機能開発とは別のコミットになっていますか？
• クリーンアップの対象は、作成者が現在作業しているコードに限られていますか？
• クリーンアップを元に戻しても、機能はそのまま保たれますか？

関連スキル

• kiss：何が「シンプル」なのかを見極めるためのスキル
• convention-over-configuration：「修正」する前に、プロジェクトの規約を把握するためのスキル
• dry：集約する価値のある重複を見つけるためのスキル