--- title: Potola Development Workflow --- development-workflow.md ## 1. 目的 本ドキュメントは、Potola の標準開発フローを定義する。 Potola は AI Coding Agent を活用した開発を前提とする。 そのため、 * 要件整理 * 設計 * Issue管理 * Plan作成 * 実装 * テスト * レビュー の手順を統一し、 人間とAIが同じ開発プロセスで協働できる状態を作ることを目的とする。 --- ## 2. 基本思想 Potola は Vertical Slice を採用する。 つまり、 * DBだけ完成 * APIだけ完成 * UIだけ完成 ではなく、 > 利用者価値を持つ体験を、小さく最後まで完成させる ことを優先する。 --- ## 3. 開発フロー Potola の標準開発フローは以下とする。 ```text アイデア ↓ DocBase ↓ Epic Issue ↓ Sub Issue ↓ Plan ↓ 実装 ↓ 受け入れテスト ↓ Pull Request ↓ レビュー ↓ マージ ↓ 完了 ``` --- # 4. Step1 要件整理 ## 目的 何を作るべきかを整理する。 実装方法ではなく、 利用者価値を定義する。 --- ## 作業場所 DocBase --- ## 記載内容 * 背景 * 課題 * 利用者価値 * ユースケース * 非機能要件 * 制約事項 * Phase 1 Scope * Out of Scope --- ## 良い例 ```text 利用者は写真をアップロードできる アップロード後はアルバムへ登録できる 公開URLで第三者へ共有できる ``` --- ## 悪い例 ```text Cloudflare Workersで実装する ``` これは設計であり要件ではない。 --- # 5. Step2 Epic作成 ## 目的 機能単位で開発対象を整理する。 --- ## Epic例 ```text Epic 0 開発基盤 Epic 1 認証 Epic 2 写真アップロード基盤 Epic 3 アルバム管理 Epic 4 公開閲覧 ``` --- ## Epicに記載する内容 * 目的 * 背景 * Scope * Out of Scope * 完成条件 --- # 6. Step3 Sub Issue作成 ## 目的 AIが実装できる粒度まで分割する。 --- ## 原則 1 Issue = 1責務 --- ## 良い例 ```text 写真アップロードAPI作成 写真一覧取得API作成 R2保存処理実装 アップロード画面作成 ``` --- ## 悪い例 ```text 写真機能を作る ``` 粒度が大きすぎる。 --- # 7. Step4 Plan作成 ## 目的 実装前に設計を確認する。 --- ## 重要原則 AIにいきなり実装させない。 必ずPlanを作る。 --- ## Planに含める内容 ### 実装対象 何を作るか --- ### 対象ファイル どこを変更するか --- ### データ構造 必要な型 テーブル API --- ### テスト観点 何を確認するか --- ## 良いPlan例 ```text 1. upload API作成 2. R2保存処理実装 3. DB登録処理実装 4. Upload画面作成 5. 受け入れテスト実施 ``` --- # 8. Step5 Planレビュー ## 目的 実装前に設計ミスを防ぐ。 --- ## 確認項目 * Scope内か * Out of Scopeを含んでいないか * Architectureに従っているか * Tech Stackに従っているか * Coding Rulesに従っているか --- ## 原則 Planレビュー前に実装しない。 --- # 9. Step6 実装 ## 目的 Planに従って実装する。 --- ## 原則 Planに書かれていない機能を追加しない。 --- ## AI利用時 AI Coding Agentへ渡す情報 ```text Issue Plan Architecture Tech Stack Coding Rules ``` --- # 10. Step7 受け入れテスト ## 目的 利用者価値が成立しているか確認する。 --- ## Potolaの方針 Phase 1 は ATDD を重視する。 --- ## 確認するもの コードではなく振る舞い。 --- ## 例 写真アップロード ```text Given ログイン済み When 写真を選択してアップロード Then 写真が保存される ``` --- アルバム作成 ```text Given ログイン済み When アルバム作成 Then アルバム一覧に表示される ``` --- # 11. Step8 Pull Request ## 目的 変更内容をレビュー可能にする。 --- ## PRに記載する内容 ### 概要 何を実装したか ### 関連Issue Issue番号 ### テスト結果 受け入れテスト結果 ### スクリーンショット UI変更がある場合 --- # 12. Step9 レビュー ## 目的 品質確認 --- ## レビュー観点 ### 要件 Issueを満たしているか ### 設計 Architectureに従っているか ### 技術 Tech Stackに従っているか ### コード Coding Rulesに従っているか ### テスト 受け入れ条件を満たしているか --- # 13. Step10 完了 以下を満たした場合に完了とする。 * 実装完了 * テスト完了 * PRレビュー完了 * マージ完了 * Done条件達成 --- # 14. Done条件 Issueには必ず Done 条件を書く。 --- ## 良い例 ```text 写真アップロード成功 R2保存成功 DB登録成功 エラー時にメッセージ表示 受け入れテスト合格 ``` --- ## 悪い例 ```text アップロード機能完成 ``` 曖昧である。 --- # 15. Vertical Slice の考え方 Potolaは機能単位で完成させる。 --- ## 良い例 ```text 写真アップロード UI API DB R2 動作確認 まで完成 ``` --- ## 悪い例 ```text 全DB作成 ↓ 全API作成 ↓ 全UI作成 ``` --- # 16. AI Coding Agent運用ルール AIは実装者であり、 要件決定者ではない。 --- AIは以下を勝手に変更してはならない。 * Scope * Out of Scope * Tech Stack * Architecture --- AIが判断に迷う場合 ```text 実装しない ↓ Planへ記載する ↓ 人間へ確認する ``` --- # 17. ドキュメント優先順位 判断に迷った場合は以下の順で従う。 1. potola-philosophy.md 2. architecture.md 3. tech-stack.md 4. coding-rules.md 5. development-workflow.md 6. GitHub Issue 7. Plan --- # 18. まとめ Potola 開発では、 > 要件 → Issue → Plan → 実装 → 受け入れテスト を基本とする。 AIにコードを書かせることが目的ではない。 利用者価値を安全に届けることが目的である。 そのため、 必ず Plan を作成し、 必ず受け入れテストを行い、 必ず Vertical Slice 単位で完成させる。