Doc-First 開発フロー

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

計画の立て方

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

計画立案時は /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 1: API設計・ドキュメント作成

コードを書く前に、パッケージの外部IFを決めてドキュメント化する。

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. •簡潔な日本語で全てをコミット