planning

プランニングスキル

使用するタイミング

ユーザーからプランニング、ロードマップ、仕様から実装への分解を求められた場合、または意思決定を文書化したい場合に、このスキルを使用します。

モード

リクエストを満たす最も簡潔なモードを選択します。

quick-plan

次の場合に使用します。

• タスクが小規模または中規模で、互換性を損なわない
• 移行がなく、複数フェーズにわたる展開もない

出力：

• 3～8 件の作業項目（WI-###）。各項目にテストと受け入れ条件を含めます。

full-plan（デフォルト）

次の場合に使用します。

• 移行や永続化の変更がある
• API／契約の変更（公開ツール、スキーマ、SDK）がある
• 複数フェーズにわたるロードマップである
• パフォーマンスが重要な作業である

出力：

• 構造化された計画セクション（「計画ファイルのテンプレート」を参照）

プロセス

1. 成果を明確にする

   • 望ましい動作と制約を言い換えて確認します。
   • 曖昧な点を特定し、ユーザーが決めない場合のデフォルトを提案します。
   • 制約と依存関係（ランタイムのバージョン、OS、外部サービス、機能フラグ、必須ツール）を記録します。
   • ギャップを記録する：ここで明らかになった要件や動作のギャップ、未決定事項を一覧にします。

2. 現在の動作を調査する

   • エントリーポイント → 状態／ストア → 副作用 → 永続化の流れを追跡します。
   • 主要なファイル／モジュールと、それらが依存する不変条件を一覧にします。
   • 所有権／優先順位のルール（ウィンドウ、ワークスペース、ファイル）を記録します。
   • ギャップを記録する：現在の動作が、明示された成果とどこで異なるかを一覧にします。

3. 目標とするルールを定義する

   • 成果を明示的なルールと優先順位に落とし込みます。
   • 各ルールには、トリガー／コンテキスト、期待される動作、適用範囲、制約、除外事項を含めます。
   • エッジケースを確認する：空／なし、無効／不正な形式、境界サイズ、状態の競合、複数の画面間の連携、永続化／復元、I/O エラーを網羅します。
   • ギャップを記録する：実装のサポートが不足しているルールや、現在の動作と矛盾するルールを一覧にします。
   • 意思決定ログを作成します。
     • 決定事項、検討した選択肢、根拠、代替案を却下した理由を記載します。
   • 未解決の質問の一覧を作成します。
     • 正確性を左右する質問、決定者、未決定の場合のデフォルトを記載します。

4. 計画を構成する

   • 次の項目を含む作業項目（WI-###）に分割します。
     • 目標
     • 受け入れ条件（測定可能）（関連する場合は正確性、パフォーマンス、UX）
     • テスト（先に作成）（ファイル名とテストの目的。該当する場合はユニット／統合／E2E）
     • 変更対象領域（ファイルパスと主要な関数／クラス／シンボル）
     • 依存関係（他の WI、外部ツール／サービス）
     • リスクと緩和策
     • ロールバック／差し戻し戦略
   • 優先度と見積もり（S/M/L）を追加し、WI 間の順序と依存関係を明記します。
   • ギャップを記録する：各ギャップを少なくとも 1 つの WI に対応付けるか、「対象外」として記録します。
   • 計画のリント（必須）：
     • セクションが存在すること（成果、制約、現在の動作、目標とするルール、作業項目、テスト）。
     • WI の番号が連続しており、一貫して参照されていること。
     • すべての WI にテストと受け入れ条件が含まれていること。

5. 計画ファイルを作成する

   • 利用可能な場合は、templates/TEMPLATE.md（このスキルに同梱）を使用します。利用できない場合は、上記の構成に従います。
   • 計画は dev-docs/plans/YYYYMMDD-HHMM-<topic>.md に保存します。
   • 保存した計画のパスを必ず報告します。

テスト要件

• すべての WI について、実装前に作成する具体的なテスト（ファイル名とテストの目的）を記載する必要があります。
• テストを作成できない場合は、その旨を明記し、テストを可能にするための最小限のテスト用接点を提案します。
• 計画には「テスト手順」セクションを含め、必要なコマンドと実行タイミングを記載します。
• 計画の最後に、簡潔な「手動テストチェックリスト」を記載します。

受け入れ基準のガイダンス

受け入れ条件は測定可能で、検証可能である必要があります。

• 良い例：「検索結果ごとに locator_v1 を含む v1 スキーマが返される（ユニットテスト）。」
• 悪い例：「検索の使い勝手が良くなる。」

計画から検証への引き継ぎ（必須）

計画の最後に、次を含めます。

• WI ごとに収集する証拠（テスト、ログ、手動手順）。
• 必要なフィクスチャやサンプルデータ。

移行／永続化の要件（該当する場合）

計画によって永続化されているもの（DB、ディスク上のキャッシュ、設定ファイル、クライアントが保存する API）に変更が生じる場合：

• データモデルセクションを追加してください（テーブル／列／キー、バージョン）。
• 移行計画を追加してください：
  • 前方移行の手順
  • ロールバックの手順
  • 互換性の保証（旧クライアントと新サーバー）
• 不変条件と検証クエリを追加してください（移行後に確認する項目）。
• 必要に応じて、バックフィル／再インデックスの戦略を追加してください。

可観測性の要件（該当する場合）

計画がインデックス作成／検索／パフォーマンスに影響する経路に関わる場合：

• メトリクスを定義してください（レイテンシ、スループット、メモリ、DB サイズの増加）。
• ログの出力先と、詳細なトレースを有効にする方法を定義してください。
• 受け入れ基準を追加してください（例：「マシン Y で 1000 件のドキュメントのインデックスを X 分未満で作成」）。

ロールアウトの要件（該当する場合）

動作の変更がユーザーに見える場合、またはリスクを伴う場合：

• ロールアウト計画を追加してください（機能フラグ、段階的な有効化、デフォルトで無効にするか有効にするか）。
• 「キルスイッチ」の条件と、迅速に元に戻す方法を定義してください。

出力要件

• 常に計画ファイルを作成し、回答にそのパスを記載してください。
• ルールに影響する場合に限り、確認の質問を 1～2 件まで行ってください。