1人でSaaSのMVPをAIエージェントと作る【2026】仕様書駆動・テスト・CI・サブエージェント

yoyakuru/
├── CLAUDE.md                    # AIと人の共通ルール
├── docs/
│   ├── prd.md                   # PRD：目的・対象ユーザー・スコープ・非スコープ
│   ├── stories.md               # ユーザーストーリーと受け入れ条件（Given/When/Then）
│   └── adr/
│       ├── 0001-web-framework.md
│       ├── 0002-database.md
│       └── 0003-auth.md
├── src/
│   ├── domain/                  # 予約の重なり判定など、フレームワーク非依存のロジック
│   ├── server/                  # DBアクセス・認可チェック（必ず tenantId で絞る）
│   └── app/                     # 画面とAPIルート
├── db/migrations/               # スキーマ変更は必ずマイグレーションで
├── tests/                       # 受け入れ条件と1対1のテスト
├── .github/workflows/ci.yml     # lint / typecheck / test / build
└── .claude/
    ├── settings.json            # permissions と hooks
    ├── agents/                  # テスト係・レビュー係・セキュリティ係
    └── skills/                  # 定型作業（新しいAPIルート追加、マイグレーション作成）

# Claude Code をインストール（手順は執筆時点。公式ドキュメントで最新を確認）
npm install -g @anthropic-ai/claude-code

mkdir yoyakuru && cd yoyakuru
git init
claude

小規模店舗向けの予約受付SaaSのMVPを1人で作りたい。まだコードは書かないで。
まず私に質問して、PRD（docs/prd.md）を作るための情報を集めて。質問は一度に5つまで。

最終的な PRD には次を含めて:
- 解決する課題と対象ユーザー（誰の・どんな場面の・何が不便か）
- MVP の成功条件（測れる形で）
- スコープ（やること）と「非スコープ（MVP ではやらないこと）」を同じ重さで
- 前提と未決事項
一般論で埋めず、私の回答に根拠がない項目は「未決」と書いて。

## 非スコープ（MVP ではやらない）
- 事前決済・キャンセル料の徴収（店舗側の月額課金のみ扱う）
- 複数店舗の一括管理（1 アカウント = 1 店舗）
- お客さんの会員登録・ポイント
- 外部カレンダーとの双方向同期（MVP では予約確定時の .ics 添付のみ）
- 多言語対応
## 成功条件
- 3 店舗が 4 週間継続して使い、うち 1 店舗以上が有料プランへの移行に同意する

docs/prd.md のスコープを、ユーザーストーリーに分解して docs/stories.md に書いて。
- 形式: 「〔役割〕として、〔目的〕のために、〔機能〕したい」
- 各ストーリーに受け入れ条件を Given/When/Then で。正常系だけでなく、
  境界値（営業時間の端、同時刻の予約）、権限（他店舗のデータ）、異常系を必ず含める
- 優先度 Must / Should / Could を付けて、Must だけで MVP が成立するか確認して

### S-03 お客さんとして、空き枠から予約したい（Must）
- AC1: Given スタッフAの 10:00-11:00 に確定予約がある
       When 別のお客さんが スタッフA 10:30-11:30 を予約しようとする
       Then 予約は作成されず「この時間は埋まっています」と表示される
- AC2: Given スタッフAの 10:00-11:00 に確定予約がある
       When 11:00-12:00 を予約する
       Then 予約できる（終了時刻と開始時刻が同じなら重ならない）
- AC3: Given 2人がほぼ同時に同じ枠を予約する
       Then 確定するのは1件だけで、もう1人にはエラーが返る
### S-07 店舗オーナーとして、自分の店の予約だけを見たい（Must）
- AC1: Given 店舗Xのオーナーがログインしている
       When 店舗Yの予約IDを指定して詳細を開く
       Then 404 を返す（存在自体を明かさない）

docs/prd.md と docs/stories.md を読んで、ヨヤクルの技術構成の選択肢を3案比較して。
前提: 開発・運用は私1人、TypeScript が得意、月額インフラ費はMVP期間は最小に、
      予約の二重登録をDBレベルで防ぎたい、店舗ごとのデータ分離が必須。
比較の軸: 学習コスト / 1人での運用負荷 / 二重予約防止の実現方法 / マルチテナントの分離方法 /
          認証の作り方 / コストの増え方 / ロックイン / 撤退（移行）のしやすさ
表にしたあと、推奨とその理由、推奨しない場合に後悔しそうな点を書いて。決定は私がする。

# ADR 0002: データベースに PostgreSQL を使う

- 状態: 承認（2026-09-xx）
- 決定者: 人間（オーナー）。比較表の作成は Claude Code

## 背景
予約の二重登録を防ぐ必要がある（stories.md S-03 AC3）。アプリ側のチェックだけでは
同時リクエストで競合する。店舗ごとのデータ分離も必須（S-07）。

## 決定
PostgreSQL を使い、二重予約は排他制約（EXCLUDE USING gist）で DB レベルで防ぐ。
全テーブルに tenant_id を持たせ、アプリの全クエリで tenant_id を条件に含める。

## 却下した選択肢
- NoSQL 系: 時間範囲の重なりを DB で一意に保証しにくい
- アプリ側ロックのみ: 複数インスタンスで破綻する

## 結果・トレードオフ
- 良い: 同時予約の整合性を DB が保証。テストも「制約違反が起きるか」で書ける
- 悪い: gist 排他制約は拡張 btree_gist が必要。マネージド DB が対応しているか確認が必要
- 見直す条件: 店舗数が増え、テナント単位のDB分離が必要になったとき

# ヨヤクル 開発ルール

## 必読
- 仕様: docs/prd.md, docs/stories.md（受け入れ条件 = テストの元）
- 設計判断: docs/adr/。ADR と矛盾する変更は提案だけして実装しない

## コマンド
- npm run lint / npm run typecheck / npm test / npm run build
- DB: docker compose up -d db → npm run db:migrate

## 実装の進め方
1. 対象ストーリーの受け入れ条件をテストとして先に書き、失敗することを確認する
2. テストを通す最小の実装をする
3. lint / typecheck / test が通ったら、変更内容とテスト結果を報告する（コミットは指示があるまでしない）

## 絶対ルール
- DB アクセスは必ず src/server/ の関数経由。全クエリに tenantId 条件を付ける
- 入力は API の入口で zod で検証する。検証前の値を DB に渡さない
- 秘密情報（.env*）を読まない・出力しない。新しい環境変数は .env.example に名前だけ追加
- スキーマ変更は db/migrations/ に新しいファイルを追加。既存のマイグレーションは編集しない
- 依存パッケージの追加は理由を説明して承認を得てから

{
  "permissions": {
    "allow": [
      "Bash(npm run lint:*)",
      "Bash(npm run typecheck:*)",
      "Bash(npm test:*)",
      "Bash(npm run build:*)",
      "Bash(git diff:*)",
      "Bash(git status)"
    ],
    "ask": ["Bash(git commit:*)", "Bash(npm install:*)", "Bash(npm run db:migrate:*)"],
    "deny": ["Read(./.env)", "Read(./.env.local)", "Read(./.env.production)", "Bash(git push:*)", "Bash(npx vercel:*)", "Bash(wrangler deploy:*)"]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "npm run lint --silent 1>&2 && npm run typecheck --silent 1>&2 || exit 2" }]
      }
    ]
  }
}

docs/stories.md の S-03 を実装したい。まずテストだけ書いて、実装はまだしないで。
- AC1, AC2 は src/domain/ の純粋関数（重なり判定）の単体テストで
- AC3（同時予約）は DB の排他制約が効くことを確認する統合テストで
- テストを実行して、すべて「期待どおりに失敗する」ことを確認して報告して

import { describe, it, expect } from "vitest";
import { overlaps } from "../../src/domain/overlap";

const t = (hhmm: string) => new Date(`2026-10-01T${hhmm}:00+09:00`);

describe("overlaps（S-03 AC1/AC2）", () => {
  it("一部でも重なる枠は重複とみなす", () => {
    expect(overlaps({ start: t("10:00"), end: t("11:00") }, { start: t("10:30"), end: t("11:30") })).toBe(true);
  });
  it("終了時刻と開始時刻が同じなら重ならない（半開区間）", () => {
    expect(overlaps({ start: t("10:00"), end: t("11:00") }, { start: t("11:00"), end: t("12:00") })).toBe(false);
  });
  it("一方が他方を完全に含む場合も重複", () => {
    expect(overlaps({ start: t("10:00"), end: t("12:00") }, { start: t("10:30"), end: t("11:00") })).toBe(true);
  });
});

export type Slot = { start: Date; end: Date };

// 半開区間 [start, end) として重なりを判定する。
// 「11:00 終了」と「11:00 開始」は重ならない（S-03 AC2）
export function overlaps(a: Slot, b: Slot): boolean {
  return a.start < b.end && b.start < a.end;
}

-- 同じスタッフの確定予約が時間的に重なることを DB で禁止する（S-03 AC3 / ADR 0002）
CREATE EXTENSION IF NOT EXISTS btree_gist;

ALTER TABLE reservations
  ADD CONSTRAINT no_double_booking
  EXCLUDE USING gist (
    staff_id WITH =,
    tstzrange(start_at, end_at, '[)') WITH &&
  )
  WHERE (status = 'confirmed');

name: ci
on:
  pull_request:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: postgres
        ports: ["5432:5432"]
        options: >-
          --health-cmd pg_isready --health-interval 5s --health-timeout 5s --health-retries 10
    env:
      DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm run db:migrate
      - run: npm test
      - run: npm run build
      - run: npm audit --audit-level=high

---
name: security-reviewer
description: PR前に差分をセキュリティ観点でレビューする。認証・認可・入力検証・秘密情報・依存パッケージを確認。コードは修正しない。
tools: Read, Grep, Glob, Bash
---
あなたはマルチテナントSaaSのセキュリティレビュアーです。`git diff main...HEAD` を対象に確認し、
「重大 / 要確認 / 軽微」に分けてファイルと行を添えて報告してください。修正はしません。

- 認可: src/server/ の全クエリに tenantId 条件があるか。ID を URL から受け取る箇所で所有者チェックがあるか
- 認証: 管理画面の API ルートにセッション確認があるか。公開予約ページから管理 API を呼べないか
- 入力検証: API の入口で zod 検証しているか。検証前の値が DB・HTML・メール本文に渡っていないか
- 秘密情報: キー・トークンのハードコード、ログへの個人情報（メール・電話）出力
- 依存: 新規追加パッケージの必要性・メンテ状況・権限（postinstall スクリプト等）

---
name: add-api-route
description: ヨヤクルに新しい API ルートを追加するときの手順。管理画面・公開ページどちらの API にも使う。
---
1. docs/stories.md の該当ストーリーと受け入れ条件を確認する
2. 入力スキーマを zod で src/app/api/<name>/schema.ts に定義する
3. 受け入れ条件のテストを tests/api/<name>.test.ts に先に書き、失敗を確認する
   - 必ず含める: 未ログイン→401、他テナントのID→404、不正入力→400
4. src/server/ にテナントで絞ったデータアクセス関数を追加する（直接 DB を呼ばない）
5. ルートを実装し、npm run lint / typecheck / test を通す
6. 変更ファイル一覧とテスト結果を報告する

import { z } from "zod";

export const CreateReservation = z.object({
  staffId: z.string().uuid(),
  menuId: z.string().uuid(),
  startAt: z.string().datetime({ offset: true }),
  customerName: z.string().trim().min(1).max(50),
  customerEmail: z.string().email().max(254),
  note: z.string().max(500).optional(),
});

export type CreateReservationInput = z.infer<typeof CreateReservation>;

// ルート側: const parsed = CreateReservation.safeParse(await req.json());
//           if (!parsed.success) return Response.json({ error: "invalid_input" }, { status: 400 });

import { describe, it, expect } from "vitest";
import { getReservation } from "../../src/server/reservations";
import { seedTwoTenants } from "../helpers/seed";

describe("S-07 AC1: 他店舗の予約は見えない", () => {
  it("店舗Xのオーナーが店舗Yの予約IDを指定すると null（APIでは404）", async () => {
    const { tenantX, reservationOfY } = await seedTwoTenants();
    const result = await getReservation({ tenantId: tenantX.id }, reservationOfY.id);
    expect(result).toBeNull();
  });
});

本番で次のエラーが出ている（スタックトレースとログを下に貼る）。コードはまだ変えないで。
1. 原因の仮説を 3 つ、それぞれの確かめ方とセットで出して
2. 最も可能性が高い仮説について、このエラーを再現する失敗テストを書いて実行して
3. 再現できたら、修正方針を提案して（実装は承認後）
ログに個人情報が含まれていたら、その箇所も指摘して
--- ログ ---
（ここに貼る。メールアドレスなどはマスクしてから）