業務要件・受入条件とAPI契約を分け、AIが参照できる設計図を作る
2026-10-10訂正:OpenAPI/ProtobufだけがコーディングAIに読ませられる形式、という説明を訂正しました。Markdownの要件・受入条件、エージェントへの作業指示、API契約を分担させます。以下は公開一次資料を踏まえた設計案です。実ワークフローの稼働、生成品質・工数・費用の改善は本記事では検証していません。
はじめに:仕様書は「コードの種(Seed)」であり「SSOT」である
仕様書は、人間が要件を確認し合意するためにも、AIが実装・レビューの根拠を参照するためにも使います。形式を整えるだけで、実装完了や整合性の監視が保証されるわけではありません。
ここでは SSOT(単一の信頼できる情報源) を「全情報を一つのファイルに詰めること」ではなく、要件・API契約・実装方針ごとに正本と更新責任を決め、相互の参照を維持することとして扱います。
無秩序な入力や矛盾した前提は、誤った生成・レビューの原因になり得ます。本記事では、AIが参照しやすい仕様、Gitベースの変更管理、Context ETL(入力情報の整理)、防御的Agentic Workflowを設計上の選択肢として解説します。
ベストプラクティス1:Context ETLと「論理の重力(Gravity)」の制御
素材をそのまま放り込むのはアンチパターンです。
入力が多い場合は、Dify等で情報を整理し、衝突時の扱いを明示する方法があります。少量の要件なら、手動整理と通常のレビューでも構いません。
1. Dify「Question Classifier」による文脈の階層化
DifyのQuestion Classifierは、定義したクラスへ入力を分類し、対応するワークフローに分岐させるノードです。以下の分類は本記事の設計例であり、不足の検出や聞き返しは別途設計・検証します。公式説明
- Level 1: Core Requirements (事実/制約): DB定義、セキュリティ制約、API仕様。
- Level 2: Supplementary Info (意図/参考): ユーザーインタビュー、Vibe、過去の経緯。
2. Weighted Priority & Conflict Resolution Policy(紛争解決)
「セキュリティ制約」と「パフォーマンス要件」が衝突した場合、AIが承認されていない妥協案を出す可能性があります。
- 設計の規律: 衝突時はConflict Reportを出して保留するよう指示します。プロンプトだけに依存せず、未解決の状態から次工程へ進めない分岐と、人間の承認を確認する処理を実装します。
3. 情報の鮮度管理(Metadata Weighting & TTL)
メタデータには根拠の出典、確認日、適用期間、承認状態を残します。日付が新しいだけでは、正確・承認済みとは判断しません。
流動的な要件は再確認期限を設け、期限切れを現行の判断材料から除外する設計を検討します。履歴は保持し、削除は保存方針と権限に従います。TTLや除外処理が製品の標準機能として自動実行される、という意味ではありません。
ベストプラクティス2:仕様形式の分担と「不変条件(Invariants)」
Markdownでも、業務要件・受入条件・例外を明確にすればAIへの入力になります。APIやデータの契約が必要な箇所には、用途に合ったスキーマを併用します。
1. AIが参照しやすい仕様を、用途ごとに分ける
本記事ではLRS(LLM-Readable Spec)を「AIが参照しやすく整理した仕様」という説明上の呼び名として使います。固有の標準フォーマットや、特定製品が必須とする形式ではありません。
OpenAPI/Protobufは、コーディングAIが読める唯一の形式ではありません。 CursorはMarkdownのAGENTS.mdや.mdcのProject Rulesを作業指示として扱います。GitHub Spec Kitの仕様テンプレートもMarkdownで、利用シナリオ、受入条件、要件、未確定事項を記載します。Cursor Rules、Spec Kit仕様テンプレート
| 資料・形式 | 主に記す内容 | 確認すること |
|---|---|---|
| Markdownの業務要件・受入条件 | 利用者、目的、業務ルール、正常・異常時の期待結果、未確定事項 | 要件の合意と、受入条件に対応するテスト |
AGENTS.md/Project Rules |
コード構成、作業範囲、レビュー・検証手順 | 適用範囲と実際の検証結果。指示文をアクセス制御の代わりにしない |
| OpenAPI | HTTP APIのパス、入出力、エラー、認証方式等の契約 | 仕様の検証と、実装との契約テスト |
Protobuf(.proto) |
構造化データやRPCのメッセージ・サービス定義 | コンパイル、互換性、実装との結合テスト |
OpenAPIはHTTP APIの記述、Protobufは構造化データの定義・シリアライズ等に使います。プロジェクトの方式に応じて選び、仕様ファイルだけで業務要件や実装品質を保証しないようにします。OpenAPI 3.1.1、Protocol Buffers概要
2. 「不変条件(Invariants)」の抽出と検証
システムが維持すべき性質をAIに候補として挙げさせ、人間が業務ルールと照合します。論理式を書いたりテストしたりすることだけで、形式検証・数学的証明を完了したとは扱いません。
- 不変条件の例: $Stock \ge Reserved$ (在庫数は常に予約数以上でなければならない)
3. 仕様から検証コードへの変換
抽出した不変条件をZodスキーマやSQLのCHECK制約として表現できるか検討します。生成したものは候補として保存し、構文・境界値・並行更新時の動作を確認してから採用します。
n8nを使うなら、LLMによる候補生成、Codeノードによる結果の整形・検査、Gitの差分レビューを別工程にします。Codeノードが実行する言語はJavaScriptまたはPythonです。TypeScriptやSQLを文字列として生成・整形することと、その言語で検証・実行することは別です。n8n Codeノード
ベストプラクティス3:防御的Agentic WorkflowとGitベースの双方向同期
一回の生成で誤りを見落とす可能性があるため、重要な変更では生成とレビューの役割を分ける方法があります。ただし、複数エージェントの合意も正しさの証明ではありません。Gitで変更履歴を残し、実際の検証結果と人間の承認を組み合わせます。
1. Git-based Spec Management と Diff-Centric Review
Git-based Spec Management(Gitベースの仕様管理)とは、仕様書(スペック)をコードと同様にGitリポジトリで管理し、バージョン管理やレビューのプロセスに組み込む手法です。
特に近年、GitHubがリリースした Spec Kit の登場により、AIを活用した「仕様駆動開発(Spec-Driven Development)」としての注目が高まっています。
Diff-Centric Review(差分中心のレビュー)とは、仕様やコードの「変更点(Diff)」そのものに焦点を当て、その妥当性を検証するレビュー手法です。
Gitベースの仕様管理では、「何がどう変わったか」という差分からレビューを始めます。必要な周辺仕様と照合し、効率や精度の改善は実際の運用で評価します。
仕様と実装を同じ変更単位でレビューしたい場合、Gitリポジトリで管理する方法が有効です。Gitに置くだけで仕様の乖離が防げるわけではなく、Wikiでも更新責任・レビュー・検証を設計する必要があります。
AIによる仕様更新はPRの提案として扱い、人間は差分と意図に加え、関連要件・API契約・テスト結果を確認します。仕様と実装の双方向同期は、この更新手順として設計するもので、Gitだけで自動的に成立する機能ではありません。
2. 役割の分担と実装から仕様へのフィードバック
ここで行うのは仕様への差し戻しです。ニューラルネットワーク学習のバックプロパゲーションとは別の処理です。
- Agent A (PM): ビジネス要件からドラフトを作成。
- Agent B (Engineer): LRSや既存スキーマとの矛盾を突き、実装の穴を埋める。
- Agent C (Feedback): 実装で判明した制約を仕様レビューへ差し戻し、正本の更新案を作る。未承認の案を確定済みの仕様として扱わない。
3. 再試行上限と人間の判断のADR保存
Architecture Decision Record (ADR) とは、ソフトウェア開発において下された 「重要な設計上の意思決定」とその背景、理由、結果を簡潔に記録するドキュメント です。
単に「何を決めたか」だけでなく、「なぜその選択をしたのか」「どのような代替案を検討し、なぜそれらを却下したのか」といったコンテキストを残すことに重点を置いています。これにより、数年後に新しいメンバーが加わった際や、技術選定を再検討する際に「当時の状況」を正確に把握でき、同じ議論の繰り返しを防ぐことができます。
AI同士をループさせると無限に再試行を繰り返すリスクがあります。
- 再試行上限の設計例: 初回を含めて最大3回とし、3回目でも未解決なら保留状態で停止します。Conflict Reportは人間のレビュー対象です。通知や再開条件を別途設計します。単なる回数上限を、障害時に遮断・回復を管理するサーキットブレーカーと同一視しません。
- 人間の判断とADR: 承認された判断、根拠、代替案、制約をMarkdownのADR案にまとめ、機密情報を除いてレビューします。ログ全文を無条件に保存せず、コミット・マージはリポジトリの権限と承認手順に従います。
ベストプラクティス4:FinOpsとしてのコスト管理
全ての変更に複数エージェントのループを適用すると、費用・待ち時間・レビュー量が増える場合があります。次は、リスクに応じて検証の強度を変える設計例です。人数や役割数だけで品質を判断せず、呼出し回数、トークン、再試行、人間の確認時間を実測します。
| ティア対象機能 | ワークフロー強度 |
|---|---|
|
Tier 1 (Core) 決済、認証、認可、基幹ロジック |
独立レビュー・人間承認、契約・権限・状態遷移のテスト。必要なら専門的な形式検証 |
|
Tier 2 (High) 新機能、外部API連携、複雑なUI |
生成とレビューを分け、スキーマ・結合・受入条件を検証 |
|
Tier 3 (Normal) 文言変更、既存画面の微調整 |
小さな差分のレビューと必要な表示・操作確認 |
2026年式:分離型「実行可能プロンプト」集
以下は役割ごとの指示例です。プロンプトは入力を整理する手段であり、権限管理、状態の保留、テスト、承認処理は別途実装・確認します。
1. 【ドラフト生成】PMエージェント用
あなたは経験豊富なシニアPMです。インプット情報を「Core」と「Supplementary」に分類し、仕様書ドラフトを作成してください。
プロジェクトで承認済みの優先順位に従ってください。未定義なら推測で確定しないでください。
衝突・不足は「Conflict Report」に記載し、未解決状態として返してください。
業務要件・受入条件・未確定事項はMarkdownで整理してください。
HTTP APIが対象なら採用バージョンのOpenAPI、Protobuf採用箇所なら.protoの契約案を添えてください。
作業・検証手順は既存のAGENTS.md等に従い、資料間の参照と正本を明示してください。
2. 【攻撃的レビュー】エンジニアエージェント用
あなたはリードエンジニアです。Markdownの要件・受入条件、該当するAPI契約、既存スキーマを照合し、矛盾、PII(個人情報)露出リスク、技術的負債をレビューしてください。
実装不能な箇所は具体的な制限事項と共に「Feedbackエージェント」へ差し戻しを要求せよ。
[Git制約] 修正案には変更意図と必要な検証を添えてください。コミットメッセージはリポジトリの規約に従う案とし、この指示だけでコミット・マージ・公開を実行しないでください。
3. 【検証・不変条件定義】QAエージェント用
あなたはQAシニアエンジニアです。仕様から、システムが維持すべき不変条件の候補を抽出してください。
受入条件を、データ検証・業務ロジック・API結合・利用者操作のどこで確認するか分類してください。
テストやスキーマの候補と未検証箇所を示してください。JSON化やテスト生成だけで検証済みとは扱わないでください。
おわりに
AI向けの仕様では、業務要件・受入条件、作業指示、API契約の役割を分け、生成結果を検証できる形にすることが重要です。Markdownとスキーマは、その目的に応じて併用できます。
まず小さな機能で、要件と受入条件をMarkdownに整理し、該当するAPI契約とテストを対応付けます。未解決事項、検証結果、承認状態を残し、生成・レビュー・運用の費用と改善効果を確認してから、適用範囲を広げます。バグのないコードや高速化を、形式やエージェント数だけで保証しないようにします。
この記事を書いた人✏️@YushiYamamoto
ITPRODX.com代表。AI × Web × 業務自動化の開発・検証に取り組んでいます。
技術選定・品質・運用の判断材料を、検証範囲と制約を示して発信しています。
AI導入や業務自動化の技術選定・設計整理については、対応できる範囲を確認のうえご相談を承ります。
