Claude CodeのようなAIコーディングツールを使えば、数分で機能全体を生成できますが、基盤となるビジネスロジックに欠陥があれば、生成速度がどれほど速くても意味がありません。根本的な原因はモデル自体にあるのではなく、むしろ、暗黙の前提に満ちた人間中心の要件を依然としてAIに与えていることにあります。AIは曖昧な点に遭遇すると、明確化を求めることなく推測するだけであり、その推測が最終的に本番環境で障害を引き起こします。

この記事では、AIコーディングの仕様記述技術を習得することで、このギャップを埋める方法を解説します。従来のPRDが自律型エージェントでは十分に機能しない理由、曖昧さを解消するための6つの要素からなるCafeKitフレームワークの使い方、そして複雑なエッジケースを処理するためのEARSやExample Mappingといった実践的なテクニックについて詳しく解説します。この記事を読み終える頃には、漠然としたアイデアをClaude Codeが初回で完璧に実行できる、厳密で機械可読な仕様に変換する方法を正確に理解できるようになっているでしょう。

AIコーディングの仕様書作成が他と異なる理由

従来のPRD（プロダクト要件定義書）は開発者が膨大な量の暗黙的なコンテキストを共有しているため、人間の開発チームでは十分に機能します。開発者は行間を読み、簡単な質問をし、短い会話の中でビジネス目標について合意することができます。しかし、AIエージェントは、こうした共有された背景知識を持たない状態で動作します。 

人間に曖昧な要件を伝えると、コードを書く前に立ち止まって内容を明確にします。しかし、同じ要件をAIに伝えると、統計的な推測に基づいてすぐにコードの生成を開始します。この根本的な違いは要件定義書の作成方法を完全に変えてしまいます。

AIは人間のように要件を解釈しない

人間の開発者は文脈を踏まえて要件を解釈できます。「注文が発送されたらユーザーに通知する」という記述を見れば、そのドメインの文脈を理解します。「通知」とは、B2Bシステムではメール、モバイルアプリではプッシュ通知を意味する可能性が高いことを認識します。既存のコードをチェックしてパターンを探し、不明な点があればプロダクトオーナーに質問します。

AIはこれらのことを一切行いません。訓練データからパターンを処理し、統計的に最も可能性の高い実装を生成します。必ずしも正しい実装とは限りません。単に、AIがこれまで見てきた中で最も一般的な実装を生成するだけです。

クーポンに関する要件を考えてみましょう。「システムは注文に割引を適用するものとする。」AIは、パーセンテージ割引、固定金額割引、または注文金額に基づく段階的割引を実装する可能性があります。割引を税引前に適用するのか、税引後に適用するのか、あるいは特定のカテゴリの商品のみに適用するのかも明確ではありません。明示的な指示がない場合、AIはオープンソースコードで頻出する実装パターンに基づいて、いずれかの方式を選択します。この決定はうまくいく場合もあれば、ビジネスロジックに全く合わない場合もあります。

曖昧さはそのまま実装になる   

AI仕様における重要なルールは要件の曖昧な部分はすべてAIが決定するという点です。「注文が出荷されたらユーザーに通知する」と記述した場合、AIは配信チャネル、メールテンプレート、送信者アドレス、再試行ロジック、オプトアウト処理、レート制限ルールなどを選択する必要があります。AIは、これらの項目をユーザーに確認することなく独自に決定します。その際、自らの前提を明示したり、不確実な点を警告したりすることはありません。 

人間の開発者にとって、曖昧さは質問につながります。一方、AIにとってはコード生成につながります。そのコードはコンパイルされ、テストに合格し、一見正常に動作しているように見えますが、不足していたエッジケースが本番環境で表面化することがあります。 

コンテキストの欠如は誤った推測を生み出す 

AIエージェントは与えられたコンテキストのみを参照して動作します。コードベースを調査して既存のパターンを把握することはできますが、明示されていないアーキテクチャ上の制約までは推測できません。仕様書にすべてのデータベース操作でリポジトリパターンを使用する旨の記載がない場合、AIはコントローラーにSQLを直接記述する可能性があります。JWTベースの認証を指定しなければ、AIがセッションCookie方式を実装する可能性があります。タイムスタンプをUTCで保存するよう指定していない場合、サーバーのローカル時間が使用されます。

人間の開発者は周囲のコードを見て、確立された慣習に従います。一方、Claude Codeは仕様書を見ます。仕様書に記載されていないものは存在しないものとみなされます。そのため、仕様書はAIにとっての完全な判断基盤となる必要があり、すべての前提を明示しなければなりません。

シフトレフトの原則は仕様策定から始まる

従来の開発手法では、シフトレフトとはテストをサイクルの早い段階に移動させることを意味します。AIコーディングにおいては、曖昧さの解消を仕様策定段階まで前倒しすることを意味します。AI生成コードの修正コストは、デバッグよりもコードの再生成にかかります。問題点を特定し、要件を書き直し、エージェントを再実行します。この各イテレーションには時間とトークン予算がかかります。

厳密な仕様はこのような悪循環を防ぎます。「注文ステータスが『出荷済み』に変更されたら、システムは顧客のメールアドレスにメールを送信する」と記述すれば、AIが独自の判断を差し挟む余地がありません。入力に解釈の余地がないため、出力は意図と一致します。これがAIコーディングの生産性を左右する本質的なポイントです。つまり、より良いプロンプトではなく、より良い仕様です。そして、これほど正確な仕様を記述する最も実用的な方法は、曖昧さを排除するように設計された構造化構文であるEARSを使用することです。

EARSを使用してAI要件の曖昧さを軽減する

EARSとは何ですか？

EARSは「Easy Approach to Requirements Syntax」の略称です。これはロールス・ロイス社のアリスター・マビン氏とその同僚によって、航空宇宙および防衛システム向けに開発されたもので、これらの分野では、誤った解釈が数百万ドル規模の損失につながる可能性があります。この構文では、要件を厳格かつ予測可能な構造で記述するため、人間の言語に固有の曖昧さを抑えることができます。EARSのすべての要件は明確なパターンに従い、何がアクションをトリガーするのか、どのような条件が適用されるのか、そしてシステムがそれに応じて何をしなければならないのかを正確に規定します。

この構造はAIコーディングエージェントにとって特に価値があります。なぜなら、AIは意図を解釈するよりもパターンを処理する方がはるかに効率的だからです。要件を自然言語の英語で記述する場合、AIはどの単語がトリガーで、どの単語が条件で、どの単語がアクションなのかを推測しなければなりません。EARS形式で記述すると、役割は構文自体によって明確に示されます。AIは推論する必要はなく、構造化された入力を構造化された出力にマッピングするだけです。

EARSがAIエージェントにうまく機能する理由

AIコーディングエージェントは指示が予測可能なパターンに従う場合に最高のパフォーマンスを発揮します。人間は漠然とした記述の要件から意味を推測できることが多いものの、AIモデルは要件が構造化され、明確に記述されている場合にはるかに信頼性が高まります。 

開発者が通常、PRD（プロダクト要件定義書）でどのように要件を記述するかを考えてみましょう。

注文が発送されたら、ユーザーに通知を送信する必要があります。 

多くの関係者はこの要件文の意図を理解できます。しかし、いくつかの重要な点には解釈の余地が残ります。どの種類の通知を送るべきでしょうか。誰に送るべきでしょうか。いつ送信すべきでしょうか。配信に失敗した場合は、どのように処理すべきでしょうか。 

EARSを使用すると、同じ要件は次のようになります。

注文ステータスが「発送済み」に変更された場合
システムは、5分以内に顧客の登録済みメールアドレスに電子メール通知を送信するものとする。

ビジネス上の意図は変わりませんが、実装の詳細がはるかに明確になります。AIに漠然とした記述を解釈させるのではなく、要件によってトリガー、アクション、および期待される結果が明確に定義されます。この構造により曖昧さが軽減され、Claude Codeは初回で正しい実装を生成するためのより強固な基盤を得ることができます。

EARSの主要要件タイプ

EARSは少数の要件パターンに基づいて構築されています。これらのパターンはソフトウェア開発中に遭遇するほとんどのシナリオを網羅し、チームが仕様全体にわたって一貫性を維持するのに役立ちます。AI支援開発においては、これらのパターンによって予測可能な構造が構築され、要件の解釈と実装が容易になります。

従来の要件とEARS要件の比較

従来型の要件とEARS要件の違いは単なる書式の違いではありません。AIに推測させる内容と仕様として明示すべき内容の違いです。 

従来の要件「注文が発送されたら、ユーザーに通知を送るべきである。」AIはこの記述を読み取り、「通知」の意味、「発送済み」の意味、対象ユーザー、使用するチャネル、通知内容、通知が失敗した場合の処理​​方法などを判断しなければなりません。これらはすべて、実際のシステム要件ではなく、トレーニングデータに基づいてAIが行う判断です。

EARSの要件：「注文ステータスが『出荷済み』に変更された場合、システムはステータス変更後5分以内に顧客の登録済みメールアドレスにメール通知を送信する」。これにより、AIは実装すべき内容を正確に把握できます。トリガーはステータスが特定の値に変更されること、応答は特定のアドレスへのメール送信です。実行タイミングも明示されており、解釈の余地はほとんどありません。メール送信が失敗した場合の動作を指定したい場合は、エラー処理要件を追加します。

以下に、それぞれのケースでAIが判断しなければならない内容を並べて比較した表を示します。

どちらのバージョンも同じビジネスアイデアを伝えています。違いはEARSでは実装時に必要な解釈の多くを排除している点です。人間の開発者にとっては、これにより明確性が向上します。Claude Codeにとっては、生成すべき動作についてより明確なシグナルが得られます。

EARSはテストに適した入力を提供する 

EARSのもう一つの利点はテスト手法との自然な整合性です。多くのチームは既に、Given-When-Thenシナリオを通して受入基準を定義するために、振る舞い駆動開発（BDD）を使用しています。EARSは、トリガー、条件、および期待される結果を明確にすることで、同様の考え方に基づいています。

例えば、次のような要件があります。顧客のサブスクリプションの有効期限が切れた場合、システムはプレミアム機能へのアクセス権を取り消さなければなりません。

以下のようなGiven-When-Then形式のテストシナリオに変換できます。 

Given（前提条件）：有効なプレミアムサブスクリプションを持つ顧客がいる 

When（操作）：サブスクリプションが有効期限に達する 

Then（期待結果）：プレミアム機能にアクセスできなくなる 

この関係性はAIコーディングツールを使用する際に特に役立ちます。Claude Codeは実装、単体テスト、統合テスト、および受入基準の基礎として、同じ要件を使用できます。曖昧な記述からコードを生成するのではなく、AIは期待される動作を既に定義した仕様に基づいて動作します。

EARSはAI実行向け仕様書を作成するための完全なフレームワークではありません。ビジネスコンテキスト、ドメイン用語、技術的な制約、エッジケースなどは定義していません。しかし、システム動作を曖昧さを最小限に抑えつつ実装精度を高める形で記述するための強力な基盤を提供します。 

詳しく見る：Claude Codeのための仕様駆動開発：CafeKit、GitHub Spec Kit、BMAD、claude-code-spec-workflowの比較

AI実行向け仕様書の構成 

EARSはシステム動作を明確に定義するのに役立ちますが、AIコーディングの仕様書を作成するには、構造化された要件だけでは不十分です。Claude Codeがビジネス上の課題、対象ドメイン、遵守すべき技術的制約を理解するには、十分なコンテキストが必要です。 

よくある間違いは、EARS要件の集合体だけで実装が十分だと考えてしまうことです。実際には、2つのチームが全く同じ要件を提示しても、周囲の状況によって全く異なる結果が得られる可能性があります。そのため、AI活用に成熟した開発チームは人間によるレビューだけでなくAIによる実行も想定した、AI実行向け仕様書へと移行しつつあります。

フォーマットは組織によって異なりますが、効果的なAI実行向け仕様書には、いくつかの共通する中核要素があります。 

背景と目標

要件を定義する前に、仕様書ではその機能が存在する理由と、それが解決する問題を明確にする必要があります。このセクションは、AIがより適切な実装判断を下すために必要なビジネスコンテキストを提供します。コンテキストがなければ、モデルは個々の要件を満たすことに集中し、機能の背後にあるより広範な目的を見失ってしまう可能性があります。

例えば、いきなり「顧客が割引コードを入力したら、システムは対応する割引を適用する」といった個別要件を列挙するのではなく、まず機能の目的を簡潔に説明します。例えば、「この機能の目的は、顧客がチェックアウト時に割引コードを利用できるようにすることでプロモーションキャンペーンの利用率を高め、同時に割引ルールがウェブとモバイルプラットフォーム全体で一貫していることを保証することです。」といった具合です。これにより、Claude Codeはその機能が実現しようとしているビジネス成果をより明確に理解できます。 

ドメイン用語集

AI生成コードで混乱が生じる主な原因の一つが用語の不統一です。多くの組織では、議論の中で似たような用語を区別なく使用していますが、こうした違いは実装時に大きな影響を及ぼす可能性があります。例えば、仕様書の中で「ユーザー」「顧客」「会員」「購読者」といった用語が使われている場合、それぞれ業務上の異なるエンティティを表しているにもかかわらず、混乱が生じる可能性があります。

AI実行向け仕様書には、実装開始前に主要なドメイン概念を定義する用語集を含める必要があります。

EARSを使用した機能要件

文脈と用語が確立されたら、一貫した構造を用いて機能要件を定義する必要があります。ここでEARSがシステム動作を記述するための主要なメカニズムとなります。自由形式の記述に頼るのではなく、各要件はトリガー、条件、および期待される応答を明確に定義します。

EARSの5つのパターンはソフトウェア開発で一般的に発生するシナリオを網羅しています。常に適用される普遍的な動作、特定のアクションによってトリガーされるイベント駆動型の動作、システムの状態に依存する状態駆動型の動作、特定の条件下でのみ適用されるオプション機能、そして問題が発生した場合のエラー処理です。

エラー処理要件は特に重要です。チームは正常系に意識が偏り、例外処理を見落としがちだからです。クーポンコードが無効な場合に何が起こるかを指定しないと、AIはケースを無視するか、ビジネスルールに合わない動作を生成してしまう可能性があります。イベント駆動型の要件ごとに、操作が失敗した場合に何が起こるかを示す対応するIF条件を少なくとも1つ記述してください。

割引システムの要件例：

• 顧客がチェックアウト時に有効な割引コードを入力した場合、システムは最終的な注文合計を計算する前に、該当する割引を適用するものとする。
• 割引コードの有効期限が切れている場合、システムはエラーメッセージを表示し、割引を適用しないものとする。
• 割引コードの使用制限を超えた場合、システムはその操作を拒否し、「このクーポンは使用制限に達しました」と表示する。
• 注文が確定済みの状態で顧客がクーポンを適用した場合、システムは変更を拒否し、「確定済みの注文は変更できません」と表示する。
• 2人の顧客が同時に同じクーポンを適用した場合、システムはそれらの処理を順次実行し、使用制限を正しく適用するものとする。

これらの要件は予測可能な構造に従っているため、レビュー担当者とAIコーディングエージェントの両方にとって理解しやすくなっています。例外処理の方法をAIが推測する必要はありません。例外は明示的に文書化されているからです。

受入基準

要件はシステムが何を行うべきかを定義します。受入基準は成功をどのように測定するかを定義します。このセクションは、異なる関係者が同じ要件を異なる方法で解釈することを防ぐのに役立ちます。また、AIが生成した実装の明確な検証目標も提供します。多くのチームは、人間が読みやすくテストしやすいという理由から、BDDスタイルの形式を使用しています。

例：

Given（前提条件）：有効な割引コードが存在する 

When（操作）：顧客がチェックアウト時にそのコードを適用する 

Then（期待結果）：正しい割引額が注文合計金額に反映される 

受入基準 はビジネス上の期待と実装結果との間に直接的なつながりを生み出します。

技術的な制約

AIが生み出す不必要な複雑さの最大の原因の一つは技術的なガイダンスの欠如です。制約が与えられていない場合、Claude Codeはシステムの他の部分とは異なる新しいパターン、依存関係、またはアーキテクチャアプローチを導入する可能性があります。専用の技術的制約セクションを設けることで、このリスクを大幅に軽減できます。

例としては以下のようなものがあります。

• 既存のリポジトリパターンを使用すること
• 顧客とのすべてのコミュニケーションには、既存の通知サービスを再利用すること
• 新しいサードパーティ依存関係を追加しないこと 
• プロジェクト既存のAPIレスポンス形式に従うこと
• 通常負荷時のレスポンスタイムを500ms未満に抑えること

バリデーションルールとビジネスルール

多くの要件が失敗する原因はバリデーションロジックが明文化されず、暗黙の前提として扱われていることにあります。例えば、仕様書に「割引コードの入力を検証する」とだけ記載されている場合、解釈の余地が大きすぎます。

より厳格な仕様では、ルールが明確に定義されています。

• 割引コードの長さは50文字以内である必要があります。
• 割引コードの照合では、大文字と小文字を区別しません。
• 有効期限切れのコードは使用できません。
• 割引コードは併用可能と明示されている場合を除き、他の割引コードと併用できません。 

ビジネスルールが具体的であればあるほど、AIが実装時に推測する必要のある部分は少なくなります。

テストシナリオと完了の定義

最終セクションでは、その機能がどのように検証されるか、そしていつ完成したとみなされるかを定義する必要があります。

これにより、開発者とAIコーディングエージェントの双方に明確な完了条件を提示できます。 

完了の定義には以下が含まれる場合があります。

• すべてのEARS要件が実装されていること 
• 単体テストおよび統合テストに合格していること 
• 受入基準を満たしていること 
• 重大なセキュリティ上の問題がないこと 
• 関連ドキュメントが更新されていること 

これらの要素を組み合わせることで、従来の要件定義書をAI実行向け仕様書へと変換できます。EARSは動作を記述するための構造を提供し、コンテキスト、用語、制約、バリデーションルールは、Claude Codeがビジネス上の期待に沿ったコードを生成するために必要な情報を提供します。しかし、最も構造化された仕様書であっても、重要なエッジケースが見落とされると失敗する可能性があります。そのため、例外、障害シナリオ、境界条件を文書化することが、次の重要なステップとなります。

CafeKitを使用してAI実行向け仕様書を構築する 

優れた仕様書を作成することは課題の一部に過ぎません。エンジニアリングチーム全体でAIの導入が進むにつれて、組織はすぐに別の問題に気づきます。それは、要件、ビジネスコンテキスト、アーキテクチャ上の決定、およびドメイン知識を長期にわたって一貫性を保つことです。

単一の機能仕様には、数十ものEARS要件、バリデーションルール、エッジケース、および受入基準が含まれる場合があります。これを複数のチームやプロジェクトにまたがらせると、信頼できる唯一の情報源を維持することが、ますます困難になります。情報が文書、チケット、会議メモ、チャットの会話などに分散している場合、AIコーディングエージェントは不完全または古いコンテキストを受け取ることがよくあります。

そこで価値を発揮するのが、CafeKitのようなプラットフォームです。 

CafeKitは仕様書を独立した文書として扱うのではなく、AIコーディングエージェントが依存するより広範なコンテキストをチームが管理できるように支援します。要件、ビジネスルール、ドメイン用語、および関連知識を構造化された形式で整理できるため、人間とAIの両方が同じ情報に容易にアクセスできます。

CafeKitについて詳しく見る：｢Vibe Coding」を超えて：CafeKitがAI自動化にもたらす仕様駆動開発（SDD）

ビジネスコンテキストの一元化

AI実装エラーの最も一般的な原因の一つはコンテキストの断片化です。ビジネス要件は一つのドキュメントに、アーキテクチャ上の決定事項は別のドキュメントに、そして専門用語は全く別の場所に記載されているといった具合です。経験豊富な開発者であればこうしたギャップをうまく処理できますが、重要な情報が複数のソースに分散している場合、AIエージェントは困難に直面します。

一元化されたナレッジベースは要件と関連コンテキストに関する、信頼できる唯一の情報源を構築することで、この問題を軽減します。Claude Codeは推測に頼るのではなく、既に文書化されレビュー済みの情報に基づいて作業できます。これにより、AIが分散した情報源から不完全な情報をつなぎ合わせて推測する必要がなくなります。 

一貫したドメイン知識の維持

システムが大きくなるにつれて、用語の重要性はますます高まります。顧客、会員、購読者、ユーザーといった概念は似ているように見えますが、実際には異なるビジネスエンティティを表している場合が少なくありません。共通の用語集がないと、不整合が要件、コード、API、ドキュメントに急速に広がる可能性があります。AIによる実装は、モデルが用語を文字通りに解釈する傾向があるため、特にこの問題の影響を受けやすいと言えます。

ドメイン定義を一元的に管理することで、チームは曖昧さを減らし、AI支援開発ワークフロー全体の一貫性を向上させることができます。AIが「プレミアム顧客」の意味を正確に理解すれば、微妙なエラーを発生させることなく、関連するビジネスルールを正しく実装するコードを生成します。

アーキテクチャ上の意思決定の維持 

要件はシステムが何を行うべきかを説明するものであり、アーキテクチャ上の決定事項はシステムをどのように構築すべきかを説明するものです。これらの決定事項は、設計パターン、インフラストラクチャの選択、統合アプローチ、パフォーマンス制約などのトピックを網羅したアーキテクチャ決定記録（ADR）によって文書化されることがよくあります。開発者はこれらの決定事項を既に理解しているかもしれませんが、AIエージェントは実装時にアクセス可能な場合にのみ、それらに従うことができます。

AIにアーキテクチャに関するガイダンスを提供することで、確立されたエンジニアリング標準からの不必要な逸脱を減らし、一貫性のないソリューションを導入するリスクを低減できます。Claude Codeはチームがリポジトリパターンを使用し、特定のAPI規約に従っていることを認識すると、リファクタリングを必要とする新しいパターンを導入するのではなく、既存のコードベースや設計方針と整合するコードを生成します。

Claude Codeのワークフローを改善する

現在、多くのチームが単純なプロンプトベースの開発から、仕様主導型のワークフローへと移行しつつあります。Claude Codeに単に「機能を作ってください」と指示するのではなく、開発プロセスを次のように構造化します。 

1. ビジネス目標と要件を定義する。
2. EARSの要件と受入基準を文書化する。
3. エッジケースとバリデーションルールを整理・文書化する。
4. アーキテクチャ上の制約と、それを裏付ける背景情報を提供する。
5. 仕様に基づいて実装とテストを生成する。

このアプローチはモデルによる推測を減らし、明確に定義された要件の実装に集中できるため、AI支援開発の基盤を大幅に強化します。その結果、コード生成の質が向上するだけでなく、実装の一貫性が高まり、手戻りが減り、ビジネス上の期待とエンジニアリングの成果との整合性が向上します。最終的に、Claude Codeのようなツールは、構造化された仕様環境内で動作することで、その効果を飛躍的に高めます。

 結論

AIコーディングの仕様書を作成することは人間の開発者向けの要件書を作成することとは根本的に異なります。人間の開発者は仕様書を解釈し、質問、不足している部分を補います。Claude Codeはユーザーが指定した内容を実行します。仕様や周辺コードが曖昧な場合は、利用可能なコンテキストに基づいて最適な推論を行います。EARSは、トリガー、条件、応答を明示するための構造を提供し、要件の曖昧さを抑えます。CafeKitは、AIエージェントがビジネスの期待に沿ったコードを生成するために必要なワークスペースとワークフロー（コンテキスト、用語、制約、バリデーションルール）を提供します。

Haposoftでは、これらの手法をプロジェクトで積極的に活用しており、コード品質と開発速度の向上に取り組んでいます。CafeKitはオープンソースとして早期利用が可能です。ぜひインストールして、AIが実行しやすい仕様書の作成を体験してみてください。ご質問やご相談がございましたら、お気軽にご連絡ください。弊社が得た知見も喜んで共有いたします。 

---

これを実践に移す準備はできましたか？

CafeKitはオープンソースであり、早期利用が可能です。インストールして、実際に動作するAIコーディングの仕様書を作成しましょう。

bash

npx @haposoft/cafekit

GitHub Repository →