モジュール設計

コードをどう分けて、どこに置くかの話です。Claudeは何もお願いしなければ、動くことを優先して一つのファイルへ処理を積み上げていきます。積み上がった構造は今動いていても、機能を継ぎ足したり仕様を変えたりした時に壊れます。分け方と置き方を口に出して指定するだけで、壊れにくさもClaudeの作業の精度も変わります。

ディレクトリ構成

機能の種類による区分（画面、処理、データ）と、意味による区分（予約、会員、支払い）を使い分けて、名前から中身を予測できる構造にします。予測できる構造は人間の可読性のためだけではありません。Claudeは修正のたびに「どこを直すべきか」を探しており、構造が予測可能だとその探索が正確になり、関係ないファイルを触るミスが減ります。

機能ごとにディレクトリを分けて、ファイル名から中身が予測できる構成にして

1ファイル1関数・1クラス

弊社では、1ファイルに1つの関数またはクラスを基本にします。密接に関連する小さな型や定数の同居は許容します。大きなファイルは変更の影響が見えず、修正が関係ない処理を巻き込みます。ファイルが小さければ、変更は1ファイルの差分として見え、壊れた時も原因の範囲が絞れます。

1ファイル1関数を基本に分割して。関連する型は同じファイルに置いていい

分解してテストできる単位に保つ

関数やクラスは、内部の処理が増えるほどテストが難しくなります。入口から出口まで一本につながった長い処理には、途中の一箇所だけを確かめる手段がありません。分解されていれば部品ごとに確かめられます。テストのしやすさが設計の指標になるという話（品質の観点）の、実際の分け方がこれです。

この関数が大きくなってきた。テストできる単位に分解して

肥大化は一度に起きるのではなく、修正の積み重ねで進みます。日常点検や全体の見直し（開発の「部分で進めて、全体で整える」）の際に、大きくなりすぎたファイルがないかも確認してもらいます。