Markdown×LLMで実現する開発ドキュメントの提案
なぜ今、Markdownなのか
エンジニアの皆さん、こんにちは。
毎日のように更新される要件定義書やプロジェクト文書の作成に、頭を悩ませていませんか？
今、個人的に「Markdown + LLM」という新しいドキュメント作成手法に注目しています。この組み合わせは、以下のような悩みが一気に解決できる可能性を秘めていると考えています。
📝ドキュメント作成に時間がかかりすぎる
🔄 バージョン管理が面倒
👥 チームでの共同編集がスムーズにいかない
🤖 AIツールとの連携がうまくいかない
今回は、私のインフラエンジニアとしての実務経験も交えながら、この手法について解説していきます。
従来のExcelベースの文書作成の限界
多くの案件では、まだOfficeドキュメント（ExcelやWordやパワポ）でプロジェクトドキュメントを作成していると思います。確かにOfficeドキュメントには以下のような利点があります。
表やグラフの作成が簡単
関数を使った計算が可能
なじみがあり人が読みやすい形式
みんな使っている
でも、こんな経験ありませんか？
「最新の要件定義書を確認したいけど、『NEW_～』とか『新_～』とかあって、どのファイルが正しいものか分からない...」
「チームメンバーと同時編集していたら、変更内容が消えてしまった...」
「バイナリファイルだからGitでの管理に向いてない。差分をいちいちXMLにして比較するのもわかりずらい…」
「マクロでデータを読み込みたいけど、セル結合やセル改行を一度整形しないと…」
これらはExcelの典型的な限界です。特に、チーム開発やシステム間のデータ連携が当たり前となった今、この問題は自動化や効率化のボトルネックにすらなっています。
Markdownが解決する5つの課題
1. 圧倒的な軽量性
Markdownは単なるテキストファイル。そのため・・・
ファイルサイズが小さい（同じ内容のWordファイルの約1/10）
開くのが早い（起動時間はWordの約1/5）
バージョン管理が容易（Gitでの差分確認が可能）
2. 抜群の可読性
# プロジェクト概要
## 目的
このプロジェクトは...
## 要件
1. ユーザー認証機能
2. データ分析機能このように、装飾なしでも構造が分かりやすいのが特徴です。
マシンリーダブル（機械が読みやすい）でありながらヒューマンリーダブル（人間が読みやすい）でもあり、両方の良いとこどりをしたものがMarkdownとも言えます。
3. 出力形式の汎用性の高さ
Markdownの大きな強みの一つは、様々な形式に変換できる汎用性です。Pandocなどの変換ツールやVS Codeなどのエディタの拡張機能を活用することで、一度作成したMarkdown文書を多様な形式に書き出すことができます。例えば、Webサイトのコンテンツとして利用する場合はHTMLに変換し、印刷用の資料としてはPDFに、クライアントへの提出用としてはWord形式に、それぞれ変換することが可能です。
また、JiraやServiceNowなどのITマネジメントサービスでは、これらのツールが提供するMarkdown互換の記法を使って内容を転記することができます。
さらに、TeamsやSlackなどのチャットツールでも、各サービスがサポートするMarkdown記法の範囲内で、書式を保持したまま内容を共有できます。
Slackで、ペーストしたテキストの書式設定の反映が Ctrl-Shift-F でできることをメモ。https://t.co/bywPVuOUVj
— kenichiice (@kenichiice) April 22, 2021
このように、適切な変換ツールや受け手のサービスの機能を活用することで、一度作成した文書を様々な場面で効率的に展開することができます。
4. バージョン管理の容易さ
Markdownの重要な利点の一つは、テキストベースのフォーマットであることを活かした優れたバージョン管理機能です。
特にGitを使用することで、文書の変更履歴を簡単かつ詳細に追跡することができます。例えば、`git log`コマンドを使用すれば、誰がいつどのような変更を行ったのかを時系列で確認することができ、さらに`git diff`コマンドを使えば、特定のバージョン間での具体的な変更内容を文単位で比較することが可能です。
これは、バイナリファイル形式で保存されるWordなどの従来の文書形式では難しかった機能です。このように、Gitを活用することで、チームでの文書作成において誰がどの部分をいつ変更したのかを正確に把握でき、必要に応じて過去のバージョンに戻ることも容易です。これにより、文書の変更管理が格段に効率化され、チームでの共同作業がよりスムーズになります。
# Gitでの変更履歴確認
git log --pretty=format:"%h - %an, %ar : %s"
# 特定バージョンとの差分
git diff abc123 requirements.md5. チーム協業の効率化
Markdownとバージョン管理システムを組み合わせることで、チームでの文書作成作業が大幅に効率化されます。
例えば、GitHubやGitLabなどのプラットフォームでは、Pull Request機能を使って文書の変更内容を他のメンバーに提案し、レビューを受けることができます。レビュアーは変更された箇所を明確に把握でき、その部分に直接コメントを付けることができるため、具体的な議論や修正提案が可能です。
また、複数のメンバーが同じ文書を同時に編集した場合でも、テキストベースの特性を活かしてコンフリクト（競合）を検出し、どのように解決するかを視覚的に判断できます。
これは従来のバイナリ形式の文書では難しかった機能です。
このように、モダンなバージョン管理システムの機能を最大限に活用することで、チーム全体での文書管理や共同編集作業が、より透明で効率的なものとなります。
LLMとの相性の高さ
ここからが本題です。
Markdownの真価は、実はLLMとの組み合わせにあります。なぜなら…
1. 構造化された情報をAIが理解しやすい
Markdownの特徴の一つは、AIシステムとの親和性の高さです。
Markdownで作成された文書は、見出しレベルを`#`の数で明示的に示し、箇条書きも`-`や`*`で明確に構造化されているため、AIがテキストの階層構造や関係性を正確に理解しやすい形式となっています。
また、装飾や書式設定のための複雑なメタデータを含まないピュアなテキストベース形式であるため、AIによる解析が容易です。
さらに、文書の構造が一定のスキーマ（例：タイトル、見出し、本文、リストという階層構造）に従って記述されるため、AIはその規則性を活かして内容を適切に解釈し、処理することができます。
このような特性により、Markdown形式の文書は、AIによる自動処理、内容の分析、要約生成などのタスクにおいて、特に優れたパフォーマンスを発揮することができます。
2. 双方向の変換が可能
Markdownと生成AIを組み合わせることで、様々な形式の文書やコードの相互変換が実現可能です。
例えば、Markdown形式で書かれた詳細な要件定義書から、AIが実装用のプログラムコードを自動生成したり、逆にプログラムコードの内容をAIが解析して、その機能や仕様をMarkdown形式のドキュメントとして自動的に作成したりすることができます。
また、Markdownで記述された要件定義書を基に、AIがテストケースを網羅的に洗い出してテスト仕様書を生成したり、プロジェクトの作業項目を体系的に整理したWBS（Work Breakdown Structure）を自動作成したりすることも可能です。
このような双方向の変換により、開発者は文書作成やコーディングに費やす時間を大幅に削減でき、より創造的な業務に注力することができます。
特に、仕様変更が発生した場合でも、関連するドキュメントやコードを迅速に更新できるため、プロジェクト全体の効率が向上します。
3. AIによる迅速なフィードバック
AIとMarkdownを組み合わせることで、文書作成プロセスにおいて迅速なフィードバックループを実現できます。
テキストベースで編集が容易なMarkdownの特性により、AIが指摘した問題点や提案された改善点を即座に反映することができます。
また、AIとの対話的なやり取りを通じて、文書の品質を段階的に向上させることが可能です。例えば、要件の曖昧な部分を指摘してもらい、より明確な表現に改善したり、文書の構造や論理展開について提案を受けたりすることができます。
さらに、人間のレビュアーが詳細なレビューを行う前に、AIによる事前チェックで基本的な問題点を洗い出すことで、レビュープロセス全体の効率化も図れます。
このように、AIを活用することで、文書の品質向上のサイクルを高速に回すことができ、より効率的な文書作成が実現できます。
実践的な活用方法
Step1: 環境構築
開発環境の構築において、特に重要なのは効率的なMarkdown編集と文書管理の基盤作りです。
必須ツール
VSCode（Carsor）
Git for バージョン管理
OpenAI API（必要に応じて）
まず、必須ツールとして、高機能なコードエディタであるVSCode（もしくはCursor）をインストールします。
VSCodeには「おすすめの拡張機能」にあるMarkdown Preview Enhancedプラグインを追加することで、編集中の文書をリアルタイムでプレビューしながら作業することが可能になります。
また、文書のバージョン管理のためにGitをインストールし、必要に応じてOpenAI APIに接続できる環境も整えておきます。
おすすめの拡張機能
さらに、より快適な編集環境を実現するために、以下の拡張機能の導入がおすすめです：。
Markdown All in One：キーボードショートカットやテーブル編集など、Markdown編集を効率化する機能を提供
markdownlint：Markdownの文法チェックやスタイルの一貫性を保つためのリンター
Markdown PDF：文書をPDF形式に変換する機能を追加
Markdown Preview Enhanced：Markdownプレビュー機能を追加してくれます。
Paste Image：画像をコピー&ペーストでMarkdownノートに貼ることが出来ます。
Marp：Markdownからスライドを作ることが出来ます。
みやっち│令和トラベル(NEWT)MLチームさんのポスト。エディタ上でmarkdownからガントチャートを作成してくれるという面白いツールもあるようです。
これらのツールと拡張機能を組み合わせることで、効率的なMarkdown編集環境が整い、文書作成作業の生産性を大きく向上させることができます。
また、これらはすべてオープンソースまたは無料で利用可能なツールであり、導入コストを抑えながら高度な文書管理環境を構築できます。
Step2: テンプレート作成
プロジェクトを効率的に進めるために、標準化されたMarkdownテンプレートを作成することが重要です。このテンプレートは、プロジェクトに関する重要な情報を体系的に整理する枠組みを提供します。
# プロジェクト要件定義書
## 1. プロジェクト概要
### 1.1 プロジェクトの目的
- 背景
- 解決すべき課題
- 期待される効果
### 1.2 プロジェクトのスコープ
- 対象範囲
- 対象外の範囲
- ステークホルダー
### 1.3 前提条件・制約条件
- 技術的制約
- 予算的制約
- スケジュール制約
- 法的制約・規制要件
## 2. 機能要件
### 2.1 システム全体構成
- システム概要図
- 主要機能一覧
- システム間連携図
### 2.2 機能要件詳細
#### 2.2.1 ユーザー管理機能
- ユーザー登録・認証
- 権限管理
- プロフィール管理
#### 2.2.2 業務機能
- 機能名
- 機能概要
- 入力項目
- 処理内容
- 出力項目
- バリデーションルール
#### 2.2.3 データ管理機能
- データ入力
- データ更新
- データ削除
- データ検索・照会
#### 2.2.4 外部連携機能
- 連携システム一覧
- 連携方式
- データフォーマット
- エラー処理
### 2.3 画面要件
- 画面遷移図
- 画面レイアウト
- UI/UXに関する要件
- レスポンシブ対応要件
### 2.4 帳票要件
- 帳票一覧
- 出力形式
- 出力条件
- レイアウト要件
## 3. 非機能要件
### 3.1 性能要件
- レスポンス時間
- スループット
- 同時接続数
- データ容量
### 3.2 可用性要件
- サービス提供時間
- 計画停止要件
- バックアップ要件
- 障害復旧要件
### 3.3 セキュリティ要件
- アクセス制御
- データ暗号化
- 監査ログ
- 脆弱性対策
- コンプライアンス要件
### 3.4 運用・保守要件
- 運用時間
- 監視要件
- バックアップ運用
- 障害対応
- メンテナンス要件
## 4. プロジェクト推進計画
### 4.1 スケジュール
- フェーズ分け
- マイルストーン
- 各フェーズの期間
- 主要タスク
### 4.2 体制
- プロジェクト体制図
- 役割分担
- 責任範囲
- 外部ベンダーとの関係
### 4.3 成果物
- 設計ドキュメント
- ソースコード
- テスト結果
- 運用マニュアル
### 4.4 品質管理
- 品質目標
- レビュー計画
- テスト計画
- 受入基準
## 5. リスク管理
### 5.1 想定されるリスク
- 技術的リスク
- スケジュールリスク
- 予算リスク
- 人的リスク
### 5.2 リスク対策
- リスク低減策
- 代替案
- エスカレーションルール
## 6. 付録
### 6.1 用語集
- 業務用語の定義
- 技術用語の定義
### 6.2 参考資料
- 関連ドキュメント
- 参考URL
- 規格・標準
## 改訂履歴
| 版数 | 改訂日 | 改訂者 | 改訂内容 |
|------|--------|---------|----------|
| 1.0 | YYYY/MM/DD | 作成者名 | 初版作成 |以下の主要セクションで構成します：
# プロジェクト要件定義書
## 1. プロジェクト概要
プロジェクトの基本情報を定義するセクション。目的、範囲、制約条件など、プロジェクトの方向性を決定する重要な情報を記載します。
## 2. 機能要件
システムが提供する具体的な機能や、実装すべき要件を詳細に記述するセクション。システム構成、個別機能、画面設計、帳票など、具体的な実装に必要な要件を定義します。
## 3. 非機能要件
システムの品質特性に関する要件を定義するセクション。性能、可用性、セキュリティ、運用保守など、システムの質を確保するための要件を記載します。
## 4. プロジェクト推進計画
プロジェクトの実行計画に関する情報を記載するセクション。スケジュール、体制、成果物、品質管理など、プロジェクト進行に必要な計画を定義します。
## 5. リスク管理
プロジェクト実行上の潜在的なリスクとその対策を記載するセクション。技術的リスク、スケジュールリスク、予算リスクなどを特定し、その対応策を定義します。
## 6. 付録
用語の定義や参考資料など、補足的な情報を記載するセクション。プロジェクトの理解を深めるための追加情報を提供します。
## 改訂履歴
文書の変更履歴を管理するためのセクション。いつ、誰が、どのような変更を行ったかを記録します。
これらは一例ですが、このような構造化されたテンプレートを使用することで、プロジェクトの情報を漏れなく整理でき、チームメンバー間での情報共有も円滑になります。また、AIによる文書解析や自動生成の際にも、一貫した構造があることで精度の高い処理が可能になります。
Step3: LLMとの効果的な連携
基本的なプロンプト例
LLM（大規模言語モデル）とMarkdownを組み合わせることで、開発プロセスの様々な場面で効率化が図れます。特に重要な活用方法として、以下の3つのパターンがあります。
要件からのWBS（作業分解構造）作成
Markdown形式で記述された要件定義書をLLMに入力することで、必要なタスクを体系的に抽出し、WBSとして構造化することができます。
この方法により、プロジェクトの全体像を素早く把握し、必要な作業を漏れなく特定することができます。要件定義からのコード生成
要件定義書の内容を基に、実装コードの雛形を自動生成することができます。
これにより、基本的な実装部分を効率的に作成し、開発者はよりビジネスロジックの実装に集中できます。テスト仕様書の自動生成
機能仕様から、必要なテストケースを網羅的に抽出し、テスト仕様書として文書化することができます。
これにより、テストの漏れを防ぎ、品質管理の効率を向上させることができます。
これらのプロンプトはあくまで基本例であり、プロジェクトの特性や必要に応じてカスタマイズすることで、より効果的な活用が可能です。
また、LLMの出力結果は必ず人間がレビューし、必要に応じて修正や調整を行うことが重要です。
以下応用や発展系でとても参考になります。
あきらパパ【生成AIエンジニア&3児のパパ】さんのポスト。要件定義書作成プロンプト。
元木大介さんのポスト。システム開発用要件定義プロンプト。
テツトモさんのポスト。元木さんのプロンプトを魔改造。
同じくテツトモさんのポスト。perplexityのコレクション機能に仕込んで実行。
高度なプロンプト例
LLMの高度な活用方法として、要件の品質向上やセキュリティ強化に関する分析が可能です。特に重要な2つのユースケースについて説明します。
要件の整合性チェック
LLMの文脈理解能力を活用して、要件定義書内の矛盾や潜在的な問題点を検出することができます。
以下の要件定義書の中で、互いに矛盾する可能性のある要件を指摘し、解決案を提示してください：
[要件定義書の内容]LLMは以下のような観点でチェックを行います：
機能要件間の依存関係と矛盾
非機能要件との整合性
リソース制約との適合性
タイムラインの実現可能性
検出された問題に対して、具体的な解決案も提示されます。
2.セキュリティレビュー
システム仕様に対して、セキュリティの観点から包括的な分析を行います。
以下のシステム仕様において、潜在的なセキュリティリスクを分析し、対策を提案してください：
[システム仕様の内容]LLMは以下の観点でセキュリティ分析を実施します。
認証・認可に関するリスク
データ保護の脆弱性
通信セキュリティの課題
インフラストラクチャのセキュリティ
コンプライアンス要件との整合性
各リスクに対する具体的な対策案も提示されます。
これらの高度なプロンプトを活用することで、人間の専門家による詳細なレビューの前に、潜在的な問題点を早期に発見し、対応することが可能になります。ただし、LLMの分析結果はあくまで参考として扱い、最終的な判断は必ず専門家が行うべきです。
また、セキュリティに関する提案については、必ず実際のセキュリティ専門家によるレビューを受けることが重要です。
注意点と対策
AIとMarkdownを活用する際の注意点と対策について解説します。
1. AIの限界に関する課題と対策
主な課題：
AIが生成する内容には誤りや不適切な提案が含まれる可能性があります。
AIは文脈や業務特有の細かいニュアンスを完全には理解できません。
機密性の高い情報をAIに入力することでセキュリティリスクが生じる可能性があります。
効果的な対策：
AIの出力は必ず人間の専門家がレビューし、最終判断を行います。
入力するプロンプトは具体的で明確な内容とし、あいまいさを排除します。
機密情報は事前に匿名化やマスキングを行い、センシティブな情報はAIに入力しません。
2. チームへの導入に関する課題と対策
主な課題：
チームメンバーのMarkdown記法への習熟度に差があります。
既存の文書作成フローからの移行に抵抗感があります。
新しいツールの使い方の習得に時間がかかります。
効果的な対策：
まずは簡単な議事録や簡易な文書からMarkdownを導入し、徐々に範囲を広げていきます。
定期的な勉強会を開催し、基本的な使い方から応用テクニックまでを共有します。
最初は基本的な記法だけを使用し、チームの習熟度に応じて高度な機能を導入していきます。
これらの課題と対策を認識した上で、以下のような段階的なアプローチを取ることをお勧めします。
まとめ
Markdown + LLMの組み合わせは、単なるドキュメント作成手法の改善ではありません。組織のプロジェクト進行の方法を根本から変える可能性を秘めています。
特に、今後AI活用が当たり前となっていく中で、この手法が選択肢のひとつとなっていく可能性もあると思います。