先に書いて、
全部渡します。

1. 01

   要件定義

   機能に ID を振り、Must / Should を決めます。曖昧なまま実装に入らないための土台です。

   ### 5.7 Human-in-the-Loop (FR-H)
   
   | ID | 要件 | 優先度 |
   | --- | --- | --- |
   | FR-H-01 | 回答は `draft → pending_review → approved → sent` の順序でのみ遷移する | Must |
   | FR-H-02 | `approved` 以外の回答は送信APIを呼べない (DB制約 + アプリ検証) | Must |
   | FR-H-03 | レビュー時に差し戻し (`rejected`) ができ、理由が必須である | Must |
   …
   | FR-H-07 | 承認済み回答を編集した場合、`draft` に戻り再承認が必要になる | Must |
   | FR-H-08 | 送信失敗時は `failed` となり、再送できる | Should |
   
   **状態遷移図**
   
   ```
                    ┌─────────── reject (理由必須) ───────────┐
                    ↓                                          │
     [draft] ──submit──> [pending_review] ──approve──> [approved] ──send──> [sent]
        ↑                                                  │                   │
        └────────── edit (承認済みの編集は draft へ戻る) ────┘                   │
                                                                               │
                             [rejected] ──edit──> [draft]        [failed] ──retry┘
   ```

   この FR- 番号は、以降の設計書・テスト・チェックリストから参照され続けます。 「どの要件が、どのコードとどのテストで守られているか」を後から辿れる状態にしておくためです。

2. 02

   アーキテクチャ設計

   層の分け方と、守るべき性質をどこで担保するかを決めます。差し替え可能な箇所もここで決めます。

   ### 7.2 三重の防御
   
   送信可能な回答は `approved` のみ。これを**3箇所**で担保する。
   
   1. **Domain 層** — `transition()` が `approved` 以外からの `send` を拒否する
   2. **Application 層** — `response.service.ts` の `sendResponse()` が実行前に現在の状態をDBから再取得して検証する
   3. **DB 層** — `outbound_messages` に INSERT する際、`responses.status = 'approved'` を要求するトリガー制約を張る
   
   > UIでボタンを隠すことは防御ではなく UX である。3層とは別に数える。

   最後の一行が、この段階でいちばん大事な判断です。「画面に出していないから安全」は設計とは呼ばない、という線引きを文章で残しておきます。

3. 03

   データベース設計

   テーブル・制約・トリガー・行レベルの権限まで、SQL の形で書き下します。ER 図と索引設計も同じ文書に入ります。

   ### 7.2 ヘルパー関数
   
   `policy.ts` の `isAdmin()` / `isPrivileged()` に 1:1 で対応させる。
   
   ```sql
   -- policy.ts: PRIVILEGED_ROLES = ["admin", "manager"]
   create or replace function public.app_role()
   returns text
   language sql stable security definer set search_path = public
   as $$
     select u.role from public.users u where u.id = auth.uid() and u.is_active;
   $$;
   
   -- policy.ts: isAdmin(user)
   create or replace function public.is_admin()
   returns boolean
   language sql stable
   as $$ select public.app_role() = 'admin'; $$;
   …
   ```
   
   `is_active` を条件に含めることで、無効化ユーザーはトークンが残っていてもデータに触れない（FR-009 の DB 側担保）。

   同じ文書の 7.8 節には、アプリ側の権限関数と DB 側ポリシーの対応表が全件並んでいて、 「片方を変更したら必ずもう片方も変更する。」 と明記されています。権限は 2 か所に書くので、ずれない仕組みを文書側で決めておきます。

4. 04

   画面設計

   画面ごとにワイヤーフレームを引き、通常表示だけでなく Loading / 空 / エラー / 権限不足の 4 状態を決めます。

   ### 5.2 SC-02 ダッシュボード
   
   ```
   ┌─ PageHeader ─────────────────────────────────────────────────────────────┐
   │ ダッシュボード                              [自分の案件のみ ○ ] [期間 ▾]  │
   │ 営業状況の全体像を確認できます                                            │
   └──────────────────────────────────────────────────────────────────────────┘
   
   ⚠ 期日を過ぎた未完了 TODO が 3 件あります                      [確認する →]
   
   ┌──────────────┬──────────────┬──────────────┬──────────────┐
   │ 案件総額      │ 受注見込      │ 受注済み(12M) │ 勝率          │
   │ ¥248,500,000 │ ¥112,340,000 │ ¥86,200,000  │ 62.5%        │
   │ 進行中 42 件  │ 加重平均 45%  │ 前年比 +12%   │ 24勝 / 14敗   │
   └──────────────┴──────────────┴──────────────┴──────────────┘
   
   ┌──────────────────────────────────────┬───────────────────────────────┐
   │ 月別売上見込                          │ ステータス別                   │
   │ ┌──────────────────────────────────┐ │ ┌───────────────────────────┐ │
   │ │  ▁▃▅▂▇▄ ▃▅▆▄▂▁                    │ │ │ リード      12件  ¥52.0M  │ │
   │ │  ■受注済 ■加重見込 ▨パイプライン  │ │ │ ████░░░░░░░░░░░░          │ │
   │ │  3月 4月 5月 6月 7月 8月 ...       │ │ │ 提案        18件  ¥98.5M  │ │
   │ └──────────────────────────────────┘ │ │ ████████░░░░░░            │ │
   │  (ComposedChart / chart-1..3)         │ │ 交渉        12件  ¥98.0M  │ │
   │                                       │ │ 受注        24件  ¥86.2M  │ │
   │                                       │ │ 失注        14件  ¥41.0M  │ │
   │                                       │ └───────────────────────────┘ │
   └──────────────────────────────────────┴───────────────────────────────┘
   …
   ```
   
   | 項目 | 仕様 |
   | --- | --- |
   | データ源 | `db.dashboard.getSummary(ownerId?)` の 1 回呼び出しで `DashboardSummary` を取得 |
   …
   | Empty | データ 0 件時、KPI は `¥0` を表示し、グラフ領域に `<EmptyState … />` |
   | Error | カード単位で `<ErrorState onRetry />`。全体失敗時は `error.tsx` |

   ワイヤーフレームの下には、必ずデータの取得元・表示書式・4 状態の仕様が表で続きます。 「実装してみたら空のときの見た目が決まっていなかった」を無くすための書き方です。

5. 05

   実装計画

   どの順序で、どの単位で作るか。そして何をもって完了とみなすかを先に決めます。

   ## 1. 実装方針
   
   | # | 方針 | 理由 |
   | --- | --- | --- |
   | I-01 | 共通契約を最初に凍結し、以後変更しない | 並列実装で最も壊れやすいのはレイヤー間の型の食い違い。契約を先に確定すれば、各担当は互いの完成を待たずに書ける |
   | I-02 | ファイル所有権を担当ごとに排他分割する | 同一ファイルへの同時書き込みを構造的に不可能にする |
   | I-03 | 縦切り（機能単位）で分割する | 横切り（層単位）だと全層が揃うまで 1 画面も動かない。縦切りなら顧客管理から順に動作確認できる |
   | I-04 | デモモードを先に完成させる | 環境変数ゼロで動く状態を保てば、レビューも E2E も外部依存なしで回せる |
   | I-05 | 各担当が自分の担当範囲の単体テストを同時に書く | テストを後工程にまとめると必ず削られる |
   | I-06 | 統合は必ず 1 名が担当する | 契約からの逸脱・型の齟齬は結合時にしか現れない。修正の責任者を 1 人に固定する |

   「方針」だけでなく「理由」の列があるのが要点です。後から仕様を変えたくなったとき、 何を壊すことになるのかが読めば分かります。AI を並列で走らせる前提の分割も、この段階で決めています。

6. 06

   実装とテスト

   設計書のとおりに実装し、決めた基準を機械で確認します。テストは後回しにせず同時に書きます。

     [公開ウェブアプリの安全性]
     ✓ 匿名では秘密情報を保存できない
     ✓ 匿名では秘密情報の状態も取得できない
     ✓ 拒否された保存は反映されていない
     ✓ 匿名では設定を診断できない
     ✓ 匿名では日次ジョブを実行できない
     ✓ 偽のトリガーイベントでも実行できない
   …
     ✓ 匿名でもダッシュボードは閲覧できる
     ✓ 操作者が戻れば書き込み系も実行できる
   
   ============================================================
   全 118 項目が成功しました（3 シナリオ / 1248 ms）

   テスト名は日本語です。開発者以外が読んでも「何を守っているか」が分かるようにしてあります。 6 本合計で 3,237 件。数と内訳は次の節に出します。

• 仕様

  設計書は、AI への発注書でもある

  先に書く設計ドキュメントは、そのまま AI に渡す仕様書です。 発注者向けの納品物と、実装のための指示が同じファイルなので、書きっぱなしになりません。

• 検証

  出てきたコードは、機械で確かめる

  型・lint・テスト・ビルドの全通過を、実装を進める条件にしています。 AI の出力を人の目視だけで通すことはしません。

• 境界

  プロダクト内の AI も、決定者にしない

  AI 機能は要約・分類・下書きまで。送信や登録は人の承認を通します。 その境界をアプリ層・サービス層・DB の 3 層で担保しています。

### 5-11. シートの型変換を前提にする（実際に踏んだ落とし穴）

`setValues()` に `'2026-08-15'` のような文字列を渡すと、セルの書式がテキストでない限り **Sheets はこれを日付値として保存します**。読み戻すと `Date` が返るため、次のコードは静かに壊れます。

```js
const dateKey = String(v[RAW_COL.date]);   // 'Sat Aug 15 2026 00:00:00 GMT+0900 …'
if (dateKey > f.dateTo) continue;          // 文字列比較なので常に真 → 全行が除外される
```

初回のデプロイでこれが発生し、RAW_DATA へ 591 件保存されたにもかかわらず日次集計の対象が 0 行になりました。例外は出ず、通知も「正常完了」だったため、**シートを開くまで気づけない**種類の障害です。
…
**テストへの反映**: このバグをすり抜けたのは、テスト用のインメモリ `SpreadsheetApp` が文字列をそのまま返す「素直すぎる」実装だったからです。本物と同じ型変換を再現するよう修正し、書式を壊した状態でも読み出し側だけで復旧できることを検証するシナリオを追加しました。**モックは本物より寛容であってはならない**、というのがここでの教訓です。

-- 修正: UPDATE ポリシーの WITH CHECK にロール条件が欠けていた問題
--
-- 【背景】
--   PostgreSQL は同一コマンドの複数の permissive ポリシーを OR で結合する。
--   UPDATE では USING (更新前の行) と WITH CHECK (更新後の行) が
--   ポリシー単位で対にならず、それぞれ独立に評価される。
--
--   つまり「あるポリシーの USING」と「別のポリシーの WITH CHECK」の
--   組み合わせで通過できてしまう。
--
-- 【検出された穴】
--   1. agent が responses.status を 'approved' に更新できた
--      - responses_update_agent の USING を通過 (status = pending_review)
--      - responses_update_admin の WITH CHECK を通過 (org_id 一致のみを要求)
--      → Human-in-the-Loop の承認ゲートが RLS 層で迂回可能だった
--
--   2. agent が自分の profiles.role を 'admin' に変更できた (自己昇格)
--      - profiles_update_self の USING を通過 (id = auth.uid())
--      - profiles_update_admin の WITH CHECK を通過 (org_id 一致のみを要求)
--
-- 【対処】
--   すべての UPDATE ポリシーの WITH CHECK に、USING と同じロール条件を課す。
--   これにより「更新前は許可、更新後は別ポリシーで許可」という抜け道を塞ぐ。

# 実装契約（全エージェント共通・必読）

このファイルは並列実装時の衝突を防ぐための「所有権」と「レイヤー間 API」の取り決め。
**自分の担当外のファイルを絶対に作成・編集しないこと。** 必要になったら契約に従って import する。

…

## 2. ディレクトリ所有権

```
src/
  app/
…
    (app)/layout.tsx                    [C] Sidebar + Header シェル
    (app)/dashboard/page.tsx            [G]
    (app)/customers/**                  [E]
    (app)/deals/**                      [F]
    (app)/activities/**                 [H]
    (app)/settings/users/**             [D]
    api/**                              使用しない（Server Actions に統一）
…
  lib/
    domain/types.ts                     [済] 触るな
    domain/constants.ts                 [済] 触るな
    utils/cn.ts, utils/format.ts        [済] 触るな
    env.ts                              [済] 触るな
    authz/policy.ts                     [済] 触るな（テストは J が追加）
    data/repository.ts                  [済] 触るな
…
docs/01〜05                             [A]
README.md / ARCHITECTURE.md / SECURITY.md / TESTING.md  [K]
```

• kizuna-desk

  AI問い合わせ管理システム

  AI が要約・分類・回答案を作り、送信は人が承認する。

  デモを見る

• sales-crm

  営業・案件管理Webアプリ

  顧客・案件・活動を 1 か所に集め、集計と可視化を自動で回す。

  デモを見る

• gas-ads-report

  広告レポート自動集計

  毎朝 7:00、広告データを取得して集計し、ダッシュボードまで更新する。

  デモを見る

  スプレッドシートを見る

• shiori-rag

  社内文書AI検索（RAG）

  社内規程やマニュアルに出典つきで答え、記載が無ければ答えない。

  デモを見る

• ai-doc-workflow

  AI文書業務自動化

  請求書や発注書を AI が読み取り、自信の無い項目だけを人が確認して承認する。

  デモを見る

• ai-meeting-workflow

  AI会議後業務自動化（n8n）

  会議の文字起こしを AI が整理し、人が承認してから Slack・メール・予定・台帳へ同時に反映する。

  デモを見る

• ai-browser-automation

  AIブラウザ業務自動化

  APIの無い既存Webシステムへ、AIが判断し人が承認した内容をブラウザ操作で自動登録する。

  デモを見る

トップページへ戻る：7 本の画面キャプチャ・機能・技術スタック・デモアカウントはそちらにまとめています。