AI超高速・高安定開発フロー 標準作業手順書 (SOP)

SOP（標準作業手順書：Standard Operating Procedure）

1. 目的と基本理念

本手順書は、AI駆動型開発とドキュメント管理を高度に融合させ、極めて短期間（実証実績：3日間でMVPフェーズだけでなく開発全体フェーズ４まで含めて95%を完了）で高品質なシステムを構築・安定稼働させることを目的とする。本フローの核心は「ドキュメントを正本（製本）とし、AIを実装の実行者とする」プロセスデザインにある。

• AIのための「正本（製本）」管理: ドキュメントは人間のみならず、AIが迷わず実装するための「唯一の真実」である。
• ドキュメント・ファーストによる安定性の担保: 実装前に「正解」を定義することで、AIのハルシネーション（誤回答）を抑制し、3日間という超高速開発においてもデグレードを許さない。
• 利用者満足を最優先とした判断軸: 「迷わない、失敗しない、状態が分かる」状態を最速で作り上げ、価値の早期検証を実現する。

--------------------------------------------------------------------------------

2. 開発環境のセットアップ（前提条件）

AI駆動型開発を円滑に進めるため、以下の標準ツールスタックを定義する。Dockerによるコンテナ化は、AIが環境依存の不具合に惑わされるのを防ぎ、開発の再現性を担保するために不可欠な前提条件である。

--------------------------------------------------------------------------------

3. ドキュメント・ファーストの設計原則

「迷わず見つけられる状態」を維持するため、ドキュメントは以下の4つの目的別に整理し、厳格な命名規則に従って管理する。README.mdは全ドキュメントへの入り口（地図）として機能させる。

4つの目的

1. なぜ作るか: 事業方針・戦略（ec-strategy-checklist-2026.md等）
2. 何を作るか: 機能一覧・画面遷移（feature-list.md, screen-flow-spec.md等）
3. どう運用するか: 運用手順・ルール（operations-runbook.md, sales-operations-spec.md等）
4. どう実装するか: データ設計・権限設計（product-model-spec.md, authorization-spec.md等）

命名規則とディレクトリ構造

docs/
├── README.md              # 全ドキュメントの入り口（地図）
├── *-spec.md              # 【正本】運用、画面、権限等の「仕様書」
├── *-plan.md              # 【進行管理】実行計画、移行計画等の「計画書」
└── *-model-spec.md        # 【設計】データ構造やモデルの責務定義書

--------------------------------------------------------------------------------

4. AI駆動型開発の実行サイクル（5ステップ）

開発は以下の5ステップを1サイクルとして高速に回転させる。

1. Codexによる設計の深化: 人間がCodexとの対話を通じて要件や設計の曖昧な箇所を詰め、ロジックを確定させる。
2. docs/内のドキュメント整備: 確定した設計を *-spec.md に記載し、プロジェクトの「正本」を更新する。
3. Claude Codeによる実装: 更新されたドキュメントをClaude Codeに読み込ませ、具体的なコーディング指示を出す。
4. 進捗確認と検証: 実装されたコードがドキュメントの定義を満たしているか、また既存の機能を壊していないかを人間が検証する。
5. ドキュメントの同時更新: 実装中に判明した詳細仕様や変更点を、Claude Codeにタスクとして与え、即座にドキュメントへフィードバックさせる。これにより「ドキュメント＝最新の実装」という状態を維持し、情報の乖離（ドリフト）を完全に防止する。

--------------------------------------------------------------------------------

5. チケット駆動による進捗管理（mvp-task-plan.mdの運用）

タスク管理は mvp-task-plan.md をバックログとして活用する。優先順位は、以下の利用者満足を優先した判断軸に基づいて決定する。

判断基準：重視する順番

1. 迷わないこと: 出店者や管理者が、次に何をすべきか、どこを見ればよいかが直感的に理解できるか。
2. 失敗しないこと: ブランド間のデータ混在防止や、SKUを正本とした数値（価格・在庫・売上）の整合性が担保されているか。
3. 状態が分かること: 売上、返金、手数料、入金見込み等が画面上で明確に視覚化されているか。

• P0 (必須): ブランド開設、商品の公開・販売、売上確認の完遂に必須なタスク。
• P1 (重要): 期間別集計、商品別分析、ブランド横断検索など、実運用に必要な機能。
• P2 (拡張): キャンセル・返金の詳細反映、手数料管理の高度化、分析機能の強化。

--------------------------------------------------------------------------------

6. 実装フェーズ：Product/SKUモデルの遵守

商品の販売・在庫・売上に関する実装は、以下の「商品モデル定義」を絶対的なルールとして遵守し、数値の整合性を担保する。

• Product（商品コンセプト）: 商品名、説明、画像、公開状態を担当。
• ProductSku（販売単位）: 価格、原価、在庫数、SKUコードを担当。販売に関わる数値の唯一の正本。

[!WARNING] やってはいけないこと（Don'ts）

• products.price や products.stock を UPDATE 文の直接の対象にしてはならない。これらは旧コード互換および高速表示のための「キャッシュ」であり、数値のソース・オブ・トゥルース（正本）ではない。
• SKUの更新後、必ず Product::syncLegacySkuSnapshot() を通じて再計算・同期を行うこと。
• SKUが1件も存在しない状態で商品を公開してはならない。

--------------------------------------------------------------------------------

7. 権限制御とセキュリティの実装手順

認証・認可は、Laravel Breezeをベースとし、ミドルウェアによって多層的に保護する。

ミドルウェアの重要ロジック

• ResolveSite: Hostヘッダからサイトを解決。domains.is_verified = true のドメインのみを有効とし、未解決時は404を返す。
• site.owner: ログインユーザーが対象ブランドの owner_user_id と一致することを要求。

ロール別アクセス範囲

--------------------------------------------------------------------------------

8. 品質管理とテスト観点

開発速度を維持しつつ安定性を確保するため、テスト駆動（TDD）の姿勢を維持する。リリース前には必ず以下のチェックリストをパスしなければならない。

• [ ] 225件以上のテストと668件以上のアサーションをすべてパスしているか。
• [ ] ブランドをまたいだ商品混在や、注文データの漏洩が起きていないか。
• [ ] Stripe Checkoutの成功からWebhookによる注文確定・在庫減算までのハンドシェイクが正常に機能するか。
• [ ] 売上サマリーの数値と、注文明細（OrderItem）の合計が1円の狂いもなく一致しているか。
• [ ] 管理者監視画面において、異常ステータスが期待通りに検知・表示されているか。

--------------------------------------------------------------------------------

9. 運用への引き継ぎ（Operations Runbook）

開発完了後、日常運用において以下の「インシデント・レスポンス・フロー」および定期確認項目を遵守する。

障害発生時の初動フロー（1-6ステップ）

1. 検知: 事象の発生時刻、影響範囲（全サイトか特定ブランドか）を特定する。
2. 切り分け: 再現性を確認し、Blade側かNext.js側か、あるいはStripe/API/DBのどこに起因するかを判別する。
3. 重大度判断: 「注文不可」「決済後の注文作成失敗」「ブランド混在」を重大障害と定義し、優先度を決定する。
4. 一時対応: 必要に応じて特定機能の停止や、サイトの非公開化を実施する。
5. 復旧・確認: 原因箇所修正後、主要導線の再テストを行い、他ブランドへの波及がないかを確認する。
6. 記録（ポストモーテム）: 障害内容、原因、再発防止策をドキュメントに記録する。

定期確認項目

• 日次: 新規注文・未発送確認、在庫アラート、異常ブランドの有無。
• 週次: ブランドごとの売上推移、返金発生状況の確認。
• 月次: 月次売上集計、入金見込みと実入金の消込、SKU追跡率（補完状況）の確認。

--------------------------------------------------------------------------------

10. スケーラビリティと将来フェーズへの展望

MVP完了後は、システムの完成度を高め、段階的にフロントエンドをNext.jsへ移行する。

• 優先度 A (実装済み/最優先): 商品詳細、横断商品一覧、カートのNext.js化。購入率に直結するモバイル体験を最適化する。
• 優先度 B: トップページ、ブランド一覧、特集ページ等の回遊性を高める画面の移行。
• 優先度 C: 注文完了、マイページ、法的ページ等の補助画面の移行。

組織文化へのメッセージ この「AI超高速開発フロー」は、単なる効率化の道具ではない。ドキュメントを通じて思考を整理し、AIという強力なパートナーに「正解」を与え続けることで、最速かつ安全に価値を届けるという「文化」である。特に、マルチテナントにおける「データ分離（一貫した site_id による隔離）」を組織の絶対的な文化価値として守り抜き、常に変化し続けるビジネス要求に即応せよ。