こんにちは。秋田県のIT企業、北日本コンピューターサービスのR&Dチーム「AUL（アウル）」に所属しています。トラフクロウです。
最近、「なんちゃか駆動開発」や「ループエンジニアリング」など、新しい開発手法がどんどん出てきていますよね。
僕の会社でもAI駆動開発を推進する動きがありますし、自分が関わっているプロジェクトでも実際にAI駆動開発をしています。
AI駆動開発でプロジェクトを進めることが決定した当時、
「R&Dたるもの時代に取り残されるわけにはゆかぬ！！」
という使命感に駆られて、世間で話題になっている手法を色々と試してみようと思いました。
僕らのプロジェクトでは普段 Claude Code を使って開発しているので、
「とりあえず、練習するならCLAUDE.mdから作っていこうかな～。サクッと書いて、ジャンジャカ練習しよ～」
と思って、意気揚々とCLAUDE.mdから作り始めました。
ところが、これがまったく書けない！！
書かなきゃいけないことは分かっているはずなのに、いざ文字にしようとすると手が止まる。そして、できあがったのは期待する役割とタスクを数行並べただけの、なんとも味気ないものでした。
当然、期待通りに動くわけもなくイマイチな受け答えしか返ってきません。
「これはひどいな」と思ったので、作戦変更、「実はこういうことしたいんだけど……」という感じでAIと会話しながらmdファイルを作ることにしました。
すると、なかなかどうして、ある程度満足のいく結果を返すようになりました。
そのとき、ふと
- CLAUDE.mdの書き方ってサンプルはよく見かけるけど、作り方そのものってあまり紹介されてないよな？
- 自分の望むコンテキストファイルを簡単に作る方法ってないのかな？
ということが気になったので、色々調べてみることにしました。
そんなわけで今回は、色々あーだこーだ考える中で僕がたどり着いた、
「いま時点でもっともしっくりくるコンテキストファイルを作る方法」
を紹介したいと思います。
僕は普段 Claude Code を使っているので、今回はCLAUDE.mdを作る場合のやり方として紹介します（たぶん、AGENTS.mdや他のプロンプト作成にも応用できると思う。たぶん。）。
この記事での用語の定義
コンテキストファイル:
CLAUDE.mdやAGENTS.mdのような、生成AIにプロジェクトの前提、文脈を読ませるファイルのこと
プロンプト:
生成AIへ入力するテキスト、またはコンテキストファイルの中身のこと
トラフクロウ流、プロンプト作成の流れ
今現在は、次の流れでCLAUDE.mdを作っています。
1. 自分がどんなことをしたいのか、そのために生成AIに何をして欲しいのか生成AIと雑談する
2. 生成AIと話をする中で「こいつ、わかってないな？」と感じる部分を探し、訂正する
3. AIとの認識齟齬がないと感じるようになったら、これまで話してきたことを再現できるようにCLAUDE.mdを作らせる
4. 生成したCLAUDE.mdを見直して、抜け漏れ、認識齟齬がないか確認する
5. 一緒にタスクを進める中で追加したルールがあればCLAUDE.mdに追記させる
以下、それぞれのステップを簡単に補足していきます。
まずはAIと雑談する
かつてCLAUDE.mdがうまく書けなかった一番の原因は、おそらく、「自分が何をしたいのか、僕自身も生成AIもわかっていなかった」ことだと思います。
普段の仕事やチーム作業でも同じですが、誰かと何かをするときには、「なぜやるのか、どうやるのか、何をやってはいけないのか」という前提が大切になります。
なので、まずは腹を割って話そうと思いまして、プロジェクトフォルダ内で Claude Codeを立ち上げて、次のようにお話することにしました。
「○○というプロジェクトを始めることになったんだ。お客さんは○○な人で、状況としては○○な場面で、○○をするために使うシステムなんだよね。開発するのを手伝ってよ。」
意識しているのは、「仕事とは関係ない親しい友人、または初めましての人に対して、これから一緒にやりたいことをゼロから説明する」という気持ちで話すことです。
仮に開発プロジェクトなら、この雑談の延長でそのままフロント・バックエンド・DB・インフラといった構成を一緒に組んでいったり、簡単な画面を１つ作ってみたり、フロントからバックエンドに通信する処理を１つ作ってみたりします。
ですが、これは「成果物を作るため」にプログラムを書かせるわけではありません。
「生成AIが、僕の考えと同じ方向を向いて作業をしているか」を確認するために目に見えるコードを書かせます。
ですので、「一気に全部AIに作らせない」ことを強く意識して１つ１つ小さく作らせるようにしています。具体的には次のような粒度です。
- フロントやバックエンド側の構成
- サンプル用の簡単な画面
- フロントからアクセスするAPI処理を１つ
- DBへのコネクションの作り方や、スキーマのイメージ
これらを作らせるときも、雑談の体は崩しません。
実際に誰かと開発をするときのように、「○○なふうにしたい」「○○にしようと思ってるんだよね」と方向性を話し、AIにまず実装計画や方針の叩き台を作らせるようにしています。
入力内容は自己責任で
一緒にタスクを進めるためには、ある程度細かい情報を教える必要がありますが、個人情報や機密情報は入れないように注意しています。
皆さんも試す場合は、何を入れて何を入れないか自己責任で判断してください。
「こいつ、わかってないな？」と感じたら訂正する
雑談の中でAIが質問や提案、あるいは実装の叩き台を返してきても、それをそのまま採用することはしません。
返してきた内容を観察しながら「なんかしっくりこないな」「こいつ、ちょっとわかってないな？」と感じるポイントを探していきます。
「ちがう、そうじゃない」と感じた瞬間、「なんでそう思う？、どこでそう思う？」と僕自身に問い直します。
そして「ああ、ここが変なのか」と気づいたら、「いや、そこはこうじゃなくて、○○ってことなんだよね」というふうに、AIへ伝え直すのです。
完璧に言葉にできなくても「この部分がなんか嫌だ、うまく言葉にできないけど、○○って感じにしたい」といった感じで、とにかく「自分が納得していないという事実」を生成AIにフィードバックしています。
このあたりの考え方は、以前書いた「AIと壁打ちしてますか？そして答えは出てますか？」という記事にも書いています（こちらも是非に読んでみてください）。
このようなやり取りを何度か繰り返すことで、生成AIとの認識のズレが徐々になくなっていきます（人間同士のコミュニケーションと同じですね）。
🔍このやり方は本当に効くの？という方向け
「What Should We Engineer in Prompts? Training Humans in Requirement-Driven LLM Use」という論文では、
人間がプロンプトで本当に設計すべきなのは、役割指定や「step-by-step」のような技巧ではなく、LLMに何をしてほしいかという要件である
という主張がされています。
つまり大事なのは、「何のために、具体的に何をして欲しいのか」を生成AIに正確に伝えることで、step-by-step や CoT などは二の次という主張です。
僕の紹介している今回の方法では、生成AIとの対話、雑談を通じて「生成AIに自分自身の要件が正確に伝わっているか」を検証しているわけですね。
要件を明確に書くことができればわざわざ、「雑談」なんて手間のかかる工程を踏む必要はないのですが、僕は頭の中の言語化が苦手なので、「考える＋アウトプット」が同時にできる対話形式のコミュニケーションを重宝しています。
「Conversational Prompt Engineering」という論文でも、ユーザーが最初から要望を完全に言語化できないことを前提に、AIとの短い対話を通じてプロンプトを育てていく CPE という手法が提案されています。AIとの対話を重ねることで、人間が無意識に考えている好みや価値観を引き出すことができるそうです。
そして CPE で作られたプロンプトは、例示を与えるプロンプト（few-shot）と同等以上の性能を出すことができたのだとか。
会話から好みを察してくれるなんて、いやはやAIは賢いですよね。
認識齟齬がなくなったら、CLAUDE.mdを作らせる
生成AIとのやりとりを重ねて、「もう指摘することないな」「これから一緒に作業を進めていけそうだ」と感じたら、次のフェーズに移るサインです。ここで初めて、こう伝えます。
「今後も同じ考え方やルールで開発をしていきたいから、今日話した内容を踏まえてCLAUDE.mdを作ってくれる？」
依頼はこれくらいシンプルでOKです。
ここまでの雑談と訂正の中で、すでに文脈や要件が十分に共有できているので、あとは生成AIがイイ感じに書いてくれます。
🔍構造化されたプロンプトは強いらしい
「Meta Prompting for AI Systems」という論文には、
LLMの推論能力を高めるには、具体例を大量に与えるよりも、問題解決の「構造」を明示したプロンプト（Meta Prompting）を与える方が有効である
という旨の主張が書かれています。
タスクの目的や制約、処理手順や出力形式を構造化して渡すことでLLMの精度が上がるということです。
通常、CLAUDE.mdはマークダウン記法で書かれます（mdファイルなんだから、それはそう）。
マークダウン形式も１つの構造化ですが、今回のように雑談ベースで記述内容を洗い出していくと、
プロジェクトの前提や、ユーザーの好み、シチュエーションごとの具体例など、
複数の種類の重要な情報がたくさん出てきて、それらをすべてmdファイルに記載しなくてはいけません。
すると
「特定の種類の情報がどこからどこまで書いてあるのか、生成AIが正しく読み取れない」
という問題が出てくる場合があります。
このように複数種類の情報を混ぜ込む必要がある場合は、XMLタグで囲む方法が有効とされているようです。
構造化を意識しつつ、複数の情報を効果的に読み込ませるために、
記載する内容が複雑になりそうなときは、XMLタグで構造化したmdファイルを作るように指示を出すということも僕はよくやります。
効果はあるような気がしていますが、プラシーボかもしれません（試してみてください）。
# Project Instructions
<project_context>
このプロジェクトは、ReactとFastAPIで構成されたWebアプリケーションです。
</project_context>
<development_rules>
- 既存の設計とコーディング規約を優先する
- 関係のないリファクタリングを行わない
- 変更前に関連コードとテストを確認する
- 本番環境へのデプロイは実行しない
</development_rules>
<workflow>
- 関連する実装箇所を調査する
- 影響範囲を整理する
- 必要最小限の変更を行う
- テストを実行する
</workflow>
<response_format>
回答では、**確認できた事実と推測を区別**してください。
</response_format>
生成されたCLAUDE.mdを見直す
できあがったCLAUDE.mdをそのまま使うことはしません。必ず一度全部読みます。
読みながら、これまでの雑談、訂正の内容がちゃんと反映されているか、抜け漏れや認識齟齬がないかを確認します。
誤字の修正や、いらないと思う記述の削除は自分でパッと済ませて、直したら「md修正したよ」とAIにひと声かけるようにしています。
ここのチェックで大事にしているのは、「CLAUDE.mdに書くものの捉え方」です。
僕自身は、CLAUDE.md（というかコンテキストファイル全般）を
「一緒に仕事をする上で絶対に忘れてほしくない情報、思いや目的、価値観」
を書く場所だと思っています。
ですので、「この心境（CLAUDE.md）の人と今後一緒に作業を進めても大丈夫だろうか？」という視点で内容を確認し、必要に応じて修正をしています。
タスクを進める中で追加ルールがあればmdファイルに追記させる
CLAUDE.mdは一度作ったら終わりというものではありません。
プロジェクトを回しながら「あ、これも今後守ってほしいな」と気づいたことがあれば、その都度
「さっきの件、今後もこうしたいから、CLAUDE.mdに追記しといて」
というふうに軽く頼んで、そのまま追記させます。
CLAUDE.mdは完成品ではなく、プロジェクトと一緒に育てていく「生きたドキュメント」です。
このやり方は開発以外でも使える
ここまでは開発プロジェクトの例をイメージして書いてきましたが、これらのやり方は技術調査やドキュメント作成のようなプロジェクトでも同じように使っています。
具体的には次のようなプロジェクトを立てています。
- AIや関連技術、最新情報の調査、質疑応答
- 資料作成時の構成作成
- 資格試験勉強などの自己学習アシスタント
ここでもやることは同じで、
「自分が本当は何がしたくて、そのためにどんな支援をして欲しいのか」
をAIと雑談する中で明らかにしていきます。
最初は曖昧なイメージしかなくても、手を動かして考えていること、感じていることを入力していくうちに自然とこれらが輪郭を帯びてくるはずです。
AI相手でもちゃんとコミュニケーションをとりましょう
頭の整理というのは「誰かにわかってもらうために一生懸命言葉にする」ことで初めて行われます。ですので、AI相手だからと手を抜かずに、リアルな人間（友人や同僚、上司や取引先の人）と接するような気持ちで会話をしてみてください。
まとめ
- 生成AIと雑談する：何をしたいか、AIに何をして欲しいかを、友人にゼロから説明するつもりで話す。
- 「こいつ、わかってないな？」と感じたら訂正する：AIの提案や叩き台を聞いて「しっくりこない」と思ったら、そこを言語化して伝え直す。これから一緒に仕事をする仲間との打ち合わせだと思う。
- 認識齟齬がなくなったら、mdファイルに出力させる：「ここまでの内容をまとめて」程度のシンプルな指示でよい。結果は前の雑談である程度決まっている。
- AIの生成したルールを見直す：抜け漏れや認識齟齬がないか自分の目で確認する。「この人と一緒にタスクを進めていけそうか」を考える。
- タスクを進める中で追加ルールがあれば追記させる：CLAUDE.mdは完成品ではなく生きたドキュメント。気を付けて欲しいことは気づいたタイミングで追記する。
最後まで読んでいただきありがとうございました！
最後まで読み進めていただき、ありがとうございました！
「コンテキストファイルの作り方」にフォーカスしたドキュメントが少ないなと感じ、自分なりに手ごたえを感じている方法をまとめてみました。
そこそこイイ結果が得られるんじゃないかなと思うので、ぜひお試しいただければと思います。
一方で、このやり方をチーム開発で採用する際の懸念点もあります。
「From Prompt Engineering to Prompt Science With Human in the Loop」という論文では、「単一の研究者が場当たり的にプロンプトを改訂すると、個人のバイアスや主観が入り込む恐れがある」という趣旨の記載がされています。これは「１人でAIと壁打ちして仕上げる」僕のやり方にダイレクトアタックしてくる指摘です。
一旦の対処法として、日頃のプロジェクト開発を行う際は、次のことをルールとしてチームメンバーで共有しています。
「チーム共有のCLAUDE.mdについてはチーム全体で合意形成してから追記する」
これにより、特定の個人の思想が生成AIに強く流れ込みバイアスになることを避け（たつもりになっ）ています。
今回の僕の方法は正解ではないでしょうし、もっとウマいやり方をしている人もたくさんいるはずです。皆さんも、どうすればよいプロンプトを作れるのか考えてみてはいかがでしょうか？
調べてみると結構楽しいですよ。