Claude Codeを使い始めたものの、思った通りに動いてくれない。
そんな経験はありませんか？
実はその原因、CLAUDE.mdの書き方にあることが多いんです。
設定ファイル一つで、Claudeの理解度は驚くほど変わります。
この記事では、CLAUDE.mdを「ただの設定ファイル」から「相棒レベル」に育てる書き方を解説します。
今日から実践できる具体例も交えてお伝えします。
この記事でわかること
- CLAUDE.mdの基本構成がわかる
- 実践的な書き方のコツがわかる
- ありがちな失敗パターンを避けられる
相棒みたいなclaudeの具体例
窓口エージェントを1人だけ立てる
最近よく聞くのが、秘書のようなキャラクターや関西弁のキャラクターにカスタムして、そのエージェントだけに話しかけるスタイルです。
ユーザーは窓口役に話すだけで、裏側でサブエージェントたちが調整して、最終的な回答だけが返ってくる仕組みですね。
「結局何を聞けばいいかわからない」という悩みが、これで解消されます。
これは技術的には「オーケストレーター型」の設計です。
CLAUDE.mdに窓口エージェントの人格と、裏側の指示系統を書いておくことで実現できます。
# あなたの役割
あなたはこのプロジェクトの秘書です。
ユーザーからの依頼を受け取ったら、内容を整理し
適切なサブエージェントに振り分けてください。
ユーザーには専門用語を使わず、わかりやすく報告してください。
窓口エージェントには「人格」と「調整役」の2つの仕事を持たせるのがポイントです。
キャラクター設定は口調だけでなく判断軸も書く
関西弁や敬語といった口調の指定だけでは、実はあまり効果がありません。
ぶっちゃけ、口調はおまけです。
本当に効くのは、「どう考えて、どう振る舞うか」という判断軸まで書き込むことです。
# キャラクター設定
- 口調：関西弁で親しみやすく話す
- スタンス：まず結論から話し、詳細は聞かれたら答える
- 判断軸：ユーザーの手間を最小化することを最優先する
- サブエージェントへの依頼は、専門用語を噛み砕いてから振る
調整役としての振る舞いを具体的に書く
窓口エージェントがサブエージェントとどうやり取りするか、流れも書いておくと安定します。
なんとなく任せるのではなく、手順として明記するのがコツです。
| ステップ | 窓口エージェントの役割 |
|---|---|
| 1 | ユーザーの依頼を要約し、意図を確認する |
| 2 | 必要なサブエージェントを判断し、依頼を振る |
| 3 | 返ってきた結果をユーザー向けにまとめ直す |
窓口エージェントに全部の作業をやらせようとすると、コンテキストが肥大化して精度が落ちます。
実際の作業はサブエージェントに任せ、窓口は「翻訳」と「調整」に徹するのがおすすめです。
こうして設計すると、ユーザーは複雑な指示体系を意識せずに済みます。
まるで有能な秘書に丸投げしているような感覚で、Claude Codeを使えるようになるはずです。
具体例：秘書系オーケストレーターの実装例
言葉だけだとイメージしづらいと思うので、実際のファイル構成で見てみましょう。
ここでは「エンジニア秘書」という設定で例を出します。
まずCLAUDE.mdには、窓口役の人格と大まかな振り分けルールだけを書きます。
# あなたの役割
あなたは「山田」という名前のエンジニア秘書です。
一人称は「わたし」、敬語ベースだが堅すぎない口調で話してください。
## 振り分けルール
- コード実装の依頼 → subagent「builder」に振る
- 調査・リサーチの依頼 → subagent「researcher」に振る
- レビュー依頼 → subagent「reviewer」に振る
- 上記に当てはまらない雑談や相談 → あなた自身が直接答える
## 報告のルール
サブエージェントからの結果は、専門用語を噛み砕いて
3行以内で要約してからユーザーに伝えてください。
そして .claude/agents/ 配下に、それぞれのサブエージェントを定義します。
---
name: builder
description: コード実装を担当するエージェント
tools: Read, Edit, Write, Bash
model: sonnet
---
あなたは実装担当のエンジニアです。
指示された機能を実装し、テストまで実行してください。
UIやドキュメントの変更は行わず、実装のみに集中してください。
---
name: researcher
description: 技術調査・比較検討を担当するエージェント
tools: WebSearch, WebFetch, Read
model: sonnet
---
あなたは技術調査担当です。
複数の情報源を比較し、結論と根拠をセットで報告してください。
断定できない場合は「要検証」と明記してください。
この状態でユーザーがすることは、山田に話しかけるだけです。
「ログイン機能を実装して、ついでに他社の実装例も調べておいて」と伝えるだけで、裏側で builder と researcher が動き、山田がまとめて報告してくれます。
まるで本当に山田秘書に頼んでいるような感覚になりますよね。
ポイントは、CLAUDE.mdに「振り分けルール」までセットで書くことです。人格設定だけでは、調整役としては機能しません。
複数の作業を同時に依頼したいときはworktreeを使う
「バグ修正と新機能開発を同時に進めたい」
そんなときに便利なのが、git worktreeを使った並列セッションです。
Claude Codeには--worktreeというオプションがあり、これを使うと1つのリポジトリから複数の独立した作業ディレクトリを作れます。
それぞれのセッションが別々のブランチ・別々のファイルで動くため、編集内容が衝突しません。
# バグ修正用のセッションを新しいworktreeで起動
claude --worktree bugfix-123
# 別のターミナルで、新機能開発用のセッションを起動
claude --worktree feature-login
こうすると、片方のセッションでファイルを編集していても、もう片方のセッションには一切影響しません。
セッションごとにCLAUDE.mdの解釈も独立しているので、それぞれの作業に集中できます。
サブエージェントにも同じ仕組みが使えます。
.claude/agents/のfrontmatterにisolation: worktreeを指定すると、そのサブエージェントは自分専用のworktreeでコードを編集するようになります。
---
name: backend-builder
description: バックエンド実装を専用worktreeで行うエージェント
tools: Read, Edit, Write, Bash
isolation: worktree
model: sonnet
---
あなたはバックエンド実装担当です。
自分に割り当てられたディレクトリ以外は編集しないでください。
worktreeは新規チェックアウトなので、.envなどgitignore対象のファイルは自動では引き継がれません。
プロジェクト直下に.worktreeincludeを置いておくと、必要なファイルを自動でコピーしてくれるので設定しておきましょう。
複数のサブエージェントが同じファイルを触ろうとして、静かに上書きし合う。
これはサブエージェント運用でかなりよくある失敗です。
worktreeで隔離しておけば、この手のトラブルはほぼ防げます。
作業内容ごとにセッションを分けるか、サブエージェントごとに隔離するか。
状況に応じて使い分けるのがおすすめです。最後におすすめの人格を好みで設定しておきましょう。
おすすめの人格設定パターン集
とはいえ、ゼロから人格を考えるのは大変ですよね。
ここでは実際に人気のある人格パターンを、判断軸つきで紹介します。
そのままコピーして、CLAUDE.mdに貼り付けてもらって大丈夫です。
関西弁の突っ込み役
# キャラクター設定
- 口調：関西弁。堅苦しくならず、テンポよく話す
- スタンス：無駄な処理や非効率なコードを見つけたら遠慮なく突っ込む
- 判断軸：シンプルさを最優先し、複雑な実装には代替案を提示する
- 一言目：「ほな、まず確認させてな」から入る
エラーメッセージを読むのが苦手な人にとって、テンポよく突っ込んでくれるキャラは相性がいいはずです。
「これアカンやつやん」と言われると、なぜか素直に直したくなるから不思議です。
原始人（コーチ役）
# キャラクター設定
- 口調：単語を区切って話す。「コード、汚い。直す、必要」のような話し方
- スタンス：本質だけを短く伝える。前置きや言い訳は一切しない
- 判断軸：とにかく動くこと、シンプルであることを最優先する
- 装飾的な説明を避け、結論から話す
長々とした説明が苦手な人には、これがかなり刺さるでしょう。
情報量を絞って伝えてくれるので、忙しいときの相棒として重宝します。
英国紳士風の皮肉屋
# キャラクター設定
- 口調：丁寧語だが、時折皮肉を交える。「なるほど、実に興味深い書き方ですね」など
- スタンス：問題点を直接的に叱らず、遠回しに気づかせる
- 判断軸：コードの保守性と一貫性を重視する。場当たり的な修正には賛同しない
- 皮肉は攻撃的にならない範囲に留め、最後は必ず改善案を添える
私も最初はこの手のキャラは冗談半分で試したのですが、指摘の的確さに驚きました。
遠回しな言い方でも、逆に印象に残りやすいのかもしれません。
体育会系の後輩
# キャラクター設定
- 口調：元気で前向き。「了解っす！」「やってみます！」を多用する
- スタンス：まず手を動かしてから相談する。完璧主義より前進を優先する
- 判断軸：スピード重視。ただし致命的なリスクがある場合は必ず先に確認する
- 失敗を恐れず提案し、うまくいかなければすぐ別案を出す
プロトタイピングやアイデア出しの段階では、このくらい勢いのあるキャラの方が進みやすいでしょう。
慎重すぎるキャラだと、逆にスピード感を削いでしまうこともあります。
どの人格を選ぶにしても、「判断軸」だけは抜かないようにしてください。口調だけのキャラは、3往復もすれば飽きてしまいます。
作業内容によって人格を使い分けるのも、実はおすすめです。
レビュー用には英国紳士風、実装のスピード重視には体育会系、といった具合に、CLAUDE.mdを複数用意して切り替えるという運用もあります。
CLAUDE.mdは「役割」と「制約」を明記する
CLAUDE.mdを効果的にするコツは、シンプルです。
Claudeに「何者であってほしいか」と「何をしてはいけないか」を、はっきり書くこと。
これだけで動きが大きく変わります。
多くの人がCLAUDE.mdを、単なるコマンド一覧として書いてしまいます。
でもそれでは、Claudeはただの実行係になってしまうんです。
私も最初はそうでした。
コマンドだけ並べて、なぜか意図が伝わらないと悩んでいました。
そこで役割定義と制約条件を追加したところ、提案の質がガラッと変わったんです。
エンジニアなら読むべき本を30冊以上紹介しています。
正直、私の仕事のやり方をガラッと変えた神本やSQLのチューニングに悩んだ時にめちゃくちゃ役に立ったもあります👇
→記事を読む
CLAUDE.mdの基本構成
CLAUDE.mdに何を書けばいいのか、迷う方も多いはずです。
まずは基本の型を押さえておきましょう。
1. プロジェクト概要
どんなプロダクトで、何を目的にしているのか。
ここが曖昧だと、Claudeは的外れな提案をしがちです。
# プロジェクト概要
これはQiita記事管理用のダッシュボードです。
Python/FastAPI/Jinja2で構築しています。
目的は記事の分析と効率的な管理です。
2. 技術スタックとディレクトリ構成
使用している言語やフレームワーク、主要なディレクトリの役割を書きます。
これがあるだけで、無駄なファイル探索が減るでしょう。
ディレクトリ構成は「意味」も添えて書くのがポイントです。
単に src/ tests/ と書くだけでなく、「テストはpytestで実行」のように運用ルールまで書くと精度が上がります。
3. コーディング規約
命名規則やコメントの書き方、禁止事項などを明記します。
ここを丁寧に書くほど、レビューの手間が減っていくはずです。
# コーディング規約
- 変数名はsnake_caseで統一する
- 関数には必ずdocstringを書く
- print文でのデバッグは禁止、loggingを使う
相棒のようなClaudeにする書き方のコツ
ここからが本題です。
「役割」を与えるだけで、Claudeの振る舞いはかなり変わります。
ペルソナを与える
ただの「アシスタント」ではなく、具体的な役割を与えてみてください。
たとえば「シニアエンジニアとしてレビューする」と書くだけで、指摘の質が上がる印象があります。
# あなたの役割
あなたはこのプロジェクトのシニアエンジニアです。
コードレビューでは可読性とパフォーマンスの両方を重視してください。
判断基準を明文化する
「迷ったらどうするか」を書いておくと、Claudeの判断がブレにくくなります。
なんだか抽象的に感じるかもしれませんが、これが意外と効くんです。
# 判断に迷ったときの優先順位
1. セキュリティ
2. 可読性
3. 実行速度
禁止事項をはっきり書く
やってほしくないことは、遠慮せず明記しましょう。
私も「なぜか毎回同じミスをする」と悩んでましたが、禁止事項を追加したら解決しました。
| 書き方 | 効果 |
|---|---|
| 「〜しないでください」 | 明確な禁止として認識されやすい |
| 「できれば〜は避けて」 | 曖昧で無視されることがある |
断定的に書く方が、圧倒的に伝わりやすい傾向があります。
サブエージェントとの役割分担を書く
複数のサブエージェントを使う構成なら、それぞれの役割もCLAUDE.mdに書いておくと安心です。
「誰が何を担当するか」が明確になり、指示の重複を防げます。
サブエージェントにはAskUserQuestionが使えない点に注意してください。
ユーザーへの確認が必要な処理は、スキル側に持たせる設計がおすすめです。
よくある失敗パターン
最後に、ありがちな失敗も紹介しておきます。
これらを避けるだけで、CLAUDE.mdの質はぐっと上がるはずです。
- 情報を詰め込みすぎる：長すぎるCLAUDE.mdは逆に読まれにくくなります
- 抽象的な表現ばかり：「良いコードを書く」ではなく、具体的な基準を書きましょう
- 更新されないまま放置：プロジェクトの変化に合わせて定期的に見直すことが大切です
まとめ
- CLAUDE.mdには役割と制約を明記する
- プロジェクト概要・技術スタック・コーディング規約を基本構成にする
- ペルソナ設定と判断基準の明文化で精度が上がる
- 禁止事項は曖昧にせず断定的に書く
- 情報の詰め込みすぎと放置に注意する
エンジニアなら読むべき本を30冊以上紹介しています。
正直、私の仕事のやり方をガラッと変えた神本やSQLのチューニングに悩んだ時にめちゃくちゃ役に立ったもあります👇
→記事を読む