はじめに
Claude Code を使い始めると、つい毎回同じ指示を手打ちしてしまいがちです。
この記事では、筆者の開発環境で実践している CLAUDE.md と PR テンプレートを使ったワークフロー設定を紹介します。指示の手打ちから解放されるための第一歩になれば幸いです。
今回作成するフォルダ構成
この記事では以下の構成を例に説明しますが、ディレクトリ名や配置はチーム・個人の好みに合わせて自由に変えて構いません。CLAUDE.md にパスさえ正しく書いてあれば動作します。
your-project/
├── CLAUDE.md ← Claude への指示ファイル（.claude/CLAUDE.md でも可）
├── .claude/
│ ├── plan/ ← 実装計画（Claude が保存）
│ └── pr/ ← PR 説明（Claude が保存）
└── project/
├── PR_template.md ← PR 説明テンプレート（AI 向け指示つき）
└── migration/ ← DDL ファイル置き場
CLAUDE.md とは
Claude Code が起動時に自動で読み込む設定ファイルです。ここに書いたルールは毎回のチャットに適用されます。
プロジェクトのルートに置くだけで有効になります。.claude/CLAUDE.md に置いても同様に認識されます。
your-project/
├── CLAUDE.md ← ルートに置く場合
└── .claude/
└── CLAUDE.md ← こちらでもOK
読み込みの仕組み
CLAUDE.md は以下の4つのスコープで読み込まれ、すべてが適用されます。より具体的なスコープが優先されます。
- マネージドポリシー — 組織全体に適用される設定（管理者が配置）
-
プロジェクトの CLAUDE.md —
./CLAUDE.mdまたは./.claude/CLAUDE.md -
ユーザーの CLAUDE.md —
~/.claude/CLAUDE.md（個人設定） - サブディレクトリの CLAUDE.md — Claude がそのディレクトリのファイルを読んだときにオンデマンドで読み込む
設計のポイント：シンプルに保つ
CLAUDE.md は長くなるほどコンテキストを消費し、指示への準拠率が下がります。1ファイルあたり200行以内を目安にしましょう。
指示が増えてきた場合は、ディレクトリ階層ごとに CLAUDE.md を分割できます。
your-project/
├── CLAUDE.md ← プロジェクト全体の共通ルール
├── backend/
│ └── CLAUDE.md ← バックエンド固有のルール
└── frontend/
└── CLAUDE.md ← フロントエンド固有のルール
HTMLコメントはトークンを消費しない
CLAUDE.md 内のブロックレベルの HTML コメントは読み込み時に除去されます。メンテナ向けのメモを書いてもトークンを消費しません。
<!-- この行はClaude に渡されないので、人間向けのメモに使える -->
## 禁止事項
- ユーザーの指示なしにコミット・pushしない
完成した CLAUDE.md
- 回答は日本語
- ユーザーの指示なしにコミット・pushしない
- `--no-verify` でフックをスキップしない
## 技術スタック
- Go / Echo / PostgreSQL
- API は REST 準拠
## 作業フロー
1. 計画を `.claude/plan/<機能カテゴリ>/` に保存する
2. 必ずユーザーの承認を得てから実装を開始する
3. テーブルが必要な場合は DDL を `project/migration/` に保存する（既存 DDL を参考に作成）
4. 実装後、PR 説明を `.claude/pr/<機能カテゴリ>/` に保存する（`project/PR_template.md` に従う）
## テスト
- テストはプロジェクトの既存テストに合わせる
- 1 テストで 1 つの事柄のみ検証（複数になる場合はテストを分割）
## ドキュメント
- ドキュメントを修正したら関連ドキュメントも合わせて修正する
各セクションの解説
禁止事項を明示する
「意図しない操作を防ぐ」ために禁止事項は明示が効果的です。特に以下は入れておくべきです。
- コミット・push禁止：勝手に git 操作されると困る場面が多い
-
--no-verify禁止：バリデーションのバイパスを防ぐ
作業フローを番号付きリストにする
番号付きリストにすると、Claude が順序どおりに処理し、各ステップで止まるべきタイミングを認識しやすくなります。これは公式の推奨ではなく運用上の経験則ですが、箇条書きだと順序が曖昧になりステップを飛ばされるケースが減りました。
プロジェクトに応じてステップを追加するのも有効です。たとえば Swagger を使っている場合は、アノテーション記述後にスクリプトを実行するステップを入れると生成ファイルの取りこぼしを防げます。
PR テンプレートを AI 向けに設計する
PR 説明を Claude に書かせる場合、テンプレートに AI への指示を埋め込んでおくと毎回クオリティが安定します。これは CLAUDE.md 固有の機能ではなく、作業フローでテンプレートの参照を指示することで Claude がその構成に従って出力するという、プロンプト設計の応用です。
ポイント：コメントに何を書けばいいか明示する
## 背景
<!--
以下を1〜3文で説明する：
- このPRで何を追加・変更したか
- なぜ必要だったか
例: 「管理画面に認証基盤を追加しました。...」
-->
コメントに例文・記載項目を書いておくと、Claude が他の PR 説明を参照しなくても書けるようになります。
また、既存の PR 説明がいくつかあれば、「これらを参考にテンプレートを作って」と Claude に依頼するのも有効です。実際の書き方のトーン・構成をそのまま反映したテンプレートが作れます。
まとめ
| 設定 | 効果 |
|---|---|
| CLAUDE.md をシンプルに保つ | 指示の重みが均一になる |
| 禁止事項を明示 | 意図しない操作を防ぐ |
| 作業フローを番号付きリスト | 承認タイミングが明確になる |
| PR テンプレートに AI 指示を埋め込む | PR 説明のクオリティが安定する |
CLAUDE.md は一度作れば毎回チャットで指示を繰り返す必要がなくなります。チームで共有して育てていくのがおすすめです。
また、今回は「計画 → 承認 → 実装 → PR説明」というフローを設定しましたが、作業フローの項目は自由に拡張できます。たとえば Issue の作成や要件定義ドキュメントの作成を組み込みたい場合は、同様に作業フローに追記するだけで Claude がそのフローに従って動くようになります。
## 作業フロー
1. 要件定義を `project/requirements/` に保存する
2. Issue を作成する（ユーザーの承認を得てから）
3. 計画を `.claude/plan/<機能カテゴリ>/` に保存する
4. 必ずユーザーの承認を得てから実装を開始する
5. テーブルが必要な場合はDDLを `project/migration/` に保存する
6. 実装後、PR説明を `.claude/pr/<機能カテゴリ>/` に保存する