AIエージェント28体でSaaSを構築した話：kupo-radar.jp開発ノウハウ

この記事をシェア

kupo-radar.jp（クポ活レーダー）が機能オープンしました。これは、紙クーポンを AI-OCR で読み取り、期限前にお知らせしてくれる PWA（Progressive Web App）サービスです。

このプロジェクトで特筆すべきは、「仮想の AI システム開発会社」をコンピュータ内に構築し、ほぼオートメーションで開発を完遂した点です。本記事では、その構築プロセスとノウハウを公開します。

🎯 この記事のポイント
28 体の AI エージェントによるウォーターフォール開発プロセス
PM ゲートウェイ・アーキテクチャの実装
SDLC 14 フェーズの自動化
Playwright による E2E テスト自動化の課題

1. プロジェクト概要

サービス名：クポ活レーダー（Kupo Radar）

URL：https://kupo-radar.jp

概要：紙クーポンをスマホで撮影するだけで、AI-OCR が自動読み取り。期限 3 日前と当日に通知してくれるブラウザアプリ

ターゲット：30〜40 代主婦層（節約志向・家計管理担当）

技術スタック：Next.js 16 + Supabase + Vercel + OpenRouter（OCR）

図 1: kupo-radar.jp ランディングページ（「もらったクーポン全部使う！」がメインキャッチ）

2. 仮想 AI 会社の設立

このプロジェクトは、Claude Code の AI エージェントチームを作成することから始まりました。コンピュータ内に「仮想の AI システム開発会社」をつくり、僕はプロジェクトオーナーとしてシステムのコンセプトやおおまかにやりたいことだけを伝えるだけで、あとは AI のプロジェクトマネージャが各チームを指揮して開発を進めました。

2.1 エージェント組織図

28 体のエージェントと 14 の Skill で構成される開発組織：

カテゴリー	エージェント数	主な役割
設計・要件系	7 体	要件定義、業務フロー、技術選定、ブランド設計、外部/内部設計、テスト計画
レビュー系	6 体	各フェーズの成果物をレビュー（読み取り専用）
実装・テスト系	7 体	実装、ユニットテスト、E2E テスト、トレーサビリティ監査
SaaS 特化系	7 体	認証、決済、モバイル、LINE、マーケティング、SEO、動画生成
プロジェクト管理	1 体	全体 PM（Opus モデル）

2.2 PM ゲートウェイ・アーキテクチャ

最も重要な設計が「PM ゲートウェイ」です。ユーザー（僕）からのすべてのメッセージは project-manager 宛てとして扱い、PM が以下の判断を自律的に行います：

メッセージの意図を解釈する
自分で回答できる場合 → 直接回答
専門エージェントが必要な場合 → 該当エージェントを起動し、結果を受け取り要約・報告
複数エージェントが必要な場合 → 並列または順次で起動し、統合して報告

これにより、僕は「要件定義を始めよう」「現状を把握して」「決済追加したい」といった自然言語の指示だけで、適切なエージェントが自動起動される仕組みになりました。

3. ウォーターフォール型 SDLC 14 フェーズ

より汎用的にシステムを開発するため、やや古いウォーターフォール型のプロセスを採用しました。14 のフェーズを順次進行します：

SDLC 14 フェーズ進行図 — 図 2: SDLC 14 フェーズ進行（Phase 1〜14 を順次進行）

Phase	名称	担当エージェント	成果物
1	要件定義	requirements-architect	requirements.md v0.5.1（714 行）
2	要件レビュー	requirements-reviewer	review-v0.5.1.md（PASS）
3	企画（並列）	business-flow-designer tech-stack-architect brand-design-strategist	業務フロー/機能一覧/ADR/ブランド戦略
4	企画レビュー	planning-reviewer	横断レビュー（Warning → 解消）
5	外部設計	external-designer	画面一覧（25 画面）/ 画面遷移/API 仕様/ERD
6	外部設計レビュー	external-design-reviewer	review-phase5.md（Approve）
7	内部設計	internal-designer	ディレクトリ構造/モジュール設計/シーケンス図
8	内部設計レビュー	internal-design-reviewer	review-phase7.md（Approve）
9	テスト計画	test-planner	テスト戦略/テストケース（250〜350 ケース）
10	テスト計画レビュー	test-plan-reviewer	review-phase9.md（Warning / Phase 11 進行可）
11	実装＋ユニット/統合	implementation-worker tester	Next.js 実装（20 ページ）/ コンポーネント
12	ユースケース E2E	e2e-usecase-tester	E2E シナリオ（45/45 pass）
13	要件トレーサビリティ監査	requirement-traceability-auditor	traceability-audit.md（Conditional Go）
14	実装＋全テストレビュー	implementation-reviewer	review-phase14.md（Deploy GO）

3.1 Phase 12/13 のスキップ禁止

v0.2.0 から新設された Phase 12 と 13 は必須・スキップ禁止です：

Phase 12（ユースケース E2E）：新規登録・課金・退会など売上直結フローを実ブラウザで通しテストするゲート
Phase 13（要件トレーサビリティ監査）：要件定義で約束した機能・業務フロー分岐がブラウザで本当に到達できるかを監査するゲート

PM が Phase 11 → 12 → 13 → 14 を自動で連結起動し、デプロイ判断を行います。

4. ログイン後画面の UI

実際にログインした後に表示される主要画面のスクリーンショットです。Next.js App Router の app/(authed)/ ディレクトリに実装されています。

クポ活レーダーホーム画面 - クーポン一覧と期限バッジ — 図 3: ホーム画面 — 有効なクーポンの一覧表示。期限 3 日前はオレンジバッジ、当日はレッドバッジで強調表示。

クポ活レーダースキャン画面 - 紙クーポン撮影 — 図 4: スキャン画面 — 紙クーポンを撮影して OCR 処理。Gemini 3 Flash Preview が特典・期限・店舗名を自動抽出。

クポ活レーダースキャン確認画面 - OCR 結果の確認 — 図 5: スキャン確認画面 — OCR 抽出結果の確認・編集。期限はカレンダーピッカーで修正可能。

クポ活レーダークーポン詳細画面 - 個別クーポンの情報表示 — 図 6: クーポン詳細画面 — 個別クーポンの全情報表示。バーコード/QR コードも表示され、レジで使用可能。

4.1 UI 実装のポイント

モバイルファースト：390×844（Pixel 5 相当）を基準に設計
PWA 対応：manifest.webmanifest と Service Worker でオフライン動作をサポート
アクセシビリティ：ARIA ラベル、キーボードナビゲーション、カラーコントラスト比 4.5:1 以上を確保
パフォーマンス：Next.js Image コンポーネントで WebP 変換、レイアウトシフト防止

5. フレームワーク構造

フレームワークそのものは ~/noguchi-saas-framework リポジトリにあり、ここにエージェントやスキルのテンプレートを配置してあります。

4.1 リポジトリ構造

noguchi-saas-framework/
├── .claude/                          # フレームワーク本体（正本）
│   ├── agents/                       # 28 エージェント
│   │   ├── project-manager.md
│   │   ├── requirements-architect.md
│   │   ├── business-flow-designer.md
│   │   ├── tech-stack-architect.md
│   │   ├── brand-design-strategist.md
│   │   ├── external-designer.md
│   │   ├── internal-designer.md
│   │   ├── test-planner.md
│   │   ├── implementation-worker.md
│   │   ├── tester.md
│   │   ├── e2e-usecase-tester.md
│   │   ├── requirement-traceability-auditor.md
│   │   └── ...（他 16 体）
│   └── skills/                       # 14 Skill
│       ├── requirements-toolkit/
│       ├── sdlc-toolkit/
│       ├── stripe-integration/
│       ├── e2e-browser-testing/
│       └── ...（他 10 種）
├── templates/
│   └── project-init/                 # 新規案件の初期セットアップ
│       ├── CLAUDE.md
│       ├── PROJECT_LEARNINGS.md
│       ├── setup.sh
│       └── .framework-version
├── docs/
│   ├── learnings/                    # 各案件から還流した知見
│   ├── operations/                   # 運用ガイド
│   └── projects/                     # 案件レジストリ
├── scripts/
└── CHANGELOG.md

4.2 coupon-rader プロジェクト構造

coupon-rader/
├── .claude/                          # フレームワーク取込（28 エージェント +14 Skill）
│   ├── agents/
│   └── skills/
├── app/                              # Next.js アプリケーション
│   ├── (auth)/                       # 認証画面（6 ページ）
│   ├── (authed)/                     # 認証後画面（ホーム、クーポン一覧等）
│   ├── (marketing)/                  # LP（kupo-radar.jp ルート）
│   ├── scan/                         # OCR 撮影画面
│   ├── coupon/                       # クーポン詳細
│   └── settings/                     # 設定画面
├── components/                       # React コンポーネント
├── lib/                              # 共通ライブラリ
│   ├── mock-data.ts                  # モックデータ
│   └── supabase/                     # Supabase クライアント
├── docs/                             # SDLC 成果物
│   ├── 00-requirements/              # Phase 1
│   ├── 10-business-design/           # Phase 3
│   ├── 11-tech-stack/                # Phase 3
│   ├── 12-brand-design/              # Phase 3
│   ├── 15-marketing-site/            # LP 設計
│   ├── 20-external-design/           # Phase 5
│   ├── 30-internal-design/           # Phase 7
│   ├── 40-test-plan/                 # Phase 9
│   ├── 41-test-results/              # Phase 12/13 結果
│   └── 99-pm/                        # PM 資料
├── playwright/                       # E2E テスト
├── tests/                            # ユニット/統合テスト
├── CLAUDE.md                         # プロジェクトコンテキスト
└── PROJECT_LEARNINGS.md              # 知見還流ファイル

6. 各フェーズの成果物

6.1 Phase 1: 要件定義

要件定義書 requirements.md は v0.5.1 で 714 行に達しました。主な内容は：

プロダクトビジョンとターゲットユーザー（30〜40 代主婦層）
差別化軸（MVP UVP / 中期 UVP の二段構造）
機能スコープ（F-001〜F-015）
非機能要件（性能・セキュリティ・運用）
制約条件（月額上限 20,000 円、民事再生中の財務制約）
撤退基準（数値判定 + 構造リスク例外条項）

# 要件定義書（自社プロダクト）：クポ活レーダー (Kupo Radar)

## 改訂履歴

| バージョン | 日付       | 主な変更                                         |
|------------|------------|--------------------------------------------------|
| v0.1       | 2026-05-16 | 初版                                             |
| v0.5       | 2026-05-24 | 3 本柱戦略採用 / PWA 先行 / OCR マルチプロバイダー対応設計 |
| v0.5.1     | 2026-05-24 | requirements-reviewer 指摘を反映（Major 4 / Minor 6） |

## 1. プロダクト概要

- **プロダクト名（仮）**: クポ活レーダー (Kupo Radar)
- **提供チャネル（3 本柱戦略）**:
  - 柱 1（MVP 先行・実装スコープ）: PWA（Progressive Web App）
  - 柱 2（LINE 承認後）: LINE ミニアプリ（LIFF）
  - 柱 3（合算 MAU 達成後）: ネイティブアプリ（iOS / Android）

6.2 Phase 3: 企画

3 つのエージェントを並列起動して企画を策定：

business-flow-designer：業務フロー（14 のユースケース）、機能一覧（47 機能）
tech-stack-architect：技術選定（ADR 10 本）、コスト試算
brand-design-strategist：ブランド戦略、デザインシステム、ムードボード

特に重要なのがADR（Architectural Decision Record）です。10 本の ADR で技術選定の根拠を文書化しました：

ADR-001: Supabase 採用（Tier A）
ADR-002: Vercel + Next.js（PWA 対応）
ADR-003: OpenRouter 経由 OCR マルチプロバイダー設計
ADR-004: Web Push + メール通知（コスト最小化）
ADR-005: Gemini 3 Flash Preview 採用（OCR エンジン）
ADR-006: Resend 採用（メール配信）
ADR-007: LINE ヤフー広告ネットワーク（柱 2）
ADR-008: Google AdSense（柱 1 MVP）
ADR-009: Sentry 統合（監視）
ADR-010: GitHub Actions（CI/CD）

6.3 Phase 5: 外部設計

external-designer が 7 つの成果物を生成：

screen-list.md：25 画面の画面一覧
screen-transition.md：画面遷移図（柱 2/3 将来拡張含む）
api-spec.md：14 エンドポイントの API 仕様（OpenAPI）
erd.md：7 テーブルの ERD（Supabase RLS 定義）
auth-authz.md：認証・認可ルール（Supabase Auth + Magic Link/OAuth）
error-handling.md：11 エラーコードの詳細とフォールバック設計
non-functional-spec.md：非機能要件（性能・セキュリティ・アクセシビリティ）

6.4 Phase 7: 内部設計

internal-designer が 8 つの成果物を生成：

directory-layout.md：ディレクトリ構造と依存方向
module-design.md：主要モジュール設計（Supabase/OCR/通知/Zod）
sequence-diagrams.md：6 本のシーケンス図（UC-001/005/009/011/middleware/OAuth）
state-transition.md：ステートマシン（coupons.status / notification_logs.status）
transaction-design.md：トランザクション設計（補償戦略・楽観ロック）
error-logging-design.md：エラーログ設計（Sentry beforeSend / PII マスキング）
config-management.md：設定管理（.env.example / vercel.json Cron）
undecided-resolutions.md：未確定 8 件の解決（I-001〜I-009 確定）

6.5 Phase 9: テスト計画

test-planner が 8 つのテストドキュメントを生成：

test-strategy.md：テスト戦略（Unit 60% / Integration 25% / E2E 15%）
test-cases-unit.md：80 件のユニットテストケース
test-cases-integration.md：70 件の統合テストケース
e2e-scenarios.md：21 シナリオ（FunctionalID 全件付与）
test-data.md：テストデータ（Factory パターン）
non-functional-test-plan.md：非機能テスト計画
ci-cd-test-pipeline.md：GitHub Actions 設定（Free 2000 分/月以内）
test-coverage-targets.md：カバレッジ目標（行 80% / 分岐 75%）

7. 実装（Phase 11）

7.1 PWA モック実装（Phase 5.5）

Phase 5 完了後、ユーザー判断で Phase 6 を一旦保留して PWA モック UI を先行実装しました。これが後の E2E テストで大きな効果を発揮します。

実装画面数：25 画面中 24 画面（S-AUTH-001 起動スプラッシュは middleware に委譲）

app/
├── (auth)/
│   ├── login/
│   │   ├── page.tsx           # ログイン画面
│   │   └── callback/
│   │       └── page.tsx       # OAuth コールバック
│   └── register/
│       └── page.tsx           # 新規登録
├── (authed)/
│   ├── home/
│   │   └── page.tsx           # ホーム（クーポン一覧）
│   ├── coupon/
│   │   └── [id]/
│   │       └── page.tsx       # クーポン詳細
│   └── settings/
│       └── page.tsx           # 設定画面
├── scan/
│   ├── page.tsx               # 撮影画面
│   └── confirm/
│       └── page.tsx           # OCR 結果確認
└── (marketing)/
    └── page.tsx               # LP（kupo-radar.jp ルート）

スタック：

Next.js 16.2.6 + React 19
Tailwind 3.4 + shadcn/ui（Radix UI）
sonner（トースト通知）
lucide-react（アイコン）

npm run typecheck / npm run build / npm run dev（全 24 ルート HTTP 200）すべて Pass。

7.2 営業ポータルサイト（LP）実装

PWA 本体とは別に、kupo-radar.jp ルートのランディングページを実装。visual-director → marketing-site-builder → page-designer の 3 段階起動で構築しました。

主要セクション：

ヒーロー（「もらったクーポン全部使う！」）
仕組み紹介（撮る・知らせる・使うの 3 ステップ）
機能紹介（6 枚のカード）
運営者情報（個人開発・完全無料）
FAQ（5 件）
CTA（「今すぐ使ってみる」）

Playwright で PWA 実機スクショ 4 枚を生成し、LP に差し込みました。

7. E2E テスト（Phase 12）

8.1 Playwright 設定

E2E テストは Playwright を使用。設定ファイル playwright.config.ts は以下の通り：

import { defineConfig, devices } from '@playwright/test';

export const STORAGE_STATE_CONSENT = path.join(__dirname, 'playwright/.auth/consent.json');
export const STORAGE_STATE_NEW = path.join(__dirname, 'playwright/.auth/new.json');

export default defineConfig({
  testDir: './tests/e2e',
  fullyParallel: false, // DB 共有のため直列実行
  workers: 1, // Supabase ローカルへの接続数制限
  use: {
    baseURL: process.env.E2E_BASE_URL || 'http://127.0.0.1:3000',
    trace: 'on-first-retry',
    video: 'retain-on-failure',
    screenshot: 'only-on-failure',
    viewport: { width: 390, height: 844 }, // モバイル幅
    locale: 'ja-JP',
    timezoneId: 'Asia/Tokyo',
  },

  projects: [
    // セットアップ：認証状態を生成
    { name: 'setup-consent', testMatch: /auth\.setup\.ts/ },
    { name: 'setup-new', testMatch: /auth-new\.setup\.ts/ },

    // メインテスト：Chromium（モバイル幅）
    {
      name: 'chromium',
      use: { ...devices['Pixel 5'], storageState: STORAGE_STATE_CONSENT },
      dependencies: ['setup-consent'],
    },

    // Firefox/WebKit smoke テスト
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],

  webServer: {
    command: 'npm run dev',
    url: 'http://127.0.0.1:3000',
    reuseExistingServer: true,
  },
});

8.2 テスト結果

e2e-usecase-tester が 21 シナリオを実行。結果は 45/45 pass でした。

シナリオ ID	ユースケース	結果
SCN-001	新規登録 → 同意 → ホーム到達	✅ Pass
SCN-002	ログイン → 同意済みユーザーはスキップ	✅ Pass
SCN-003	クーポン撮影 → OCR → 保存	✅ Pass
SCN-004	クーポン一覧表示（期限順）	✅ Pass
SCN-005	クーポン詳細表示（バーコード）	✅ Pass
SCN-006	使用済みマーク	✅ Pass
SCN-007	クーポン削除	✅ Pass
SCN-008	期限切れクーポンの 30 日アーカイブ	✅ Pass
SCN-009	通知設定（ON/OFF）	✅ Pass
SCN-010	退会フロー	✅ Pass
...	（他 11 シナリオ）	✅ Pass

8. ブラウザテスト自動化の課題

今回、最も苦労した点がブラウザ操作のテスト自動化です。Playwright は強力なツールですが、実際にブラウザを操作してのテストには以下の課題が残りました：

9.1 iOS Standalone Mode の制約

PWA を iOS の「ホーム画面に追加」でインストールした際の Standalone Mode（アプリとして表示）のテストは、Playwright WebKit では完全再現できませんでした。

課題：

Safari の User-Agent を偽装しても、Safari 独自の機能（Web Push の制約、アドレスバー非表示等）は完全再現不可
iOS 16.4 未満の Web Push 非対応環境のフォールバックテストは実機必須

対策： 実機テスト方針とし、Phase 12 では「iOS Standalone Mode は実機確認」としてドキュメント化。

8.2 認証状態の管理

E2E テストでは、毎テストでログインしないよう storageState で認証状態を再利用しています。しかし、Supabase の Magic Link や OAuth フローはテスト環境で完全再現するのが困難でした。

課題：

Magic Link のメール到達をテスト環境で検証できない（Resend の sandbox モード使用）
Google OAuth のテスト用アカウント準備が必要

対策： テストユーザー（test+e2e-*@kupo-radar.test）を事前作成し、認証状態を JSON で保存・再利用。

8.3 OCR のモック化

本番では OpenRouter 経由で Gemini 3 Flash Preview を呼び出しますが、E2E テストではコストと速度の問題からモック化が必要です。

課題：

OCR の実際のレスポンスタイム（4.1 秒）を再現できない
エラーケース（タイムアウト、パースエラー）の再現が難しい

対策： lib/mock-data.ts で OCR 結果を固定し、テスト中はモックデータを使用。本番接続は Vercel プレビューで smoke テスト。

8.4 回帰テストの必要性

Playwright には Visual Regression Testing の機能がありますが、今回は導入しませんでした。今後の課題です。

検討中のツール：

Playwright 標準の Image Comparison
Percy（有料）
Chromatic（Storybook 連携）

9. 学んだこと・フレームワークへの還流

本プロジェクトで得た知見は、PROJECT_LEARNINGS.md に記録し、フレームワーク本体に還流する予定です。

9.1 レビュアーの Write 権限

Phase 1/2 のレビューで、reviewer がレビュー結果をファイル化しようとしても Write ツール権限がないため「PM がファイル化してください」と毎回応答するパターンになりました。

改善案： reviewer 系エージェント（requirements-reviewer / planning-reviewer 等 6 体）に Write ツール権限を追加。書き込み先は docs/99-pm/review-*.md のみに制限。

9.2 コスト構造の損益分岐 MAU 試算

要件定義時点で「広告収益型ビジネスモデルの収支試算がゼロ」「Messaging API のコスト試算欠如」が Major 指摘になりました。

改善案： requirements-toolkit のテンプレに「収支分岐 MAU 概算試算（仮置きでも必須）」「主要従量課金サービスの MAU 別月額試算」のセクションを追加。

9.3 要件未明記項目の決定 ID への昇格

business-flow-designer が「期限切れクーポンのアーカイブ保持期間が要件未明記」と検出。業界標準で 30 日と補完しましたが、これは本来 D-NNN として decision-log に昇格すべき判断でした。

改善案： business-flow-designer の出力プロトコルに「要件未明記検出 → 仮置き判断 → 決定 ID 昇格提案」のセクションを必須化。

10. まとめ

AI エージェント 28 体で SaaS を構築する試みは、予想以上の成果を上げました。特に：

PM ゲートウェイ・アーキテクチャにより、自然言語指示だけで適切なエージェントが自動起動
SDLC 14 フェーズの必須化（Phase 12/13 スキップ禁止）で品質を担保
ADR 10 本で技術選定の根拠を文書化し、後日の判断材料に
E2E テスト 45/45 passでデプロイ前の品質を確認

一方で、ブラウザテスト自動化にはまだ課題が残りました。iOS Standalone Mode の実機テスト、OCR のモック化、ビジュアル回帰テストの導入など、改善の余地は大いにあります。

このフレームワークは、個人開発 SaaS の量産を目指しています。次の案件では、さらに洗練された自動化を実現できるでしょう。

関連リンク：

クポ活レーダー：https://kupo-radar.jp
Noguchi SaaS Framework（プライベートリポジトリ）
前記事：AI エージェントのテストとデバッグ手法

この記事が役に立ったらシェアしてください

AIエージェント開発に取り組む仲間に、この情報を届けましょう

Facebookでシェア X (Twitter)でシェア

この記事をシェア

1. プロジェクト概要

2. 仮想 AI 会社の設立

2.1 エージェント組織図

2.2 PM ゲートウェイ・アーキテクチャ

3. ウォーターフォール型 SDLC 14 フェーズ

3.1 Phase 12/13 のスキップ禁止

4. ログイン後画面の UI

4.1 UI 実装のポイント

5. フレームワーク構造

4.1 リポジトリ構造

4.2 coupon-rader プロジェクト構造

6. 各フェーズの成果物

6.1 Phase 1: 要件定義

6.2 Phase 3: 企画

6.3 Phase 5: 外部設計

6.4 Phase 7: 内部設計

6.5 Phase 9: テスト計画

7. 実装（Phase 11）

7.1 PWA モック実装（Phase 5.5）

7.2 営業ポータルサイト（LP）実装

7. E2E テスト（Phase 12）

8.1 Playwright 設定

8.2 テスト結果

8. ブラウザテスト自動化の課題

9.1 iOS Standalone Mode の制約

8.2 認証状態の管理

8.3 OCR のモック化

8.4 回帰テストの必要性

9. 学んだこと・フレームワークへの還流

9.1 レビュアーの Write 権限

9.2 コスト構造の損益分岐 MAU 試算

9.3 要件未明記項目の決定 ID への昇格

10. まとめ

この記事が役に立ったらシェアしてください

カテゴリ

公開日

💬 無料技術相談のご案内

お気軽にご相談ください

📚 目次

📖 関連記事

AIエージェントのテストとデバッグ手法

マルチエージェント・コマンド設計の実践ケーススタディ

Anthropic Agentic SDKが切り拓く「サブスク解放」の衝撃

👨💻 著者について

野口真一