AIファーストなドキュメント戦略 - DocCommentにユビキタス言語を書くだけのシンプルなアプローチ

AIコーディング、特にClaude CodeやCursorのようなツールの普及に伴い、「AIにいかに正確なコンテキストを与えるか」が開発者の最大の関心事になっています。

その中で現在、 SDD（Spec Driven Development）的なアプローチ——つまり、詳細な仕様書をAIに書かせ、それこそが正としてメンテナンスを続ける手法——が注目されています。しかし、私は実務での経験を通じて、「仕様書を充実させるよりも、コード内のDocCommentを充実させるシンプルなアプローチこそが、AIファーストな開発なのでは？」 という考えに至りました。

SDD自体賛否あるアプローチで、好意的な人でも使い所が重要とする意見が多いと感じます。
これからAIファーストなプロジェクトを作りたい人に、まずはシンプルなこのアプローチを試していただけたらと思います。

前提

まず、本記事の背景となる私の開発環境は以下の通りです。

• プロジェクト: 業務でのFlutterアプリケーション開発
• 主要ツール: Claude Code (Agentic Searchを採用したCLIツール)
• ドキュメント戦略:
  • 仕様書管理（SDD）は行っていない: コードと分離したMarkdown仕様書は作らない。
  • DocComment重視: Dartdoc（///）に「UI番号」「日本語の画面名」「複雑な仕様」を集約。
  • docs/ディレクトリ: アーキテクチャ図やディレクトリ構成のルールなど、プロジェクト全体の「作法」のみを管理。

環境によって有効なAI活用のアプローチは変わってくるので、初めに共有しておきます。

具体的な実装

提案するアプローチは極めてシンプルです。

例えば画面のコードだったら、以下のようにDocComment(今回ならdartdoc)としてUI番号や画面名を書くだけです。
また、コードに実装だけでは読み取りづらい複雑な仕様があるならそちらもDocCommentとして記述します。
ポイントがあるとしたら画面名などでユビキタス言語(後述)を使うことくらいです。

/// UI-05 会社詳細画面
/// 
/// 複雑な仕様の説明
class CompanyDetailScreen extends StatelessWidget {

ユビキタス言語

ユビキタス言語とは、ドメイン駆動設計（DDD）において、プロジェクトに関わるすべてのメンバー（開発者、ビジネス担当者など）が共有する共通の言葉とその定義のことです。これにより、コミュニケーションのズレや誤解を防ぎ、一貫したモノづくりを効率的に進めることが目的です。

このアプローチによってできること

具体的にこのアプローチで実現可能になることですが、ユビキタス言語でAIに指示が出せるようになります。
プロンプトを書くのが楽になるのもそうですが、Bizサイドやデザイナーとの会話をそのままコンテキストとして渡せるのも実用性が高いと思います。

Before

@CompanyDetailScreen 画面に〇〇する機能を追加したいから実装方法を提案して
~~~(省略)
@HomeScreen に似たような実装があるから参考にして

After

会社詳細画面に〇〇する機能を追加したいから実装方法を提案して
~~~(省略)
ホーム画面に似たような実装があるから参考にして

アプローチの根拠・考察

実務でこの方法がうまくワークしているというだけでは説得力がないと思うので、なぜこのアプローチが有効なのか、技術的な側面から考えてみたいと思います。

Agentic Search

Claude Codeなどのツールが採用するAgentic Searchは、AIエージェントがgrepやlsなどの開発ツールを使って動的に複数ラウンドの検索を実行するアプローチです^[1]。事前にインデックスを作成するRAG（Retrieval-Augmented Generation）とは異なり、リアルタイムでファイルシステムを探索し、常に最新のコードを検索対象とするのが特徴です。

このAgentic Search機能は、Claude Codeに限らず多くのコーディング用AIエージェントに標準搭載されています。RAGと併用するHybridアプローチを採用するツールもありますが、いずれにせよAgentic Searchは現代のAIコーディングツールにおける基本機能だと思います。

私が実務で使っていて感じるのは、このアプローチではDocCommentが「検索可能なメタデータ」として非常に効果的に機能するということです^[2]。例えば、先ほどの例のように/// UI-05 会社詳細画面とDocCommentに書いておくと、「会社詳細画面」という日本語や「UI-05」という番号で確実にgrep検索がヒットします。

/// UI-05 会社詳細画面
class CompanyDetailScreen extends StatelessWidget {

クラス名がCompanyDetailScreenであっても、日本語の「会社詳細画面」でも検索可能になるので、ユビキタス言語でそのままAIに指示を出せるようになります。また、UI番号があることで仕様書との紐付けも即座に行えるのが便利です。

Agentic Searchは完全一致の文字列検索に強みがあるので、DocCommentに明確なキーワード（画面名、UI番号、機能名など）を記述しておくことで、AIエージェントは確実に目的のコードを見つけてくれます。表記揺れには注意が必要ですが、正規表現での対応も可能です。

このように、DocCommentにユビキタス言語を書くだけで、Agentic Searchを採用したツールにとって最適な検索対象になると言えます。

LLMの学習データ

そもそも、なぜAIはDocCommentを自然に理解できるのでしょうか？これは、LLMが何を学習してきたかに関係していると考えています。

LLMのコーディング能力は、GitHubなどで公開されている膨大なオープンソースソフトウェア（OSS）のコードを学習することで獲得されています。

そして、優れたOSSプロジェクトを見てみると、ドキュメントの多くはコードの直上にDocComment形式で記述されています。例えば、Flutter SDK自体やその他の著名なDartパッケージでは、すべてのパブリックAPIにdartdocコメント（///）が詳細に記述されており、それがそのまま公式ドキュメントとして生成されます。Pythonのdocstring、JavaのJavadoc、JavaScriptのJSDocなど、あらゆる言語で同様のパターンが見られますよね。

LLMはこのような「DocComment → 実装コード」という構造を何億回も学習しているので、DocComment形式で仕様が書かれている状態が、最も予測精度が高まる環境 だと予想できます。

このように、DocCommentにユビキタス言語や仕様を書くアプローチは、LLMの学習パターンを自然に活かす方法なのかなと思います。

Colocation

最後に、Colocation（コロケーション） についても触れておきたいと思います。これは、関連する情報を物理的に近い場所に配置するという考え方です。

仕様書をコードとは別のMarkdownファイルとしてきれいに管理するのは、情報の整理という意味では素晴らしいアプローチだと思います。しかし、実務で運用してみると、そこにはどうしても 「物理的な距離」 という課題が生まれてしまいます。

コードを修正する際、別のディレクトリにある仕様ファイルも同時に開いて更新し続けるには、人間にとって高い規律が求められます。「コードは直したが、仕様書の更新を後回しにしてしまった」——誰もが経験するこの小さなズレの積み重ねが、結果として仕様と実装の乖離を招いてしまいます。

これはAIにとっても同様だと感じています。コードと仕様が離れていると、AIはそれらを結びつけるために余計な探索ステップを踏まなければなりません。逆に、コードのすぐ近くに説明があれば、AIはファイルを開いた瞬間に仕様を理解できます。

仕様をコードに 「同居（Colocation）」 させること。それは、AIと人間の双方にとって「あっちこっち見に行く手間」を減らす、シンプルですが効果的な工夫だと思います。

まとめ

DocCommentにユビキタス言語を書くシンプルなアプローチの紹介でした。
AIファーストなプロジェクトを整備する最初の一歩として参考になれば幸いです。

脚注

1. Anthropicの公式ブログより：Claude Agent SDKは従来の開発ツール（grep、ls、readなど）を使って動的に複数ラウンドの検索を実行する「Agentic Search」アプローチを採用しています。出典: Building agents with the Claude Agent SDK

2. DocCommentに記載された画面名やUI番号などのキーワードがgrep検索で確実にヒットするので、ユビキタス言語を使った自然な指示が可能になります。仕様書との紐付けも即座に行えるのが便利です。