---
title: PoC and Experiments
---

本ドキュメントは、Potola における本番導入前のPoC、技術検証、一時実験の配置と運用ルールを定義する。

正式実装の配置は `02-repository-structure.md`、技術選定とシステム全体の設計は `01-architecture.md` を正本とする。

## 1. 基本方針

Potolaでは、すべての実装をPoCから開始するわけではない。

通常のIssueで、採用技術・実装方式・影響範囲が明確な場合は、承認されたPlanに従って正式実装へ進む。

PoCまたは実験を行うのは、主に次のような場合である。

- 新しい技術や外部サービスを採用する
- 実現可能性が不明
- 複数方式を比較する必要がある
- 性能・コスト・互換性を実測する必要がある
- 本番コードへ直接入れるには不確実性が高い

## 2. sandbox と experiments

Potolaでは検証コードを2種類に分ける。

| 項目 | `sandbox/` | `experiments/` |
| --- | --- | --- |
| 目的 | 本番候補のPoC | 技術調査・比較・一時検証 |
| 本番昇格 | 想定する | 原則想定しない |
| 構造 | 整理する | ラフでよい |
| 寿命 | 検証完了まで保持可能 | 短期 |
| ドキュメント | README推奨 | 必要最小限 |
| 品質 | 昇格判断できる程度 | 検証目的を満たせばよい |

## 3. sandbox

`sandbox/` は、本番採用の可能性がある方式を検証するためのPoC置き場である。

```text
sandbox/
├─ supabase/
├─ cloudflare-pages/
├─ r2/
├─ bunny/
├─ integration/
└─ _templates/
```

例:

```text
sandbox/cloudflare-pages/poc-2026-09-public-album-ui
sandbox/supabase/poc-2026-09-rls-pattern-a
sandbox/integration/poc-2026-09-upload-pipeline
```

### sandbox に置くもの

- 採用候補技術のPoC
- 本番方式を決定するための試作
- 外部サービス連携の実証
- UI/UXの実装方式を確認する試作
- 本番昇格を判断するために必要なコード

### sandbox に置かないもの

- 単純なバグ修正
- 実装方式が確定済みの通常Issue
- 一時的なベンチマークだけのコード
- 捨てる前提の小さな調査コード

## 4. experiments

`experiments/` は、本番昇格を前提としない技術調査・比較・一時検証を配置する。

```text
experiments/
├─ benchmarks/
├─ spikes/
├─ throwaway/
└─ notes/
```

例:

```text
experiments/benchmarks/r2-vs-bunny-download
experiments/spikes/cloudflare-cache-test
experiments/throwaway/tmp-upload-test
```

### benchmarks

性能・速度・コスト等を比較するための検証。

### spikes

未知の技術やAPIについて、実現可能性や挙動を短時間で確認するための検証。

### throwaway

結果だけ得られればよく、再利用を想定しないコード。

### notes

実験結果や判断材料を簡潔に残す。

## 5. 命名規則

### sandbox

```text
poc-YYYY-MM-topic
```

例:

```text
poc-2026-09-public-album-ui
poc-2026-09-rls-owner-policy
```

### experiments

```text
YYYY-MM-topic
```

または、一時性を明示する場合:

```text
tmp-YYYY-MM-topic
```

名前から検証対象が分かるようにする。

## 6. PoCのREADME

`sandbox/` のPoCには、原則としてREADMEを置く。

最低限、次を記録する。

```text
目的
検証する仮説
採用候補
確認方法
結果
結論
本番へ昇格するか
```

PoCそのものを長期的な仕様書にしない。採用された設計判断は、必要に応じてArchitectureや正式な仕様書へ反映する。

## 7. Figma・生成コードの扱い

Figma等から生成されたコードは、そのまま正式実装として `frontend/` に入れない。

本番採用前に検証が必要な場合は `sandbox/` で確認する。

概念的には:

```text
design
↓
sandbox
↓
frontend / backend
```

ただし、このフローは「生成コードや不確実性の高い試作を本番候補として検証する場合」のルールであり、すべての通常開発にPoCを要求するものではない。

## 8. 外部サービス連携のPoC

Potolaでは複数の外部サービスを組み合わせる可能性があるため、サービス単体だけでなく連携部分の検証も重視する。

連携方式に不確実性がある場合は、

```text
sandbox/integration/
```

を使用する。

例:

- 認証とフロントエンドの連携
- ストレージへのアップロード
- CDN・画像配信
- DBとストレージの整合性
- 外部APIのエラー処理

採用済みで方式が確立した連携については、通常IssueのたびにPoCを作らない。

## 9. 本番への昇格

`sandbox/` のコードをそのままコピーして本番コードとみなさない。

昇格時には、少なくとも次を確認する。

1. PoCの目的を満たしたか。
2. 採用する方式がArchitectureと矛盾しないか。
3. 本番の既存コード構造に適合するか。
4. エラー処理・型・セキュリティ・テストが本番品質になっているか。
5. 不要な検証コードやハードコードが残っていないか。
6. 正式な配置先が `02-repository-structure.md` に従っているか。

PoCは「動いたコード」、正式実装は「運用できるコード」として扱う。

## 10. PoC完了後

PoC完了後は次のいずれかを明確にする。

### Adopt

方式を採用する。

必要な設計判断を正式ドキュメントへ反映し、本番品質として実装する。

### Reject

方式を不採用とする。

不採用理由が将来の判断材料になる場合は、READMEやnotesに結論を残す。

### Continue

追加検証が必要。

何が未確認なのかを明示して継続する。

## 11. AIコーディング時の判断

AIは、通常のIssueを理由なく `sandbox/` や `experiments/` に実装してはならない。

PoC・実験を開始する前に、次を判断する。

1. 本当に不確実性があるか。
2. 本番候補を検証するのか、単なる調査なのか。
3. `sandbox/` と `experiments/` のどちらが適切か。
4. 検証終了条件は何か。
5. 本番へ昇格する場合、何を正式実装として作り直す必要があるか。

## 12. 開発フロー

通常のIssue:

```text
Issue
↓
Plan
↓
frontend / backend
↓
Test / Review
```

不確実性の高い新規方式:

```text
Issue / Technical Question
↓
sandbox または experiments
↓
結果・採否判断
↓
必要ならArchitecture / Planを更新
↓
frontend / backend
↓
Test / Review
```

つまり、PoCはPotola開発の必須フェーズではなく、技術的不確実性を本番実装から隔離するための手段である。

## 13. 要約

- `sandbox/` = 本番昇格候補のPoC
- `experiments/` = 昇格前提ではない技術調査
- 通常のIssueはPoCを経由する必要はない
- 不確実性が高い場合だけ検証レイヤーを使う
- PoCコードをそのまま本番品質とみなさない
- 採用した設計判断は正式なドキュメントへ戻す

この分離により、正式実装を安定させながら、新技術や外部サービスを安全に検証できる状態を維持する。