CLAUDE.mdのベストプラクティス(agentic coding編)
AIと開発してきて、こうすると良さそうだと見えてきたのでまとめる。
Claude Codeでの開発の構成要素
Claude Codeを使った開発は3つの要素で構成されている。
- ワークフロー
- CLAUDE.md
- AIとの会話
CLAUDE.mdの目指す姿
3つの要素で構成されているという前提のもと、CLAUDE.mdで何を担保したいかというと、大枠を作ることを担保したい。
もう少し具体的にいうと、本質的でないやり取りを減らすことを目的とする。本質的でない指摘の例を挙げよう。
- 既存ディレクトリ構成と異なるディレクトリにファイルを作成したことを指摘する。
- キャメルケースとスネークケースの違いを指摘する。
- 利用する予定のないOSSを使わないように指摘する。
こういった指摘は当たり前に担保されるべきものなので、開発のノイズになり、開発生産性が下がってしまう。例のような指摘をなくすことを目的として、CLAUDE.mdを作っていく。
CLAUDE.mdの構成要素
大きく3つの要素でCLAUDE.mdを作っていく。
環境情報
1つ目は環境情報。これは言語や利用ライブラリなどの情報を指す。
# 環境情報
## 利用言語
Java 17
## 利用ライブラリ
Spring Boot 3.3系
ここで注意したいのは、具体的なバージョンまで書いたほうがよいということ。パッチバージョンまで書く必要はないが、「このバージョンではこの機能を使えない」などの判断材料となる情報を記載しておいたほうがいい。
ディレクトリ構成
2つ目はディレクトリ構成。どのパスにどんな用途を持ったファイルを、どんな命名規則で作るのかをまとめたもの。用途の部分は、ある程度具体的に書かないと意図したところにファイルを作ってくれない。
| Path | 用途 | 命名規則 |
|---|---|---|
/src/main |
アプリケーションのソースコード全体を格納するルートディレクトリ | メインディレクトリ名は小文字 |
/src/main/controllers |
HTTPリクエストを処理し、適切なレスポンスを返すコントローラー層 |
Controllerで終わるクラス名、機能名で分類 |
/src/main/models |
アプリケーションのデータ構造やビジネスロジックを表現するモデルクラス |
Modelで終わるクラス名、エンティティごとに整理 |
/src/main/services |
ビジネスロジックを処理するサービス層。コントローラーから呼び出され、データ処理や外部APIとの連携を担う |
Serviceで終わるクラス名、機能ごとに分ける |
/src/main/repositories |
データの永続化層。データベースとのやり取りを担当し、クエリの発行やデータの取得・保存を行う |
Repositoryで終わるクラス名、ドメインごとに分ける |
/src/main/utils |
アプリケーション内で再利用可能なユーティリティ関数や共通処理 |
UtilsやHelperで終わるクラス名/関数名、汎用的な機能をまとめる |
/src/main/config |
アプリケーションの設定ファイルや設定クラス（例えば、データベース接続設定、外部サービスの設定） |
Configで終わるクラス名、設定ごとに分ける |
また、可能であれば縦方向の分割基準（例えば、コントローラーを何を基準に分割するか）も記載すると、より指摘が減る。
コーディングルール
3つ目はコーディングルール。イメージとしては、モデルの性能が足りないときの底上げに使う情報に近い。
# コーディングルール
- anyは使わない
- 例外は握りつぶさない
- スネークケースを利用する
この項目はAIとコーディングしていると、情報を追加したくなる衝動に駆られることが多い。しかし、CLAUDE.mdは毎回必ず読み込まれるという特性を踏まえると、文脈によらない汎用的なベストプラクティスのような情報のみ留めておいたほうがいい。
文脈に依存する細かな指摘は、AIとの会話で担保するのがコスパ的によい。
まとめ
CLAUDE.mdは、
- 環境情報
- ディレクトリ構成
- コーディングルール
の3つをベースに考えると、良い感じになる。
Discussion