📦 プライム30日無料体験を試す
当ブログはAmazonアソシエイト・プログラムの参加者です。Amazonのアソシエイトとして、適格販売により収入を得ています。
マークダウンの書き方入門 AIに伝わるmd記法まとめ
AIに何かをお願いするとき、昔ほどプロンプトを凝る必要はなくなってきました
それでも、Claude Code の CLAUDE.md みたいな「AIが読み込むファイル」は、今もマークダウン(Markdown)で書くのが定番なんです
マークダウンは、記号をちょっと添えるだけで見出しや箇条書きを表せる書き方です
これを覚えておくと、大きく2つの場面で役に立ちます
- AIに構造を正しく伝える:見出しや箇条書きで整理して渡すと、話の区切りが伝わりやすい
- AIが作ったmdファイルを読める・直せる:CLAUDE.md や README.md を開いても慌てずに済む
この記事では、チャットでよく打つ基本記法から、チャットでは出番が少ないけどmdファイルで頻出の記法まで、初心者向けにまとめて解説します
Claudeそのものの使い方はClaudeの使い方(初心者向け)でも扱っているので、あわせてどうぞ
ジャベ雄記号は10個ほど覚えれば、たいていの場面をカバーできます
目次
そもそもマークダウンとは?
マークダウン(Markdown)とは、記号を少し添えるだけで見出しや箇条書き・装飾を表せる軽量マークアップ言語です
覚えることが少なく、書いた記号がそのまま残っていても意味を読み取れるのが持ち味です
いちばんの狙いは読みやすさで、記号付きのテキストのままでも人がすっと読めるように作られています
だからこそ、人が編集して、AIも読む、という使い方に向いていて、CLAUDE.md のような設定ファイルにも採用されています
まずは、記号とそれが表す構造の対応をざっと見ておきましょう
細かい書き方は次の章でまとめて扱います
スクロールできます
| 記号 | 表す構造 |
|---|---|
| # | 見出し |
| – | 箇条書き |
| **(2つ) | 太字 |
| ` (バッククォート) | コード |
作ったのは John Gruber という人で、2004年に考案しました
Aaron Swartz も相談役として関わりましたが、共同作者というより協力者という立ち位置です
その後、実装ごとの挙動のズレをそろえる CommonMark という標準仕様も整備されています
拡張子の .md がマークダウンで書かれたファイルの目印で、CLAUDE.md 以外に README.md や AGENTS.md などでも使われます
Claude Code の設定ファイルの中身は、Claude Code 設定ファイル早見表にまとめています
ジャベ雄まずは「記号で構造を書くテキスト」とだけ覚えておけば十分です
マークダウンの記法一覧
ここからは、マークダウンの記法をよく使う順に3段階でまとめます
「まず覚える」「mdファイルで頻出」「AIのmdで見かける」の順なので、上から読んでいけば無理なく身につきます
必須 – まず覚える
チャットでもmdファイルでも出番が多い、土台の6つです
まずはこの書き方から押さえましょう
# 見出し1
## 見出し2
- 箇条書き
- もうひとつ
1. 番号つき
2. その次
**太字** と *斜体*
`インラインコード`
[リンクの文字](https://example.com)- 見出し:行頭に # と半角スペース、# の数でレベルが決まる、話題の区切りを示す(# の直後の半角スペースは省かない)
- 箇条書き:行頭に – と半角スペース、並列の項目を並べる
- 番号リスト:1. の形、手順に使う、番号は打ち間違えても表示は自動で連番になる
- 太字・斜体:記号2つで太字、1つで斜体、強調したい語に(単語の途中はアスタリスクが安全)
- インラインコード:バッククォート1つで囲む、コマンドやファイル名を文中で見せる
- リンク:角カッコに表示テキスト、続けて丸カッコにURL
ジャベ雄この6つが打てれば、日常のやり取りはほぼ回せます
よく使う – mdファイルで頻出
CLAUDE.md や README.md でよく見る、少し長めの記法です
チャットでは出番が少なくても、ファイルを読むなら押さえておきたいところ
```python
print("hello")
```
> 引用文はこう書きます
---
| 列A | 列B |
| --- | --- |
| あ | い |
- 親の項目
- 子の項目(半角スペースで下げる)- フェンスドコードブロック:バッククォート3つで前後をはさむ、先頭に python などの言語名を書くとハイライトの合図になる、コードのかたまりを見せる、AIが吐くmdで頻出
- 引用:行頭に大なり記号、注記や引用文に使う
- 表:縦棒で区切り、見出しの下に区切り行を1本入れる(GFM拡張、対応環境でだけ効く、詳しくは次の章)
- 水平線:ハイフンを3つ以上並べた単独行、話題の切れ目に
- 箇条書きのネスト:子の項目を半角スペース2〜4個下げて揃える、入れ子の階層を表す(下げ幅は環境で違うので揃えるのが大事)
知っておいた方がいい – AIのmdで見かける
自分で書く機会は少なくても、AIが生成したmdには顔を出す記法です
読めれば、崩さず直せます
- [ ] 未完了のタスク
- [x] 完了したタスク
~~打ち消し線~~
[表示テキスト][ref]
[ref]: https://example.comマークダウンで足りないところは、HTMLをそのまま書けます
AIの生成物では、折りたたみの <details> や改行の <br> あたりでよく見かけます
段落の途中で改行<br>したいとき
<details>
<summary>クリックで開く</summary>
折りたたみの中身
</details>- チェックリスト:角カッコの中を空白で未完了、エックスで完了、ToDoに使う(GFM拡張、対応環境でだけ効く)
- 打ち消し線:チルダ2つで前後を囲む、消し込みの表現に(GFM拡張、対応環境でだけ効く)
- 画像:リンクの先頭にビックリマークを付ける、代替テキストとURLを続ける
- 参照リンク:本文は角カッコにラベル、別の行で「ラベルとコロンとURL」を定義する、リンクが多い文書向け
- エスケープ:記号の直前にバックスラッシュ、意図しない装飾を止める(くわしくは「よくある崩れ」の章で)
- HTML直書き:改行の <br> や折りたたみの <details> など、HTMLをそのまま書ける
- setext見出し:テキストの下に イコール3つ でH1、ハイフン3つ でH2、古いmdで見かけることがある
最後に、ここまでの記法を早見表にまとめます
「どこで使うか」は チャット / mdファイル / AIが生成 の3つに分け、○=よく使う・△=たまに・×=ほぼ出ない の目安で示しました
迷ったらここに戻ってきてください
スクロールできます
| 記法 | 書き方 | レベル | チャット | mdファイル | AIが生成 |
|---|---|---|---|---|---|
| 見出し | # と半角スペース | 必須 | ○ | ○ | ○ |
| 箇条書き | – と半角スペース | 必須 | ○ | ○ | ○ |
| 番号リスト | 1. の形 | 必須 | ○ | ○ | ○ |
| 太字・斜体 | **太字** / *斜体* | 必須 | ○ | ○ | ○ |
| インラインコード | バッククォート1つで囲む | 必須 | ○ | ○ | ○ |
| リンク | 角カッコに文字、丸カッコにURL | 必須 | ○ | ○ | ○ |
| コードフェンス | バッククォート3つ+言語名 | よく使う | △ | ○ | ○ |
| 引用 | 行頭に大なり記号 | よく使う | △ | ○ | ○ |
| 表 | 縦棒と区切り行(GFM) | よく使う | △ | ○ | ○ |
| 水平線 | ハイフン3つ以上の単独行 | よく使う | × | ○ | ○ |
| ネスト | 子を半角スペース2〜4個下げる | よく使う | △ | ○ | ○ |
| チェックリスト | 角カッコに空白かエックス(GFM) | 知っておく | × | ○ | ○ |
| 打ち消し線 | チルダ2つで囲む(GFM) | 知っておく | × | △ | △ |
| 画像 | ビックリマーク+代替テキスト+URL | 知っておく | × | ○ | △ |
| 参照リンク | 角カッコにラベル+別行で定義 | 知っておく | × | △ | × |
| HTML直書き | <br> や <details> など | 知っておく | × | ○ | ○ |
ここまでで、表・チェックリスト・打ち消し線には「GFM拡張」と付けました
これが効くかどうかは貼り先しだいで、その仕組みは次の章で整理します
ジャベ雄全部を丸暗記せず、早見表で引きながらで十分です
素のマークダウンとGFM拡張・環境依存の違い
「同じ書き方なのに、効いたり効かなかったりする」
これがマークダウン最初のつまずきで、答えは記法が3つの層に分かれていることにあります
3層というのは、素のMarkdown(CommonMarkコア)/ GFM拡張 / 表示環境依存 の3つです
ざっくり表にするとこうなります
スクロールできます
| 層 | 含まれる記法 | 効く場所 |
|---|---|---|
| 素のMarkdown(CommonMarkコア) | 見出し・箇条書き・太字/斜体・リンク・画像・引用・水平線・コード | ほとんどの環境 |
| GFM拡張 | 表・タスクリスト・打ち消し線・URLの自動リンク | GitHub など GFM に対応した環境だけ |
| 表示環境依存 | コードの色付け(シンタックスハイライト) | 表示する側の実装しだい |
CommonMark は、実装ごとにバラバラだったマークダウンの挙動を、あいまいさなく決めた標準仕様です
ここに入っている記法は、だいたいどの環境でも同じように効きます
いっぽう GFM(GitHub Flavored Markdown)は、GitHubがCommonMarkに独自の拡張を足したものです
表・タスクリスト・打ち消し線・URL自動リンクは、この拡張にあたります
つまり対応している環境でしか効かないことがあるんです
WordPressの素のエディタや一部のチャット欄では、表やタスクリストが効かず、縦棒や角カッコがそのまま出ることがあります
「効かないな」と思ったら、まず貼り先がGFMに対応しているかを疑ってみてください
身近な例だと、GitHubで書いたタスクリスト付きのメモを、GFMに対応していないメモアプリに貼るとします
すると、チェックボックスが出ずに角カッコがそのまま残ることがあります
記法が悪いわけではなく、貼り先がその拡張に対応していないだけ、というケースです
もうひとつ紛らわしいのが、コードの色付けです
言語名を書く「記法」自体はCommonMarkコアなので素のマークダウンの範囲ですが、実際に色を付けるかどうかは表示する側しだいです
だから「言語名を書いたのに色が付かない」ことも起こります
ジャベ雄効いたり効かなかったりの正体は、この3層の切り分けです
AIに構造を正しく伝えるマークダウンのコツ
ここからが、AIとマークダウンを組み合わせる本題です
結論から言うと、見出しと箇条書きで整理して渡すだけで、AIの読み違いはかなり減ります
これは私の体感だけの話ではなくて、Anthropicの公式ドキュメントでもそう案内されています
CLAUDE.md を書くときは「構造化のために見出しと箇条書きで指示をまとめる」ことが推奨されていて、公式は「Claudeは人と同じように構造をスキャンする」と説明しています
なぜ構造が効くかというと、見出しや箇条書きは「ここで話題が変わる」「ここは並列の項目」という区切りを、記号で分かるようにしてくれるからです
人が流し読みするときの手がかりと同じものを、AIにも渡しているイメージで捉えると分かりやすいです
だらだら続く長い文章より、区切られた見出しのほうが追いやすい、というわけです
やることはシンプルで、次の3つを意識するだけで整います
- 見出しで話題の階層を示す(大きな話題は上位、細かい話題は下位の見出しに)
- 箇条書きで並列の項目を並べる(手順や条件を1行ずつ)
- コードのかたまりはコードフェンスで区切る(命令と説明が混ざらない)
たとえば「まずAをして、次にBをして、最後にCを確認して」とベタ書きするより、手順を箇条書きで1つずつ並べたほうが、AIは順番を取り違えにくくなります
渡す前に自分でざっと読み返して、区切りが見えるかを確かめるのがコツです
逆に、全部を1つの長い段落に詰め込むと、どこが指示でどこが補足か分かりにくくなります
難しく考えず、話題ごとに見出しを立てて、並ぶものは箇条書きにする
それだけでAIに渡す情報がぐっと整理されます
コードフェンスの区切りも、AIに渡すときに効いてきます
コマンドや設定を三連バッククォートで囲んでおくと、そこが「そのまま扱うコード」だとAIに伝わり、説明文と混ざって解釈される事故が減ります
短い1行でも、コードはコードとして囲っておくと安全です
Claude Code の拡張機構そのものに興味が出たら、Claude Code 拡張機構入門もあわせてどうぞ
ジャベ雄見出しと箇条書きを足すだけで、読み違いがぐっと減ります
AIが作ったmdファイルを読む・直すコツ
AIに任せていると、CLAUDE.md のようなmdファイルをAI自身が書いてくれる場面が増えてきます
中身を読めるようになると、気になったところを自分で微調整できます
たとえば、こんな中身のCLAUDE.md があったとします
# プロジェクトの前提
このプロジェクトは Python 製の集計ツールです
## コーディング規約
- インデントはスペース4つ
- 文字コードは UTF-8
## やってほしいこと
1. まずテストを書く
2. それから実装する読み方はシンプルです
# ではじまる行が見出し(話題の区切り)、– や数字ではじまる行が箇条書き
あとはふつうの文章、と分けて読めば構造がつかめます
直すときに崩れやすいのは、見出しの記号やインデントのあたりです
1行いじったら、エディタのプレビューで表示が崩れていないかを確認すると安心です
特に、見出しの # と本文のあいだの空行や、箇条書きのインデントは崩しやすいところです
コピペで持ってくると全角スペースが紛れ込むこともあるので、貼ったあとに一度プレビューを見ておくと、そのまま進めて大丈夫か判断できます
読むときのコツとして、インデント(行頭の字下げ)にも注目すると構造がつかみやすくなります
字下げされた箇条書きは、上の項目のさらに細かい中身、という入れ子の関係を表しています
ここが半端にずれていると階層を取り違えやすいので、直すときは字下げの幅をそろえておくと崩れにくくなります
「触るのはちょっと怖い」というときは、直し方をClaude自身に頼んでしまうのが早いです
ただし丸投げにはせず、書き込む前に直した内容を提示してもらうようにすると、意図しない変更を防げます
そのまま使える頼み方の例
この CLAUDE.md の「コーディング規約」に1項目足したいです
まず直した全文をここに出してから、私がOKしたら書き込んでください
ジャベ雄自信がないときは、直し方をClaudeに聞いてしまうのが早いです
マークダウンでよくある崩れとつまずき対処
最後に、初心者がつまずきやすい「崩れ」を、症状・原因・直し方でまとめておきます
ほとんどは記号のまわりを半角スペースで揃えると解決します
スクロールできます
| 症状 | よくある原因 | 直し方 |
|---|---|---|
| 改行が反映されない | 行末の半角スペース2個が消えた/単一改行として扱われた | 空行で段落を分ける・行末に半角スペース2個・<br> |
| リストのインデントがずれる | タブと半角スペースの混在・インデント量がバラバラ | 半角スペース2〜4個で揃える(揃えることが大事) |
| 記号がそのまま出る/消える | 記号が装飾として発動してしまう | 直前にバックスラッシュ \ でエスケープ |
| 見出しにならない | # の直後にスペースが無い | # の後に半角スペースを入れる |
| 記法が効かないことがある | 全角スペースが混ざっている | 半角スペースに打ち直す |
| コードに色が付かない | 言語名の指定漏れ | フェンスの後に言語名(色は環境しだい) |
| 表が崩れる | 縦棒と区切り行のずれ・列数の不一致 | 列数を揃える・区切り行を入れる |
いくつか補足します
行末の半角スペース2個は目に見えないうえ、エディタが保存時に勝手に消すことがあります
強制的に改行したいなら、行末にバックスラッシュ \ を置く方法もあります
改行が消えて困るときは、空行で段落を分けるか <br> を使うのが無難です
全角スペースは日本語入力あるあるの落とし穴です
マークダウンの記法は半角スペースを前提にしているので、# の後などに全角スペースが入ると認識されないことがあります
「なぜか効かない」ときは、いちど半角に打ち直してみてください
エスケープも覚えておくと便利です
たとえば商品名に付けたアスタリスクが2つ並ぶと太字の記号と解釈されたり、変数名の my_var_name に含まれるアンダースコアが斜体の合図とみなされて、途中が斜体に化けたりします
そのまま文字として出したいときは、記号の直前にバックスラッシュを1つ足すと、装飾が発動しなくなります
表がうまく出ないときは、直す前に貼り先がGFMに対応しているかをまず確かめてください
対応していれば、各行で縦棒の数をそろえて、見出しの下に区切り行を1本入れれば整います
列の中で縦棒そのものを文字として使いたいときは、その縦棒の前にもバックスラッシュを足すと、区切りと勘違いされずに済みます
ジャベ雄崩れの大半は、半角スペースで揃えると直ります
まとめ
マークダウンは、記号を少し添えるだけで構造を表せる書き方です
AIに指示を渡すときも、AIが書いたmdファイルを読むときも、同じ記法が土台になります
- まずは見出し・箇条書き・太字・リンクの基本記法から
- 表やタスクリストは GFM拡張=対応環境だけで効く
- AIに渡すときは見出しと箇条書きで構造を整理する
- 崩れたら半角スペースで揃える・プレビューで確認・迷ったらClaudeに直してもらう
設定まわりをもう少し知りたくなったら、Claudeデスクトップアプリの設定ガイドもあわせてどうぞ
ジャベ雄まずは見出しと箇条書きから、気楽に使ってみてください
最後に・・・
PythonとExcelを中心に仕事に役立つ業務ツールや自動化、スクレイピングツールの作成を受注していて、クラウドワークスでは気が付けば100件以上のお仕事を受注してきました！
会社員をやりながらの副業なので時間の捻出は相応ですが、クライアントの方々と近い立場でこちらからも提案しながら活動していますのでお悩みあれば是非ご相談ください
コメント