06　Markdown　～AI時代に最適なドキュメントの表記法と活用シナリオ ｜新・IBM i入門ガイド［コード生成AI編］ 基本ツール

優れたソフトウェア開発には、優れたドキュメントが不可欠である。しかし仕様書、設計書、テスト手順書、日々の議事録といったドキュメントの作成とメンテナンスはとても負担がかかる。

生成AIがこの状況を一変させつつある。AIは、ソースコードを解析して仕様書を自動生成したり、変更内容の要約を作成したりと、ドキュメント作成の強力なアシスタントとなり得る。

またこれからのAIは、仕様書を読み込んでコードを自動生成するなどの機能も実現するだろう。このAIとのやり取りを最も効率的に実現するフォーマットが、Markdown（マークダウン）である。

なぜAI時代のドキュメントはMarkdownなのか 

Markdownは、#（見出し）や*（箇条書き）といった簡単な記号を使って、構造的な文章を記述するための軽量マークアップ言語である。なぜこのシンプルな形式が、AI時代のドキュメントとして最適だと言えるのだろうか。

プレーンテキストでGitと相性抜群

プログラムの仕様書や設計書のようなドキュメントは、Wordや、場合によってはExcelを使って記述されることが多い。このWordやExcelが生成する.docxや.xlsx形式のファイルは、それを生成したプログラムでしか内容を理解できない。このようなファイルをバイナリ形式という。

バイナリ形式のファイルは、Gitでバージョン管理しようとすると、少しの変更でもファイル全体が「変更された」と認識されるため、差分の比較はかなり困難になる。

一方、Markdownはただのテキストファイル（プレーンテキスト）であるため、変更個所が行単位で明確に記録される。AIがドキュメントに加えた修正も一目瞭然であり、Gitによる厳密な履歴管理に完璧に適合する（図表1）。

AIにとって「生成しやすい」フォーマット

Markdownの構造は非常にシンプルで論理的であるため、生成AIがこの形式で文章を出力するのは得意中の得意である。

「このRPGソースの処理概要を、Markdown形式の仕様書として出力して」といったプロンプトで、AIは人間が読みやすい構造化されたドキュメントを瞬時に生成してくれる。

人間にとっても「読み書きしやすい」フォーマット　

Markdownの記法は学習が容易であり、特別なエディタがなくても内容を直感的に理解できる。また、VS CodeにはMarkdownのプレビュー機能が標準で備わっており、書きながらリアルタイムで整形後の表示を確認できるため、非常に効率的に記述できる。VS Code上でソースコードを記述しながら、関連するドキュメントも同時に記述できるのは、文書化を進めるうえで非常に有用である。

生成AIにとっても「理解しやすい」フォーマット

実は、Markdown記法で書かれた文章は、AIにとっても理解しやすいフォーマットと言われている。最近の生成AIは、人に話すのと同じような文章で細かな指示（5W1H）を与えても、ある程度は正確に解釈して回答してくれる。しかし読みにくい文章の場合は、こちらの意図が正しく伝わらず期待した回答が得られない場合もある（筆者は今でも苦労している）。

与えられた「難解な」長文から5W1H情報をどのように「読み解くか」は人間でも苦労するのだから、AIにとってはなおさらだ。何も毎回好んで「長文読」を解かせなくてもよい。はじめから「どう振る舞ってほしいか、前提条件は何か、どのように出力してほしいか、元となるデータは何か」などをMarkdownで書けばよい。

高い移植性と再利用性

Markdownファイルは、Pandocのようなオープンソース・ツールを使えば、HTML、PDF、Word文書など、さまざまな形式へ簡単に変換できる。また、VS Codeの拡張機能でMarkdownをPDFに出力するものもある。一度Markdownで作成しておけば、このようなツールを使って用途に応じた最適なフォーマットで出力できるため、ドキュメントの再利用性が格段に向上する。

IBM i開発現場でのMarkdown活用シナリオ　

Markdownの活用という点では、他のプラットフォームの開発に比べて特別なことがIBM iにあるわけではない。以下の用途でMarkdownは利用可能なので、この記法に少しでも早く触れて習得してほしい。

AIによる仕様書生成　

既存のRPGソースコードをAIに与え、「このプログラムの機能をMarkdownで解説して」と指示するだけで、プログラムの概要、処理フロー、使用ファイルなどを記述した仕様書の原案を作成できる。

プルリクエストの記述

Gitでソースコードの変更をレビュー依頼する際、AIに変更点の要約をMarkdown形式で自動生成させ、レビューの効率を大幅に向上させる。

技術的なメモや手順書　

VS Codeで日々の開発メモやちょっとした手順をMarkdownで書き留め、そのままGitリポジトリにコミットすれば、VS Codeから離れることなく、システム開発に必要な情報をチームメンバー間で漏れなく共有できる。

                                                                          *

Markdownは、現代の開発ワークフローでは、開発に携わるすべてのメンバーが習得すべき基礎知識である。AIが生成するドキュメントや、各種技術文書の多くがMarkdown形式に収斂していくことは、もはや避けられない事実であると言える。

日々の作業ログやプロジェクトの進捗管理、技術的なメモに至るまで、VS Codeを活用してMarkdownで記述することで、情報の整理と共有が劇的に効率化されるだろう。

AIとの協調作業が不可欠となるこれからの時代において、Markdownを習得し使いこなすことは、開発者の生産性を高め、より創造的な業務に集中するための重要な鍵となるはずだ。