要件定義・仕様書・設計書が誤っていた場合の開発破綻リスクと対策提案
0. 結論
ご懸念は正しいです。要件定義書、仕様書、技術要件、アーキテクチャ、SDD、テスト計画、テストハーネス設計をAIとリサーチで作ること自体は有効ですが、それらを「正しい完成物」として扱うと危険です。特に非エンジニアが発注者・企画者である場合、文書が立派に見えても、実装不能、運用不能、修復不能、法務・規約違反、外部API制限超過、セキュリティ欠陥、データ消失などに気づけない可能性があります。
したがって、最終版リサーチプロンプトには、単に情報を集めて成果物を生成するだけでなく、証拠管理、反証、独立レビュー、トレーサビリティ、MVP検証、テストハーネス、CI品質ゲート、ロールバック、バックアップ、変更管理、障害復旧、人間承認ゲートを最初から組み込むべきです。
重要な考え方は、「完璧な文書を一発で作る」ではなく、間違っていても早期に検知でき、壊れても戻せ、素人でも赤信号を判断できる開発運用にすることです。
1. 今回の最終版リサーチプロンプトに残る主なリスク
最終版リサーチプロンプトは、SNS、YouTube、note、論文、公式ドキュメント、GitHub、コミュニティなどから材料を集め、要件定義・仕様書・設計書へ落とし込む設計です。この方向性は正しい一方で、以下のリスクが残ります。
| リスク | 何が起きるか | 素人が気づきにくい理由 | 対策 |
|---|---|---|---|
| 情報の信頼性リスク | SNSやnoteの成功事例を一般解として採用してしまう | 体験談と再現性ある設計知識の区別が難しい | 情報源ランク付け、一次ソース優先、反証調査を必須化 |
| 要件の過剰化 | MVPに不要な機能までMust化され、実装不能になる | 「あった方がよい」と「最初に必要」の区別が難しい | Must / Should / Later / Reject分類とMVP境界を固定 |
| 外部API依存リスク | note、Substack、Kindle、YouTubeなどのAPI・規約・自動化制限で詰まる | 規約、API制限、審査、OAuth、レート制限が見えにくい | 公式API・規約・代替手段・手動介入点を事前調査 |
| アーキテクチャ不整合 | 設計図は立派でも、データ、認証、ジョブ、エラー処理がつながらない | 図がきれいだと正しく見える | C4、ADR、シーケンス、データフロー、障害フローを必須化 |
| SDDの曖昧さ | 実装者が解釈できず、コードがバラバラになる | 「仕様っぽい文章」と「実装可能な仕様」の違いが難しい | API契約、状態遷移、例外、境界値、受入基準を明文化 |
| テスト不足 | 成功パターンだけテストされ、失敗時に壊れる | テストの種類と粒度を判断しにくい | テストピラミッド、契約テスト、E2E、回帰、スモークを定義 |
| テストハーネス不足 | 外部サービスを安全に模擬できず、開発中に実データや本番を壊す | モック、スタブ、サンドボックスの必要性が見えにくい | APIスタブ、録画再生、テストデータ、隔離環境を必須化 |
| 変更不能化 | コードやDBが壊れ、どこから戻せばよいか分からない | Git、マイグレーション、バックアップの運用が難しい | 小さなPR、タグ、バックアップ、DB rollback、復旧手順を必須化 |
| AI過信リスク | CodexやOpusのレビューを正しいものとして採用してしまう | もっともらしい文章に弱い | AIレビューは仮説扱い、実ファイル・一次ソース・テストで検証 |
2. 調査で確認した信頼できる根拠
NIST SSDFは、セキュア開発をPrepare、Protect、Produce、Respondの実践群として整理し、開発前の準備、ソフトウェア保護、脆弱性の検出・対応、再発防止を重視しています。これは、要件定義や設計書を作った時点で終わりではなく、実装後の検知・対応・改善までを含めて設計する必要があることを示します。1
OWASP SAMMは、ソフトウェアライフサイクル全体にわたってセキュリティ活動を測定可能に改善するモデルです。特定技術に依存せず、リスクに応じた成熟度管理ができるため、素人がAI生成文書を扱う場合にも、チェックリストと成熟度評価の土台として有効です。2
OWASP ASVSは、Webアプリケーションの技術的セキュリティコントロールを検証する標準であり、開発者向けのセキュア開発要件リストとしても使えます。特に、要件IDを付けてセキュリティ要件をトレースする運用に向いています。3
GitHub Actionsは、ビルド、テスト、デプロイなどのソフトウェア開発ワークフローを自動化する仕組みです。素人が開発品質を判断できない場合でも、CIにより「赤なら進めない」「緑なら次へ進む」という機械的な品質ゲートを作れます。4
テストピラミッドの考え方では、単体テストを多く、統合テストを適量、E2Eテストを少数にし、粒度の異なるテストを組み合わせることが推奨されます。これは、全てを手動確認やE2Eテストに頼ると遅く不安定になるためです。5
IEEE 29148は、システムおよびソフトウェアの要求仕様に関する標準として参照されます。要求品質、利害関係者要求、システム要求、ソフトウェア要求を分ける考え方は、要件定義書の「型」を作るうえで重要です。6
C4 modelは、ソフトウェアアーキテクチャをContext、Container、Component、Codeの階層で表現する手法です。素人にとっても、システム全体像、外部サービス連携、主要コンポーネント、実装単位を段階的に理解しやすくする効果があります。7
ADR、すなわちArchitecture Decision Recordsは、重要な設計判断を、背景、決定、結果として記録する軽量な方法です。AIや開発者が後から方針を変更するときに、なぜその設計にしたかを追跡できます。8
3. 最大の対策方針: 文書品質ではなく「安全な開発運用」に寄せる
要件定義や設計書を完璧にしようとすると、紙の議論が増え、実装前に疲弊します。一方で、文書が不完全なまま大きく実装すると、修復不能になります。したがって、最も安全な方針は次の通りです。
| 層 | 対策 | 目的 |
|---|---|---|
| リサーチ層 | 一次ソース、公式API、規約、反証、競合事例を確認 | 誤情報を減らす |
| 要件層 | Must / Should / Later、受入基準、非目標を定義 | 作りすぎを防ぐ |
| 設計層 | C4、ADR、データフロー、障害フローを作成 | つながらない設計を防ぐ |
| 実装層 | 小さいPR、ブランチ、タグ、コードレビュー | 壊れる範囲を限定する |
| テスト層 | 単体、統合、契約、E2E、回帰、スモーク | バグを早期検知する |
| ハーネス層 | モック、スタブ、サンドボックス、テストデータ | 外部サービスや本番を壊さない |
| CI層 | 自動テスト、lint、型チェック、セキュリティスキャン | 素人でも赤/緑を判断できる |
| リリース層 | 段階リリース、ロールバック、バックアップ | 失敗時に戻せる |
| 運用層 | ログ、監視、アラート、手動停止スイッチ | 障害を検知し止血する |
| レビュー層 | Codex、Opus、人間承認、証跡台帳 | AIの見落としを減らす |
4. 「正しいか分からない」問題への対策
素人が設計の正しさを判断できない場合、判断を人間の感覚に任せず、機械的なゲートにします。
| 判定対象 | 素人向け判定方法 | 赤信号 |
|---|---|---|
| 要件定義書 | 各Mustに受入基準とテストIDがあるか | Mustなのに検証方法がない |
| 仕様書 | 入力、出力、例外、権限、状態遷移があるか | 正常系だけで異常系がない |
| 技術要件 | API制限、認証、データ保存、費用、規約が確認済みか | 公式情報がない、SNS根拠だけ |
| アーキテクチャ | C4 Context / Container / Componentが揃うか | 外部サービスとの境界が曖昧 |
| SDD | 実装単位、API契約、DB設計、エラー処理があるか | 実装者が勝手に解釈する余地が大きい |
| テスト計画 | 単体、統合、契約、E2E、回帰、スモークが分類済みか | E2Eだけ、または手動テストだけ |
| テストハーネス | 外部APIを使わずにテストできるか | 本番API・本番データでしか確認できない |
| 復旧設計 | バックアップ、ロールバック、停止手順があるか | 壊れたときの戻し方がない |
5. 「作った通りに開発してダメだった」場合の対策
最も重要なのは、失敗した後に直すことではなく、失敗しても壊れる範囲を小さくすることです。
| 破綻パターン | 事前対策 | 破綻後の復旧策 |
|---|---|---|
| コードが壊れる | 小さいPR、テスト必須、main直コミット禁止 | 最後に通ったタグへ戻す |
| DBが壊れる | マイグレーション、バックアップ、seedデータ | バックアップ復元、逆マイグレーション |
| 外部APIで失敗 | モック、スタブ、サンドボックス、レート制限検証 | API連携をOFFにする機能フラグ |
| 認証が壊れる | OAuthフローのハーネス、テストアカウント | 連携解除、再認証手順 |
| 自動投稿が暴走 | dry-run、承認キュー、投稿上限、kill switch | ジョブ停止、投稿削除、トークン失効 |
| 要件が間違う | MVP検証、受入基準、ユーザーテスト | 要件変更台帳に戻して再設計 |
| AI修正で悪化 | 変更差分レビュー、テスト、Codex/Opus再確認 | 変更前コミットへrevert |
| 修正不能になる | バックアップ、タグ、環境分離、ログ保存 | 初期化手順で再構築 |
6. note、Substack、Kindle、YouTube自動化のような案件で特に危険な点
この種の「複数プラットフォーム自動化」は、通常のWebアプリよりリスクが高いです。理由は、外部サービスの仕様変更、規約、自動化制限、アカウント停止、OAuth、API制限、投稿ミス、著作権、二重投稿、重複課金、収益化ポリシーなどが絡むからです。
| 領域 | 必ず調べること | 成果物への反映先 |
|---|---|---|
| 公式API | API提供有無、認証方式、レート制限、利用可能操作 | 技術要件、SDD、テストハーネス |
| 利用規約 | 自動投稿、自動生成、スクレイピング、商用利用の可否 | 要件定義、リスク台帳 |
| コンテンツ権利 | 著作権、引用、AI生成物、画像・音声・動画利用 | 仕様書、運用ルール |
| 投稿フロー | 下書き、予約投稿、承認、削除、編集、再投稿 | SDD、受入基準 |
| 失敗時処理 | 投稿失敗、重複投稿、途中停止、API障害 | アーキテクチャ、テスト計画 |
| データ保持 | 原稿、メタデータ、投稿ID、ログ、トークン | データ設計、セキュリティ要件 |
| 人間承認 | 完全自動か、公開前承認を挟むか | 要件定義、運用設計 |
特に最初から「完全自動公開」にするのは危険です。最初は、完全自動生成ではなく、半自動生成＋人間承認＋dry-run＋下書き保存にするべきです。
7. 最終版リサーチプロンプトに追加すべき安全要件
既存の最終版リサーチプロンプトには、以下の章を追加することを推奨します。
# 追加章: 開発破綻防止・素人運用安全設計
このリサーチでは、要件定義書や設計書を作るだけでなく、それらが誤っていた場合に開発が破綻しないための予防・検知・復旧策を必ず調査する。
## 必ず調査すること
1. 公式API、利用規約、レート制限、OAuth、商用利用、自動化制限。
2. 外部サービス停止、仕様変更、API廃止時の代替案。
3. データ消失、重複投稿、誤投稿、課金事故、アカウント停止のリスク。
4. 本番環境を壊さずに検証するためのサンドボックス、モック、スタブ、dry-run設計。
5. 素人でも判断できるCI品質ゲート、赤/黄/緑の判定基準。
6. Git、タグ、バックアップ、DBマイグレーション、ロールバックの最低運用。
7. AI生成コードを安全に検証するためのCodex/Opusレビュー、テスト、差分確認。
8. 完全自動化する前に、人間承認を挟むべき工程。
9. 修正不能になった場合に、最後に動いていた状態へ戻す復旧手順。
10. 要件・設計・実装・テスト・ハーネス間のトレーサビリティ。
## 必須出力
- 開発破綻リスク台帳
- 素人向け赤/黄/緑ゲート表
- ロールバック設計
- バックアップ設計
- CI品質ゲート設計
- テストハーネス安全要件
- 外部API依存リスク表
- 規約・法務確認リスト
- 完全自動化前の人間承認ポイント
- Codex/Opus反復レビュー対象論点
8. 開発前に必ず作るべき追加成果物
要件定義書、仕様書、アーキテクチャ設計書、SDD、テスト計画書、テストハーネス設計書に加え、以下の成果物を必須化してください。
| 成果物 | 目的 | 素人にとっての価値 |
|---|---|---|
| Evidence Matrix | どの要件がどの情報源に基づくか記録 | もっともらしい嘘を減らす |
| Assumption Register | 仮説・未確認事項を管理 | 未確認を事実扱いしない |
| Decision Log / ADR | なぜその設計にしたか記録 | 後で変更理由が分かる |
| Traceability Matrix | 要件、仕様、設計、テストを接続 | 抜け漏れが見える |
| Risk Register | リスク、影響、対策、担当を管理 | 赤信号が見える |
| Rollback Plan | 壊れたとき戻す手順 | 修復不能を防ぐ |
| Backup Plan | コード、DB、設定、秘密情報の保全 | 消失を防ぐ |
| CI Gate Definition | 自動検査の通過条件 | 素人でも進行可否を判断できる |
| Human Approval Plan | 人間が承認すべき箇所 | 暴走自動化を防ぐ |
| Kill Switch Design | 自動処理を止める設計 | 誤投稿・暴走を止める |
9. 開発を始めてよい条件
以下を満たすまでは、実装開始ではなく、リサーチ・設計・PoC段階に留めるべきです。
| 条件 | 判定 |
|---|---|
| Must要件に受入基準がある | 必須 |
| Must要件にテストIDがある | 必須 |
| 外部API・規約の一次ソース確認がある | 必須 |
| 本番投稿せずに検証できるdry-runがある | 必須 |
| テストハーネスで外部APIを模擬できる | 必須 |
| mainブランチ保護、PR、CIがある | 必須 |
| 最後に動いた状態へ戻す手順がある | 必須 |
| DBバックアップと復元手順がある | 必須 |
| CodexレビューとOpus再分析が完了している | 必須 |
| Blockerがゼロである | 必須 |
10. 素人向けの赤・黄・緑判定
| 色 | 状態 | 次の行動 |
|---|---|---|
| 緑 | 自動テスト成功、Blockerなし、復旧手順あり | 次の小さい実装に進む |
| 黄 | 未確認事項はあるが、本番影響なし | PoCまたはLaterに隔離して進む |
| 赤 | 本番データ、外部投稿、課金、認証、DB破壊の恐れ | 実装停止、レビュー、復旧準備 |
11. Codex/Opusに追加でレビューさせるべき観点
AIレビューは、文書の文章品質ではなく、以下を重点的に確認させるべきです。
| 観点 | Codexに見せる理由 | Opusで再分析する理由 |
|---|---|---|
| 実装不能要件 | 技術的矛盾を発見 | 事業目的との関係で採否判断 |
| 外部API制約 | API仕様や制限を確認 | 回避策・MVP範囲を判断 |
| テスト不能要件 | 検証不可能な要件を発見 | 受入基準へ落とし込む |
| 復旧不能設計 | 壊れたとき戻せない箇所を発見 | Must/Blocker化する |
| 過剰設計 | 実装を重くする項目を発見 | Laterへ落とす |
| セキュリティ欠陥 | OWASP/NIST観点で確認 | 実装前Blocker判定 |
| 素人運用不能 | 運用手順が難しすぎないか確認 | 赤黄緑ゲートへ翻訳 |
12. 追加用リサーチプロンプト
以下は、既存の最終版リサーチプロンプトに続けて貼るための追加プロンプトです。
ここからコピー開始
あなたは、要件定義・仕様書・技術設計・アーキテクチャ・SDD・テスト計画・テストハーネス設計の破綻リスクを専門に評価するシニアソフトウェアアーキテクト兼SRE兼QAリードです。
今回の目的は、成果物をきれいに作ることではありません。目的は、非エンジニアがAIと開発者に依頼してシステムを作る場合でも、要件や設計が間違っていたときに、開発が修復不能にならないようにすることです。
対象プロジェクトについて、以下を徹底的にリサーチし、証拠付きで提案してください。
# 1. 調査対象
- 公式APIドキュメント
- 利用規約
- 開発者ポリシー
- レート制限
- OAuth・認証方式
- サンドボックス・テスト環境
- Webhook仕様
- データ保存・削除・エクスポート仕様
- コミュニティで報告されている失敗事例
- GitHub上の類似実装
- セキュリティ標準
- テスト自動化事例
- ロールバック・バックアップ・障害復旧事例
# 2. 必ず確認する一次ソース
- 対象サービスの公式ドキュメント
- 対象サービスの利用規約
- NIST SSDF
- OWASP SAMM
- OWASP ASVS
- GitHub Actions公式ドキュメント
- C4 model
- ADRに関する実務資料
- テストピラミッドに関する実務資料
# 3. 必ず作る成果物
以下をMarkdownで作成してください。
1. 開発破綻リスク台帳
2. 要件・仕様・設計の正しさ検証チェックリスト
3. 外部API依存リスク表
4. 利用規約・自動化制限チェックリスト
5. テストハーネス安全要件
6. CI品質ゲート設計
7. ロールバック設計
8. バックアップ設計
9. Kill Switch設計
10. 素人向け赤/黄/緑判定表
11. Codexレビュー用プロンプト
12. Opus再分析用プロンプト
# 4. 評価基準
各要件・仕様・設計項目について、以下を評価してください。
| 項目 | 評価 |
|---|---|
| 一次ソース根拠 | あり/なし/弱い |
| 実装可能性 | 高/中/低 |
| テスト可能性 | 高/中/低 |
| 復旧可能性 | 高/中/低 |
| 素人運用可能性 | 高/中/低 |
| 外部依存リスク | 高/中/低 |
| セキュリティリスク | 高/中/低 |
| MVPに必要か | Must/Should/Later/Reject |
# 5. NO-GO条件
以下のいずれかがある場合は、実装開始をNO-GOにしてください。
- Must要件に受入基準がない
- Must要件にテスト方法がない
- 外部APIや規約の一次ソース確認がない
- 本番環境を使わない検証方法がない
- 自動投稿や外部操作を止めるKill Switchがない
- DBや設定を壊したときの復旧手順がない
- mainブランチへ直接変更する運用になっている
- CIで自動テストが走らない
- APIキーやトークンの保護方針がない
- 誤投稿、重複投稿、課金事故、アカウント停止への対策がない
# 6. 出力形式
以下の順番で出力してください。
## A. 総合判定
GO / CONDITIONAL GO / NO-GO / ESCALATE
## B. 重大リスク一覧
| No | リスク | 影響 | 根拠 | 対策 | 判定 |
## C. 素人向け説明
専門用語を使いすぎず、何が危ないのか、どうすれば安全に進められるのかを説明してください。
## D. 修正すべき成果物
| 成果物 | 修正内容 | 理由 | 優先度 |
## E. 実装開始前チェックリスト
| チェック項目 | 必須/任意 | 状態 | 備考 |
## F. Codexに渡すレビュー依頼プロンプト
コピー可能な形で出してください。
## G. Opusに渡す再分析プロンプト
コピー可能な形で出してください。
ここまでコピー終了
13. 最終提案
最終版リサーチプロンプトは、要件定義や設計書の材料を集める目的としては有効です。ただし、現実の開発で最も危険なのは、立派な文書ができたことで安心してしまい、大きく実装してから壊れることです。
そのため、今後の標準フローは次のようにしてください。
| 順番 | 作業 | 目的 |
|---|---|---|
| 1 | リサーチ | 材料を集める |
| 2 | 要件・仕様・設計生成 | 仮説として文書化する |
| 3 | Evidence Matrix作成 | 根拠を紐づける |
| 4 | Codexレビュー | 技術的矛盾を探す |
| 5 | Opus再分析 | 採否と優先度を判断する |
| 6 | テストハーネス設計 | 安全に検証できるようにする |
| 7 | 小さいPoC | 本当に動くか確認する |
| 8 | CI品質ゲート | 素人でも赤/緑を判断できるようにする |
| 9 | MVP実装 | 最小範囲だけ作る |
| 10 | 段階リリース | 影響範囲を限定して公開する |
これにより、素人でも「文書が正しいか」を直接判断する必要が減ります。代わりに、一次ソース、テスト、CI、レビュー、ロールバック、バックアップ、赤黄緑ゲートで安全性を判断できます。