plan-interview

計画インタビュースキル

インストール

gh skill install pskoett/pskoett-skills plan-interview

Agent Skills CLI を使った代替手段：

npx skills add pskoett/pskoett-skills/skills/plan-interview

哲学

このコレクションのすべてのスキルは、エージェントが自力で身につけるのに苦労する中核となる哲学、つまり原則を軸に構築されています。

このスキルの哲学は、**「変更を容易にしてから、変更する」**ことです。

エージェントは、道筋がどれほど入り組んでいても、実装をまっすぐ進めるのが基本です。「準備としてリファクタリングすれば、この変更は難しいものではなく簡単なものになるのでは？」と立ち止まって尋ねることはほとんどありません。計画の段階では、その問いを投げかけます。コードベースの調査や計画の作成中は、対象の変更をやりにくく、壊れやすく、あるいは過度に複雑にしている構造上の障害を積極的に探してください。見つかった場合、計画では準備段階を提案します。まず変更しやすい状態にしてから、変更そのものを行います。英雄的に一気にやり遂げるより、明確に分けた2つのステップのほうが優れています。

目的

実装を計画する前に、構造化された要件インタビューを実施します。想定で済ませず、明示的な要件を収集することで、ユーザーとの認識を一致させます。

呼び出し時

ユーザーが /plan-interview <task description> を呼び出します。

実装を伴わない調査や探索のみのタスクでは、このスキルを使用しないでください。

インタビュープロセス

フェーズ 1：事前インタビュー（調査の前）

ホストに構造化された質問ツール（ask_user、 AskUserQuestion、または同等のツール）があるか確認します。次の計画ステップに進む前にユーザーが回答できる、焦点を絞った質問にはそのツールを使用してください。構造化された質問ツールがないホストでは、同じ質問をチャットで直接尋ね、回答を待ちます。ホストのツール名が異なるという理由だけで、通常のチャットに切り替えてはいけません。ホストのスキーマに従ってください。ツールが1回の呼び出しにつき1つの質問しか受け付けない場合は、質問をまとめず、各領域について順番に尋ねます。

必須の質問領域

先に進む前に、以下4つの領域すべてを確認してください。

1. 技術的な制約

   • パフォーマンス要件
   • 互換性の要件
   • 既存のパターンに従う必要性
   • アーキテクチャの理解（コードベースに不慣れな場合）

2. スコープの境界

   • 明確に対象外とするもの
   • MVP と最終的な構想のどちらを目指すか
   • 他の作業への依存関係

3. リスク許容度

   • 許容できるトレードオフ（速度と品質のバランス）
   • 技術的負債への許容度
   • 破壊的変更を受け入れられるか

4. 成功基準

   • 何をもって完了とするか
   • 何をもって正しく動作していると判断するか
   • テストや検証の要件

質問の作成

• 固定テンプレートではなく、タスクに応じて動的に質問を作成します。
• 関連する質問をテーマ別のまとまりにまとめます。
• 1つのまとまりにつき2～3問（それを超えないこと）
• 具体的な実装手順を説明できる状態になるまで、質問を続けます。

計画の深さの調整

インタビューを終える前に、タスクを分類し、計画の深さを選びます。

• 単純／軽微（小規模なバグ修正、独立した変更）：最小限の計画とし、見直しは最大1回
• 中程度（既知の領域での機能開発）：標準的な計画とし、通常は1～2回の見直し
• 複雑／高リスク（複数ファイル、新しいアーキテクチャ、不慣れなコードベース、移行、認証、並行処理）：改善が収束するまで反復的に見直す、詳細な計画

明確な希望がある場合は、ユーザーがこの深さを fast と deep から選べるようにします。

例外的なケースへの対応

状況	対応
要件が矛盾している	根拠とともに推奨案を示し、確認を求める
ユーザーが要件を変更する	新しい方針でインタビューを最初からやり直す
セッションが中断された	続きから再開するか、最初からやり直すかをユーザーに尋ねる

避けるべきアンチパターン

• 同じ質問を言い換えて繰り返さないでください。
• 確認せずに重大な前提を置かないでください。
• 単純なタスクの計画を過剰に複雑化しないでください。

フェーズ 2：コードベースの調査

インタビューが完了したら、コードベースを調査して、次の点を把握します。

• タスクに関連する既存のパターン
• 影響を受けるファイル
• 統合ポイント
• 潜在的なリスク
• 構造上の摩擦 — 現在のコード構成が、予定している変更の妨げになっていないでしょうか？ 実装を簡潔に進められるよう、事前にリファクタリング（名前の変更、切り出し、再構成など）したほうがよいでしょうか？ 該当する場合は、計画の独立した最初のステップとして提案してください。

複雑なプロジェクトや不慣れなプロジェクトでは、詳細な計画を立てる前に、簡単にコンテキストを確認します。

• AGENTS.md と README.md が存在し、関連する場合は、再度読みます。
• 計画を詰める前に、現在のアーキテクチャの境界と規約を特定します。
• セッションが中断された場合や、コンテキストがずれてしまった場合は、計画の見直しを再開する前に、これらを再確認します。

ナレッジの監査（調査と計画の間）

計画を作成する前に、明確に問いかけます。「このタスクを完了するために必要なナレッジは、アクセス可能な場所に存在するでしょうか？」

重要な実装ステップごとに、必要なナレッジがどこにあるかを分類します。

• コードベース — 実装方法を示す既存のパターン、規約、コード。調査で確認します。
• プロンプト／コンテキスト — インタビューでユーザーが提示した要件、制約、ドメイン知識。
• 学習データ — モデルが確実に把握している、一般的なプログラミング知識、広く知られたライブラリ、標準的なパターン。
• アクセス可能な場所にない — 必要なナレッジが上記のいずれにも存在しません。エージェントは推測することになります。

ステップのナレッジが「アクセス可能な場所にない」に該当する場合は、次の対応を行います。

1. 作業を止めて、その不足を明らかにします。 自信ありげな推測で不足を埋めてはいけません。
2. 不足しているナレッジの提供、ドキュメントの提示、またはベストエフォートで進めてよいかをユーザーに確認します。
3. ユーザーから参考資料（ドキュメントの URL、API 仕様、例など）が提供された場合は、そのステップの計画を立てる前に内容を確認します。
4. 不足を埋められない場合は、計画の「未解決の質問」セクションで、そのステップをブロック中として記載します。

この監査によって、ナレッジがないにもかかわらず自信を持って作業を進め、もっともらしいが誤った出力を生成してしまうという、エージェントにありがちな失敗を防ぎます。

フェーズ 3：計画の作成

計画を docs/plans/plan-NNN-<slug>.md に保存します。NNN は連番です。

ドラフト → 改善のワークフローを使います。実質的な改善点を探している間は、計画の作成に集中してください。複雑なタスクでは、計画に使うトークンのコストは、通常、実装に使うトークンのコストよりかなり低くなります。

まずドラフトを作成し、その後で改善する

1. インタビューと調査の結果をもとに、計画のドラフトを作成します。
2. 承認を求める前に、反復的な改善を行います（回数はタスクの複雑さに応じて調整します）。
3. 改善した計画を提示し、ユーザーにレビューを依頼します。

計画の反復的な改善ループ（ユーザーにレビューを依頼する前）

複雑さに応じて 1..N 回の改善を行います。各回では、次の手順に従います。

1. 新鮮な視点で開始する（必須）： 修正を始める前に、「新鮮な視点」でインタビューの回答、制約、成功基準、現在の計画のドラフトを読み直します。
2. 矛盾、考慮漏れのエッジケース、統合リスク、実装手順の曖昧さを確認します。
3. ユーザーにとって明確な利点がある場合は、アーキテクチャ、手順、信頼性を改善します。
4. テストと検証の計画を強化します（適用可能な場合は、単体テストと統合テスト／E2E テストに加え、役立つ診断やログも含めます）。
5. 機能が維持されていることを確認します。
   • 過度に単純化しないでください
   • ユーザーがスコープの縮小を明示的に承認しない限り、合意した機能や動作を削除しないでください。
6. 各回で変更した点とその理由を、短くまとめて記録します。

次のいずれかに該当する場合は、反復を終了します。

• 連続する 2 回の改善で、実質的な改善がない
• 変更が文言やスタイルに限られ、実行品質に影響しない
• タスクが単純で、計画がすでに実行可能である
• ユーザーが中止して先に進むよう求める

任意：複数プランの統合（「最良の要素を組み合わせる」）

ユーザーが複数の競合するプラン（異なるモデルや過去の反復によるもの）を提示した場合：

• 現在のプランと照らし合わせて、率直に比較します
• 最良のアイデア、トレードオフ、リスク軽減策を抽出します
• 合意済みのスコープを維持しながら、単一の標準プランに統合します
• ユーザーが改訂版の出力を求めた場合は、既存のプランへのgit-diff形式の変更を優先して提示します

改良ループと複数プランの統合に再利用できるプロンプトテンプレートは、references/iterative-plan-refinement-prompts.md にあります。

必須要素

すべてのプランに必ず含めるもの：

## Success Criteria
[Clear definition of done from interview]

## Risk Assessment
[What could go wrong + mitigations]

## Affected Files/Areas
[Which parts of codebase will be touched]

## Test Strategy
[Unit tests, integration tests, and e2e tests/scripts where applicable; include key scenarios, failure modes, and fixtures/mocks]

## Validation and Diagnostics
[How to verify the feature works after implementation; include detailed logging/diagnostics expectations in tests/scripts when useful for debugging]

## Knowledge Map
[For each major step, where does the required knowledge live?]
| Step | Knowledge Source | Confidence |
|------|-----------------|------------|
| Step 1 | Codebase (existing pattern in src/auth/) | High |
| Step 2 | Training data (standard OAuth2 flow) | High |
| Step 3 | Nowhere — need user to provide API spec | Blocked |

## Open Questions
[Uncertainties to resolve during implementation]
- [ ] Question 1 - [Blocks implementation / Can proceed]
- [ ] Question 2 - [Blocks implementation / Can proceed]

## Implementation Checklist
- [ ] Step 1
- [ ] Step 2
...

任意の要素

関連する場合に含めます：

• 却下した代替案：主要なアーキテクチャ上の決定に限ります
• 判断ツリー：有効なアプローチが複数ある場合に限ります
• 視覚的な図：理解に役立つ場合は、ASCIIまたはMermaidを使用します

制約

• 所要時間の見積もりは禁止 — どれくらい時間がかかるかではなく、何を行う必要があるかを記述します
• 長さの制限なし — プランの詳細度はタスクの複雑さに合わせます
• スコープを黙って縮小しない — プランを「すっきり」させるために、合意済みの機能を削除しません
• 単純な作業を過度に反復しない — 上記のプランニング深度の調整に従います
• 必須要素以外の構成は自由です

フェーズ 4：承認後

ユーザーがプランを承認した場合：

1. 実装を直ちに自動開始します（別途「進めてよいか」の確認は不要です）。intent-framed-agent が有効な場合は、そのまま忠実なIntent Frameに進み、プランの承認を再利用します。フレームによって重要な変更や未解決の判断が生じる場合に限り、再度確認します。
2. チェックリスト項目を TodoWrite に追加します（TodoWrite が利用できない場合は、出力内の構造化コメントで進捗を管理します）
3. 自然な区切り（重要な判断を行った時点）で、進捗をプランと照らし合わせます

高速モード

ユーザーが迅速なプランニングを希望する場合は、ドラフト＋改良を使用します：

1. タスクに焦点を当てたコードベース検索を実施します
2. プランのドラフトを作成します
3. 簡略化したインタビューで改良します
4. fresh-eyesによる改良パスを1回だけ実施します（機能を維持し、手順を明確にし、テスト／検証のカバレッジを追加します）

再開サポート

docs/plans/ に未完成のプランがある場合：

AskUserQuestion: "I found an existing partial plan. Would you like to:"
- "Continue the interview"
- "Resume plan drafting/refinement"
- "Review current plan and finalize"
- "Start fresh with a new plan"

改良を再開する場合は、まず現在のプランの状態と直近の改良内容を要約してから、fresh-eyesによる改良ループを続けます。

他のスキルとの相互運用性

このスキルが受け取るもの

• ユーザーから： タスクの説明、要件、インタビューの質問への回答。
• コードベースから： 調査中に見つかった既存のパターン、アーキテクチャ、規約。
• context-surfingの引き継ぎファイルから（再開時）： コンテキストのずれにより前のセッションが終了した場合、.context-surfing/ 内の引き継ぎファイルに、再開地点と再計画に必要な残作業が記載されています。

このスキルが生成するもの

• プランファイル（docs/plans/plan-NNN-<slug>.md）— intent-framed-agentがIntent Frameのコンテキストとして使用し、context-surfingがウェーブアンカーの一部として使用します。コンテキストのずれによる終了時には、引き継ぎファイルにそのままコピーされます。
• プランニング深度の分類 — 有効にするスキルの数を決定する際に使用します（READMEのパイプライン深度テーブルを参照）。

パイプライン内の位置

1. plan-interview（要件とプランの作成 — 現在のステップです）
2. intent-framed-agent（実行契約＋スコープのずれの監視）
3. context-surfing（Large、長期実行、またはコンテキストに明示的に配慮する必要がある実行に対する、任意のコンテキスト品質監視）
4. verify-gate（機械的な検証：コンパイル＋テスト＋lint）
5. simplify-and-harden（完了後の品質／セキュリティ確認）
6. self-improvement（繰り返し現れるパターンを記録し、永続的なルールとして定着させる）

例

User: /plan-interview Add OAuth authentication to the API

Claude: I'll help you plan the OAuth authentication feature. Let me gather
        requirements first.

[AskUserQuestion - Scope batch]
1. Which OAuth providers need to be supported (Google, GitHub, etc.)?
2. Is this replacing existing auth or adding alongside it?

[Copilot guidance: ask the same two questions in chat and wait for responses]

User: Google and GitHub. Adding alongside existing JWT auth.

[AskUserQuestion - Technical batch]
1. Should OAuth tokens be stored in the existing session table or separately?
2. Any specific callback URL constraints from your hosting setup?

User: Separate table. We're on Vercel so callback URLs need to be configured per environment.

[AskUserQuestion - Risk/Success batch]
1. What's the acceptable degradation if an OAuth provider is down?
2. How should we handle users who already exist with the same email?

User: Fall back to standard login. Link accounts by email if user confirms.

Claude: [Explores codebase for auth patterns, session handling, database schema]

Claude: [Writes docs/plans/plan-003-oauth-authentication.md]

        Plan created. The main decision point is whether to use Passport.js
        or implement OAuth flows directly - I've documented both approaches
        with tradeoffs. Ready to review?

User: Looks good, go with Passport.js

Claude: [Auto-starts implementation with TodoWrite tracking]