スタッフブログ

STAFF BLOG

アプリ開発日誌

2025.07.07

Markdown形式の設計書を見やすくする三つの工夫

設計書をMarkdown形式で書くメリットとデメリット

近年、生成AIを取り入れた開発プロセスが注目を集めています。それにともなって見直されつつあるのが、開発のためのドキュメント・設計書類をどのように作成するか、ということです。
というのも、生成AIに思い通りのコードを出力させるには、仕様や要件を細かく伝えることが必要不可欠だからです。AIエージェントが人間のように設計書を読み、その内容に沿って開発を進めることができれば、指示する人間の負担はぐっと少なくなります。
Markdown形式の設計書は、生成AIにとって解釈しやすいというメリットがあります。多くの生成AIは自然言語の処理には長けていますが、画像やバイナリを認識することは苦手です。専用のソフトやPDFを使った設計書よりも、MarkdownのほうがAIにとっては扱いやすい形式であると言えます。

一方、Markdown形式のドキュメントにはデメリットもあります。まず挙げられるのは、Excelなどを使ったドキュメントに比べて表現力が低く、読みづらいという点です。オフィスソフトでは図や表を自由に追加することができ、画像の貼り付けも容易ですが、Markdownの場合そうはいきません。また、Markdownそれ自体は単なるテキストですので、マークアップされた状態を確認したい場合には、なんらかの方法でプレビュー表示する必要があります。
そのような制約もあって、慣れるまでは読み書きがしづらく、短文を羅列しただけの読みづらい設計書になってしまいがちです。

しかし、いくつかの工夫をすれば、Markdownでも読みやすく使いやすいドキュメントを作ることは可能です。この記事では、Markdown形式のドキュメントをプロジェクトに取り入れるに当たって、必ず実践したい工夫ポイントを三つ紹介します。

工夫その1:Linterを導入する

Linterとは、主にプログラミングで用いられる解析ツールの総称です。プログラムの文法などから、間違った書き方や推奨されない書き方を検出し、指摘したり自動で修正したりできるというものです。
Markdownでも、このようなLinterがいくつか作られています。Markdownの文法に従って、誤りがあれば修正してくれるので、文法に慣れていない人でも書きやすくなります。また、プロジェクト独自のルールを設定することにより、ドキュメントによって微妙に書き方が違う、といった問題を減らすことにも繋がります。

もっとも広く使われているMarkdownのLinterがmarkdownlintです。CLIで実行可能なものや、VS Codeのようなテキストエディタのプラグインとして組み込まれているものなど、さまざまなツールが用意されているので、自分の使い方にあったものを選んで採用しましょう。

さらに進んで、日本語の文章そのものをLinterで校正するということもできます。たとえば、句読点の位置や半角・全角の使い分けなど、執筆した時期やメンバーによって微妙にドキュメントの書き方が異なるということが起こりがちですが、ツールを活用することで簡単に見た目を統一でき、品質の向上に繋がります。
文章校正のためのLinterとして代表的なものがtextlintです。日本語の校正に役立つルールがこちらにまとまっているので、必要と思われるものを導入してください。

以下は、実際に導入した場合の例です。今回はVS CodeのプラグインをCursor上で使用しています。

ルールに沿っていない書き方をしているファイルには、このような形で警告が表示されます。コミット前に確認することで、細かいレビューをしなくても機械的にチェックができます。

工夫その2:図や画像、リンクを挿入する

Markdownの設計書を便利で読みやすいものにするため、ファイル間のリンクを効果的に使うとよいでしょう。Markdownでは、以下のように書くことで簡単にリンクを作成することができます。

[リンクを設定したい文字列](./リンク先のファイル.md)

たとえば、画面設計書をそれぞれの画面ごとに作成した後、目次となる設計書からまとめてリンクしたり、設計書の中の重要なキーワード(機能名やAPI名)から対応する設計書にジャンプさせたり、といった使い方が考えられます。

図や画像を挿入することも効果的です。リンクの構文の先頭に「!」をつけると、文書内に埋め込む形で表示させることができます。

![画像の代替テキスト](./画像ファイル.png)

しかし、このように画像を用意してリンクを貼るのは少し面倒です。もっと便利な方法はないのでしょうか?
あなたがVS Codeを使っているなら、Shiftキーを押しながら画像をドラッグ&ドロップすることで、Markdownファイルの任意の場所に画像を埋め込むことができます。画像ファイル自体もプロジェクト内にコピーされるので、用意したファイルをどんどん貼り付けていくことが可能です。ファイルの格納場所は、VS Codeの設定にあるmarkdown.copyFiles.destinationという項目で指定できます。

MermaidPlantUMLを使って図を作成し、ドキュメントに埋め込むことも選択肢のひとつです。この場合、あらかじめ画像ファイルを準備しなくても、文書内にコードを記述することでフローチャートやダイアグラムを作成できます。
ただし、これはMarkdownの標準機能ではありません。GitHubObsidianなど、プラットフォーム側でMermaid記法をサポートしているケースもありますが、それ以外の多くのケース(たとえば後述するように、静的サイトジェネレーターを利用するケースなど)では、図を描画するためのプラグイン導入が別途必要です。

また、図や画像をふんだんに使ったドキュメントは、生成AIにとっては理解しづらいものになる点も注意してください。最近ではマルチモーダル機能で画像を解釈できるAIも増えていますが、自然言語のテキストと比べれば速度・精度ともに劣ります。AIフレンドリーなドキュメントを目指す場合、ロジックや設計の詳細はできるだけ文章で表現したほうがよいでしょう。

工夫その3:静的サイト化してブラウザで閲覧する

Markdown形式のドキュメントの欠点は、ソース単体では装飾がなく読みづらいことです。これはMarkdownが「構造と表現の分離」という原則に忠実であるためですが、プレビューのための環境を毎回整えるのは大変で、とくに非エンジニアのメンバーにとっては負担が大きい場合もあるでしょう。GitHubなどを利用しているなら、ブラウザでリポジトリを開くだけでもそれなりにリッチな体験が得られるものの、そうでないなら工夫が必要です。

ここでは、静的サイトジェネレーターでドキュメントをサイト化し、社内向けに公開するというユースケースを考えてみます。Markdownをサイト化するツールとしては、以下が代表的です。

HonKit

これはGitBookというツールをフォークして作られたもので、Markdownで書かれたドキュメントをHTMLに変換し、閲覧できるようにするツールです。JavaScriptで作られています。自由度はあまり高くありませんが、Markdownを閲覧する手段としては十分でしょう。

MkDocs

こちらも同様のツールで、機能的にはHonKitなどと大きく変わりません。こちらはサイトの構成をYAMLファイルで設定できることと、Python製であることが主な違いです。Pythonを利用しているプロジェクトであれば、こちらのほうが便利だと思います。

mdBook

やはり同様のツールで、Rustで作られています。大きな特徴は、Rustのコードを文書内に埋め込み、ブラウザ上で実行できることです。Rustを使うプロジェクトであれば、サンプルコードをドキュメントに記載しておき、その場で動作を確認するような使い方ができます。

Docsify

静的サイトを生成するという点では上記のツールと変わりませんが、上記がMarkdownファイルをそれぞれHTMLファイルに変換するのに対し、こちらはひとつのHTMLファイルでMarkdownファイルの中身を読み込み、SPAのように表示します。HTMLファイルを追加するだけで簡単にサイト化できるので、既存のプロジェクトに後から導入する場合には便利です。

まとめ

  • 生成AIを活用するためには、AIが読みやすい形式でドキュメントを用意することが重要
  • しかしAIに配慮した結果、人間にとって使いづらいドキュメントになってしまっては意味がない
  • Markdown形式のドキュメントでも可用性や利便性を損なわないように工夫しよう
BACK

お問合せ

イーディーエーに興味をお持ちいただいて
ありがとうございます!
スマホアプリに関するご相談、
お見積りや弊社へのご質問など、
お気軽にお問い合わせください。
担当者より折り返しご連絡させていただきます。

    お名前必須
    会社名
    メールアドレス必須
    電話番号必須
    お問合わせ種別必須
    お問合わせ内容必須

    アンケートにご協力ください。
    弊社サイトへはどのようにしてアクセスされましたか?

    個人情報のお取扱いに関する同意事項

    1.事業者の氏名又は名称

    株式会社イーディーエー

    2.個人情報保護管理者の氏名又は職名、所属及び連絡先

    個人情報保護管理者 小宮 保人
    Mail:[email protected]

    3.取得した個人情報の利用目的

    当フォームで取得した個人情報は、お問い合わせに関する回答のために利用し、目的外利用はいたしません。

    4.弊社が取得した個人情報の第三者への委託、提供について

    弊社は、ご本人に関する情報をご本人の同意なしに第三者に委託または提供することはありません。

    5.個人情報保護のための安全管理

    弊社は、ご本人の個人情報を保護するための規程類を定め、従業者全員に周知・徹底と啓発・教育を図るとともに、その遵守状況の監査を定期的に実施いたします。
    また、ご本人の個人情報を保護するために必要な安全管理措置の維持・向上に努めてまいります。

    6.個人情報の開示・訂正・利用停止等の手続

    ご本人が、弊社が保有するご自身の個人情報の、利用目的の通知、開示、内容の訂正、追加又は削除、利用の停止、消去及び第三者への提供の停止を求める場合には、下記に連絡を頂くことで、対応致します。

    株式会社イーディーエー 個人情報お問合せ窓口
    〒106-0032 東京都港区六本木7丁目14番23 ラウンドクロス六本木4F
    TEL:03-5422-7524 FAX:03-5422-7534
    Mail:[email protected]

    7.ご提供いただく情報の任意性

    個人情報のご提供は任意ですが、同意を頂けない場合には、第3項にあります利用目的が達成できない事をご了承いただくこととなります。

    8.弊社Webサイトの運営について

    弊社サイトでは、ご本人が弊社Webサイトを再度訪問されたときなどに、より便利に閲覧して頂けるよう「クッキー(Cookie)」という技術を使用することがあります。これは、ご本人のコンピュータが弊社Webサイトのどのページに訪れたかを記録しますが、ご本人が弊社Webサイトにおいてご自身の個人情報を入力されない限りご本人ご自身を特定、識別することはできません。
    クッキーの使用を希望されない場合は、ご本人のブラウザの設定を変更することにより、クッキーの使用を拒否することができます。その場合、一部または全部のサービスがご利用できなくなることがあります。