Markdownをプログラミング言語として用いる仕様駆動開発の可能性 ——GitHub Blogより | gihyo.jp

GitHubは2025年9月30日、ブログ記事「Spec-driven development: Using Markdown as a programming language when building with AI」を公開し、Markdownをプログラミング言語として用いる仕様駆動開発の可能性の一端が紹介された。

プログラムを作成するときにコーディングエージェント利用する場合、もっとも基礎的な使い方として「Xをおこなうアプリを作成」といった指示から開始し、逐次「機能Yを追加」「⁠バグZを修正」といった指示を反復する方法がある。しかしこの方法は、エージェントがアプリの目的や過去の決定を忘れ、説明の再提示や指示に対する矛盾が発生するといった課題がある。

その対応の一つに、エージェントの振る舞いをあらかじめ設定できるカスタムインストラクションがある（GitHub Copilotではcopilot-instructions.mdなどが使われることになる⁠）⁠。ただ、カスタムインストラクションは開発中に更新する必要が出てくることもしばしばあり、忙しいときなどはその更新を忘れてしまう問題が挙げられている。

さらなる候補として、仕様駆動開発（Spec-driven development）が挙げられている状況がある。GitHubでは仕様駆動開発のツールキット「Spec Kit」がオープンソースで継続的に開発されている。

仕様駆動開発では、アプリの実装仕様と文脈をMarkdownに集約し、それをコーディングエージェントがコードへ変換することでコンテキストの損失を防ぎ、仕様と実装を同期させる狙いがある。

では実際に、仕様駆動開発でどの程度のことができるのか。ブログ著者のGitHubのTomas Vesely氏は実験を兼ねて、今回GitHub Brain MCP Server（Go言語製）を、Go言語のプログラムファイルを書かずに、Markdownファイルのみを使ってプログラムを生成してみることにした。開発環境としてはVS CodeとGitHub Copilotを利用している。

なおGitHub Brain MCPサーバーは、GitHub上のDiscussions、Issues、プルリクエストを要約するためものであり、「⁠ユーザーXの先月の貢献は？」「⁠今月の議論を要約して」といった質問に答えるのに役立つという。

ブログでは、以下のファイル構成を示して解説した。

.
├── .github/
│   └── prompts/
│       └── compile.prompt.md
├── main.go
├── main.md
└── README.md

README.mdはユーザー向けドキュメントであり、簡単な概要とワークフロー、インストール方法、CLIの利用方法を記述する。

main.mdは実質的にソースコードの仕様になる。形式的に定義できる部分は見出しや箇条書き・コードブロックで明示し、振る舞いなどの高レベルな意図は自然言語で宣言的に書く。また、README.mdのインポートもおこなう。なお、機能追加やバグ修正への対応もこのMarkdownを編集するかたちになる。

このmain.mdの記述は仕様としての要求を明確にする必要があり、著者にとって直接Goを書くよりも難しい場合があったという。その際、Copilotを使った支援も利用して解決したとのこと。データベースにはSQLiteを使っており、この仕様もmain.mdに記述している。なお、外部リソース取得はGraphQLクエリとタイムスタンプ停止条件により効率化するようにしたという。

compile.prompt.mdは仕様をmain.goに変換させるための繰り返し利用可能なプロンプトファイルであり、「⁠仕様へ従いアプリを更新」「⁠VS Codeタスクでビルド（手動のgo build/go test指示の回避⁠）⁠」⁠「⁠使用ライブラリごとにGitHubホームページを取得しドキュメントと例を得る」といった指示が含まれている。

さらに、main.mdの明確化と簡潔化を目的としてlint.prompt.mdが作られた。このファイルでは「仕様の明確化・簡潔化」「⁠英語をプログラミング言語として扱う」「⁠用語統一」「⁠重複削除・重要詳細保持」「⁠Goコードは変更せずMarkdownのみ最適化」「⁠プロンプト自身は変更しない」などいった指示が含まれている。

作業の流れとしては、README.mdとmain.mdを編集し、コーディングエージェントに/コマンドでcompile.prompt.mdを使った変換を指示し、Goのコード生成するかたちになる。なお随時/コマンドでlint.prompt.mdを呼び出し、main.mdを整理する。

そしてプログラムの実行と動作テストをおこない、期待する動作と一致しない場合には仕様を更新して再変換する……といった反復がおこなわれた。なお、仕様が大きくなってからは、focus on といった文脈を追加することで、コーディングエージェントの焦点を誘導できたという。

こうして、仕様をみたすGitHub Brain MCPサーバーができたとのこと。GitHub Copilotのコーディングエージェントのアップデートのたびに、ワークフローの改善ができていることも付け加えられている。

今後は、main.goが肥大化するとコンパイル速度が低下するので各##セクションをモジュールに分割する指示を追加することや、テストファイルの追加などを検討したいという。また、Go言語のコードではなく、他のプログラミング言語で生成する案にも言及がある。