project-planner

プロジェクトプランナー

使用する場面

次の場合にこのスキルを有効にします：

• 機能リクエストやユーザーストーリーを実装計画に落とし込むとき
• Python／React プロジェクトのスプリント計画やバックログのリファインメントを行うとき
• 新しいモジュール、サービス、機能領域を設計するとき
• 提案された変更の全体的な複雑さを見積もるとき
• 実装を始める前に、ファイル単位の影響範囲を特定するとき
• バックエンドとフロントエンドの各レイヤーにおける変更の影響をマッピングするとき

次の場合はこのスキルを使用しないでください：

• アーキテクチャ上の判断や技術的なトレードオフを検討するとき（system-architecture を使用）
• 実装コードを書くとき（python-backend-expert または react-frontend-expert を使用）
• API コントラクトを設計するとき（api-design-patterns を使用）
• 実装タスクを細かい単位に分解するとき（task-decomposition を使用）

手順

計画ワークフロー

計画に関するすべてのリクエストに対し、次の4ステップのワークフローに従います：

ステップ1：要件を分析する

1. 機能リクエスト、ユーザーストーリー、またはプロダクト要件を最後まで読む
2. 中核となる目的を特定する — どのような価値をもたらすのか
3. 明示的な入力（機能を起動するもの）と出力（ユーザーに表示されるもの）を列挙する
4. 曖昧な点や詳細が不足している点を記録し、未解決の質問として列挙する
5. 新機能、機能強化、バグ修正、リファクタリングのどれに該当するかを判断する

ステップ2：影響を受けるモジュールをマッピングする

プロジェクトを調査し、変更の影響を受けるファイルやモジュール領域をすべて特定します：

バックエンド（FastAPI）：

• routes/ — 新規または変更されたエンドポイントハンドラー
• services/ — ビジネスロジックの変更
• repositories/ — データアクセスレイヤーの変更
• models/ — SQLAlchemy モデルの変更（マイグレーションが発生）
• schemas/ — Pydantic のリクエスト／レスポンススキーマの変更
• core/ — 設定、セキュリティ、またはミドルウェアの変更
• migrations/ — Alembic のマイグレーションファイル

フロントエンド（React/TypeScript）：

• pages/ — 新規または変更されたページコンポーネント
• components/ — 共通 UI コンポーネントの変更
• hooks/ — カスタムフックの変更または追加
• services/ — API クライアントの変更（TanStack Query のキー、ミューテーション）
• types/ — 共通の TypeScript 型定義
• utils/ — ユーティリティ関数の変更

共通／横断的な領域：

• types/ または shared/ — バックエンドとフロントエンドで共有する型
• .env / config — 環境変数の変更
• tests/ — 変更された各モジュールのテストファイル

モジュールマップを表として提示します：

| Layer    | Module           | Change Type       | Impact    |
|----------|-----------------|-------------------|-----------|
| Backend  | models/user.py  | Add field         | Migration |
| Backend  | schemas/user.py | Add response field| API change|
| Frontend | hooks/useUser.ts| Update query      | UI change |

ステップ3：検証基準を定義する

機能の完成をどのように検証するかを定義します：

統合検証：

• ユーザーの操作全体を説明するエンドツーエンドテストのシナリオ
• 自動 E2E テストを利用できない場合は、手動スモークテストの手順

リグレッションチェック：

• 既存のテストが引き続き成功すること：pytest -x && npm test
• 型エラーがないこと：mypy src/ && npx tsc --noEmit
• lint の問題がないこと：ruff check src/ && npm run lint

ステップ4：リスクと未確定事項を特定する

以下のカテゴリを使って、潜在的な問題を明示します。各リスクについて、次を記載します：

• リスク： 起こりうる問題の説明
• 可能性： 低／中／高
• 影響度： 低／中／高
• 軽減策： リスクを低減または解消する方法

リスクカテゴリの一覧は、references/risk-assessment-checklist.md を参照してください。

出力形式

計画をプロジェクトのルートにあるファイルへ書き込みます：plan.md（計画が複数ある場合は plan-<feature-name>.md）。テンプレートには references/plan-template.md を使用します。

ファイルには次の内容を含める必要があります：

# Implementation Plan: [Feature Name]

## Objective
[1-2 sentence summary of what this delivers]

## Context
- Triggered by: [user story / feature request / bug report]
- Related work: [links to related plans, ADRs, or PRs]

## Open Questions
[List ambiguities that need resolution before implementation]

## Affected Modules
[Module map table from Step 2]

## Verification
[Integration verification from Step 3]

## Risks & Unknowns
[Risk table from Step 4]

## Acceptance Criteria
[Bullet list of observable outcomes that confirm the feature works]

## Estimation Summary
[Overall complexity estimate — see table below]

計画は必ずファイルに書き込んでください。 これにより、/task-decomposition が入力として読み取れるようになります。書き込み後、ユーザーに次のように伝えます：「計画を plan.md に書き込みました。/task-decomposition を実行して、細かいタスクに分解してください。」

見積もりの概要

次の表を使用して、機能全体の複雑さを見積もります。

指標	値
影響を受けるバックエンドモジュールの合計	[N]
影響を受けるフロントエンドモジュールの合計	[N]
マイグレーションが必要	はい / いいえ
API の変更	はい / いいえ（新しいエンドポイント / 変更されたコントラクト）
全体的な複雑さ	trivial / small / medium / large

複雑さのガイドライン：

• 些細: 1～2 個のモジュール、マイグレーションなし、50 行未満
• 小: 2～4 個のモジュール、マイグレーションなし、200 行未満
• 中: 4～8 個のモジュール、マイグレーションの可能性あり、500 行未満
• 大: 8 個以上のモジュール、マイグレーションの可能性が高い、500 行以上

例

例：「ユーザープロフィール画像のアップロードを追加する」計画

目的： ユーザーがプロフィール画像をアップロードして表示できるようにします。

影響を受けるモジュール：

レイヤー	モジュール	変更の種類	影響
バックエンド	models/user.py	avatar_url を追加	マイグレーション
バックエンド	schemas/user.py	フィールドを追加	API コントラクト
バックエンド	services/upload.py	新しいサービス	新しいファイル
バックエンド	routes/users.py	エンドポイントを追加	API の変更
フロントエンド	components/AvatarUpload	新しいコンポーネント	UI の変更
フロントエンド	hooks/useUploadAvatar.ts	新しいフック	データ取得
フロントエンド	pages/ProfilePage.tsx	統合	UI の変更

検証：

• プロフィールページから画像をアップロードし、表示されることを確認する
• サイズ超過のファイルをアップロードし、エラーメッセージとともに拒否されることを確認する
• 回帰テスト：pytest -x && npm test

リスク：

• ファイルサイズ制限の検証が必要です（サーバー + クライアント） — 発生可能性は中 — 早期に検証を追加する
• S3 の権限設定が必要になる場合があります — 発生可能性は低 — まずローカルストレージでテストする

受け入れ条件：

• ユーザーがプロフィールページからプロフィール画像をアップロードできる
• アップロードされた画像がアプリ全体でユーザーのアバターとして表示される
• 5MB を超えるファイルは、明確なエラーメッセージとともに拒否される
• 画像以外のファイルは拒否される
• 既存のすべてのテストに合格する

見積もりの概要：

指標	値
影響を受けるバックエンドモジュール	4
影響を受けるフロントエンドモジュール	3
マイグレーションが必要	はい
API の変更	はい（新しいアップロードエンドポイント）
全体的な複雑さ	medium

出力： plan.md に書き込まれます。/task-decomposition を実行して、計画を個別のタスクに分割します。

エッジケース

• 複数領域にまたがる変更（認証ミドルウェア、エラー処理、ロギング）：多くのモジュールに影響します。計画を立てる前に、アーキテクチャレビューが必要であることを明記してください。変更を独立した計画にすべきか検討してください。

• データ変換を伴うデータベースマイグレーション：リスクとして明記してください。マイグレーションのテスト（アップグレード + ロールバック）が必要であることを記載してください。タスク分解では、専用のマイグレーションタスクが作成されます。

• フロントエンドの状態の連鎖的な影響：共有状態（React Context、TanStack Query キャッシュ）を変更する場合は、モジュールマップでコンポーネントツリーをたどり、すべての利用箇所を特定してください。

• API の後方互換性を損なう変更：既存のエンドポイントのコントラクトを変更する場合は、まずフロントエンドの利用箇所を確認してください。外部利用者がいる場合は、API のバージョニングを検討してください。フロントエンドの更新を調整する必要があることを計画に記載してください。

• 機能フラグ：複数のスプリントにまたがる大規模な機能では、機能フラグが必要であることを計画に記載してください。タスク分解で実装の順序が処理されます。

• サードパーティ依存関係の更新：機能に新しいパッケージが必要な場合は、計画の影響を受けるモジュールに追加してください。ピア依存関係の競合が発生する可能性をリスクとして記載してください。