Claude CodeのCLAUDE.mdに最初に書く項目：ビルド・テスト・禁止事項の雛形
AIを使いこなすClaudeで執筆し、GPTで自動校閲・修正しています。
最初の1枚に入れる項目は、次の5つで足ります。 1. プロジェクトの概要（1〜2行） 2. ビルド・起動・テストなどの実行コマンド 3. 「完了」とみなす条件 4. 触らないもの・やらないこと（禁止事項） 5. コードを読むだけでは分からない決まりごと Claude Codeは、セッションごとに新しいコンテキストで始まり、CLAUDE.mdは各会話の開始時に読み込まれます。ただし、これは強制設定ではなく、モデルへの文脈です。公式ドキュメントは、具体的で簡潔な指示ほど一貫して従われやすいと説明しています（How Claude remembers your project）。やり直しは、リポジトリを読んでも分からない情報が足りないときや、作業を確認する手段がないときに起きやすくなります。最初の1枚は、その不足を埋めるものと考えてください。
小さなWebアプリ向けの雛形
次は説明用の例です。Node.jsとTypeScriptで作った小さなWebアプリを想定しています。コマンド名やパスは架空なので、自分のプロジェクトの実際の値に置き換えてください。この雛形自体を実際のプロジェクトで動かして検証したものではありません。
# プロジェクト概要
社内向けの予約管理Webアプリ。フロントはReact、APIはNode.js（TypeScript）。
# コマンド
- 依存関係のインストール: npm ci
- 開発サーバー: npm run dev（http://localhost:3000）
- 型チェック: npm run typecheck
- テスト（全体）: npm test
- テスト（1ファイル）: npm test -- src/api/booking.test.ts
- ビルド: npm run build
# 完了の条件
- 変更後に typecheck と npm test を実行し、結果を報告する
- 失敗したテストを削除・スキップして通さない
- 新しい関数には、同じ階層に *.test.ts を追加する
# 禁止事項
- .env と .env.* は読まない・編集しない（値が必要なら私に聞く）
- migrations/ 配下の既存ファイルは編集しない（新規追加のみ）
- package.json の依存を、確認なしに追加・更新しない
- git push と本番デプロイはしない
# コードの決まり
- APIハンドラは src/api/handlers/ に置く
- 日付処理は src/lib/date.ts の関数を使い、独自実装しない
- 文言は src/i18n/ja.json に追加し、コンポーネントに直書きしない各項目に書く理由
コマンド：Claudeはpackage.jsonなどから推測できますが、「1ファイルだけテストする方法」や開発サーバーのURLは、人が書いたほうが確実です。毎回探し直す手間とやり直しを減らせます。
完了の条件：公式のベストプラクティスは、確認手段（実行するチェック）を渡すことを重視しています（Best practices for Claude Code）。「テストを実行して結果を報告する」と書いておけば、見た目だけ直った状態で終わりにくくなります。テストを削除して通す、という近道をふさぐ一行も入れておきます。
禁止事項：「やってはいけないこと」は、「代わりにどうするか」まで書きます。「.envを触らない」だけだと、Claudeは必要な値を推測で埋めるかもしれません。「値が必要なら私に聞く」まで書くと、止まったときの動きが決まります。
コードの決まり：既存コードを読めば分かる一般論（「きれいに書く」など）は不要です。書くのは、読んでも気づきにくい独自の置き場所や共通関数だけです。
書く・書かない・hookに回す判断表
- 実行コマンド、完了条件、判断：CLAUDE.mdに書く、理由：毎回必要で、短く書ける
- 独自の置き場所や命名ルール、判断：CLAUDE.mdに書く、理由：コードから推測しにくい
- 「きれいに書く」などの曖昧な指示、判断：書かない、理由：守れたか確認できない
- 長いAPI仕様や設計資料、判断：別ファイルに分ける、理由：毎回読み込む分量が増える
- 例外なく止めたい操作（.envの読み取りなど）、判断：hookや権限設定に回す、理由：CLAUDE.mdは強制ではない
最後の行が重要です。公式ドキュメントによると、Claudeは CLAUDE.md を強制される設定ではなく文脈として扱います。確実にブロックしたい操作には、PreToolUse hookを使うよう案内されています。上の雛形の禁止事項は「お願い」にとどまるので、漏れると困るものは別途hookか権限設定で守ってください。設定方法はhooksのガイドを参照してください。
分量の目安として、最初の1枚は50行前後に収めるのがおすすめです。これは編集上の提案で、公式の行数制限ではありません。長くなったら、別ファイルへの分割を検討します。
雛形を試して育てる
雛形を置いたら、次のような依頼で効果を確かめます。
CLAUDE.mdの内容に従って、src/api/handlers/ に
「予約のキャンセル」APIを追加してください。
作業後は、実行したコマンドと結果を一覧で報告してください。
CLAUDE.mdのどの項目に従ったかも、箇条書きで教えてください。人が確認する点は3つです。
- 報告されたコマンドが、CLAUDE.mdに書いたものと一致しているか
- 禁止事項に触れる変更（依存追加、migrations編集など）が差分に混ざっていないか
- テストが本当に実行されたか（出力を自分でも見る）
意図と違う動きがあれば、その場で口頭で直すだけで終わらせず、原因になった一行をCLAUDE.mdに足すか書き換えます。同じ修正指示を2回したら、書く合図です。逆に、書いても挙動が変わらない行は削ります。
なお、公式ドキュメントでは /init を使ってプロジェクトのCLAUDE.mdを生成する方法も案内されています。生成された内容はそのまま信用せず、上の5項目で過不足を点検してください。
