.mdという拡張子は、あちこちにある
CLAUDE.md、README、GitHubのissue（課題を書き留める場所）やプルリクエストの説明欄、そしてこのサイトの記事そのもの。エージェントと開発をする場では、.mdという拡張子のファイルがやたらと登場します。正体は全部同じで、Markdown（マークダウン）という書式で書かれたプレーンテキスト——飾りのない、文字だけのファイルです。
Markdownは、誰が何のために作ったのか
Markdownは、2004年にJohn Gruberが公開した書式です。設計の目標を、本人はこう説明しています。
“The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible.”
（Markdownの書式が目指した最大の設計目標は、できる限り読みやすくすること）
もう少し具体的に言うと、タグだらけのHTMLに見えず、そのままプレーンテキストとして読める・公開できることを目指した書式です。HTMLで<strong>強調</strong>と書くところを、Markdownなら**強調**と書くだけで済みます。記号は最小限、読みやすさは最大限、という発想です。
Markdownの基本の記法
覚えることは多くありません。よく使うものだけ挙げます。
| 書きたいもの | 書き方 | 見た目 |
|---|---|---|
| 見出し | ## 見出し |
大きな文字の見出し |
| 太字 | **強調** |
強調 |
| 箇条書き | - 項目 |
・項目 |
| 番号つきリスト | 1. 項目 |
1. 項目 |
| リンク | [表示名](URL) |
表示名（クリックできるリンク） |
| コード（1行） | `code` |
code（等幅フォント） |
| コードブロック | ``` で前後を囲む |
複数行のコードをそのまま表示 |
| 表 | | A | B | |
表組み |
| 引用 | > 引用文 |
字下げされた引用 |
見た目を整える記号を、そのまま丸暗記する必要はありません。#は見出し、*は強調やリスト、`はコード——この3種類の記号の役割さえ押さえておけば、たいていのMarkdownは読めます。
なぜMarkdownが、エージェント時代にこれほど使われているのか
理由は単純です。文字だけのファイル（プレーンテキスト）だから、エージェントが読み書きしやすい。 画像や複雑なレイアウトを持つWordファイルと違い、Markdownはただの文字の並びです。エージェントにとっては、読むのも書くのも、他の文章と変わらない扱いでできます。
Gitの基本的な使い方とも相性がいい。変更を「差分」として管理する仕組みなので、1行ごとの変更を追いやすいプレーンテキストのほうが向いています。
チャットでのエージェントの返答も、たいていMarkdownで返ってきます。見出しや箇条書き、太字が使われた読みやすい返答は、裏側でMarkdownとして生成され、表示側で変換されているものです。
同じ.mdでも、中身の役割は違う
.mdだからといって、中身の目的は一様ではありません。
CLAUDE.md——人間が書く、エージェントへの指示書。下で説明するfrontmatterは使わず、鉄則を書き並べる形が多い- README——リポジトリを作るときに添えられる説明書。何のプロジェクトか、使い方はどうか、を書く定番の置き場所
- このサイトの記事——冒頭にYAML形式のfrontmatter（
titleやcategoryのような設定）をつけたMarkdown。同じ.mdでも、冒頭にこの一区画があるかないかで、用途がだいぶ変わります。YAMLについては、また別の記事で扱います
記号がそのまま見えてしまうのは、変換する側がいないとき
Markdownは変換されて初めて見た目が整う書式です。GitHubやこのサイトのようにMarkdownを解釈する場所で見れば、## 見出しはちゃんと大きな見出しになります。ただしcatでターミナルにそのまま出したり、対応していないメモ帳で開いたりすると、#や**の記号がそのまま文字として残ります。
エージェントとのやり取りでも同じです。環境によって記号がそのまま表示されることもあれば、太字やリストとして整形されて見えることもあります。「記号が見えるのは壊れているからではなく、変換する側がいないだけ」と知っておくと、慌てずに済みます。
日本語の強調で、このサイトが踏んだ罠
一見単純な書式ですが、日本語で書いていると踏みやすい罠が1つあります。強調にした語句を、鉤括弧（「」）でくくったときです。
✗ 最上位は**「難所で出す切り札」**です。
○ 最上位は「**難所で出す切り札**」です。上の書き方だと、太字として変換されず、**という記号がそのまま画面に残ります。 CommonMark——Markdownの曖昧さを解消するために2014年に作られた仕様——のルール上、**の直後に「のような約物（句読点や括弧などの記号）が来ると、強調の開始とみなされない場合があるためです。開くカッコの外に**を置かず、カッコの内側に強調を収める書き方に変えると解決します。
このサイトでは何度もこれを踏んだので、最終的にサイト側で自動的に太字へ直す仕組みを用意しました。Markdownを変換する部分にプラグインを足して、取り残された**を強調に変換しています。
ただし、これはこのサイトだけの対策です。GitHubやObsidian、他のツールで同じファイルを開けば、**はそのまま出ます。 どこで読まれても大丈夫なようにしたいなら、やはりカッコの内側に**を収めるのが確実です。
まとめ
.mdは全部同じ書式（Markdown）。ただし中身の役割はファイルごとに違う- 目標は「プレーンテキストのまま読める・書ける」こと。記号は最小限
#（見出し）・*（強調・リスト）・`（コード）の3種類を覚えれば、たいてい読める- エージェント時代に広まったのは、プレーンテキストだから機械にも扱いやすいという理由が大きい
- 日本語の強調（
**「〜」**）には、太字に変換されない罠がある。カッコの内側に**を収めると安全