psi

PSI - 計画・仕様策定・実装

ドキュメントを先に整備するアプローチで、変更の計画、仕様策定、実装を行うための構造化されたワークフローです。

使用するタイミング

次の場合にのみ使用してください：

• ユーザーから明示的に指示された場合
• プロジェクトの AGENTS.md ファイルに記載されている場合

自動的には使用しないでください。これはオプトインのワークフローであり、既定ではありません。

コアワークフロー

計画 → 仕様策定 → 実装

各フェーズは独立しています。どのフェーズからでも開始できますが、すべてのフェーズでドキュメントを最新の状態に保つ必要があります。

主な原則

1. 一時的な計画 - 計画は ~/.dot-agent/ に保存されます（コミットしません）
2. ドキュメント優先 - 仕様はプロジェクトのドキュメント、README、AGENTS.md に反映します
3. テストファーストの実装 - コードより先に、ドキュメントやユーザージャーニーのテストを作成します
4. 設計とレビューを組み込み - 設計とレビューを計画・仕様策定フェーズに統合します
5. フェーズの独立性 - 各フェーズは単独で実行でき、すべてのフェーズでドキュメントを更新します

フェーズの概要

計画フェーズ

• ~/.dot-agent/repo/YYYY-MM-work-name.plan.md に詳細な計画を生成します
• 調査結果は ~/.dot-agent/working-dir/repo/YYYY-MM-work-name.research.md に保存します
• 設計上の考慮事項を組み込みます
• 次に進む前にレビューを行います

仕様策定フェーズ

• 次の項目の仕様を生成します：API スキーマ、インターフェース、DTO、データベースモデル、設定、環境変数、アーキテクチャ、ユーザージャーニー、パッケージ構造、技術選定
• 設計上の考慮事項を組み込みます
• 仕様を適用する前にレビューします
• 次に適用します：docs/、README.md ファイル、AGENTS.md ファイル

実装フェーズ

• テストファースト：コードより先に、ドキュメントやユーザージャーニーのテストを作成します
• CI 検証：コミット前に型チェック、テスト、リンターがすべて成功することを確認します
• アトミックコミット：関連する変更をテストとともにまとめます
• コードの進化に合わせて、ドキュメント、README.md、AGENTS.md を更新します
• ドキュメントに仕様が存在する場合は、単独で作業できます

調査の管理

次のような表現を検出します：

• 「調査内容を確認して」→ 調査ファイルを読み込みます
• 「調査内容を絞り込んで」→ 調査ファイルを更新し、焦点を絞ります

ドキュメント構成

• README.md：1000 行未満を目指します（厳密なルールではありません）。必要に応じて長くしてもかまいません
• AGENTS.md：200 行未満とし、ルート／パッケージ／モジュール／コードの各階層に配置します
• docs/：アーキテクチャ、ロードマップ、技術選定、setup/、user-journeys/、design/

参考資料

詳細な手順については、以下を参照してください：

• references/plan-phase.md - 設計とレビューを組み込んだ計画の生成
• references/spec-phase.md - 仕様の生成と適用
• references/implement-phase.md - テストファーストの実装
• references/review-protocol.md - 計画／仕様／設計のレビュー
• references/research-management.md - 調査ファイルの取り扱い
• references/docs-structure.md - ドキュメント整理のルール
• references/file-paths.md - 保存先と規約