株式会社ウエスタンカンパニー

AIコーディングツールを使った開発で、「さっき説明したのに、また同じことを聞かれる」という経験はないでしょうか。長時間の作業で文脈が切れるたびに仕様を説明し直す ── この「説明の無限ループ」は、AIコーディングを導入したチームが最初にぶつかる壁のひとつです。本記事では、Markdownファイルに要件をまとめて渡すだけで手戻りを大幅に減らせる実践的な方法をご紹介します。

AIコーディングで起きる「説明の無限ループ」問題

AIコーディングツールと長時間やり取りしていると、以下のようなループに陥ることがあります。

• 仕様・要件をAIに説明する
• 実装が進む
• 会話の文脈が切れる（コンテキストウィンドウの限界やセッション再開など）
• AIが要件を「忘れて」手戻りが発生する
• 最初からまた説明し直し

この繰り返しにより、AIに任せたはずなのにかえって遅くなったり、レビューで「前に直した箇所がまた元に戻っている」といった事態が起きます。特に、修正箇所が多い大規模案件や仕様が複雑なプロジェクトほど、この問題の影響は深刻です。

解決策は「要件をMarkdownファイルにまとめて渡す」だけ

解決の考え方はシンプルです。要件・制約・NGパターンを1つのMarkdownファイルに集約し、AIに「このファイルを基準に進めてください」と明示的に渡します。

• タスク実行のたびに要件ファイルを参照させることで、文脈が切れても実装がブレにくくなる
• 別セッションでも「このファイルを見てください」と伝えるだけで作業を継続できる
• 実行した履歴をドキュメントに追記させれば、進捗の記録としても機能する
• 何度か指示を繰り返すと、AIが自発的にドキュメントを更新してくれるようになる

さらに見落とせない副次効果として、要件を文書にまとめる過程で自分自身の頭の中も整理されるという点があります。曖昧だった仕様や抜け漏れに気づけるため、AI活用以前の段階から品質向上につながります。

文書化が効果的な場面・不要な場面

すべてのタスクで文書化が必要というわけではありません。「規模×期間」を判断軸にすると、適用すべき場面が明確になります。

文書化が必要なケース

• 修正箇所が広い大規模案件 ── 規模と期間が大きいほど効果を発揮
• 仕様が複雑で関係者が多いプロジェクト ── 認識のブレが減り、手戻りコストが下がる

文書化が不要なケース

• 1〜2日で終わる軽い修正 ── ドキュメント作成の手間の方が大きい
• 1ファイルで完結する修正 ── 直接指示で十分

要件ドキュメントに書くべき4つの項目

効果的な要件ドキュメントには、以下の4つの項目を含めます。特に重要なのは「Why（なぜそうするのか）」と「やってはいけないこと」を明示することです。AIは「何をするか」は文脈から推測できますが、「過去の経緯でやってはいけないこと」は明示しないと毎回同じ失敗を繰り返します。

機能要件

実装すべき機能を箇条書きで列挙します。対応しない範囲も「スコープ外」として明記しておくと、AIが余計な実装を行うことを防げます。

制約・前提

使用するライブラリやフレームワーク、認証方式、データ形式、パフォーマンス要件など、実装の前提条件を記載します。

NGパターン

過去に失敗した実装方法や、この案件では避けるべきアプローチを記載します。AIが繰り返しやすいミスを事前に防ぐ、最も重要な項目です。

参照すべきファイル

既存コードへのパスや仕様書・設計書の場所を明記します。AIが適切なコードを参照しながら実装を進められるようになります。

運用のコツ — 肥大化を防いで長く使う

要件ドキュメントは運用を続けるうちに肥大化しがちです。ファイルが大きくなりすぎると、AI側で不要な情報まで読み込んでしまい、かえって効率が落ちたり、古い情報に引っ張られる問題が発生します。

• 1ファイルが長大になったら、機能単位やフェーズごとにファイルを分割する
• 却下済みの方針や完了したタスクの記述は定期的に整理する
• ドキュメントの整理はAIに完全に任せず、人の目でメンテナンスする

また、大規模案件ではAIツールのプランモード（実装を行わず要件整理や壁打ちに使うモード）で先に要件を固め、その後に実装モードへ切り替えるという2段階のフローも効果的です。要件が曖昧なまま実装を始めると手戻りが増えるため、この「考える段階」と「作る段階」を分けるアプローチは、AI活用に限らず開発全般に通じる考え方です。

当社ではAIツールを活用した開発効率化に関するご相談を承っております。自社の開発フローにAIをどう組み込むか、お気軽にお問い合わせください。