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

Potola Development Workflow

development-workflow.md

1. 目的

本ドキュメントは、Potola の標準開発フローを定義する。

Potola は AI Coding Agent を活用した開発を前提とする。

そのため、

  • 要件整理
  • 設計
  • Issue管理
  • Plan作成
  • 実装
  • テスト
  • レビュー

の手順を統一し、

人間とAIが同じ開発プロセスで協働できる状態を作ることを目的とする。

2. 基本思想

Potola は Vertical Slice を採用する。

つまり、

  • DBだけ完成
  • APIだけ完成
  • UIだけ完成

ではなく、

利用者価値を持つ体験を、小さく最後まで完成させる

ことを優先する。

3. 開発フロー

Potola の標準開発フローは以下とする。

アイデア

↓

DocBase

↓

Epic Issue

↓

Sub Issue

↓

Plan

↓

実装

↓

受け入れテスト

↓

Pull Request

↓

レビュー

↓

マージ

↓

完了

4. Step1 要件整理

目的

何を作るべきかを整理する。

実装方法ではなく、

利用者価値を定義する。

作業場所

DocBase

記載内容

  • 背景
  • 課題
  • 利用者価値
  • ユースケース
  • 非機能要件
  • 制約事項
  • Phase 1 Scope
  • Out of Scope

良い例

利用者は写真をアップロードできる

アップロード後はアルバムへ登録できる

公開URLで第三者へ共有できる

悪い例

Cloudflare Workersで実装する

これは設計であり要件ではない。

5. Step2 Epic作成

目的

機能単位で開発対象を整理する。

Epic例

Epic 0
開発基盤

Epic 1
認証

Epic 2
写真アップロード基盤

Epic 3
アルバム管理

Epic 4
公開閲覧

Epicに記載する内容

  • 目的
  • 背景
  • Scope
  • Out of Scope
  • 完成条件

6. Step3 Sub Issue作成

目的

AIが実装できる粒度まで分割する。

原則

1 Issue = 1責務

良い例

写真アップロードAPI作成

写真一覧取得API作成

R2保存処理実装

アップロード画面作成

悪い例

写真機能を作る

粒度が大きすぎる。

7. Step4 Plan作成

目的

実装前に設計を確認する。

重要原則

AIにいきなり実装させない。

必ずPlanを作る。

Planに含める内容

実装対象

何を作るか

対象ファイル

どこを変更するか

データ構造

必要な型

テーブル

API

テスト観点

何を確認するか

良いPlan例

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へ渡す情報

Issue

Plan

Architecture

Tech Stack

Coding Rules

10. Step7 受け入れテスト

目的

利用者価値が成立しているか確認する。

Potolaの方針

Phase 1 は ATDD を重視する。

確認するもの

コードではなく振る舞い。

例

写真アップロード

Given
ログイン済み

When
写真を選択してアップロード

Then
写真が保存される

アルバム作成

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 条件を書く。

良い例

写真アップロード成功

R2保存成功

DB登録成功

エラー時にメッセージ表示

受け入れテスト合格

悪い例

アップロード機能完成

曖昧である。

15. Vertical Slice の考え方

Potolaは機能単位で完成させる。

良い例

写真アップロード

UI

API

DB

R2

動作確認

まで完成

悪い例

全DB作成

↓

全API作成

↓

全UI作成

16. AI Coding Agent運用ルール

AIは実装者であり、

要件決定者ではない。

AIは以下を勝手に変更してはならない。

  • Scope
  • Out of Scope
  • Tech Stack
  • Architecture

AIが判断に迷う場合

実装しない

↓

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 単位で完成させる。

Was this page helpful?