AIが「誤解」する仕様書の5つのアンチパターン
「AIにレビューさせたら、全然違う解釈をしてきた」
要件定義にAIを使い始めたチームから、よく聞く声だ。そして多くの場合、原因はAIの能力不足ではない。仕様書の書き方にある。
人間同士ならなんとなく通じる書き方が、AIには通じない。明示されていない文脈、暗黙の前提、ふわっとした言葉——これらがAIを迷 子にさせる。
アツメルでは複数のプロジェクトで仕様書×AIエージェントの組み合わせを試してきた。そこで繰り返し遭遇した「AIが誤解しやすい仕様書のパターン」を5つ整理した。
アンチパターン1: 主語が曖昧な要件
「ユーザーが操作できること」という要件を見たとき、AIは文字通り解釈する。「ユーザー」とは誰か？ログイン済みのユーザーか、ゲストユーザーも含むのか。「操作」とは何を指すか？
人間であれば過去の会議の文脈から「ここでいうユーザーは管理者ロールを持つ人だ」と推測できる。AIにはその文脈がない。
この問題が顕在化しやすいのは、テストコードの生成場面だ。「ユーザーが〜できること」という要件から自動テストを生成させると、AIは「ユーザー」を最も広い意味で解釈し、未認証ユーザーへのアクセス許可テストを書いてしまうことがある。レビュー時に初めて「意図と違う」と気づく。
改善策:
要件の主語は常に具体的なロール名で書く。「ユーザー」ではなく「管理者ユーザー（admin権限保持者）」と明示する。プロジェクトの用語集（グロッサリー）をAIに一緒に渡すことで、この種の誤解はほぼ防げる。最初に15分かけてグロッサリーを整備するだけで、以降の作業精度は大きく変わる。
アンチパターン2: ネガティブ要件だけの記述
「セキュリティ上の問題がないこと」。
これはネガティブ要件だ。「問題がないこと」という書き方は、何をすれば達成なのかをAIに伝えない。AIは正の基準、つまり「何をすれば良いか」という記述でないと、適切な実装や検証プランを生成しにくい。
実際、ある案件でこの種の要件を渡したところ、AIは「セキュリティ問題なし」を「既知の脆弱性がないこと」と解釈し、OWASP Top 10に対応した実装を省略した形で提案してきた。「問題がない」という基準が人によって違うのと同様に、AIにとっても基準が定まっていない。
改善策:
「〜しないこと」という記述は、必ず「〜すること」に変換する。「セキュリティ上の問題がないこと」ではなく、「OWASP Top 10に準拠した実装であること」「パスワードはbcryptで128bit以上のハッシュ化を適用すること」のように書く。ネガティブな表現を使うなら、その逆の「何をした状態が正解か」を必ずセットで明記する。
アンチパターン3: OR条件が連続する複合要件
「AdminユーザーまたはManagerロールを持つユーザー、あるいはオーナーが明示的に許可したユーザーは〜できる」
これを一文に詰め込むと、AIは条件の優先順位と網羅性を正確に判断できないことがある。特に「または」が3つ以上続くケースは危険だ。
テストコードを生成させると、特定の組み合わせが抜け落ちたり、互いに矛盾するケースが見逃されたりする。「Adminかつオーナーが許可していない場合はどうなるのか」といったエッジケースは、文章要件から自動的に導き出すのが難しい。
改善策:
OR条件は決定表（デシジョンテーブル）形式で書く。ロールごとの権限を表形式で整理し、各セルに「許可/禁止/条件付き」を明示する。AIはテーブル形式のデータが得意だ。複合条件を文章で書くより、表で渡した方が格段に精度が上がる。仕様書のどこかに必ず「権限マトリクス」のセクションを設けることを強くすすめたい。
アンチパターン4: 「既存の動作に合わせる」という参照要件
「現行システムの仕様を踏襲すること」という要件をよく見る。
ひどい場合は「既存のExcelファイルの動作を再現すること」だけが要件として書かれている。AIは現行システムにアクセスできない。「踏襲する」の中身が伝わらない。レガシーコードをAIで仕様書に起こす手法もあるが、それはあくまで「現行仕様を引き出す」フェーズの話であり、引き出した内容を仕様書に正しく書いて渡すことが前提だ。
このパターンで生成されたコードは、AIが合理的に判断した「それっぽい動作」になる。意図した動作とは別物だ。Excelのマクロに隠れていた計算ロジックや、例外処理のルールが丸ごと再現されない。
「なぜここでこの計算式を？」と確認すると、AIは「標準的な実装を選んだ」と答える。そこには20年分の業務ルールが詰まったExcelが存在することを、AIは知らない。
改善策:
「既存の動作に合わせる」と書く場合は、必ずその動作を具体的に記述する。現行システムの動作をスクリーンショット・APIレスポンス・計算ロジックのサンプルデータとして添付する。AIに「見せる」か「読み取れる形で伝える」かのどちらかしかない。最低限、代表的なケースのINPUT/OUTPUTを3〜5件書くだけでも大きく違う。
アンチパターン5: 暗黙の優先順位
「パフォーマンスよりも正確性を優先する」という前提は、文書に書かれていないことが多い。チームの共通認識として存在しているからだ。
AIには共通認識がない。コードを生成させると、最適化 のために精度を犠牲にする実装を提案してきたり、あるいは逆に正確性のために著しく遅い実装を選んだりする。
「なぜこんな実装に？」と確認すると、AIは合理的に判断したと答える。実際に合理的だ——ただし、共有されていない前提のもとで。この問題は単体のコードだけでなく、アーキテクチャ選定でも起きる。どのDBを使うか、どのキャッシュ戦略を取るか。優先度が明示されていなければ、AIは何らかの「合理的な」判断を下す。
改善策:
仕様書の冒頭に「設計原則」セクションを設ける。「このシステムは〜を最優先とする。次いで〜。〜は犠牲にして良い」という形で、明示的に優先順位を書く。これ一つ加えるだけで、AIの判断の質は大きく変わる。仕様駆動開発（SDD）では、この設計原則の明文化を要件定義の標準ステップとして位置づけている。
仕様書は「AIへの指示書」として書く
人間向けに書かれた仕様書と、AIが処理できる仕様書は、構造的に異なる。
人間は文脈を補完する。AIは書いてあることだけを処理する。この違いを理解して仕様書を設計することが、AI時代の要件定義の起点になる。
5つのアンチパターンを振り返ると、共通点が見えてくる。いずれも「人間なら察してくれる」部分に依存した記述だ。AIにその察しは期待できない。
逆に言えば、AIにとって読みやすい仕様書は、人間にとっても誤解が少ない仕様書になる。AIへの対応が、チーム全体のコミュニケーションの質も上げる副産物として働く。ある開発チームでは、「AI可読な仕様書への改訂作業」を通じて、長年曖昧にされてきたビジネスルールが初めて明文化されたという事例もある。
仕様書の書き直しをゼロから始めるのが難しければ、まず一つの要件を選んで5つのアンチパターンに当てはめてみてほしい。問題のある箇所は思ったより早く見つかる。そして一つ直すと、他の要件も同じパターンで書き直したくなるはずだ。
アツメルでは、「AIが読める仕様書」の設計を支援するプロダクトKakusillを開発している。要件定義のドキュメントをAIが処理しやすい構造に変換し、矛盾・曖昧性・優先度の欠落を自動検知する。要件定義にAIを使い始めるなら、ドキュメントの構造化から始めることをすすめたい。
参考資料:
- OWASP Top 10 (2021) — セキュリティ要件の具体化に活用できる業界標準
- IEEE 830 ソフトウェア要件仕様の推奨プラクティス — 要件記述の国際標準
- NTT DATAのAIエージェント実証事例 — 大手SIerにおけるAIエージェント実用化の最前線
