Claude Code を本格運用する

CLAUDE.md 設計の思想

Claude Code を何度か使い始めると、「毎回同じ説明をしている」という感覚が生まれてきます。 それを解決するのが CLAUDE.md です。このChapterでは、なぜ必要なのか・何を書くのか・どう使い分けるかを体系的に学びます。

Claude Code はセッションをまたいで会話を「覚えていません」。ターミナルを閉じてまた開けば、AI は完全な新人として登場します。 あなたのプロジェクトの技術スタックも、セキュリティ上の禁止事項も、あなたのスキルレベルも——全部忘れた状態でスタートします。

CLAUDE.md を置いておくと、Claude Code はセッション開始時に自動的に読み込みます。 その結果、AIは「最初から文脈を知った状態」でスタートできる——これが本格運用の第一歩です。

CLAUDE.md は実は2箇所に置けます。それぞれ役割が違うので、最初から分けて運用すると後で苦労しません。

何でも書けばいいわけではありません。効果が高い要素は次の 3 つです。

以下の 3 つのテンプレートから、あなたの状況に最も近いものを選んでコピーしてください。 CLAUDE.md というファイル名でプロジェクトのルートフォルダに置くだけで有効になります。

# わたしのClaude Code設定

## わたしのこと
- プログラミング初心者です
- 技術用語は最小限で、必要な時だけ使ってください
- 専門用語が出る時は意味も一緒に教えてください
- 日本語でやりとりしてください

## 絶対やらないでほしいこと
- APIキー、パスワード、個人情報をコードに直書きしない
- わたしの確認なしにファイルを削除しない
- わたしの確認なしに `git push` しない
- GitHubリポジトリをpublicにしない（明示指示時のみ可）
- 自前の認証システムは作らない（既存サービスを使う）

## やってほしいこと
- リスクや副作用は先に教えてください
- 「できません」より「できる方法を3つ」考えてください
- エラーは「原因／対策／確認方法」で説明してください
- 不明点は推測せず、わたしに質問してください

## 進め方
- 大きな変更前は必ずプランを共有してください
- 1つずつ確認しながら進めてください
- 完了時は何をやったかを箇条書きで報告してください

# わたしのClaude Code設定（業務利用版）

## ロール
- あなたはわたしの作業パートナーです
- 専門用語は使ってOKですが、初出時は1行注釈をつけてください
- 重要な判断はわたしに確認してください

## セキュリティ（絶対）
- APIキー、パスワード、顧客情報、個人情報をコードに直書きしない
- `.env` 等の機密ファイルはgit管理外（`.gitignore` に必ず登録）
- 自前認証は作らない（Auth0/Clerk/Firebase Auth等の既製品を使う）
- GitHub Publicにする時は事前に必ず確認

## コード品質
- 関数は単一責任。20行超えそうなら分割を提案
- 命名は英語。コメントは日本語OK
- エラーハンドリングを省略しない（try-catch / 戻り値チェック）
- 外部API呼び出しはタイムアウトとリトライ方針を必ず確認

## 進行
- 大きな変更前にプラン共有 → 同意 → 実行 → 報告 の順
- 不明点は推測せず確認
- 完了時は変更ファイル一覧 + 動作確認手順を報告

## 言語
- やりとりは日本語
- コード内コメントは日本語OK

# Claude Code Configuration

## Identity
- You are my engineering collaborator on this codebase.
- Default language: 日本語. Switch to English on request.
- Be concise. Skip preamble.

## Stack & Conventions
- Language: TypeScript / Python / etc. (← プロジェクトに合わせて編集)
- Style: prettier + eslint / black + ruff
- Test: vitest / pytest
- Branch strategy: trunk-based, feature branches off main

## Security (HARD STOPS)
- Never commit secrets (API keys, tokens, credentials, PII).
- Never `git push --force` to main/master.
- Never delete files without explicit confirmation.
- Never disable type checking, lint, or tests to "make it pass".
- Never bypass pre-commit hooks (`--no-verify`).
- No DIY auth; use established providers.

## Workflow
1. Plan first. Share approach before non-trivial changes.
2. One concern per commit. Descriptive messages.
3. Tests with new behavior. Update tests with refactors.
4. After completion: report changed files + verification steps.

## Communication
- Surface risks and edge cases proactively.
- Replace "I can't" with "Here are 3 ways and their tradeoffs".
- Errors → root cause / fix / verification.

セッション管理の技術

「セッション」を意図的に管理できると、AIとの作業効率が劇的に変わります。 思いつきで長時間作業するのではなく、区切り・引き継ぎ・再開を設計する——それがR4レベルの使い方です。

1つのターミナルウィンドウで Claude Code を起動したとき、それが「1セッション」です。 ターミナルを閉じる・exit する・別のウィンドウで新しく起動する——このいずれかでセッションが終わります。

逆に言えば、セッション内では文脈がどんどん積み上がります。 長すぎるセッションは「AIが古い会話に引っ張られて精度が下がる」「処理が重くなる」という問題を引き起こします。 意図的に区切ることが、品質とコストの両方に効きます。

「いつ区切ればいい？」に迷わないよう、4つのサインを覚えておきましょう。

セッションを終える前に「引き継ぎ文書」を作ってもらいましょう。 次のセッション冒頭でこれを貼るだけで、AIは前回の続きから始められます。

ここまでの作業を要約してください。
・何を作ったか
・現在の状態（動く / 動かない）
・次にやること（優先順位つきで）
次のセッションでこの要約を渡すので、引き継ぎ文書として書いてください。

生成された引き継ぎ文書は、ターミナルからコピーしてメモアプリや handover.md などのファイルに保存しておきます。 次のセッションでそのまま貼り付けるだけで、スムーズに再開できます。

長いセッションで文脈が積み上がってきたら、以下のコマンドでコントロールする。

新しいセッションを始めるとき、「昨日の続きです」だけでは AI は何も分かりません。 以下のフォーマットで状況を整理して渡すのが定石です。

[前回の作業] 単語帳メーカーのCSV読み込みを実装した
[現在の状態] index.html がブラウザで動く。スコア機能はまだない
[今日やること] スコア機能を追加したい
[注意事項] デザインはいじらなくてOK。既存のCSSは変えないで

複数プロジェクト管理

副業・個人開発・学習プロジェクトが増えると、「どのプロジェクト用の指示だっけ？」という混乱が生まれます。 プロジェクトごとに CLAUDE.md を持ち、フォルダ構成を整えることで、すっきりと並走できます。

最もシンプルで効果的な構成は「プロジェクトごとにフォルダを分け、各フォルダに CLAUDE.md を置く」です。

~/projects/
  ├── word-app/         ← 単語帳プロジェクト
  │   ├── CLAUDE.md    ← このプロジェクト専用の指示
  │   ├── index.html
  │   └── words.csv
  ├── pomodoro/         ← ポモドーロタイマー
  │   ├── CLAUDE.md    ← 別の指示ファイル
  │   └── pomodoro.html
  └── business/         ← 副業プロジェクト
      ├── CLAUDE.md    ← クライアント情報含む（.gitignore 推奨）
      ├── .gitignore   ← CLAUDE.md を除外する設定を追記
      └── src/

Claude Code はカレントディレクトリ（今いるフォルダ）の CLAUDE.md を自動で読みます。 つまり cd word-app してから起動すれば単語帳の指示が、cd business してから起動すれば副業の指示が自動的に適用されます。

# .gitignore に追記（個人情報が入る場合）
CLAUDE.md

# または特定のパスだけ除外
/CLAUDE.md

• グローバル設定だけで全プロジェクト兼用 「汎用の CLAUDE.md を一個だけ作れば楽」と思いがちですが、プロジェクト固有の技術スタックや禁止事項が適用されず、AI が汎用的な応答をしてしまいます。
  ✓ 解決: プロジェクトフォルダに個別の CLAUDE.md を必ず作る
• CLAUDE.md を Git にコミットして秘密情報が漏れる クライアント名・API キー・社内情報を書いた CLAUDE.md をうっかり git add . で含めてしまうパターン。副業案件で致命的なミスになりえます。
  ✓ 解決: 副業・クライアント案件は必ず .gitignore に CLAUDE.md を追加
• 古い CLAUDE.md をそのまま別プロジェクトに流用 前のプロジェクトの禁止事項や技術スタックが新しいプロジェクトに混入し、AI が「前のプロジェクトのルール」で動いてしまいます。
  ✓ 解決: テンプレートから作り直す習慣をつける

PM責任者設定

Claude Code の標準的な動作は「1つのタスクを逐次実行」です。 PM責任者設定を使うと、AIがタスクを自ら細分化・段階化して進捗を報告するようになります。

これは真のマルチスレッド並列処理ではなく、AIに「PM役割」を演じさせるプロンプトエンジニアリングです。 Claude Code のトークン処理はシングルスレッドですが、PM役割を与えると以下の変化が起きます:

• タスクを細分化して段階的に処理する傾向が強まる
• 「今〇〇を処理中、完了したら報告します」という進捗報告を行うようになる
• 大きなタスクを自分で分割して順番に実行する

次のプロンプトをセッション開始時に貼り付けるだけです。 一度設定すれば、そのセッションが終わるまで有効です。

あなたがPMとして動いてください。
窓口・部下・サブエージェントの採用・役割分担・統括を全てあなたにお任せします。
重い作業は部下に任せて、あなた自身は全体把握と判断に専念してください。
部下に作業させている間も、ユーザーとの会話を止めないようにしてください。
重要なことは忘れずに覚えておいてください。
迷ったら曖昧な状態で動かず確認してください。
この役割は常時有効、セッション終わりまで忘れないでください。

• 📁
  複数ファイルを同時に書き換えるとき
  「コンポーネント全体のプロップ名を変更したい」「全ページのナビゲーションを更新したい」などの横断的変更。PMに「全ファイルを調査してリストを作ってから実行して」と指示すると安全です。
• 🧪
  テスト実行しながら別のコードを書くとき
  「テストを走らせながら、失敗した箇所の修正案を並行して考えてほしい」という使い方。処理待ちゼロで作業が進みます。
• 🔧
  大きなリファクタリング中に進捗を確認したいとき
  「このリファクタリング、どこまで終わった？」「残りどのくらい？」と途中でリアルタイムに確認できます。 全部終わるまで黙って待つ必要がなくなります。

コストと使い方の最適化

「使いすぎ」への不安は多くのユーザーが感じます。 原則を知っておけば、必要以上に怖がらず、かつ無駄なく使えます。

Claude Code の処理コストは、会話の長さ（コンテキストの量）に比例します。 1つのセッションで何時間も作業を続けると、AI が「序盤の会話」を参照するコストが高くなります。

意図的にセッションを区切り、引き継ぎ文書を使って再開する運用は、 品質を保ちながらコストを下げる一石二鳥の方法です。 Chapter 2 のセッション管理テクニックが、コスト最適化にも直結しています。

「苦手」を理解しておくと、AI に任せるべきでない場面を正しく判断できます。 特に「推測が必要な仕様」は、曖昧なまま動かせると後で大きな修正が必要になるので、 迷ったら必ず確認させる習慣が大切です。