😽
Spec Kit で SRE AI Agent を開発する 〜 仕様をガン詰めしながら決める
本記事は MIXI DEVELOPERS Advent Calendar 2025 シリーズ2の 1日目の記事です。
個人的なミッションとして ”SRE AI Agent” を開発し本番運用させることを掲げています。
"SRE AI Agent" とは、SRE（Site Reliability Engineering）業務を支援するための自律的 AI エージェントです。
このエージェントは、システムの監視、障害対応、パフォーマンス最適化などのタスクを自動化し、SRE チームの負担を軽減することを目指しています。
開発スキルが ”Bash スクリプトの延長” である私でも AI エージェントを開発できるのか？ SDD にチャレンジしながら SRE AI Agent を開発しています。
チャレンジの最初の一歩は以下を参照ください。
仕様決めが大切
Spec Kit の思想は 「仕様が王様」 です。
ふわふわした仕様のまま実装へ突入すると、ふわふわしたコードが生成されます。これは LLM の責任ではなく指示を出している人間の責任です。
ということで、今回は仕様を固める方法を模索します。
仕様作成
Spec Kit の仕様作成コマンドは /speckit.specify でした。
今回は例として、SRE AI Agent に RAG 機能を付与する仕様を作成します。
/speckit.specify 仕様002 SRE AI Agent に RAG 機能を付与する。
RAG にはクラウドベストプラクティス、ユーザーガイド、過去のインシデント対応履歴、Runbook などを保存し、SRE AI Agent がユーザーから問い合わせに対して適切な回答を返す手助けをする目的で利用する。
しばらくすると SPEC.md ファイルが生成されます。
Coding Agent を使ったコーディングでは、直近の変更を無かったことにしたい場面がそこそこあるので、まめに git commit しておくことをお勧めします。
ここまでの変更を git commit して
仕様の明確化
/speckit.clarify コマンドを実行すると仕様の曖昧性検出と明確化を行ってくれます。
/speckit.clarify
しばらくすると以下の画像のように分析結果が表示されます。
SPEC.md ファイルの分析をしてくれていると思われます。
質問に回答していくと明確ではない箇所が順次明確になります。質問は大抵3択＋自由記入になっています。
選択肢に解決策があるならそれを選択、そうでない場合は短い回答を入力します。
考慮しなくてよい質問であれば "考慮不要"、"仕様外にする" などの指示をすれば OK です。
/speckit.clarify コマンドは繰り返し実行できます。納得いく仕様になるまで繰り返すのもありです。効果があるかは不明ですが。
/speckit.clarify コマンドを実行し終わったらコミットしておきましょう。
ここまでの変更を git commit して
実装計画の作成
仕様の明確化が完了したら、実装計画を作成します。
/speckit.plan 開発言語は Python 3.13 を採用する。AI Agent フレームワークは LangChain 1.0 と LangGraph 1.0 を採用する。
アプリケーション起動の環境変数で RAG DB を使い分ける。
想定している環境変数は以下の通り。
- run_mode=local -> ローカルの PostgreSQL (localhost:5432)
- run_mode=aws -> Amazon Bedrock Knowledge (現フェーズでは実装する必要はない、モックで良い)
計画が作成されました。今回は仕様を詰めるというお題目なので計画は素通りします。
コミットしておきます。
ここまでの変更を git commit して
チェックリスト作成
/speckit.checklist すべての機能要件・非機能要件の網羅的な品質チェックリストを作成して。実装前に要件の曖昧性・欠落を事前に検出および修正したい。チェックリストの深度は標準を想定する。
/speckit.checklist コマンドを実行すると品質チェックリストを作ってくれます。
これがとてもパワフルです。
チェックリストの焦点、深さ、使用者の観点を聞いてきます。これに答えるとチェックリストが生成されます。パターンごとに複数のチェックリストを作るのも面白そうです。
チェックリストの内容
チェックリストが生成されました。下に貼ります。長いのでアコーディオンは閉じています。
私のような開発経験が少ない者にとって、仕様不足を洗い出すことは困難です。がしかし、このチェックリストを使えば、仕様の穴を洗い出すことができそうです。
クリックして展開
# Comprehensive Requirements Quality Checklist
**Feature**: 002-ops-ai-agent-rag (SRE AI Agent RAG機能)
**Purpose**: 実装前に機能要件・非機能要件の曖昧性、欠落、不整合を検出し修正する
**Depth**: Standard
**Created**: 2025-11-21
**Target Audience**: 実装前レビュー（著者・PRレビュアー）
---
## 1. Requirement Completeness（要件の完全性）
### 1.1 機能要件の網羅性
- [ ] CHK001 - ドキュメント登録時の入力バリデーション要件（最大ファイルサイズ、許可される文字セット、必須フィールド）は明確に定義されているか？ [Completeness, Gap]
- [ ] CHK002 - PDF以外のドキュメント形式（Markdown、プレーンテキスト）の処理要件は、PDF処理要件と同等の詳細度で定義されているか？ [Completeness, Spec §FR-001]
- [ ] CHK003 - バッチドキュメント登録（User Story 2）の要件として、バッチサイズの上限、並列処理の可否、部分的失敗時の挙動は定義されているか？ [Gap, Spec §US2]
- [ ] CHK004 - ドキュメント削除（FR-009）時のカスケード削除要件（関連するチャンク、検索結果、回答履歴の扱い）は明確か？ [Completeness, Spec §FR-009]
- [ ] CHK005 - ドキュメント更新（既存ドキュメントの再登録）の要件は定義されているか？更新時のバージョン管理、チャンク再生成、既存検索結果への影響は？ [Gap]
- [ ] CHK006 - 質問応答（FR-004）において、複数の関連ドキュメントを統合して回答を生成する際の優先順位付けロジックは定義されているか？ [Clarity, Spec §FR-004]
- [ ] CHK007 - ドキュメントメタデータ（FR-005）の検索活用方法は具体的に定義されているか？（例: カテゴリフィルタリング、日付範囲検索、作成者別検索） [Clarity, Spec §FR-005]
- [ ] CHK008 - 重複検出（FR-010）の判定基準（完全一致、類似度閾値、チェックサムのみ）は明確に定義されているか？ [Ambiguity, Spec §FR-010]
### 1.2 非機能要件の網羅性
- [ ] CHK009 - 同時リクエスト処理数の要件は定義されているか？（Plan §Technical Context で NEEDS CLARIFICATION と記載） [Gap, Plan §Technical Context]
- [ ] CHK010 - スケーラビリティ要件として、1,000件を超えるドキュメント数（10,000件、100,000件など）での性能目標は定義されているか？ [Gap, Spec §SC-004]
- [ ] CHK011 - 可用性要件（Availability）は定義されているか？（例: アップタイム目標、ダウンタイム許容範囲） [Gap]
- [ ] CHK012 - データ永続化要件（PostgreSQLのバックアップ、リカバリ、データ保持期間）は定義されているか？ [Gap]
- [ ] CHK013 - セキュリティ要件（認証、認可、データ暗号化、監査ログ）は定義されているか？ [Gap]
- [ ] CHK014 - 監視・ロギング要件（何をログに記録するか、ログレベル、メトリクス収集対象）は定義されているか？ [Gap]
- [ ] CHK015 - エラーハンドリング要件（エラー分類、リトライポリシー、ユーザーへのエラーメッセージ内容）は定義されているか？ [Gap]
### 1.3 エッジケース・例外シナリオの網羅性
- [ ] CHK016 - ゼロ状態シナリオ（ナレッジベースが空の場合）の要件は定義されているか？ [Coverage, Edge Case, Gap]
- [ ] CHK017 - 部分的失敗シナリオ（ベクトル化は成功したがDBへの保存が失敗）の要件は定義されているか？ [Coverage, Exception Flow, Gap]
- [ ] CHK018 - 外部依存障害時（LLM API、エンベディングAPI、PostgreSQL接続失敗）のフォールバック要件は定義されているか？ [Coverage, Exception Flow, Spec §Edge Cases]
- [ ] CHK019 - タイムアウト処理要件（検索、LLM生成、DB操作それぞれのタイムアウト値）は定義されているか？ [Gap]
- [ ] CHK020 - リソース枯渇シナリオ（メモリ不足、ディスク容量不足）の検出と対処要件は定義されているか？ [Gap]
---
## 2. Requirement Clarity（要件の明確性）
### 2.1 曖昧な用語の定量化
- [ ] CHK021 - 「適切な応答時間内」（Spec §Edge Cases）は具体的な数値で定義されているか？（SC-001の5秒以内と整合しているか確認） [Clarity, Spec §Edge Cases]
- [ ] CHK022 - 「意味的に関連性の高いドキュメント」（FR-003）における「関連性の高い」の定義（関連性スコア閾値）は明確か？ [Ambiguity, Spec §FR-003]
- [ ] CHK023 - 「バランスのとれた回答」（複数ドキュメント統合時）の定義は明確か？ [Ambiguity, Spec §Edge Cases]
- [ ] CHK024 - 「矛盾を検出」（Spec §Edge Cases）の検出ロジックは定義されているか？ [Ambiguity, Spec §Edge Cases]
- [ ] CHK025 - 「不正なフォーマット」（User Story 2, Acceptance Scenario 3）の定義は明確か？（ファイル形式エラー、文字エンコードエラー、サイズ超過など） [Clarity, Spec §US2]
- [ ] CHK026 - 「一般的な知識での回答」（Spec §Edge Cases, User Story 3）における「一般的な知識」の範囲は定義されているか？ [Ambiguity, Spec §Edge Cases]
### 2.2 測定可能性の確認
- [ ] CHK027 - SC-002「関連性の高いドキュメントが参照される」の測定方法は定義されているか？（何をもって「関連性が高い」と判断するか） [Measurability, Spec §SC-002]
- [ ] CHK028 - SC-005「80%以上が有用であると評価」の評価方法（アンケート形式、評価基準）は定義されているか？ [Measurability, Spec §SC-005]
- [ ] CHK029 - SC-006「情報検索時間が平均50%短縮」のベースライン（従来の手動検索時間）は定義されているか？ [Measurability, Spec §SC-006]
- [ ] CHK030 - パフォーマンス目標（5秒以内の応答時間）の測定条件（ネットワーク環境、ドキュメント数、質問の複雑さ）は定義されているか？ [Measurability, Spec §SC-001]
### 2.3 受け入れ基準の明確性
- [ ] CHK031 - User Story 1の受け入れシナリオ4「該当する情報が見つかりませんでした」のメッセージ内容は具体的に定義されているか？ [Clarity, Spec §US1]
- [ ] CHK032 - User Story 2の受け入れシナリオ1「以降の質問で参照可能になる」の「以降」のタイミング（即時、数秒後、バッチ処理後）は明確か？ [Clarity, Spec §US2]
- [ ] CHK033 - User Story 3の受け入れシナリオ2「元のドキュメントの詳細が表示される」の「詳細」の範囲（全文、メタデータ、該当チャンクのみ）は明確か？ [Clarity, Spec §US3]
---
## 3. Requirement Consistency（要件の一貫性）
### 3.1 要件間の整合性
- [ ] CHK034 - FR-006（4種類のカテゴリ管理）とFR-005（メタデータ保存）のカテゴリ定義は一致しているか？ [Consistency, Spec §FR-005, §FR-006]
- [ ] CHK035 - FR-011（関連性スコアによる優先順位付け）とFR-003（意味的関連性検索）のスコアリング方式は整合しているか？ [Consistency, Spec §FR-003, §FR-011]
- [ ] CHK036 - Edge Cases の「古いドキュメントも通常のドキュメントとして扱う」方針と、「最新の情報を優先する」（矛盾検出時）は矛盾していないか？ [Conflict, Spec §Edge Cases]
- [ ] CHK037 - User Story 3（ソース表示）とFR-012（ドキュメント情報の提示）の提示情報範囲は一致しているか？ [Consistency, Spec §US3, §FR-012]
### 3.2 技術選定との整合性
- [ ] CHK038 - Plan §Technical Context の「NEEDS CLARIFICATION」項目（ベクトルDB、PDF処理、LLMクライアント）はresearch.mdで解決されているか？ [Consistency, Plan §Technical Context, research.md]
- [ ] CHK039 - PostgreSQL + pgvector の選定は、SC-004（1,000件以上のドキュメント対応）を満たすことが検証されているか？ [Consistency, Plan, Spec §SC-004]
- [ ] CHK040 - LangChain 1.0 + LangGraph 1.0 の選定は、FR-003（意味的関連性検索）とFR-004（回答生成）の実現可能性を保証しているか？ [Consistency, Plan, Spec §FR-003, §FR-004]
---
## 4. Acceptance Criteria Quality（受け入れ基準の品質）
### 4.1 受け入れ基準の完全性
- [ ] CHK041 - すべての機能要件（FR-001〜FR-012）に対応する受け入れ基準またはユーザーストーリーが存在するか？ [Coverage, Spec §FR-001〜FR-012]
- [ ] CHK042 - すべての成功基準（SC-001〜SC-006）の達成を検証するテストシナリオは定義されているか？ [Coverage, Spec §SC-001〜SC-006]
- [ ] CHK043 - User Story 1（P1）の受け入れシナリオは、正常系・異常系・境界値を網羅しているか？ [Coverage, Spec §US1]
- [ ] CHK044 - User Story 2（P2）の受け入れシナリオは、単一登録とバッチ登録の両方をカバーしているか？ [Coverage, Spec §US2]
### 4.2 テスト可能性の確認
- [ ] CHK045 - User Story 1の「適切な回答が返ってくる」の判定基準（回答の正確性、完全性）は客観的に測定可能か？ [Measurability, Spec §US1]
- [ ] CHK046 - User Story 2の「すべてのドキュメントが正常に登録される」の検証方法は定義されているか？ [Measurability, Spec §US2]
- [ ] CHK047 - User Story 3の「参照したドキュメントのタイトルまたはIDが表示される」の表示フォーマットは定義されているか？ [Clarity, Spec §US3]
---
## 5. Scenario Coverage（シナリオ網羅性）
### 5.1 主要フローの網羅性
- [ ] CHK048 - ドキュメント登録から検索可能になるまでの完全なフロー要件は定義されているか？（登録→チャンク分割→エンベディング生成→DB保存→インデックス更新） [Coverage, Gap]
- [ ] CHK049 - 質問応答の完全なフロー要件は定義されているか？（質問受付→エンベディング生成→ベクトル検索→LLM生成→ソース付き回答返却） [Coverage, Spec §FR-003, §FR-004, §FR-012]
- [ ] CHK050 - ドキュメント削除の完全なフロー要件は定義されているか？（削除リクエスト→関連データのカスケード削除→インデックス更新→削除完了通知） [Coverage, Spec §FR-009]
### 5.2 代替フローの網羅性
- [ ] CHK051 - 検索結果が0件の場合の代替フロー（一般知識での回答、推奨検索キーワードの提示など）は定義されているか？ [Coverage, Alternate Flow, Spec §FR-007]
- [ ] CHK052 - 複数の関連ドキュメントが見つかった場合の代替フロー（統合回答、個別回答、ユーザー選択）は定義されているか？ [Coverage, Alternate Flow, Spec §Edge Cases]
- [ ] CHK053 - ドキュメント重複検出時の代替フロー（警告後に登録継続、登録中止、マージ提案）は定義されているか？ [Coverage, Alternate Flow, Spec §FR-010]
### 5.3 例外・リカバリフローの網羅性
- [ ] CHK054 - LLM生成失敗時のリカバリ要件（リトライ、フォールバックモデル、エラーメッセージ）は定義されているか？ [Coverage, Exception Flow, Gap]
- [ ] CHK055 - ベクトル検索タイムアウト時のリカバリ要件（部分結果の返却、エラー通知）は定義されているか？ [Coverage, Exception Flow, Gap]
- [ ] CHK056 - PostgreSQL接続断時のリカバリ要件（再接続、エラー通知、データ損失防止）は定義されているか？ [Coverage, Exception Flow, Spec §Edge Cases]
- [ ] CHK057 - ロールバック要件（ドキュメント登録失敗時の部分データ削除、トランザクション管理）は定義されているか？ [Coverage, Recovery Flow, Gap]
---
## 6. Edge Case Coverage（エッジケース網羅性）
### 6.1 境界値の定義
- [ ] CHK058 - ドキュメントサイズの上限値は定義されているか？（最大文字数、最大ファイルサイズ） [Gap]
- [ ] CHK059 - 質問テキストの長さ制限は定義されているか？（最小1文字、最大値） [Gap]
- [ ] CHK060 - 検索結果の返却上限数（top_k）の範囲は定義されているか？ [Gap]
- [ ] CHK061 - メタデータフィールドの長さ制限（タイトル、作成者など）は定義されているか？ [Gap]
### 6.2 データ品質の扱い
- [ ] CHK062 - 空のドキュメント（内容が空文字列）を登録しようとした場合の要件は定義されているか？ [Edge Case, Gap]
- [ ] CHK063 - 特殊文字・非ASCII文字を含む質問テキストの処理要件は定義されているか？（Spec §Edge Casesで言及済み） [Completeness, Spec §Edge Cases]
- [ ] CHK064 - 極端に短い質問（1〜2単語）や極端に長い質問への対応要件は定義されているか？ [Edge Case, Gap]
- [ ] CHK065 - 壊れたPDFファイルや読み取り不可能なファイルの処理要件は定義されているか？ [Edge Case, Gap]
### 6.3 並行処理・競合
- [ ] CHK066 - 同一ドキュメントが同時に複数のユーザーから登録された場合の要件は定義されているか？ [Edge Case, Gap]
- [ ] CHK067 - ドキュメントが削除される直前に検索された場合の要件は定義されているか？ [Edge Case, Gap]
- [ ] CHK068 - 大量の同時質問が発生した場合のスロットリング・キューイング要件は定義されているか？ [Edge Case, Gap]
---
## 7. Non-Functional Requirements（非機能要件）
### 7.1 パフォーマンス要件の詳細化
- [ ] CHK069 - 応答時間目標（5秒）の内訳（検索時間、LLM生成時間、データ取得時間）は定義されているか？ [Clarity, Spec §SC-001]
- [ ] CHK070 - パフォーマンス低下時の検出・通知要件は定義されているか？ [Gap]
- [ ] CHK071 - 負荷テストの要件（同時ユーザー数、想定リクエスト数）は定義されているか？ [Gap]
- [ ] CHK072 - キャッシュ戦略（検索結果、エンベディング、LLM回答）の要件は定義されているか？ [Gap]
### 7.2 セキュリティ要件
- [ ] CHK073 - 認証・認可要件（誰がドキュメントを登録・削除できるか）は定義されているか？ [Gap]
- [ ] CHK074 - データ暗号化要件（保存時、転送時）は定義されているか？ [Gap]
- [ ] CHK075 - 監査ログ要件（誰がいつ何をしたか記録）は定義されているか？ [Gap]
- [ ] CHK076 - プロンプトインジェクション対策要件は定義されているか？ [Gap]
- [ ] CHK077 - APIエンドポイントのレート制限要件は定義されているか？ [Gap]
### 7.3 可用性・信頼性要件
- [ ] CHK078 - システムアップタイム目標（SLA）は定義されているか？ [Gap]
- [ ] CHK079 - データバックアップ・リストア要件は定義されているか？ [Gap]
- [ ] CHK080 - フェイルオーバー要件（プライマリDB障害時の切り替え）は定義されているか？ [Gap]
- [ ] CHK081 - 災害復旧（DR）要件は定義されているか？ [Gap]
### 7.4 保守性・運用性要件
- [ ] CHK082 - ログ出力要件（ログレベル、フォーマット、ローテーション）は定義されているか？ [Gap]
- [ ] CHK083 - メトリクス収集要件（何を監視するか、アラート条件）は定義されているか？ [Gap]
- [ ] CHK084 - デプロイ・ロールバック手順の要件は定義されているか？ [Gap]
- [ ] CHK085 - 設定変更（環境変数、パラメータ調整）の反映方法要件は定義されているか？ [Gap]
### 7.5 アクセシビリティ・国際化要件
- [ ] CHK086 - 多言語対応要件（日本語以外の言語サポート）は定義されているか？ [Gap]
- [ ] CHK087 - タイムゾーン処理要件（作成日時、更新日時の表示）は定義されているか？ [Gap]
- [ ] CHK088 - 文字エンコーディング要件（UTF-8以外のサポート）は定義されているか？ [Gap]
---
## 8. Dependencies & Assumptions（依存関係と前提条件）
### 8.1 外部依存の明確化
- [ ] CHK089 - LLM API（Amazon Bedrock Claude 3.5 Sonnet）の可用性・レイテンシに関する前提条件は文書化されているか？ [Assumption, Plan]
- [ ] CHK090 - エンベディングAPI（Titan Embeddings v2）の可用性・レイテンシに関する前提条件は文書化されているか？ [Assumption, Plan]
- [ ] CHK091 - PostgreSQLの可用性・パフォーマンスに関する前提条件は文書化されているか？ [Assumption, Plan]
- [ ] CHK092 - 外部依存が満たされない場合の代替案は定義されているか？ [Dependency, Gap]
### 8.2 インフラ要件の明確化
- [ ] CHK093 - 必要なインフラリソース（CPU、メモリ、ストレージ）の要件は定義されているか？ [Gap]
- [ ] CHK094 - ネットワーク要件（帯域幅、レイテンシ、ファイアウォール設定）は定義されているか？ [Gap]
- [ ] CHK095 - 本番環境とステージング環境の構成要件は定義されているか？ [Gap]
### 8.3 データ移行・初期化要件
- [ ] CHK096 - 初期データ投入要件（サンプルドキュメント、テストデータ）は定義されているか？ [Gap]
- [ ] CHK097 - 既存システムからのデータ移行要件は定義されているか？（該当する場合） [Gap]
- [ ] CHK098 - データベーススキーマ変更時のマイグレーション手順要件は定義されているか？ [Gap]
---
## 9. Ambiguities & Conflicts（曖昧性と矛盾）
### 9.1 要件の曖昧性
- [ ] CHK099 - 「適切な回答」（User Story 1）の定義は客観的に評価可能か？ [Ambiguity, Spec §US1]
- [ ] CHK100 - 「複数の候補がある場合はそれらを統合した回答」（Spec §Edge Cases）の統合方法は定義されているか？ [Ambiguity, Spec §Edge Cases]
- [ ] CHK101 - 「矛盾を検出し、運用担当者に通知する」（Spec §Edge Cases）の通知方法・タイミングは定義されているか？ [Ambiguity, Spec §Edge Cases]
- [ ] CHK102 - 「一般的な知識での回答にフォールバックする」（Spec §Edge Cases）の判断基準は明確か？ [Ambiguity, Spec §Edge Cases]
### 9.2 要件間の矛盾
- [ ] CHK103 - FR-010（重複検出と警告）とUser Story 2の受け入れシナリオ1（登録成功）は、重複時の挙動について矛盾していないか？ [Conflict, Spec §FR-010, §US2]
- [ ] CHK104 - Edge Casesの「古いドキュメントも通常として扱う」と「最新情報を優先」は、実装上矛盾しないか？ [Conflict, Spec §Edge Cases]
### 9.3 未定義の優先順位
- [ ] CHK105 - パフォーマンスと精度がトレードオフになる場合、どちらを優先するかは定義されているか？ [Gap]
- [ ] CHK106 - 複数のエラーが同時発生した場合、どのエラーを優先してユーザーに通知するかは定義されているか？ [Gap]
---
## 10. Traceability & Documentation（トレーサビリティとドキュメント）
### 10.1 要件の追跡可能性
- [ ] CHK107 - すべての機能要件（FR-001〜FR-012）は一意のIDで識別されているか？ [Traceability, Spec §FR-001〜FR-012]
- [ ] CHK108 - すべての成功基準（SC-001〜SC-006）は一意のIDで識別されているか？ [Traceability, Spec §SC-001〜SC-006]
- [ ] CHK109 - 各ユーザーストーリーと機能要件の対応関係は明確か？ [Traceability, Spec]
- [ ] CHK110 - 各成功基準と機能要件の対応関係は明確か？ [Traceability, Spec]
### 10.2 設計文書との整合性
- [ ] CHK111 - data-model.mdのエンティティ定義は、Spec §Key Entitiesと整合しているか？ [Consistency, Spec §Key Entities, data-model.md]
- [ ] CHK112 - contracts/api.yamlのエンドポイント定義は、機能要件（FR-001〜FR-012）をすべてカバーしているか？ [Completeness, Spec §FR-001〜FR-012, contracts/api.yaml]
- [ ] CHK113 - quickstart.mdの使用例は、主要なユーザーストーリー（US1, US2, US3）を反映しているか？ [Consistency, Spec §US1〜US3, quickstart.md]
---
## Summary（チェックリスト要約）
- **総チェック項目数**: 113項目
- **カテゴリ**:
1. Requirement Completeness（要件の完全性）: 20項目
2. Requirement Clarity（要件の明確性）: 13項目
3. Requirement Consistency（要件の一貫性）: 7項目
4. Acceptance Criteria Quality（受け入れ基準の品質）: 7項目
5. Scenario Coverage（シナリオ網羅性）: 10項目
6. Edge Case Coverage（エッジケース網羅性）: 11項目
7. Non-Functional Requirements（非機能要件）: 20項目
8. Dependencies & Assumptions（依存関係と前提条件）: 10項目
9. Ambiguities & Conflicts（曖昧性と矛盾）: 8項目
10. Traceability & Documentation（トレーサビリティ）: 7項目
- **重点領域**:
- **機能要件の完全性**: 特に非機能要件（セキュリティ、可用性、運用性）の欠落が多数検出されました
- **エッジケース**: 境界値、並行処理、データ品質に関する要件が不足しています
- **例外・リカバリフロー**: ロールバック、フェイルオーバー、エラーハンドリングの要件が不明確です
- **曖昧な用語**: 「適切な」「一般的な」「統合した」などの定性的表現の定量化が必要です
- **次のアクションアイテム**:
1. Gap として識別された項目（特にセキュリティ、可用性、運用性）について、要件を追加定義する
2. Ambiguity として識別された項目について、定量的基準を明確化する
3. Conflict として識別された項目について、矛盾を解消する
4. すべての NEEDS CLARIFICATION 項目（Plan §Technical Context）が解決されていることを再確認する
仕様の追加祭り
上のチェックリストから ”これ” といったものをピックアップして仕様追加を Coding Agent へ依頼します。
要件を追加して。
Vector Store に格納する際の 'id' は、ロードする際のファイル名にする。
ロード時にファイル名の検査を行い、アルファベット・数字・記号(_,-)のみに限定する。
要件を追加して。
RAG 検索は20秒でタイムアウトし、検索処理を中断する。
タイムアウト値は環境変数から取得できる。
要件を追加して。
embedding に使用するモデルは環境変数の値により決定する。
- run_mode=local -> OpenAI のモデル
- run_mode=aws -> Bedrock のモデル
OpenAI の認証情報は環境変数 'OPENAI_API_KEY' から取得する。
Bedrock の認証情報は IAM ロールから取得するので環境変数は不要。
要件を追加して。
SRE AI Agent で使うモデルは環境変数から取得する。
- MODEL_ID: チャットで使う model_id
- EMBEDDING_MODEL_ID: embedding で使う model_id
要件を追加して。
検索時 Vector Store から返されるドキュメント数を環境変数 'VS_RETURN_ITEMS' から取得する。環境変数未設定時のデフォルトは '20 'とする
要件を追加して。
Vector Store から返されたドキュメントのうち、関連性スコアが一定以上のものを呼び出し元へリターンする。関連性スコアのしきい値は環境変数 'VS_RELEVANCE_SCORE' から取得する。環境変数未設定時のデフォルトは '0.8 'とする。
質問して仕様追加
チェックリストを見てもよく分からないものは、そのままコピペして質問してしまいます。
すると推奨事項を提示してくれますので、自然言語で解決していくことが可能です。
バッチドキュメント登録（User Story 2）の要件として、バッチサイズの上限、並列処理の可否、部分的失敗時の挙動は定義されているか？
まとめ
「仕様が王様」 の思想通り、仕様をガン詰めしました。
AI/LLM の良いところは、どんなにしつこく質問しても嫌な顔をしないところです。
仕様をガン詰めしてから実装に入ることで、手戻りを減らせると思います。
熟練の開発者であれば仕様を細かく記述することは可能です。しかし、私のような経験が少ない者にとってはそもそも決めるべき仕様が分からないことがあります。
Spec Kit を上手に使うことによって、仕様の穴を洗い出し、より良い仕様を作成できる可能性があると感じました。
Discussion