【ITニュース解説】Augmented Intelligence (AI) Coding using Markdown Driven-Development

この解説は、人工知能（AI）を活用して効率的にソフトウェア開発を進める「Augmented Intelligence (AI) Coding using Markdown Driven-Development」という新しい手法について説明する。システムエンジニアを目指す初心者の皆さんにも、現代の開発現場でどのようにAIと共存し、生産性を向上させるのかを理解してもらうことを目的とする。

この手法は、開発の初期段階で詳細なドキュメントを作成することから始める「Readme-Driven Development」をさらに発展させたものだ。具体的には、週末のうちに50ページにも及ぶ複雑な技術仕様書（RFC）の実装を完了させた事例を基に、その具体的な手順が紹介されている。

開発は主に四つのステップで進められる。

最初のステップは、「オンライン思考モデルを使って機能のドキュメントを設計する」ことだ。ここでは、ウェブを検索できる高性能な大規模言語モデル（LLM）を用いる。しかし、この段階でコードを書かせることはしない。まず、開発しようとしている機能が何を達成すべきか、その目的や要件についてLLMと徹底的に議論する。そして、その議論を通じて得られた情報を基に、ユーザー向けのドキュメント、例えばプロジェクトの概要を記す「README.md」ファイルやブログ記事の草稿を作成する。このドキュメントは、あなたが実際にコードを書きたくなるほど、詳細で魅力的なものであるべきだとされている。最終的に、このドキュメントをMarkdown形式のファイルとして保存し、次のステップでAIに指示を出すための「設計図」とする。もし高価なLLMのサブスクリプションがない場合でも、「Dive AI Desktop」のようなツールを使って、手頃な価格のモデルで同等のウェブ調査を行うことが可能だ。

次のステップは、「説明のみの『コーディングプロンプト』をエクスポートする」ことだ。ステップ1で使ったLLMに、今度はコードを含まない「機能の説明だけを記述したコーディングプロンプト」を作成させる。このプロンプトは、AIエージェントがコードを生成するための指示書となる。一度で完璧なものができるとは限らないため、何度も修正を指示し、プロンプトの質を高めることが重要だ。もしプロンプトが長すぎる場合は、その機能が大きすぎる可能性があるため、最初からやり直し、より小さい機能単位でプロンプトを作成することが推奨されている。これは、開発作業を管理可能な小さなタスクに分割する「チケットグルーミング」のような作業だと考えれば良い。

三番目のステップは、「YOLOモードのエージェントに貼り付けて実行させる」ことだ。YOLOとは「You Only Live Once」（人生は一度きり）の略で、ここではAIエージェントに「危険を顧みず全力でやれ」という意味合いで使われている。ステップ2で作成した整えられたコーディングプロンプトと、ステップ1で作成したドキュメントをAIエージェントに渡して、コード生成を実行させる。この際、現在のコードベースを壊さないように、必ずGitの新しいブランチを作成してから作業を進めることが推奨されている。AIエージェントには、GitHubのイシュー（課題）を作成し、新しいブランチを切り、プルリクエスト（コード変更の提案）を作成するところまで指示を出すが、Gitへのコミット（変更の確定）とプッシュ（変更のリポジトリへの送信）は人間が行うように制限する。これにより、AIが自由にコードを生成しつつも、最終的な品質管理は人間の手で行うという安全策をとる。

最後の、そして最も重要なステップは、「エージェントに『逆方向から作業する』ように強制する」ことだ。AIモデルは、往々にしてすぐにコードを書き始め、既存のコードを壊したり、途中で迷走したり、ドキュメントの更新を忘れたりすることがある。これを防ぐために、AIエージェントが提示する「Todoリスト」（やるべきことのリスト）の順序を人間が積極的に再編成する。AIが最初に提示するTodoリストは、危険な順序であることが多い。例えば、「既存のロジックを削除する」「既存のコードを変更する」「テストを変更する」「新しいテストを追加する」「README.mdを更新する」といった順序だ。この順序で作業を進めると、途中でAIのコンテキスト（作業記憶）が失われたり、人間の介入で計画が中断されたりした場合に、大量の壊れたコードが残されるリスクがある。

そこで、推奨される安全なTodoリストの順序は次のようになる。まず、最も重要で全体の方向性を決める「README.md」や「AGENTS.md」（エージェント向けのガイダンス）といったドキュメントの更新から始める。次に、新しい機能に対するテストコードを追加するが、この段階ではまだ実行しない。その後、既存のテストコードを修正する（これもまだ実行しない）。そしてようやく、実際のロジックの追加や変更を行う。すべての変更が終わってから、初めてテストを実行し、コードが正しく動作することを確認する。最後に、不要になったコードやファイルを削除する。このように作業の順序を逆転させることで、AIエージェントが迷走しても、常に最新かつ正しいドキュメントが存在し、テストの準備も整っている状態を保つことができる。この手法は、まるで「地図を最初に作り、目的地へのルートを細かく計画し、安全を確認しながら進む」ことと似ている。

この開発手法は、単に理論的なものではなく、実際に複雑なシステム開発にも適用できることが示されている。例えば、筆者はこの手法を使って、週末だけで51ページもの仕様書を持つ「RFC 8927 JSON Type Definitionバリデーター」を実装した。このプロジェクトでは、約4000行の互換性テストスイートや、ランダムなJTD（JSON Type Definition）を生成するツールも活用され、最終的に509個の単体テストが作成されたという。

また、AIモデルの選定についても言及がある。一つのAIモデルファミリーに依存することは推奨されず、オンライン調査にはChatGPT、Claude、Dive Desktopといった複数のモデルを使い分け、エージェントにはCopilot、Cursor、Codex、Code、Geminiなど、様々なサービスやオープンソースモデルを活用している。しかし、最も重要なのは、どのAIモデルを使うかではなく、最初に質の高いドキュメントを作成すること、そしてAIに対して的確で明確なプロンプトを与えることだという。これにより、AIの能力を最大限に引き出し、開発プロセスを飛躍的に効率化できるのだ。