Skip to content
Potola Art Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

PoC and Experiments

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置き場である。

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

例:

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/ は、本番昇格を前提としない技術調査・比較・一時検証を配置する。

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

例:

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

benchmarks

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

spikes

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

throwaway

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

notes

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

5. 命名規則

sandbox

poc-YYYY-MM-topic

例:

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

experiments

YYYY-MM-topic

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

tmp-YYYY-MM-topic

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

6. PoCのREADME

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

最低限、次を記録する。

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

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

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

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

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

概念的には:

design
↓
sandbox
↓
frontend / backend

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

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

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

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

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:

Issue
↓
Plan
↓
frontend / backend
↓
Test / Review

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

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

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

13. 要約

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

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

Was this page helpful?