元ファイル: システム要件定義の分析と汎用化方法/external_research_final_notes.md

外部リサーチ最終メモ（フェーズ1完了）

1. vibe coding失敗パターン（masterofcode, dualbootpartners, vybe.build）

統計的事実

AI生成コードの45%がセキュリティ脆弱性を含む（byteiota調査）
Y Combinatorの最新バッチは95%がAI生成コード（非エンジニア多数）

失敗パターン（重要度順）

プロトタイプ＝製品の誤認：デモ用コードを本番に持ち込む
セキュリティ後回し：認証・暗号化・アクセス制御を後付けにする
一度に複数変更：1プロンプトで複数の変更を積み重ねると壊れる
ユーザーテスト遅延：80%完成前にユーザーに見せない
本番移行の壁：認証・データセキュリティ・信頼性・統合が最大ボトルネック

3POアプローチ（dualbootpartners）

開発フェーズ＝実行フェーズとして扱う（発見フェーズを前に置く）
LLMはコードスニペット生成は得意だがアーキテクチャ・システム設計・長期計画は苦手
「AI is a powerful crew but needs detailed blueprints」

2. Claude Code公式ベストプラクティス（code.claude.com）

最重要原則

コンテキストウィンドウが最も重要なリソース - 全会話・全ファイル読み込み・全コマンド出力がコンテキストに入る - 埋まるにつれてパフォーマンスが劣化し、初期指示を「忘れる」 - コンテキスト使用量を継続的に追跡すること

4フェーズワークフロー（公式推奨）

Explore（探索）：planモードでファイルを読み変更せず理解する
Plan（計画）：詳細な実装計画を作成する
Implement（実装）：計画に従ってコーディングし検証する
Commit（コミット）：説明的なメッセージでコミットしPRを作成

CLAUDE.md設計原則

/initコマンドで自動生成してから精緻化する
200行以内・短く人間が読めるものにする
「これを削除するとClaudeがミスをするか？」→NOなら削除
肥大化したCLAUDE.mdはClaudeが実際の指示を無視する原因になる

含めるべきもの： - Claudeが推測できないBashコマンド - デフォルトと異なるコードスタイルルール - テスト指示と優先テストランナー - リポジトリ作法（ブランチ命名、PR規則） - プロジェクト固有のアーキテクチャ決定 - 開発環境の特殊事情（必須環境変数）

除外すべきもの： - コードを読めばわかること - Claudeが既に知っている標準的な言語規則 - 詳細なAPIドキュメント（リンクを貼るだけでよい） - 頻繁に変わる情報 - 長い説明やチュートリアル - ファイルごとのコードベース説明

検証の与え方（最高レバレッジ）

テスト・スクリーンショット・期待出力を与えることでClaudeが自己検証できる
「validateEmail関数を書け」→「validateEmail関数を書け。テストケース：user@example.comはtrue、invalidはfalse」
検証なしだと「見た目は正しいが動かない」コードが生成される

コンテキスト管理

早期かつ頻繁にコース修正する
サブエージェントを調査に使う
チェックポイントで巻き戻す
会話を再開する

3. Spec-Driven Development（martinfowler, arxiv論文）

SDDの3レベル

Spec-First：仕様を先に書いてからAI支援開発に使う（最も実践的）
Spec-Anchored：仕様をコード完成後も維持し、進化・保守に使い続ける
Spec-as-Source：仕様が唯一の編集対象、コードは自動生成（最も理想的だが難易度高）

SDDの核心原則

コードは仕様の実装詳細であり、その逆ではない
仕様が意図を宣言し、コードがそれを実現する
AIへの曖昧なプロンプト→「Add photo sharing to my app」→AIが何十もの未言及の仮定をする
明確な仕様→「ユーザーはJPEGまたはPNGを最大10MBアップロードできる。S3にユーザーIDプレフィックスで保存。削除はアップローダーのみ可能」→AIが意図に合ったコードを生成

SDDワークフロー（4フェーズ）

Specify（仕様化）：何をすべきか？ユーザーストーリー・受け入れ基準・エッジケース
Design（設計）：どのように実装するか？アーキテクチャ・コンポーネント・データフロー
Implement（実装）：仕様に対してコードを生成・検証
Verify（検証）：仕様に対してコードをテスト・検証

Kiroワークフロー（最も軽量なSDD）

Requirements → Design → Tasks の3ステップ
各ステップが1つのMarkdownドキュメント
Requirementsは「As a...」形式のユーザーストーリー＋「GIVEN/WHEN/THEN」受け入れ基準

Spec-kitワークフロー（GitHub版SDD）

Constitution（憲法）→ Specify → Plan → Tasks
Constitutionは「不変の高レベル原則」（=CLAUDE.md + CONSTRAINTS.mdに相当）
各ステップでチェックリストを使って「完了の定義」を追跡

4. Claude Code × SDD実践（heeki.medium.com）

実践者の知見

「計画フェーズに多くの時間を費やす。コード生成に飛びつかない」
「要件を早期に定義・文書化することで、より良い出力と少ない挫折が得られる」
Spec-once（仕様を一度書いてそのまま忘れる）は避けるべき
仕様を継続的なフィードバックループとして使う

コンテキストウィンドウ実践知見

Pro契約：200kトークン（重い使用で45分〜1時間でOpus使用制限に達する）
Sonnet切り替えで使用制限を回避できる
コンテキスト圧縮（compaction）は3〜12分かかる

5. 現体系への示唆（リサーチ結果の統合）

現体系が対応できている点

CLAUDE.md + CONSTRAINTS.md + progress.md の3ファイル体系 → Spec-kitのConstitutionに相当
RYGゲートによる完了判定 → SDDの検証フェーズに相当
E2Eテストの事前設計 → SDDのVerifyフェーズに相当
1回の会話で1つのことだけ → Claude Code公式の「コース修正」原則に合致

現体系が対応できていない可能性がある点

Spec-Anchored（仕様の継続維持）：現体系はSpec-Firstどまりで、仕様を実装後も維持する仕組みがない
CLAUDE.md肥大化防止の具体的ルール：200行以内・削除基準が明確でない
コンテキスト使用量の可視化：素人がコンテキスト残量を把握する方法が不明
本番移行チェックリスト：プロトタイプ→本番の移行で必要な認証・セキュリティ・信頼性の具体的チェックリストがない
検証基準の具体化：「Claudeが自己検証できるテストケース」の書き方が不明
Explore→Plan→Implement→Commitの4フェーズ：現体系に明示的に組み込まれていない

外部リサーチ最終メモ：vibe coding失敗・Claude Code公式作法・SDD

要約

要点