本文へ移動
AIコーディングをはじめよう

第12章・自分用に育てる

Markdown と指示ファイル（CLAUDE.md・AGENTS.md）

AI コーディングをしていると、名前が「.md」で終わるファイルや、#・-・** のような記号の入った文章をよく見かけます。これは Markdown（マークダウン）という書き方です。AI の返事にも、プロジェクトの説明書にも、AI への指示を書いておくファイルにも使われます。

この章の前半では、Markdown の書き方を、書いた文字と表示されたものを並べて見ます。後半では、AI が作業の始めに自動で読み込む「指示ファイル」（Claude Code の CLAUDE.md、Codex の AGENTS.md、Gemini CLI の GEMINI.md）に、何を書き、どこに置くかを見ます。

読み終わるころには、「CLAUDE.md に書いておいて」と言われたときに、何をどこに書けばよいかが分かるはずです。

この章で見ること
Markdown の書き方（見出し・箇条書き・太字・番号付き・コード・リンク）と、指示ファイルが読み込まれるしくみ・書くこと・置き場所・3社のファイルの名前・/init での作り方を、図で順に見ます。
読み終わると
Markdown で見出しと箇条書きが書け、「CLAUDE.md に書いておいて」の意味と置き場所が分かる
前の章までに知っていること
AI は、コンテキスト（一度に見ている範囲）に積まれたものを読んで答えること（第9章）。「/」で始まるスラッシュコマンド（第8章）。プロジェクトを Git で記録し、チームと共有すること（第11章）。
読む時間の目安
15分ほど

この章で出てくる言葉

分かる言葉は読み飛ばして構いません。途中で分からない言葉が出たら、ここに戻ってくるか、用語集で探してください。

Markdown（マークダウン）
文章に「#」や「-」などの記号で「ここは見出し」「ここは箇条書き」と印を付ける書き方。中身はただの文字なので記号のままでも読め、対応したアプリで開くと整った見た目で表示されます。ファイル名は「.md」で終わります。
見出し
文章の区切りに付ける題名。Markdown では行の頭に「#」と空白を書きます。「#」が多いほど小さい見出しになります（1〜6個）。
箇条書き（かじょうがき）
項目を1行に1つずつ並べる書き方。Markdown では行の頭に「-」と空白を書きます。順番に意味があるときは「1.」のような番号付きの箇条書きにします。
太字
目立たせたい文字を太くすること。Markdown では「**」で文字をはさみます。日本語では、「**」のすぐ内側に「」などの記号を置くと太字にならないことがあります。
コードブロック
何行もあるコードやコマンドを、ひとまとまりで見せる書き方。Markdown では、バッククォート（`）を3つ並べた行で上下をはさみます。文の中の短いコードは、バッククォート1つではさみます。
README（リードミー）
プロジェクトが何をするか・どう使うかを書いた、人が読むための説明書のファイル。README.md のように Markdown で書くことが多く、GitHub はフォルダーに置いた README を表示して見せます。
指示ファイル
AI コーディングのツールが作業の始めに自動で読み込む、決まりごとを書いたファイル。使うコマンドや、プロジェクトの決まりを書いておくと、新しい会話でも毎回伝わります。Claude Code の CLAUDE.md、Codex の AGENTS.md、Gemini CLI の GEMINI.md など。
CLAUDE.md
Claude Code が作業の始めに読む指示ファイル。プロジェクトのフォルダー（./CLAUDE.md）や、自分用の場所（~/.claude/CLAUDE.md）に置きます。見つかったものは全部つなげて読まれます。
AGENTS.md
どの AI ツールでも使えるように決められた、共通の形の指示ファイル。Codex はこれを読みます。Claude Code は CLAUDE.md が無ければ読み、Gemini CLI は設定で読めるようにできます。
GEMINI.md
Gemini CLI が読む指示ファイル（公式の呼び名は「コンテキストファイル」）。自分用の ~/.gemini/GEMINI.md と、プロジェクトのフォルダーに置いたものが読まれます。
置き場所（自分用・プロジェクト）
指示ファイルは、置く場所で効く範囲が変わります。自分用の場所に置くとどのプロジェクトでも読まれ、プロジェクトのフォルダーに置くとそのプロジェクトだけで読まれます。プロジェクトのものは Git でチームと共有します。
/init
指示ファイルの下書きを AI に作らせるスラッシュコマンド。Claude Code・Codex・Gemini CLI のどれにもあります。Claude Code では、AI がプロジェクトを調べて書き出します。できた下書きは自分で読んで直します。
自動メモリ
Claude Code で、AI が自分で付けて次の会話に持ち越すメモ。「覚えておいて」と頼むとここに残ります。人が書く指示ファイル（CLAUDE.md）とは別のものです。

下にスクロールすると、図が1つずつ動いて説明が進みます。見逃したら、スクロールを戻せば同じところが巻き戻ります。図は、しくみを説明するために描いた模式図です。実際のアプリの画面ではありません。

  1. 01 / 20

    Markdown（マークダウン）は、文章に # や - などの記号で「ここは見出し」「ここは箇条書き」と印を付ける書き方です。

    中身はただの文字（テキスト）なので、特別なソフトがなくても書けます。ファイル名は「.md」で終わり、対応したアプリで開くと、右のような見た目で表示されます。

    会話では：「Markdown でまとめて」「md ファイルにして」は、この記号を使った書き方で書いてほしい、という意味です。

    しくみの図Markdown：記号で印を付けた文字と、その表示

  2. 02 / 20

    行の頭に # と空白を1つ書くと、その行が見出しになります。## と2つ重ねると、1段小さい見出しです。

    # は1〜6個まで使え、多いほど小さい見出しになります。# のあとの空白を忘れると見出しになりません。記号の無い行は、ふつうの文（段落）として出ます。

    会話では：「見出しを付けて整理して」「## ごとに話題を分けて」のように頼めます。

    しくみの図Markdown の書き方：書いた文字と、表示されたもの

  3. 03 / 20

    行の頭に - と空白を書くと、箇条書きになります。表示では、行の頭に点が付きます。

    - の代わりに * や + も使えます。決まりごとのように、順番の無いものを1行に1つずつ並べるときに使います。

    会話では：「箇条書きで」「- で並べて」は、1行に1つずつ並べて書いて、という意味です。

    しくみの図Markdown の書き方：書いた文字と、表示されたもの

  4. 04 / 20

    ** で文字をはさむと、太字になります。大事な決まりを目立たせたいときに使います。

    日本語では、** のすぐ内側に「」などの記号があると、太字にならないことがあります。**「必ず」** ではなく 「**必ず**」 のように、記号を外に出します。

    会話では：「ここは太字で強調して」のように頼めます。強調する行が多すぎると、どれも目立たなくなります。

    しくみの図Markdown の書き方：書いた文字と、表示されたもの

  5. 05 / 20

    行の頭に 1. のような数字と点を書くと、番号付きの箇条書きになります。順番に意味があるときに使います。

    点の代わりに 1) のようなかっこも使えます。手順のように、上から順にやってほしいことを書くのに向いています。

    会話では：「手順は番号付きで書いて」と頼むと、どの順でやるかがはっきりします。

    しくみの図Markdown の書き方：書いた文字と、表示されたもの

  6. 06 / 20

    文の中のコマンドは「`」（バッククォート）ではさみ、何行もあるコードは、バッククォートを3つ並べた行ではさみます。

    はさんだ中は、記号も書いたとおりの文字で出ます。3つ並べた後ろに sh のような言語の名前を書くと、GitHub などでは色分けして表示されます。

    会話では：「コマンドはコードブロックに入れて」「ファイル名はバッククォートで囲んで」のように使います。

    しくみの図Markdown の書き方（続き）：コードとリンク

  7. 07 / 20

    [表示する文字](行き先) と書くと、押せるリンクになります。行き先には、ページの住所（URL）やファイルの場所を書きます。

    ほかに表や引用などの書き方もあります。もとの決まりは CommonMark という仕様にまとめられていて、GitHub はそれに表などを足した GFM という書き方を使っています。

    会話では：「出典のリンクを貼って」は、この形で行き先の URL を書き足して、という意味です。

    しくみの図Markdown の書き方（続き）：コードとリンク

  8. 08 / 20

    AI コーディングでは、Markdown をあちこちで見ます。AI の返事、プロジェクトの説明書（README.md）、そしてこの章の後半の「指示ファイル」です。

    GitHub は、フォルダーに置いた README.md を、表示に直して見せます。表示に直さない画面では、** や # が記号のまま見えます。

    会話では：「返事に ** がそのまま出ている」は、太字の記号が、表示に直されずに見えている、という意味です。

    しくみの図Markdown を見かける場所

  9. 09 / 20

    新しく会話を始めるたびに、AI はまっさらなコンテキスト（第9章）から始めます。前の会話で説明したことは入っていません。

    毎回伝えたいことは、ファイルに書いておきます。これが「指示ファイル」です。Claude Code の公式は、何度も説明し直していることを書いておく場所だと説明しています。

    会話では：「毎回同じことを言っている気がする」と思ったら、それは指示ファイルに書いておくとよいことです。

    しくみの図新しい会話は、まっさらから始まる

  10. 10 / 20

    指示ファイルは、作業の始めに自動で読み込まれ、コンテキストの先頭のほうに入ります。AI はそれを読んでから、頼みごとに取りかかります。

    中身は AI が読んで従おうとする「文章」で、必ず守らせる設定ではありません。必ず動かしたい決まりは、フック（第15章）などのしくみにします。

    会話では：「CLAUDE.md は読み込まれてる？」と思ったら、Claude Code では /memory や /context で、読み込まれたファイルを確かめられます。

    しくみの図指示ファイルは、作業の始めに読み込まれる

  11. 11 / 20

    指示ファイルには、AI がコードを読んでも分からないことを書きます。動かし方やテストのコマンド、このプロジェクトだけの決まりなどです。

    Claude Code の公式は、推測できないコマンド、ふつうと違う書き方の決まり、テストのしかた、ブランチ名などの作法、気づきにくい落とし穴を挙げています。

    会話では：「テストの動かし方を、指示ファイルに書いておいて」のように頼めます。

    しくみの図指示ファイルに書くこと・書かないこと

  12. 12 / 20

    書かなくてよいのは、コードを読めば分かること・よく変わる情報・長い説明などです。指示ファイルは毎回読まれるので、短いほど大事な行が伝わります。

    公式は、1行ずつ「この行を消したら、AI は間違えるか？」と問い、間違えないなら消すよう勧めています。長すぎると、決まりが埋もれて守られにくくなります。

    会話では：「指示ファイルが長すぎる」は、書きすぎて大事な決まりが埋もれている、という意味です。削って短くします。

    しくみの図指示ファイルに書くこと・書かないこと

  13. 13 / 20

    決まりは、守れたかを確かめられるくらい具体的に書きます。「きれいに整える」より「字下げは空白2つ」です。

    何を・いつ・どうするかまで書くと、AI が毎回同じように動きやすくなります。公式も、具体的で短い指示ほど従われやすいと説明しています。

    会話では：「『ちゃんとテストして』では伝わらないので、コマンドまで書いておいて」のように直します。

    しくみの図指示ファイルの書き方のこつ

  14. 14 / 20

    関係する決まりは、Markdown の見出しと箇条書きでまとめます。長い文のかたまりより、AI が従いやすくなります。

    前半で見た Markdown が、ここで役に立ちます。Claude Code の公式は、1つの CLAUDE.md を 200 行未満に収めるのを目安にしています（2026年10月時点）。

    会話では：「CLAUDE.md を見出しごとに整理して、短くして」と、AI 自身に頼むこともできます。

    しくみの図指示ファイルの書き方のこつ

  15. 15 / 20

    指示ファイルは、置く場所で効く範囲が変わります。プロジェクトのフォルダーならそのプロジェクトで、自分用の場所ならどのプロジェクトでも読まれます。

    プロジェクトの CLAUDE.md は Git でチームと共有し、自分だけの好みは自分用の場所に書きます。下のフォルダーに置いたものは、AI がそこのファイルを触ったときに読まれます。

    会話では：「それはこのプロジェクトだけの決まりだから、プロジェクトの CLAUDE.md に書いて」のように、置き場所まで指定して頼みます。

    しくみの図Claude Code の指示ファイルの置き場所

  16. 16 / 20

    Claude Code は、見つかった指示ファイルを全部つなげて読みます。広い範囲（自分用）のものが先、プロジェクトのものが後に入ります。

    後のものが前のものを消すわけではありません。2つの指示が食い違うと、AI がどちらかを勝手に選ぶことがあるので、食い違いを作らないようにします。

    会話では：「自分用とプロジェクトの CLAUDE.md で、言っていることが食い違っている」は、直したほうがよい状態です。

    しくみの図Claude Code の指示ファイルの置き場所

  17. 17 / 20

    指示ファイルの名前は、ツールによって違います。Claude Code は CLAUDE.md、Codex は AGENTS.md、Gemini CLI は GEMINI.md を読みます。

    どれも中身は Markdown で、自分用とプロジェクト用に置ける点も同じです。自分用の置き場所は、それぞれのツールの設定フォルダーの中です。

    会話では：「Gemini CLI なら GEMINI.md、Codex なら AGENTS.md に書く」のように、ツールに合わせて名前を変えます。

    しくみの図3社のツールと、指示ファイルの名前

  18. 18 / 20

    AGENTS.md は、どの AI ツールでも使えるように決められた共通の形で、多くのツールが読めます。Claude Code も、CLAUDE.md が無ければ AGENTS.md を読みます。

    CLAUDE.md もあるときは、CLAUDE.md に @AGENTS.md と1行書くと、AGENTS.md の中身を取り込めます。Gemini CLI は、設定で読むファイルの名前に AGENTS.md を足せます。

    会話では：「AGENTS.md に移しておけば Codex でも読める」は、1つのファイルを複数のツールで使い回す、という話です。

    しくみの図AGENTS.md を、いくつものツールで読む

  19. 19 / 20

    最初の下書きは、AI に作らせられます。Claude Code・Codex・Gemini CLI はどれも、/init で指示ファイルの下書きを作ります。

    Claude Code の /init は、プロジェクトを調べてコマンドや決まりを書き出し、CLAUDE.md がすでにあれば上書きせずに直す案を出します。下書きは自分で読んで直します。

    会話では：「まず /init で下書きを作らせて、それを直そう」のように使います。

    しくみの図指示ファイルの作り方と育て方

  20. 20 / 20

    指示ファイルは、使いながら育てます。AI が同じ間違いを2回したら、それを防ぐ1行を書き足します。

    「CLAUDE.md に書いておいて」と頼めば、AI が書き足します。Claude Code で「覚えておいて」と頼むと、指示ファイルではなく、AI が自分で付けるメモ（自動メモリ）に残ります。

    会話では：「それ、CLAUDE.md に書いておいて」——次からは、新しい会話でも最初から伝わります。

    しくみの図指示ファイルの作り方と育て方

この章のまとめ

  1. 1

    Markdown は、記号で印を付ける書き方です。# で見出し、- で箇条書き、** で太字、1. で番号付き、バッククォートでコード、[ ]( ) でリンク。記号のままでも読め、名前が「.md」で終わるファイルに書きます。

  2. 2

    指示ファイルは、AI が作業の始めに読む決まりごとです。AI が推測できないコマンドや、このプロジェクトだけの決まりを、具体的に・短く・見出しと箇条書きで書きます。AI が読んで従おうとする文章で、必ず守らせる設定ではありません。

  3. 3

    名前と置き場所は、ツールで少し違います。Claude Code は CLAUDE.md、Codex は AGENTS.md、Gemini CLI は GEMINI.md。自分用とプロジェクト用があり、/init で下書きを作って、使いながら育てます。

この章の内容を確かめた情報源

確認日: 2026年10月25日

次の章（準備中）第13章 スキル：手順書を渡しておく決まった作業の手順を「スキル」としてまとめ、必要なときだけ AI に読ませる。

章の一覧へ戻る