planning-flow

name	planning-flow
description	実装計画を立てる時、作業を計画する時、plan modeで作業する時に必ず従うフロー。立案済みの計画に基づいて実装を行う場合にもこのフローに従う。
user-invocable	true

Doc-First 開発フロー

このプロジェクトではDoc-Firstで開発を行う。コードを書く前に外部IFを設計・ドキュメント化し、利用イメージで妥当性を検証してから実装に入る。

計画の立て方

plan modeの進め方自体は標準フローに従う。ただし 計画の中身（作業手順）を以下のDoc-First Phaseで構成すること。計画承認後、Phase 1から順に実行する。

計画立案時は /docs および /packages/*/docs/ の関連ドキュメントを参照する。

計画ファイル

• /plans/yyyy-mm-dd-hh-mm_plan-name.md に保存
• タイムスタンプはdateコマンドで取得し、yyyy-mm-dd-hh-mmの形式
• 実装中の方針変更や追加の観点が出た場合もmdに反映（変更理由も簡潔に記録）

---

Doc-First Phase（計画承認後に実行）

計画の作業手順を以下のPhaseで構成する。Phase間のゲートを飛ばさないこと。

重要: これらのPhaseは計画が承認された後に実行する作業である。計画承認（plan mode終了）はあくまで「このPhase構成で進めてよい」という合意であり、Phase 1・2の完了を意味しない。

Phase 1: API設計・ドキュメント作成

コードを書く前に、パッケージの外部IFを決めて packages/*/docs/ にドキュメント化する。計画ファイルへの設計方針の記述とは別の作業である。

1. 新規・変更する関数シグネチャ、型定義、エクスポートを設計
2. 対象パッケージの packages/*/docs/ にAPIドキュメントを作成・更新
3. 設計意図・制約・使い分けを明記

Phase 2: 利用イメージレビュー

ドキュメント化したAPIが要求を満たすか、利用側の視点で検証する。

1. クライアントアプリ（apps/web）からの利用コード例を示す
2. 他パッケージから利用する場合の連携パターンを示す
3. ユーザーに利用イメージを提示し、要求に合うか確認を取る
4. 問題があればPhase 1に戻りAPI設計を修正

Phase 2を通過するまでコード実装に進まない。

Phase 3: 実装

Phase 2で承認されたAPI設計に基づいてコードを書く。

1. ドキュメントに記載したIFに沿って実装
2. テストを作成・実行
3. lint/formatを通す
4. Phase 1のドキュメントとの差分確認: 実装中にシグネチャ・デフォルト値・型を変更した場合、ドキュメントも同時に更新する

Phase 4: アーキテクトレビュー

実装完了後、以下の観点で設計の再レビューを行う。

1. ドキュメント整合性（双方向）: 実装とドキュメントが双方向で一致しているか確認する
   • コード→ドキュメント: 実装した関数のシグネチャ・デフォルト値・型がドキュメントと一致しているか
   • ドキュメント→コード: ドキュメントに記載された関数・型がソースに存在し、記載通りの定義になっているか
   • Phase 3中にAPIを微調整した場合（引数追加、デフォルト値変更、型の拡張など）、ドキュメントも更新済みか
2. 要求充足: 元々の要求を正しいIFで満たしているか
3. アーキテクチャ適合: パッケージ間の責務分離、データフロー、既存の設計原則に沿っているか
4. 影響範囲のドキュメント更新漏れがないことを確認（README.mdの関数テーブル、types.mdの型定義も含む）
5. 問題があれば修正し、再レビュー

Phase 4を通過して初めてユーザーに完了を報告する。

---

完了時

ユーザーが実装結果を確認した上でコミットを指示したら：

1. planのmdに実装結果を簡潔にまとめる
2. planのmdに記載されている経過措置や変更調整の記載を束ね、最終的に実装された仕様のみの記載に整理する
   • 途中で調整した内容、うまくいかなくて取り下げたアプローチなどがある場合はまとめて「実装時の調整内容（補足）」に記載する
3. planのmdに記載されている具体的なコード例を整理削除する。詳細なコードは不要なのでアプローチや方針のみを残す。外部仕様は関数のIFや型の説明程度のコードとし、利用例は意図の伝わる最低限のもののみとして、詳細はdocsのドキュメントに誘導する
4. ペンディング事項があれば明記
5. 簡潔な日本語で全てをコミット