はじめに
Claude Code を使っていて「毎回同じことを説明している」と感じたことはありませんか？
「日本語で答えて」「このプロジェクトはPythonです」「UIは英語にしてください」―― チャットのたびに同じ前置きを書いていました。
CLAUDE.md と DOCS フォルダを整備してからは、そういった往復がほぼゼロになりました。
CLAUDE.md とは
Claude Code が起動時に自動で読み込む設定ファイルです。
プロジェクトのルールや制約をあらかじめ書いておくと、毎回の会話でそれが前提として共有されます。
調べてみるとプロジェクトの内容を書いてもいいみたいですが、私は使い回しができるように必ず守って欲しい汎用的な内容にとどめてます。プロジェクト固有の情報は DOCS フォルダの各ファイルに分けています。
実際に書いている内容
プロジェクトルートに1ファイル置くだけです。
コピペしてそのまま使えます。
## 基本方針
- 変更は最小限にとどめ、既存コードのスタイルに合わせる
- 動作確認できないコードは生成しない
- 不明点は実装前に質問する。推測で進めない
- 必ず仕様の最終整合でOKがでてから実装を進める
## コード生成ルール
- 関数には必ず型アノテーションを付ける
- 処理の意図がわかるコメントを適切に入れる
- マジックナンバーは定数化する
- エラーは握りつぶさない。必ずログ出力か例外再送出を行う
- IMPORTANT: `TODO` `FIXME` を残したまま完了報告しない
## 禁止事項
- ハードコードされた認証情報・APIキー（`.env` から読む）
- `print` デバッグの残留（デバッグ後は削除）
- 未使用のインポート・変数の残留
## テスト方針
- 新規関数には単体テストをセットで作成する
- テストは必ず実行してから完了とする
- テストコマンド: `[test command]`
## 作業フロー
1. 変更前に影響範囲を確認する
2. 実装 → テスト → Lint の順で進める
3. コミットメッセージは Conventional Commits 形式（`feat:` `fix:` `docs:` など）
## コスト意識
- 回答は簡潔に
- 必要な場合以外、大きなコードブロックの繰り返し禁止
- 可能な限り実装より説明を優先
## よくやるミス（必ず守ること）
- [例: `os.system()` 不可 → `subprocess.run()` を使う]
- [例: 例外の裸の `except:` 禁止 → 必ず型を指定]
## プロジェクト向け情報
| 機能 | 説明 |
|------|------|
| @DOCS/PROJECT.md|コンセプト,機能仕様|
| @DOCS/SPEC.md|詳細仕様|
| @DOCS/README.md|ユーザーリリース用情報|
| @DOCS/MISTAKE.md|不具合の再発防止情報|
| @DOCS/HISTORY.md|修正履歴の管理|
ポイントは「やってほしいこと」と「やってほしくないこと」を明記することです。
(これとは別に人格付けする手法もあるみたいですが、まだとりいれてません。)
また、テスト方針をいれることでコード生成後に自動でLintを行います。それまではこちらからSYNTAX ERRORの指摘をしていましたが、それが自動で解消されるようになり、余計なストレスがかからなくなりました。
DOCS フォルダと組み合わせる
CLAUDE.md から DOCS フォルダの仕様書を参照させると、さらに効果的です。
$project/
├── CLAUDE.md ← Claude への指示・運用ルール
│ ├── 基本方針・禁止事項
│ ├── コード生成ルール
│ └── DOCS 各ファイルへの参照
│
└── DOCS/
├── PROJECT.md ← コンセプト・機能仕様
│ ├── コンセプト（何を作るか・なぜ作るか）
│ ├── 対象ユーザー
│ └── 設計思想・方針
│
├── SPEC.md ← 詳細仕様（クラス・メソッド・画面構成）
│ ├── ファイル構成と行数目安
│ ├── クラス・メソッド一覧（役割付き）
│ └── バッチコマンド一覧・フローチャート
│
├── README.md ← ユーザー向けリリース説明
│ ├── UI構成・主な機能一覧
│ ├── インストール手順
│ └── 使い方・バッチ実行例
│
├── HISTORY.md ← 変更履歴（日時・内容）
│ └── YYYY/MM/DD；修正内容（1行）の積み上げ
│
└── MISTAKE.md ← 過去の間違いと再発防止策
├── 現象・発生日時・環境
├── 期待結果 vs 実際結果
├── 原因・対策・結果
└── 記入例付きテンプレート
地味に一番便利な HISTORY.md
YYYY/MM/DD；修正内容 の1行を追記するだけです。
Claudeに履歴をつけさせるのはトークンの無駄という意見もあるようですが、私はつけてもらっています。手動でコミットを行っているので、その時に参照しています。(そもそもこの作業もclaudeにやってもらえばいいのかもしれません。)
2026/04/11 ；Push仕様変更:未コミット時はPushブロック
2026/04/10 ；Merge to mainボタン追加
2026/04/03 ；Remove動作を--hardから--softに変更
まとめ
| 書くべき内容 | 効果 |
|---|---|
| 基本方針・禁止事項 | 毎回の前置き不要 |
| よくやるミス | 同じ失敗を繰り返さない |
| DOCS フォルダ参照 | 仕様の確認往復が減る |
| HISTORY.md の積み上げ | 変更の流れを把握してくれる |
設定ゼロでも使えますが、CLAUDE.md を1ファイル作るだけで Claude の振る舞いが大きく変わります。
まずは CLAUDE.md と PROJECT.md から始めてみてください。
たたき台は、各ドキュメントのコンセプトをClaudeに伝えて作ってもらい、手修正するのが早いと思います。