Claude Codeを使うなら知っておきたい「Markdown」の話

この記事の内容をスライドにまとめました。ビジュアルで先に把握したい方はこちらからどうぞ。

👉 スライドで見る（← → キーまたはスワイプで操作できます）

Claude Codeとやり取りしていると、返ってくる説明文にこんな記号が並んでいるのを見たことはありませんか？

## 変更点

- ログイン機能を追加しました
- **バリデーション処理**を強化しました

詳しくは `src/auth.ts` を確認してください。

「#とか**とか、なんだこの記号だらけの文章は」と、気にせずスルーしている方も多いと思います。これは**マークダウン（Markdown）**という記法で書かれた文章です。

Claude Codeが出力する説明文だけでなく、AIが作ったり編集したりするファイル（README・ドキュメント・作業メモなど）の多くも、このマークダウンで書かれています。読み方と書き方の基本さえ知っておけば、AIの出力が今よりずっと読みやすくなりますし、自分でメモやドキュメントを書くときにも使えます。

この記事では、「マークダウンって見たことはあるけど、ちゃんと分かってない」という方に向けて、基本の記法をまとめます。

マークダウンとは？ ── 記号だけで文章を構造化する記法

マークダウンを一言で言うと、プレーンテキスト（装飾のない、ただの文字だけのファイル）に、いくつかの記号のルールを添えるだけで、見出しや箇条書きといった文章の構造を表現できる軽量な記法です。

Wordのように「太字ボタンを押す」「見出しスタイルを選ぶ」といった操作はいりません。キーボードだけで、#や-や*といった記号を決まったルールで並べていくだけで、文章の骨組みが出来上がります。

装飾情報を持たないシンプルなテキストなので、AIにとっても人間にとっても読み書きしやすく、ChatGPTやClaudeのようなAIとのやり取りでは、返ってくる文章がだいたいこのマークダウン形式になっています。

それでは、実際によく使う記法を一つずつ見ていきましょう。

基本の記法7つ

1. 見出し ── #の数で階層を表す

# 大見出し
## 中見出し
### 小見出し

行頭に#を1〜3個（もっと増やすことも可能）つけると見出しになります。#の数が増えるほど、階層が一段深くなります。本のタイトル・章・節のような親子関係を、記号の数だけで表現できるイメージです。

2. 箇条書き ── -や数字でリストを作る

- タスクA
- タスクB

1. 最初にやること
2. 次にやること

行頭に-（ハイフンの代わりに*でも可）をつけると、順序を問わない箇条書きになります。1. 2.のように数字とピリオドをつけると、順序つきのリストになります。

3. 強調 ── **太字**と*斜体*

これは**太字**、これは*斜体*です。

文字を**（アスタリスク2つ）で挟むと太字に、*（1つ）で挟むと斜体になります。「ここだけ強調したい」というときに使う記号です。

4. リンク ── [表示テキスト](URL)

[keyaki-labs公式サイト](https://www.keyaki-labs.com)

[ ]の中に画面に表示したい文字を、続く( )の中にリンク先のURLを書きます。「文字をクリックすると別のページに飛ぶ」あの見た目を、記号だけで作れます。

5. コード ── `インライン`とコードブロック

文中で `git commit` のようにコマンド名を示したいときは、バッククォート1つで挟みます。

複数行のコードをまとめて示したいときは、バッククォート3つで前後を挟みます。

短い単語をコードとして目立たせたいときはバッククォート（`）1つで挟み、複数行のコードやコマンドをまとめて示したいときはバッククォート3つ（```）で前後を囲みます。この記事の冒頭の例も、この書き方でコードブロックにしています。

6. 引用 ── >

> これは引用文です。

行頭に>をつけると、その行が引用として一段字下げ・区別して表示されます。他の文章やメッセージを引用するときに使います。

7. 区切り線 ── ---

---

-を3つ並べるだけの行は、水平線（区切り線）になります。話題を切り替えたいときの、ちょっとした仕切りとして使われます。

まとめ

覚えることはこれだけです。Claude Codeが吐き出す文章やファイルの中にこれらの記号を見つけたら、「ああ、ここは見出しなんだな」「これは強調したい部分なんだな」と読み解けるようになります。

気軽に試すなら、実はGoogle Docsでもいい

「専用のエディタを用意しないと使えないんでしょ？」と思われがちですが、実はGoogle Docsも入力中にマークダウン記法を認識してくれます。

# に続けて文字を打つと自動で見出しスタイルに、* や- から書き始めると自動で箇条書きに、**太字**と打つとそのまま太字に変換される、といった具合です。普段からGoogle Docsを使っている方であれば、新しいツールを何も入れずに、今日の入力からこの記法の感覚を試すことができます。

それでも、この記法には気になっていることがある

ここまで紹介してきたように、マークダウンは記号だけで文章の構造を表現できる、とても軽量な記法です。プレーンテキストで無駄な装飾がなく、見出しや箇条書きで綺麗に構造化できる。だからこそAIにとって探索しやすく、読み書きしやすいフォーマットになっていて、最近のAIエージェント（ターミナルから「ここをこう直しておいて」と一言指示するだけで、AIが自律的にファイルを探索し、中身を読み解いて編集してくれるようなツール群）も、裏側では大量のマークダウンファイルをやり取りしています。

──しかし。

そんな便利なマークダウンにも、ひとつだけ気になっていることがあります。それは、「人間が全体を俯瞰したい時」には、あまり向いていない、ということです。

人間がファイルを自分で開きたくなる、たった1種類のシーン

日々の実作業はAIに任せきりでいい。それでも「ちょっとファイルを開いて、直接見たい」と手を伸ばしたくなるのには、明確な理由があります。

それは、「アイデアを整理したい時」——自分の頭の中にあるモヤモヤした思考を一旦吐き出して整理したいとき、あるいはAIが出してくれた大量のアウトプットを一歩引いて全体像を確認したいとき。

このシーンだけは、AIに頼らず、自分の目と頭で直接ドキュメントと向き合いたくなる。

視覚的に、網羅的に情報を掴みたいという感覚は、どうしても捨てられないんですよね。

「マークダウンは、人間が俯瞰するには優しくない」という矛盾

そこで向き合うことになるのが、先ほど基本の記法を見てきた「マークダウン」です。

ここに、ちょっとした矛盾があります。

マークダウンはAIにとって最強のフォーマットですが、「人間が俯瞰してアイデアを整理したい時」には、決して直感的ではないんです。

構造化されているとはいえ、マークダウンは結局、上から下へと流れる「縦長のテキストファイル」です。

文字がずらりと並んだドキュメントをスクロールしながら、「ええと、ここの見出しと、さっきの見出しの親子関係は……」と頭の中で全体像を組み立てるのには、想像以上に認知的負荷がかかります。

「全体を見渡しながら、新しい切り口を見つけたい」

そう思ってファイルを開いたのに、目の前にあるのはただの縦長の文字情報。これでは、なかなかクリエイティブに動き出せない。

裏はマークダウン、表はマインドマップ

AIにとっては最強の共通言語だけど、人間が俯瞰するにはちょっと不親切。 このギャップをどう埋めればいいのか。

私がたどり着いた答えはシンプルです。

AIが読み書きするマークダウンはそのままに、人間が見たり編集したりする時だけ、マインドマップのようなビジュアルで触れる環境があればいい。

マークダウンが持つ「見出し」の階層構造を、そのまま2次元のビジュアル（ノード）に変換するのです。

AIは裏側でマークダウンを高速で探索・書き換え、人間は表側でマインドマップをぐりぐり動かしながら直感的に全体を俯瞰し、アイデアをシャッフルする。

AIに任せながらも、人間が「考えること」に集中できる環境。それが、今の自分が思うAIとのちょうどいい付き合い方です。

実際に、こういう形で試してみている

この「裏はマークダウン、表はマインドマップ」という考え方を、自分は手元のツールとして一つ形にしてみています。Martenというノートアプリで、GitHubのリポジトリをそのままノートの置き場にするMarkdownエディタに、マインドマップ表示を標準で持たせたものです。

やっていることは、この記事で書いてきた考え方をそのまま実装しただけです。

• フォルダ・ファイル・見出しが、そのままノードになります（# の数がそのまま階層の深さになります）
• 元のファイルはただのMarkdownのまま。マインドマップ用の独自形式に変換したりはしません
• つないだリポジトリ全体・フォルダ単位・1ファイル単位で、見たい範囲を切り替えられます

逆に言うと、ノードになるのは見出しまでです。箇条書きの中身までは展開しません。「章立ての全体像を掴む」ための道具だと思ってもらうのが近いです。

実際の画面は動画にまとめているので、興味があればこちらものぞいてみてください。

→ 【GitHub×ノート術】GitHubを、そのままノートアプリにする｜Martenの機能を画面で全部見せます（YouTube）

今、こういう問題意識に共感してくれる方向けに早期登録を受け付けていて、簡単なアンケートに答えるとPremium機能が永年無料になる特典もあります（9月20日まで）。あくまで一例として、こんな形で向き合っている人もいる、くらいの気持ちで見てもらえたら嬉しいです。