マークダウン、読みにくくないですか ― AIにHTMLへ直してもらう話

会社で技術共有の場がありました。

先輩の発表を聞いていて、ひとつだけ強く引っかかったものがあります。気になりすぎて、発表が終わったあとに個人的に聞きに行きました。

それが、マークダウンをAIにHTMLへ直してもらって読むという使い方でした。

補足

前回、skillとやらを作成してみたという記事を書きました。AIへの指示を、マークダウンのファイルにして置いておく話です。今回はその「書いたものを、どうやって読むか」の話になります。

マークダウンって、人間には読みにくい

CLAUDE.md もスキルも、中身はマークダウンです。AIに指示を出すファイルは、だいたいマークダウンで書きます。

AIにとっては読みやすい形式なのだと思います。構造が記号ではっきり決まっているので、機械には扱いやすい。

ただ、書いた自分が読み返すときは、けっこうつらい。

書いているときは頭に入っているので気づきません。困るのは数日後です。「あれ、ここ何を書いたんだっけ」と開いた瞬間に、目が滑ります。

同じ内容でも、ソースのままと、ブラウザで開いたときとでは読む体力がまるで違う

引っかかるところは、いくつもありました。

見出しの階層がつかめない — # と ## と ### が記号で並んでいるだけなので、どこが大見出しでどこが子なのかが一目でわからない。長いファイルほど迷子になる
記号が目に入ってくる — ** や - や ` が文章に混ざっていて、中身を読む前に記号を読み飛ばす作業が挟まる
全体がのっぺら — 強弱がないので、大事なところもそうでないところも同じ重みに見える。上から順に全部読むしかない
表が読めない — パイプとハイフンで組まれた表は、ソースのままだと列がどこに揃っているのか見えない

どれも「読めない」わけではありません。読めるけれど、読むのに体力を使う。その積み重ねが、地味にしんどい。

先輩に教わったやり方は、拍子抜けするほど単純でした。

そのマークダウンをAIに渡して、「HTMLにして」と頼むだけ。

新しいツールを入れるわけでも、変換用のコマンドを覚えるわけでもありません。普段AIに話しかけているのと同じ場所で、同じように頼むだけです。

テキスト

このファイルをHTMLにして

これで .html のファイルが出てきます。

注意

CLAUDE.md やスキルには、仕事の内容が書かれていることがあります。外部のサービスに渡す前に、人に見せて困るものが混ざっていないか確認しておくと安心です。

できたHTMLを、ブラウザで開きました。

全然違いました。

見出しは大きさで階層がわかる。記号は消えて、太字は太字として見える。表は列が揃って見える。さっきまで目が滑っていたものが、上から普通に読めます。

書いてある内容は同じです。見え方が変わっただけで、読むのに使う体力がまるで違う。

ポイント

マークダウンはもともと「HTMLに変換されて読まれる」ことを前提にした書き方です。言われてみれば当たり前なのですが、AIへの指示ファイルはずっとソースのまま読んでいました。

これが一番ありがたかったところです。

前回の記事で書いたとおり、いま私は CLAUDE.md とスキルをマークダウンで書いています。AIに直してもらいながら育てていくので、中身がどんどん変わります。

変わるということは、そのたびに読み返すということです。

この確認を毎回ソースのままやっていました。それをHTMLにして読むようにしたら、認知負荷がはっきり下がりました。

書くのはマークダウン、読むのはHTML。役割を分けるだけでよかった。

AIの使い方というと、何かを作ってもらうとか、調べてもらうとか、そういう方向ばかり考えていました。

でもこれは、自分が読みやすくするために使うという発想です。文章の中身を新しく考えてもらったわけではありません。同じものの見せ方を変えてもらっているだけ。

そんな頼み方もあるのか、と素直に感動しました。

発表を聞いただけでは「ふうん」で終わっていたかもしれません。気になって聞きに行ってよかったな、と思っています。