Sponsored
システム開発のドキュメントがExcelで管理されているプロジェクトを、けっこうな頻度で見かけます。
設計書、テーブル定義、API仕様。全部Excelのシートに詰め込まれている。
気持ちは分かります。 非エンジニアでも開けるし、表が作りやすい。 見た目が整えやすくて、何かと馴染み深い。
ただ、開発するうえでの扱いやすさは、Markdownには敵わないと思っています。
私はシステム開発のドキュメント類はMarkdownで書いてGit管理すべきだという立場です。
差分が追える
Markdownはテキストファイルなので、Gitでそのまま管理できます。
これだけで「誰が、いつ、何を変えたか」が追えるようになります。
Excelにも変更履歴機能はあります。 ただ、複数人で同時に触ると競合が起きやすい。 「設計書_最終版_v3_修正済_確認後.xlsx」みたいなファイルが増えていく。 どれが本当に最新か分からなくなる。
Gitで管理すれば、少なくとも「最新ファイル探し」に時間を使うことは減ります。
git diffを見れば「この仕様が変わった」「この行が追加された」が一目で確認できます。
コードのレビューと同じ感覚で、設計書の変更もレビューできます。
特に長期プロジェクトや複数人開発では、この差分追跡が後からかなり効いてきます。
開発者が更新しやすい
設計書は作って終わりではありません。
開発が進むにつれて仕様は変わります。 当初想定と違う動きが判明することもある。 後から例外パターンが出てくることもある。
そのたびに設計書を更新する必要があります。
問題は、ExcelやWordで管理していると、開発者が更新しにくいことです。
ツールを開く手間がある。 レイアウト崩れが気になる。 フォーマットを合わせるのが面倒。 OfficeライセンスがないPCでは開けない。
こういう細かい摩擦が積み重なって、設計書の更新が後回しになります。
結果として、設計書が実装と乖離したまま放置される。 ドキュメントの陳腐化は、こうして進みます。
Markdownなら、普段コードを書いているエディタで編集できます。 VSCodeでもCursorでも、テキストファイルとして普通に開けます。 コードを変更したついでに、設計書も同じコミットで更新できます。
「設計書を更新するためだけにExcelを開く」という小さな面倒がなくなります。
納品時はフォーマット変換できる
「クライアントにMarkdownで渡しても読めない」という話はあります。
それはそうです。
ただ、MarkdownはPDFやHTMLに変換するのが簡単です。
pandocを使えばコマンド一発でPDFが作れます。 GitHubやGitLabに置けばブラウザで綺麗にレンダリングされます。
つまり「開発中はMarkdownで管理して、納品時はPDFに変換して渡す」という運用ができます。
作業中の管理しやすさと、納品時の見た目を両立できます。
逆に、最初からExcelで書くと、後からMarkdownに移行するのは相当手間です。 最初の形式選択が、後になって響いてきます。
LLMが読みやすい
これが2026年現在で一番強い理由かもしれません。
AIを活用して開発する場面が増えました。
コードを書くだけでなく、設計書を参照しながら実装方針を相談したり、仕様を確認したりするシーンも当たり前になっています。
そのときに、設計書がMarkdownで書かれているかどうかで扱いやすさが全然変わります。
ExcelファイルをそのままLLMに渡すのは難しい。 PDFに変換してもテキスト抽出が完全でないことがある。 レイアウト情報が混じって読みにくい状態になりがち。
Markdownならプレーンテキストなのでそのまま読み込めます。
Claude CodeやCursorのようなAIコーディングツールは、リポジトリ内のMarkdownファイルを普通に参照できます。
設計書をコードと同じリポジトリに入れておくと、「この設計書に書いてある仕様をベースに実装して」という使い方が自然にできます。
Excelだとこれが難しい。
Redirecting to: /blogs/which-llm-is-best/
どのLLMを選ぶかという話もありますが、それ以前に「LLMが読めるドキュメント」になっているかどうかが、効率に直結します。
Sponsored
「表や図が作りにくい」への返し
Markdownでテーブルを書くのはExcelほど直感的ではないです。
ただ、最近のエディタはMarkdownのテーブル入力を補助する機能があります。 図についてはMermaidを使えばコードでER図やフローチャートを書けます。
GitHubもGitLabもMermaidのレンダリングに対応しています。
完全にExcelの代替にはならない部分もありますが、開発ドキュメントとして必要な表現力は十分あります。
「クライアントがExcelを指定してくる」への返し
「納品物はExcelで」と指定されることはあります。
ただ、「開発中はMarkdownで管理して、納品物としてExcelに変換する」という運用は可能です。
多少の手間はかかります。 それでも、開発中ずっとかかり続ける管理コストの方が長い目で見ると大きいです。
納品用の体裁を整える作業は、最後に寄せた方がいい。 開発中からずっとExcelの都合に合わせる必要はありません。
設計書はコードと同じリポジトリに入れる
最終的に言いたいのは、設計書とコードを同じ場所で管理するということです。
設計書が別のフォルダやストレージに分散していると、参照が面倒になります。
コードを開くついでに設計書を確認できる状態が、一番使いやすいです。
おわりに
設計書をMarkdownで管理すると、差分が追いやすくなります。 開発者も更新しやすくなります。 必要ならPDFやHTMLに変換できます。
そこに加えて、2026年現在はLLMとの相性がかなり大きいです。
新しいプロジェクトを始めるときに、設計書の管理形式は最初に決めておく方がいいです。
「とりあえずExcel」で始めると、後から変えるのはかなり手間です。
AIを活用した開発を考えているなら、Markdownを選んでおく方が後悔は少ないと思います。
Redirecting to: /blogs/markdown-cheat-sheet/
