Claude Codeを使うなら知っておきたい「Markdown」の話｜AIへの指示が通るようになる記号7つ

Claude Codeが書き出したファイルを開くと、シャープが並び、ハイフンがあり、アスタリスクが2つ重なっている。記号だらけなので読み飛ばしている人も多いと思います。これは Markdown（マークダウン） という書き方です。この回では、その記号の話をします。覚える記法は7つだけで、それ以外は出てきません。

覚えるマークダウンは、7つだけです

AIに文章やメモを書かせると、返ってくるものはほぼ必ずこの形です。逆に言えば、この7つを知っているかどうかで、AIの出力が「読めるもの」になるか「記号の羅列」のままかが決まります。

この動画で、できるようになること

見終わった時点でできるようになっているのは、次の5つです。

1. AIが書き出す記号だらけの文章が読める
2. その7つの記法を、自分でも書ける
3. ただの文字なのに、なぜ見た目が付くのか、その仕組みが分かる
4. AIへの指示を、マークダウンで組み立てて書ける
5. 思ったとおりに表示されないときに、自分で直せる

特に4つ目が、この回でいちばん持ち帰ってほしいところです。読めるようになる、という話だけではありません。書けるようになると、AIへの指示の通り方が変わります。

記号は、文章に付ける「意味のしるし」です

マークダウンを一言で言うと、文章に意味のしるしを付けるための記号のルールです。

ワードやGoogleドキュメントで文書を作るとき、見出しを付け、段落を分け、大事なところを太字にします。読む人に伝わりやすくするために、文章に構造を付けているわけです。マークダウンがやろうとしていることもまったく同じで、違うのはその構造をボタンではなく記号で表すという一点だけです。

行の先頭にシャープを1つ置くと「この1行は見出しですよ」という意味になる。ハイフンを置けば「この1行は箇条書きの1項目ですよ」という意味になる。ボタンで作った文書は見た目の情報を抱え込みますが、マークダウンのファイルは最後までただの文字のままです。

では、誰が見た目を付けているのか。表示する側のアプリです。 アプリが記号を読み取って、そう見せているだけで、ファイルの中身は1文字も変わっていません。

これが分かると、都合のいいことが2つあります。ただの文字なのでどこにでも持ち運べること。そして、AIも人間もまったく同じものを読んでいることです。AIが文章の構造を理解できるのは、この記号を目印にしているからです。

基本の記法、まず4つ

1. 見出し — 行の先頭にシャープを置き、半角スペースを1つ空けて文字を書きます。シャープ1つで大見出し、2つで中見出し、3つで小見出し。数が増えるほど一段深い階層になります。本のタイトル、大きな見出し、小さな見出し、という親子関係だと思ってください。

2. 箇条書き — 行の先頭にハイフンを置いて、半角スペースを1つ。これで点の付いたリストになります。順番に意味があるときは、ハイフンの代わりに 1. 2. と数字を使います。

3. 強調 — 太字にしたい部分をアスタリスク2つで前後から挟みます。アスタリスク1つで挟むと斜体になります。

4. コード — コマンド名やファイル名のように、そのまま打ってほしい文字はバッククォートで挟みます。まとめて示したいときは、バッククォート3つで上下を囲みます。

# 大見出し
## 中見出し
 
- 箇条書き
1. 順番のある箇条書き
 
**太字** と *斜体*
`ファイル名やコマンド`

残りの3つで、全部です

5. リンク — 角かっこの中に画面に出したい文字を書き、続けて丸かっこの中に飛び先のアドレスを書きます。順番は、文字が先、アドレスが後。 ここだけ覚えてください。

6. 引用 — 行の先頭に大なりの記号を1つ置き、半角スペースを空けて文字を書きます。他の人の文章や、前のやり取りを引くときに使います。

7. 区切り線 — ハイフンを3つだけ並べた1行は、横線になります。話題を変えるときの仕切りです。

これで7つ、全部です

改めて並べます。見出し・箇条書き・強調・コード・リンク・引用・区切り線。 この7つだけ覚えておけば足ります。AIが書き出す文章やファイルに出てくるのは、ほぼこの7つだけです。ここまで来れば、もう記号だらけには見えないはずです。

読むだけじゃない。AIへの指示が通るようになる

ここからが本題です。マークダウンは読むための知識だと思われがちですが、書く側に回ると、AIへの指示が通りやすくなります。

動画では、同じ内容の指示を2つ並べています。片方は、思いついたまま1つの文で書いた指示です。直してほしいファイルが2つあって、変更点も2つあって、さわってほしくないものまである。それが全部1本の文につながっています。これでも通ることは通りますが、どこまでが対象で、どこからが変更内容で、どれが禁止事項なのかを、読む側で切り分けるしかありません。人間が読んでも一度で頭に入らない指示は、AIも取りこぼします。

もう片方は、同じ内容をマークダウンで組み立て直したものです。「依頼」「対象」「変更する内容」「やらないこと」。見出しを4つ置いて、その下に箇条書きを並べただけです。内容は1文字も足していません。並べ替えて、見出しと箇条書きを付けただけです。 それでもAIから見たときの読み取りやすさは変わります。見出しがあると、どこが何の話かが記号の時点で分かるからです。

特に「やらないこと」のように、見落とすと困る条件は、独立した見出しにしておくと落ちにくくなります。

同じ考え方が CLAUDE.md というファイルにも使えます。AIに毎回読ませる前提で置いておくメモで、プロジェクトの決まりごとをここに書いておくと毎回説明しなくてよくなります。中身はただのマークダウンなので、見出しで区切っておけば必要なところだけ読まれます。これが正解だという話ではなく、一例として参考にしてもらえたらと思います。

思ったとおりに出ないとき、原因は3つ

1. 記号のあとの半角スペースが抜けている — シャープのすぐ後ろに文字を書くと見出しになりません。シャープという文字がそのまま出るだけです。ハイフンの箇条書きも同じで、あとに半角スペースが要ります。

2. 改行が反映されない — 2行に分けて書いたのに、表示すると1行につながってしまう。マークダウンの決まりで、改行1回は区切りとして扱われないためです。段落を分けたいときは、あいだに1行空けてください。途中で改行したいだけなら、その行の終わりに半角スペースを2つ置く方法もあります。

3. 記号が全角になっている — 日本語入力のまま打つと、シャープもアスタリスクも全角になります。見た目はよく似ていますが、まったく効きません。

半角スペース・1行あける・全角。 うまくいかないときは、この3つを疑ってください。

今日から試せる場所

専用のアプリを入れる必要はありません。

書き方を1つ覚えるだけで、置き場所を選ばなくなる、ということです。

私自身は、マークダウンを見出しごとにマインドマップとして見られるアプリを作っていて、それを普段使っています。右にマークダウンのファイルそのもの、左にその見出しをそのままマインドマップにしたものが並ぶ形です。

まずは1つ、シャープと半角スペースから打ってみるのがおすすめです。

今日できるようになったこと

記法は7つ。見出し、箇条書き、強調、コード、リンク、引用、区切り線。記号は、文章に意味のしるしを付けるためのもの。見た目を付けているのは、ファイルではなく表示する側のアプリでした。

そして、読むだけでなく書く側に回ると、AIへの指示の通り方が変わります。見出しと箇条書きで組み立て直すだけで、どこが依頼で、どこが前提かが伝わります。思ったとおりに出ないときは、半角スペース・1行あける・全角の3つを疑う。

7つで足ります

マークダウンは、覚えることが少ないわりに効く場面が多い書き方です。記号そのものが偉いわけではありません。AIと人間が、同じ文章を同じように読むための共通の目印だというだけです。だから、7つで足ります。