設計書はマークダウンかHTMLかエクセルか
はい、どうもこんにちは佐藤です！
混沌とした第二の故郷 X で、「設計書を書くなら何が良いのか」という話が上がっていました。
markdown か。HTML か。それとも、あの Excel か。
銀行案件で方眼紙の設計書を延々と書いてきて、今は AI にコードを書かせている私なら、答えは決まっているように見えますよね。
そりゃ、AI 時代に設計書を書くなら markdown か HTML でしょ！
……と、なるんですけどね。
そんなに単純な話ではないんですよ。
先に結論を言っておきます。形式に唯一の正解はありません。 決めるのは「誰が読むのか」です。そして読み手には、とうとう AI が入ってきました。
そのあたりを書いていきますね！
「AI 時代だから markdown」で話は終わらない
markdown 推しの理由はシンプルですよね。プレーンテキストだから diff が出る。git で履歴が追える。AI がそのまま読んで、そのままコードに落としてくれる。
反論しづらい。実際、私もこのブログの記事は markdown で書いています。
でも、形式を markdown に変えた瞬間にドキュメントが良くなるかというと、そんなことはありません。形式は 4 つの軸で評価されるべきもので、AI が読めるかどうかはそのうちの 1 つでしかないのです。
その 4 つとは、こういうものです。
- テンプレート：どこに何を書くかが決まっているか
- 編集性：その場でさっと直せるか
- AI の可読性：機械がそのまま読めるか
- 到達性：チームメンバーと顧客が触れるか
順番に見ていきましょう。
そもそも、テンプレートがないとどの形式でも破綻する
markdown や HTML なら、H1・H2 の見出し、引用、コードブロックを自由に出し分けられて表現力が高い。よく言われる話です。
でもこの「自由」が曲者でしてね。
構造化したロジックツリーで文章を書ける人は、ごくわずかなんです。
白紙の .md を渡すとどうなるか、想像してみてください。見出しが「概要」と「詳細」の 2 つしかない。詳細の下に 3000 字が改行なしで詰まっている。誰かが後から書き足した章が末尾にぶら下がっている。段落番号がない。……見たことありませんか？
私はあります。しかも自分で書いていました。
一方、方眼紙の設計書には少なくとも「画面 ID」「項目名」「桁数」「必須／任意」の欄がありました。埋めるべき箱が最初から見えているのです。あれが本当に強かったのは、Excel だからではなく、テンプレートだったからです。
だから議論の順番はこうなります。形式を決める前に、テンプレートを決める。どこに何が書いてあるのかが分からない設計書は、markdown でも HTML でも等しく悲惨になります。
HTML は綺麗だけど、打ち合わせ中に直せない
次は編集性です。
HTML は表現力で言えば最強クラス。図も表もアンカーリンクも思いのまま。AI に書かせれば、それなりに整ったページが数分で出てきます。
でも、こう考えてみてください。
顧客との仕様調整中に、その綺麗なレイアウトをクリックして、さっとメモを取れますか？
無理ですよね。開くのはブラウザで、直すのはエディタです。「じゃあ AI に直させれば」と思うかもしれませんが、打ち合わせのテンポで走る微修正には、まだ即効性が足りません。「この項目、桁数 10 じゃなくて 12 で」と言われた 3 秒後に反映されている必要があるのです。
ここは Excel が圧倒的に強い。セルをクリックして、打つ。それだけ。方眼紙が滅びなかった理由の 1 つは、間違いなくこの編集性です。
markdown はその中間でしょうか。テキストなので直すのは速い。ただし整形済みのプレビューを見ながら直すには、それなりのツールが要ります。
エクセルは、AI にとって読みにくい
そして、いま一番注目されている軸。AI が読めるか。
ここは markdown と HTML に軍配が上がります。どちらも構造がテキストとして表に出ているので、そのまま読ませれば意味が取れますよね。
問題は Excel です。というより、Excel 方眼紙の巣窟が問題なのです。
- セル結合で、項目と値の対応が座標に埋まっている
- 印刷範囲やシート分割に、意味のある区切りが隠れている
- 説明の本文がテキストではなく、図形オブジェクトの中に入っている
人間は目で見て「ここが表題で、ここが値だな」と補完できます。でも機械にとっては、座標と結合情報から意味を再構築する作業になるのです。読めないわけではありません。読ませるためのコストが高いのです。
AI をチームの一員として数えるなら、この 1 点だけで Excel は不利になります。
一番の壁は、チームと顧客が触れるかどうか
さて、ここまでの 3 軸だと markdown が優勢に見えます。でも、最後の軸で話がひっくり返るんですよ。
チームメンバーと顧客が、その形式に触れるか。
技術に前のめりでないメンバーに markdown を覚えさせるのは、思っているより難しい。「見出しはシャープ、強調はアスタリスク 2 つ」と説明した次の週には、全角スペースでインデントされた文書が上がってきます。
顧客はもっと厳しいでしょう。markdown を読めるか。読めるツールが手元にあるか。メールに添付して開けるか。 現場によっては、そこが決定打になりますよね。
そして最後の砦。「ソースコードを設計書のように書けばいい」という考え方があります。命名を揃え、ファイル構成を仕様書のようにし、型で制約を表現して、ADR を残す。私はこの方向が好きですし、実際に効きます。
ただし、読めるのはエンジニアだけです。
設計書は自分のために書くものではありません。読む人がいるから書くのです。そこを忘れると、technically correct で誰も読まないドキュメントができあがります。
ステークホルダーに AI が加わった。だから状況で決める
4 つの軸を並べると、こういう構図になります。
| 軸 | Markdown | HTML | Excel |
|---|---|---|---|
| テンプレート | 自分で用意する必要あり | 自分で用意する必要あり | 元から箱がある |
| 編集性 | 速い | 遅い | 最速 |
| AI の可読性 | 高い | 高い | 低い |
| 到達性（顧客・非エンジニア） | 微妙 | 高い | 高い |
きれいに勝つ形式が 1 つもないんですよね。
で、ここが今回いちばん言いたいところです。
誰がステークホルダーなのか、その範囲が AI にまで拡張されました。 でも、「ステークホルダーを満足させる」という考え方そのものは、1 ミリも変わっていません。
読み手が顧客なら、顧客が開ける形式にする。読み手が実装する AI なら、AI が読める形式にする。読み手が 3 年後の自分なら、diff が追える形式にする。それだけの話なのです。
だから結論は、状況を見て対応しよう。
歯切れが悪いと思いましたか？ そんなことはありません。「markdown 一択」と言い切るほうが、実は考えていないのです。
そして、もう 1 つ。
変換やツールを作るのも良いよね、というところに落ち着きます。正となる 1 つを持って、相手に合わせて出し分ける。markdown を正にして、顧客には HTML や PDF で出す。集計が要るところだけ Excel に吐く。
このブログ自体、Obsidian の markdown を正にして、変換ツールを 1 本流して Astro のサイトに変えています。形式を 1 つに決めきれないなら、決めきらなくていい仕組みを作ればいいんですよ。
しかも今は、その変換ツールを書くのが一番得意なのが AI です。以前なら「そんなツールを作る工数がない」で終わっていた話が、半日で片付きます。形式論争のコストが下がった、と言ってもいいでしょう。
まとめ
というわけで、設計書の形式に正解はないよ！って話でした！
あ。正確には、読む人に合わせて出し分ける工夫をしよう って感じですねっ。
markdown か HTML か Excel かは、宗教戦争ではありません。テンプレートがあるか、その場で直せるか、AI が読めるか、相手に届くか。この 4 つを、案件ごとに測り直すだけの話です。ステークホルダーに AI が加わったぶん、測る項目が 1 つ増えた。変わったのはそこだけなのです。
そして、どうしても 1 つに決まらないときは、変換で逃げましょう。正を 1 つ決めて、あとは機械にやらせる。ぜひみなさんも、自分の現場のステークホルダーを数え直してみてください！