テンプレート — CLAUDE.md例

いつ使うか

ステージ2 — コンテキスト設計でプロジェクトルールファイルの骨格を立てる、または既存ファイルを点検・更新するときに使う。ルールファイルは、エージェントが毎セッション同じ質問(「テストはどう回すのか」「ネーミング規則は何か」)を繰り返さないようにするコンテキスト資産だ。この文書はこのサイトの他のページと違い、道具中立の原則の例外として、Claude Codeが実際に読むファイルであるCLAUDE.mdを基準に具体的な例を提供する。形式は道具ごとに異なるが、盛り込むべき内容の種類はおおむね同じなので、他の道具を使ってもセクション構成はそのまま参考にできる。

使い方

下の例をそのままコピーしない。各セクション上のコメントは「このセクションがなぜ必要か」を説明するものであり、内容をそのまま写せという意味ではない。プロジェクトに該当しないセクションは消し、毎セッション口頭で繰り返し説明していることがあれば、それからセクションとして追加する。ファイルが数千行に膨れると肝心のルールが埋もれるので、詳細ルールはこのファイルに全部書かず、別文書に分離したうえでリンクだけ残す。マルチプロジェクトのワークスペースなら、上位ディレクトリのCLAUDE.mdに組織共通ルールを、下位プロジェクトにプロジェクト別ルールを置き、継承構造で管理する。

Claude Codeを使わないチームは、道具別の対応ファイルに同じ構成を適用すればよい。例えば、多数のエージェント道具が共通で読むAGENTS.mdの慣例があり、Cursorは.cursor/rules、そのほか各道具が独自のルールファイル形式を持つ場合が多い — ファイル名と文法は違っても、「プロジェクトルールをエージェントがセッション開始時に自動で読むようにする」という目的は同じだ。

テンプレート

# CLAUDE.md

<!-- なぜあるか: ファイルの一番上でこの文書の性格を一行で釘付けにし、エージェントが「これは参考文書ではなく守るべきルールだ」とすぐ認識できるようにする。 -->
このファイルは、このリポジトリで作業するAIエージェントが必ず守るべきルールを収める。

## プロジェクト概要

<!-- なぜあるか: コードだけでは分かりにくい「このプロジェクトが何をするのか」を一段落で与え、エージェントが目的に合った判断をできるようにする。 -->
例: このリポジトリは社内の決済承認APIサーバーだ。Node.js + TypeScriptで書かれ、外部PG会社3社と連携する。

## よく使うコマンド

<!-- なぜあるか: ビルド/テスト/リントのコマンドを毎回尋ねたり推測したりしないようにする。誤って推測すると、存在しないコマンドを実行しようとして失敗する。 -->
- テスト: `npm test`
- リント: `npm run lint`
- ローカルサーバー実行: `npm run dev`
- マイグレーション: `npm run db:migrate`

## コーディング規約

<!-- なぜあるか: ネーミング・構造のルールをセッションごとに口頭で繰り返し指示することを防ぐ。規約がないとエージェントごと、セッションごとにスタイルが分かれる。 -->
- ファイル名はkebab-case、コンポーネントはPascalCaseを使う。
- APIレスポンスの型は必ず`types/`の下に明示的に宣言し、`any`を使わない。
- テストファイルは対象ファイルと同じディレクトリに`*.test.ts`として置く。

## 禁止事項

<!-- なぜあるか: 戻しにくい、あるいはリスクの大きい行動を事前に遮断する。リスクマトリクスでHighに分類された領域と噛み合う。 -->
- `main`ブランチに直接コミットしない。常にPRを通す。
- マイグレーションファイルを生成した後、別途承認なしにプロダクションDBへ直接実行しない。
- `.env`、`secrets/`下のファイルの内容をログやコミットに露出しない。

## アーキテクチャメモ

<!-- なぜあるか: 「なぜこう構造化したか」を残し、エージェントが構造を勝手に変えるリファクタリングを提案しないようにする。詳細な根拠はADRに分離し、ここでは要約だけリンクする。 -->
決済承認ロジックはPG会社別のアダプターパターンで分離されている (`src/adapters/`)。PG会社の追加時は新しいアダプターだけ実装すればよく、既存のアダプターは修正しない。背景は`docs/adr/0003-pg-adapter-pattern.md`を参照。

## ドメイン用語集

<!-- なぜあるか: チーム内で意味が分かれる用語を固定し、エージェントと人が同じ意味で対話できるようにする。 -->
- 「承認(approve)」: PG会社から決済成功のレスポンスを受け取った状態。「完了(complete)」と区別 — 完了は精算まで終わった状態を指す。
- 「加盟店(merchant)」: このシステムを使う我々の顧客企業。最終消費者を指す「ユーザー(user)」と混同しない。

## テスト原則

<!-- なぜあるか: レビューチェックリストの「テストの実在性」項目と噛み合う。テストを通すためのテストではなく、実際の検証を強制する。 -->
新しいロジックを追加するときは、正常ケースだけでなく失敗ケース(PG会社のタイムアウト、重複承認リクエスト)を必ずテストに含める。決済関連の変更は[リスクマトリクス](/ja/templates/risk-matrix)基準でHighなので、統合テストなしにマージしない。

## セッション開始時のルール

<!-- なぜあるか: 毎セッションが同じスタート地点から始まるよう、参照すべき文書を明示的に指定する。 -->
作業を始める前に最新の意図文書(`specs/`下の最も新しいファイル)をまず読む。意図文書とずれた指示を受けたら、すぐに実装せず、まずユーザーに確認する。