ドキュメント駆動型AI駆動開発

1~2ヶ月前からAIを使い始めたのですが、面白いですね。

前は仕事奪われるからAI怖いと思ってた。けどまだまだですね。

今回は私が使っている「ドキュメント駆動 x AI駆動開発」を行う方法をまとめました。

簡単におさらいすると

• ドキュメント駆動開発

  • 仕様書、設計書、APIドキュメントなどをまず作成し、それを基にコードを書く、というアプローチで、要件の明確化やチーム間の共通理解に役立ちます。

• AI駆動開発

  • コーディング支援ツール（コード生成、補完）、テスト生成、ドキュメント生成支援、要件分析支援など、開発プロセス全体でAIを活用するアプローチです。

私の制作環境は人がいないのでチーム間の共通理解は行ってませんが、AIとの共通理解は促進されてると思います。

ちなみにOSS用のコードを作成してます。

ドキュメント駆動型 x AI駆動開発の利点

まず私が感じているのは圧倒的に速いということです。

仕様が決まっていれば、マイルストーンで2~3週間と算出されていた項目が2~3時間で終わります。

これにより「サーバーがコンテナ化した時」と同じようにコードを「スクラップ&ビルド」する時代が来ると思います。

仕様を固めAIでコーディングし難しければ、コードを削除し、設計を見直し、再度AIにコーディングさせる。
そんなことが当たり前になるかもしれません。

何ができるか

• ドキュメント作成の効率化: AIが仕様のドラフト作成やドキュメントの整形を助ける。
• ドキュメントの整合性確保: AIに矛盾点があるか聞くことにより仕様書の品質をあげる。
• ドキュメントからのコード生成精度向上: 詳細で正確なドキュメントがあれば、AIによるコード生成の品質が高まる。
• ドキュメントとコードの整合性維持: AIがドキュメントとコードの差異を検出したり、同期を提案したりする。
• テストコード生成: ドキュメントやコードからAIがテストケースやテストコードを生成する。

ドキュメント駆動型AI駆動開発の手順

1. 「やりたいこと」をまとめる

まずyaritaikoto.mdを作りclaude codeなどAIに「用件定義手伝って」伝え要件を手伝ってもらう。

次にAIに質問しまくる。
例えば「最適なライブラリある？」「最適な言語は？」など

yaritaikoto.mdの内容は必要に応じて変わるけど、「やりたいこと」、「目的」、「背景」、「どんなことができる」、「どうやって？」などそのサービスを通じて実現したいことを考えてる。

ある程度仕様が固まったら、「仕様書にまとめて」とお願いしまとめてもらう。

2. 仕様書に起こす

仕様書に起こす際は抽象度の高い順から決めていくそうな。
ドキュメント駆動型はAIと同じく最近始めました。

プロジェクトプラン(やりたいこと)
↓
機能仕様書(システムが何をするか)
↓
アーキテクチャ仕様書(どうのように作るか)
↓
あった方がよい文書（なくてもできるけど）
「ユーザーインターフェース仕様書」や「デザイン仕様書」や「デザインコンセプト」など

このような順に行うといいです。AIに聞きました。

ただ一度に完璧に作るのは無理だから、ある程度仕様書を行き来してます。

抽象度の高い項目から決めていくとAIがある程度最適な方法を提案してくれるようになります。

システム設計の相談

システム設計の相談もAIにしてます。

AIの方が知識量はあるので、幅広い方法を提案してくれます。
ただし本当に設計的によいかは判断する必要があります。

提案された設計は最適でない可能性があります。
ここがエンジニアとしての勘の使い所でした。

またプロンプトで「批判的に考えて」と入れることも有効です。
もちろん仕様書を踏まえさせたうえで質問すること。

足りない項目の確認

「足りない項目ある？」と聞き詳細を詰めましょう。
エラーハンドリングやログローテーションの詳細（時間ベースかファイルベースかどの程度保持するか）など細かいところを決めていきます。

整合性チェック

仕様書がある程度出来たら整合性を確認します。

仕様書を元にAIにコーディングさせるため、仕様書が整合性を取れてないと結果が大幅にずれます。

私はclaudeを使っているので、プロプランのプロジェクト機能でgitを連携させ仕様書全体を読み込ませています。

そして「仕様書に矛盾点ある？」ときくと詳細に教えてくれます。図表の表記揺れなど教えてくれます。

それを元に修正を指示するか、自分で修正します。

ロードマップの作成

仕様書が完成し矛盾がなければ、AIに指示しロードマップを作成します。

仕様書を把握した上で「ロードマップを作成して」とお願いします。

このロードマップはAIにコーディングを指示する上で重要です。

[重要] 仕様書の書き方

AI駆動開発するためには仕様書をAIが扱いやすい形式で作ることが、肝心です。

具体的にはマークダウンを使用します。
そしてここがポイントなのですが、AIが識別しやすいようにFront Matter（フロントマター） を文書の先頭に記載します。

Front Matter（フロントマター）を使用

---
title: 'ASTronaut ドキュメント索引'
author: 'sika7'
tags: ['AST', 'ドキュメント索引']
date: 2025-05-30
audience: ['開発者', 'AIエージェント']
---

# ASTronaut ドキュメント索引

ここにマークダウンで本文を書く

このFront Matter（フロントマター）を記載することによりAIが「文書の目的」を識別しやすくなります。

また見出しなど文書のアウトラインをきちんとしましょう。AIが識別しやすくなります。

ディレクトリ構成

git管理するため docs/ ディレクトリ配下にまとめてます。

./docs/
├── INDEX.md
├── development
│   └── CODING_GUIDELINES.md
├── overview
│   ├── ARCHITECTURE.md
│   ├── CONCEPT.md
│   └── ROADMAP.md
└── specs
    ├── ARCHITECTURE.md
    ├── HOGE.md
    ├── HUGA.md
    ├── common
    │   ├── CLI.md
    │   ├── DIRECTORY.md
    │   ├── ERROR.md
    │   ├── FLOW.md
    │   ├── LIBRARY.md
    │   ├── LOGGING.md
    │   ├── PLUGIN.md
    │   └── PROJECT.md
    └── implementation

インデックスの作成

ここで重要なことは インデックスファイルを作成し各文書にリンクを貼ることで、AIが目的の文書に到達できるようにする ことです。

ファイルの分割

またファイルを分割することも重要です。
これにより 必要な仕様書のみ読み込ませる ことが出来ます。

AIは技術的制約によりコンテキストウインドウの制限があります。
これにより忘却が起こります。

つまりAIはドキュメントが長く文字数が長ければ長いど理解力を消費し処理能力が落ちます。

そのため必要な範囲に適切に分割することでこれを回避します。

また適切に分割しリンクを設置することで、重複が最小限になり仕様書の管理が楽になります。

ファイルを分割する際には以下のようなプロンプトを活用しました。

現状の仕様書が長くなっていると思います。これを改善したい。
背景：AIはドキュメントが長く文字数が長ければ長いど理解力を消費し処理能力が落ちる

目標
- docs/specs/ARCHITECTURE.mdから「ライブラリ仕様書」を作成
- 文書の場所: docs/specs/common/LIBRARY.md

重要な考慮点
- AIの処理能力最大化のため情報を整理・フォーカス
- 情報の集約だけ行う

タスク: docs/specs/ARCHITECTURE.md から docs/specs/LIBRARY.md に「ライブラリ」の情報を抽出する

3. 仕様書からコーディングを指示

仕様書が完成したら、コーディングの指示です。

プロンプトによっては成果が大きく違うため、「目的」、「重要なコンテキスト」、「タスク」を入れるようにしています。

目的: フェーズ1のマイルストーン達成

重要なコンテキスト:
- `docs/CODING_GUIDELINES.md` に準拠した実装
- `docs/SPEC.md` に準拠した実装
- `docs/levels/FILE_LEVEL_SPEC.md` に準拠した中間表現の実装
- `docs/formats/FILE_DETAIL_FORMAT.md` に準拠したフォーマット実装

タスク:フェーズ1.1の実装

簡単なタスクであれば複数記載したりします。

目的: フェーズ1のマイルストーン達成

重要なコンテキスト:
- `docs/CODING_GUIDELINES.md` に準拠した実装
- `docs/SPEC.md` に準拠した実装
- `docs/levels/FILE_LEVEL_SPEC.md` に準拠した中間表現の実装
- `docs/formats/FILE_DETAIL_FORMAT.md` に準拠したフォーマット実装

タスク1:〇〇におけるテストの作成
タスク2:作成したテストが仕様書に準拠しているか確認

このようにすることで、AIによるコーディングのブレを防ぐことが出来ます。
コンテキストウインドウが限界に近づくとAIはコーディングを端折ります。そのため大きなタスクは小さく分ける必要があります。

経験的にはテストを目的にしたら、コードをモックにされテストだけパスするようにされました。💢そうじゃねえよ!

AIは何を使っているか

再度言いますが、AIは技術的制約によりコンテキストウインドウの制限があります。
プログラミングなど複雑で創造的な活動をさせるには、コンテキストウインドウがおおいモデル選定が重要です。

なぜならAIはドキュメントが長く文字数が長ければ長いど理解力を消費し処理能力が落ちるからです。

clade codeの活用

このツールはコーディング用のCIツールだけど、ローカル環境でマークダウンの編集を行えるから。

「仕様書に記載して」とか、「仕様書を読んで矛盾点ある？」とか聞くことに使える。

モデルは「clade codeの3.7sonnet」を使用しています。

cursorの活用

cursorはclaude codeと違いドキュメント全体をコードベースに入れ管理しているため、効率的です。

またAIにlintエラーをフィイールドバックしてるみたい。
それによりインポートエラーとかすぐ対応してくれる。

やっぱりコーディングに強い。

エージェントモードでモデルは「clade codeの3.7sonnet」を使用してます。

AIの特性を考慮した設計

プログラムが複雑すぎると別の変更の影響で他の機能が壊れます。
これは人間も同じだと思いますがAIはより明確な気がします。
何度も出てきますがコンテキストウインドウです。

そのため私は複雑な抽象化をやめ処理グループに分割した設計を行うことにしました。
うまく説明できてない気がしますが、言葉が思いつかない...。

副次効果として処理グループに分割することにより人間にもわかりやすくなったと思います。

やってみてわかったことはAIの特性を考慮した設計が必要です。

ポイントのまとめ

ポイント：コンテキストウインドウの大きいモデル選定
ポイント：Front Matter（フロントマター）を活用
ポイント：マークダウンで仕様書を作成
ポイント：仕様書の整合性をとる
ポイント：仕様書は適切な単位で分割する
ポイント：AIが文書を効率的に探せるように仕様書のインデックスを作成する
ポイント：ロードマップを活用したコーディング指示
ポイント：プロンプト文で明確に指示し、必要な仕様書を指定する
ポイント：AIの特性を考慮した設計を行う

AIのコストについて

ちなみにAIの消費電力コストを下げる研究が進んでるみたいです。
今はベクトルデータの重みづけを計算して結果を出力してるけどより物理法則に沿った形、つまり「電気は一番抵抗が少ない経路を自動で探査する」特性を活かした計算ができるようになるかも。

ベクトルデータの重みがないものの電気抵抗を高めることで、重みがあるもの順に電気抵抗が少なくなる。

そうすることで全体の消費電力が少なくなるみたい。AIの利用コストが下がるかも。

早く実現してほしい。

clade codeをAPIキーで使用してたら、2日間で100$ちかく使った。(白目

結論 clade maxのような定額制がいいですよ。

終わりに

AI駆動開発の時代が来る。

その時に今回共有した「ドキュメント開発駆動 x AI駆動開発」が選択肢の一つになれたら嬉しいです。

この記事がよかったらコメントしていってください。

あとAIはプログラムなのにコードを読むことが難しいです。とくに大規模プロジェクトであればああるほど難しいです。
※コンテキストウインドウの制約

これを回避するためにコードの要約をAIが得意なテキスト形式に要約するプログラムを作成中です。
このプログラムがあれば、AIはコード全体を読むことなく俯瞰し問題点を考察できるようになります。

よかったら参加してください。