create-plans

<essential_principles>

あなたは 1 人（ユーザー）と 1 人の実装者（Claude）のために計画を立てています。 チームはありません。ステークホルダーもいません。儀式もありません。調整のオーバーヘッドもありません。 ユーザーはビジョナリー兼プロダクトオーナーです。Claude はビルダーです。 PLAN.md はプロンプトに変換されるドキュメントではありません。 PLAN.md 自体がプロンプトです。これには以下が含まれます: - 目的（何を、なぜ） - コンテキスト（@file 参照） - タスク（type、files、action、verify、done、checkpoints） - 検証（全体チェック） - 成功基準（測定可能） - 出力（SUMMARY.md の仕様）

フェーズを計画するとき、あなたはそれを実行するプロンプトを書いています。

一貫した品質を維持するため、計画はコンテキスト使用量の約 50% 以内で完了する必要があります。

品質低下のカーブ:

• 0-30% コンテキスト: 最高品質（包括的、徹底的、不安なし）
• 30-50% コンテキスト: 良好な品質（集中、管理可能なプレッシャー）
• 50-70% コンテキスト: 品質低下（効率モード、圧縮）
• 70%+ コンテキスト: 低品質（自己ロボトミー化、慌てた作業）

重要な洞察: Claude は 80% で低下するのではなく、コンテキストが増大するのを見て「完了モード」に入る約 40-50% で低下します。80% までには、品質はすでに崩壊しています。

解決策: 積極的なアトミック性 - フェーズを多数の小さく焦点を絞った計画に分割します。

例:

• 01-01-PLAN.md - フェーズ 1、計画 1（2-3 タスク: データベーススキーマのみ）
• 01-02-PLAN.md - フェーズ 1、計画 2（2-3 タスク: データベースクライアントのセットアップ）
• 01-03-PLAN.md - フェーズ 1、計画 3（2-3 タスク: API ルート）
• 01-04-PLAN.md - フェーズ 1、計画 4（2-3 タスク: UI コンポーネント）

各計画は独立して実行可能で、検証可能で、最大 2-3 タスクにスコープが限定されています。

アトミックタスクの原則: 3 つの大きく劣化した計画よりも、10 の小さく高品質な計画の方が優れています。各コミットは外科的で、焦点を絞り、保守可能であるべきです。

自律実行: チェックポイントのない計画は、新鮮なコンテキストを持つサブエージェントを介して実行されます - 劣化は不可能です。

参照: references/scope-estimation.md

**Claude は CLI または API を持つすべてを自動化します。** チェックポイントは検証と意思決定のためのものであり、手作業のためのものではありません。

チェックポイントの種類:

• checkpoint:human-verify - 人間が Claude の自動化作業を確認します（ビジュアルチェック、UI 検証）
• checkpoint:decision - 人間が実装の選択を行います（認証プロバイダー、アーキテクチャ）

ほとんど不要: checkpoint:human-action - CLI/API がないアクションのみ（メール確認リンク、2FA での Web ログインを必要とするアカウント承認）

重要なルール: Claude が CLI/API/ツールを介して実行できる場合、Claude は必ず実行しなければなりません。人間に以下を決して依頼しないでください:

• Vercel/Railway/Fly へのデプロイ（CLI を使用）
• Stripe Webhook の作成（CLI/API を使用）
• ビルド/テストの実行（Bash を使用）
• .env ファイルの作成（Write ツールを使用）
• データベースリソースの作成（プロバイダー CLI を使用）

プロトコル: Claude が作業を自動化 → checkpoint:human-verify に到達 → 実行された内容を提示 → 確認を待機 → 再開

参照: references/checkpoints.md、references/cli-automation.md

計画はガイドであり、拘束衣ではありません。実際の開発には常に発見が伴います。

実行中、逸脱は 5 つの組み込みルールによって自動的に処理されます:

1. バグの自動修正 - 壊れた動作 → 即座に修正し、サマリーに記録
2. 不足している重要項目の自動追加 - セキュリティ/正確性のギャップ → 即座に追加し、記録
3. ブロッカーの自動修正 - 続行できない → 即座に修正し、記録
4. アーキテクチャについて質問 - 主要な構造変更 → 停止してユーザーに質問
5. 機能強化のログ記録 - あると嬉しいもの → ISSUES.md に自動記録し、続行

ルール 1-3、5 にはユーザーの介入は不要です。 ルール 4（アーキテクチャ）のみユーザーの決定が必要です。

すべての逸脱はサマリーに記録されます: 発見された内容、適用されたルール、実行された内容、コミットハッシュを含みます。 結果： ワークフローは決して中断しません。バグは修正されます。スコープは適切に保たれます。完全な透明性を確保します。

参照：workflows/execute-phase.md（deviation_rules セクション）

エンタープライズ向けのプロセスはありません。承認ゲートもありません。数週間にわたるスケジュールもありません。 計画 → 実行 → リリース → 学習 → 繰り返し。

マイルストーン主導： v1.0 をリリース → マイルストーンを記録 → v1.1 を計画 → リリース → 繰り返し。 マイルストーンはリリース済みのバージョンを記録し、継続的な反復を可能にします。

マイルストーンはリリース済みのバージョン（v1.0、v1.1、v2.0）を示します。

目的：

• MILESTONES.md に履歴を記録する（いつ何をリリースしたか）
• グリーンフィールドからブラウンフィールドへの移行マーカー
• リリース用の Git タグ
• 明確な完了の儀式

デフォルトのアプローチ： 既存のロードマップに新しいフェーズを追加します。

• v1.0 をリリース（フェーズ 1-4）→ v1.1 用にフェーズ 5-6 を追加
• フェーズ番号を連続させる（01-99）
• マイルストーンのグループ分けでロードマップを整理

アーカイブするのは次の場合のみ： 別のコードベース、または全面的な書き換え（まれ）。

参照：references/milestone-management.md

計画に以下を含めてはいけません： - チーム構成、役割、RACI マトリックス - ステークホルダー管理、合意形成の会議 - スプリントのセレモニー、スタンドアップ、振り返り - 数週間単位の見積もり、リソース配分 - 変更管理、ガバナンスプロセス - ドキュメント作成のためだけのドキュメント

企業のプロジェクト管理を演じているように感じたら、削除してください。

システムの警告でトークン使用量を監視します。

残り 25% の時点： コンテキストがいっぱいになりつつあることを伝えます 残り 15% の時点： 一時停止し、引き継ぎを提案します 残り 10% の時点： 引き継ぎを自動作成し、停止します

ユーザーの確認なしに、残り 15% を下回った状態で大規模な操作を始めてはいけません。

重要な判断ポイントで、決して先走ってはいけません。次のゲートを使います： - **AskUserQuestion**：選択肢を整理して提示（2～4 個） - **インラインの質問**：簡単な確認 - **判断ゲートのループ**：「準備できましたか、それとも質問を続けますか？」

必須のゲート：

• PLAN.md を作成する前（内訳を確認）
• 信頼度の低い調査の後
• 検証に失敗した場合
• 問題がある状態でフェーズを完了した後
• 前のフェーズに問題がある状態で次のフェーズを始める前

参照：references/user-gates.md

すべての計画成果物をバージョン管理します。プロセスではなく、成果をコミットします。

• 呼び出し時にリポジトリを確認し、初期化を提案します
• コミットするのは、初期化、フェーズ完了、引き継ぎのときのみです
• 中間成果物（PLAN.md、RESEARCH.md、FINDINGS.md）は個別にコミットしません
• Git のログがプロジェクトの履歴になります

参照：references/git-integration.md

</essential_principles>

<context_scan> 現在の状態を把握するため、呼び出しのたびに実行します：

# Check git status
git rev-parse --git-dir 2>/dev/null || echo "NO_GIT_REPO"

# Check for planning structure
ls -la .planning/ 2>/dev/null
ls -la .planning/phases/ 2>/dev/null

# Find any continue-here files
find . -name ".continue-here.md" -type f 2>/dev/null

# Check for existing artifacts
[ -f .planning/BRIEF.md ] && echo "BRIEF: exists"
[ -f .planning/ROADMAP.md ] && echo "ROADMAP: exists"

NO_GIT_REPO が検出された場合： インラインの質問：「Git リポジトリが見つかりません。初期化しますか？（バージョン管理におすすめです）」 はいの場合：git init

受付の質問をする前に、調査結果を提示します。 </context_scan>

<domain_expertise> ドメインの専門知識は ~/.claude/skills/expertise/ にあります

ロードマップやフェーズ計画を作成する前に、ドメインの専門知識を読み込むべきか判断します。

<scan_domains>

ls ~/.claude/skills/expertise/ 2>/dev/null

利用可能なドメインの専門知識を確認できます（例：macos-apps、iphone-apps、unity-games、nextjs-ecommerce）。

ドメインスキルが見つからない場合： ドメインの専門知識なしで進めます（適切に機能を縮退）。このスキルはドメイン固有のコンテキストがなくても問題なく動作します。 </scan_domains>

<inference_rules> ユーザーの依頼にドメインのキーワードが含まれている場合、そのドメインを推測します：

| キーワード | ドメインスキル | |----------|--------------| | "macOS", "Mac app", "menu bar", "AppKit", "SwiftUI desktop" | expertise/macos-apps | | "iPhone", "iOS", "iPad", "mobile app", "SwiftUI mobile" | expertise/iphone-apps | | "Unity", "game", "C#", "3D game", "2D game" | expertise/unity-games | | "MIDI", "MIDI tool", "sequencer", "MIDI controller", "music app", "MIDI 2.0", "MPE", "SysEx" | expertise/midi | | "Agent SDK", "Claude SDK", "agentic app" | expertise/with-agent-sdk | | "Python automation", "workflow", "API integration", "webhooks", "Celery", "Airflow", "Prefect" | expertise/python-workflow-automation | | "UI", "design", "frontend", "interface", "responsive", "visual design", "landing page", "website design", "Tailwind", "CSS", "web design" | expertise/ui-design |

ドメインが推測された場合は、確認します：

Detected: [domain] project → expertise/[skill-name]
Load this expertise for planning? (Y / see other options / none)

</inference_rules>

<no_inference> リクエストからドメインが明らかでない場合は、選択肢を提示します：

What type of project is this?

Available domain expertise:
1. macos-apps - Native macOS with Swift/SwiftUI
2. iphone-apps - Native iOS with Swift/SwiftUI
3. unity-games - Unity game development
4. swift-midi-apps - MIDI/audio apps
5. with-agent-sdk - Claude Agent SDK apps
6. ui-design - Stunning UI/UX design & frontend development
[... any others found in expertise/]

N. None - proceed without domain expertise
C. Create domain skill first

Select:

</no_inference>

<load_domain> ドメインが選択されたら、インテリジェントな読み込みを使用します：

ステップ 1：ドメインの SKILL.md を読む

cat ~/.claude/skills/expertise/[domain]/SKILL.md 2>/dev/null

これにより、中核となる原則とルーティングのガイダンスが読み込まれます（約 5k トークン）。

ステップ 2：必要な参照を判断する

ドメインの SKILL.md には、計画のコンテキストを特定の参照にマッピングする <references_index> セクションが含まれている必要があります。

例：

<references_index>
**For database/persistence phases:** references/core-data.md, references/swift-concurrency.md
**For UI/layout phases:** references/swiftui-layout.md, references/appleHIG.md
**For system integration:** references/appkit-integration.md
**Always useful:** references/swift-conventions.md
</references_index>

ステップ 3：関連する参照のみを読み込む

（ROADMAP から）計画中のフェーズに基づき、その種別の作業で言及されている参照のみを読み込みます。

# Example: Planning a database phase
cat ~/.claude/skills/expertise/macos-apps/references/core-data.md
cat ~/.claude/skills/expertise/macos-apps/references/swift-conventions.md

コンテキストの効率性：

• SKILL.md のみ：約 5k トークン
• SKILL.md ＋ 選択した参照：約 8〜12k トークン
• すべての参照（以前のアプローチ）：約 20〜27k トークン

次のように通知します：「[ドメイン] の専門知識を読み込みました（[フェーズ種別] 向けの参照 [X] 件）。」

ドメインスキルが見つからない場合： ユーザーに通知し、ドメインの専門知識なしで続行することを提案します。

SKILL.md に references_index がない場合： コンテキスト使用量に関する警告を添えて、すべての参照を読み込むことにフォールバックします。 </load_domain>

<when_to_load> ドメインの専門知識は次の前に読み込む必要があります：

• ロードマップの作成（フェーズはドメインに適したものにする必要があります）
• フェーズの計画（タスクはドメイン固有でなければなりません）

ドメインの専門知識は次には不要です：

• ブリーフの作成（ビジョンはドメインに依存しません）
• ハンドオフからの再開（コンテキストはすでに確立されています）
• フェーズ間の移行（ステータスを更新するだけです） </when_to_load> </domain_expertise>

スキャン結果に基づき、コンテキストに応じた選択肢を提示します：

ハンドオフが見つかった場合：

Found handoff: .planning/phases/XX/.continue-here.md
[Summary of state from handoff]

1. Resume from handoff
2. Discard handoff, start fresh
3. Different action

計画構造が存在する場合：

Project: [from BRIEF or directory]
Brief: [exists/missing]
Roadmap: [X phases defined]
Current: [phase status]

What would you like to do?
1. Plan next phase
2. Execute current phase
3. Create handoff (stopping for now)
4. View/update roadmap
5. Something else

計画構造が存在しない場合：

No planning structure found.

What would you like to do?
1. Start new project (create brief)
2. Create roadmap from existing brief
3. Jump straight to phase planning
4. Get guidance on approach

続行する前に応答を待ちます。

| 応答 | ワークフロー | |----------|----------| | "brief", "new project", "start", 1（構造なし） | `workflows/create-brief.md` | | "roadmap", "phases", 2（構造なし） | `workflows/create-roadmap.md` | | "phase", "plan phase", "next phase", 1（構造あり） | `workflows/plan-phase.md` | | "chunk", "next tasks", "what's next" | `workflows/plan-chunk.md` | | "execute", "run", "do it", "build it", 2（構造あり） | **スキルを終了** → `/run-plan ` スラッシュコマンドを使用 | | "research", "investigate", "unknowns" | `workflows/research-phase.md` | | "handoff", "pack up", "stopping", 3（構造あり） | `workflows/handoff.md` | | "resume", "continue", 1（ハンドオフあり） | `workflows/resume.md` | | "transition", "complete", "done", "next" | `workflows/transition.md` | | "milestone", "ship", "v1.0", "release" | `workflows/complete-milestone.md` | | "guidance", "help", 4 | `workflows/get-guidance.md` |

重要： 計画の実行ではこのスキルを呼び出してはいけません。コンテキストの効率性のために /run-plan を使用してください（スキルは約 20k トークンを読み込み、/run-plan は約 5〜7k を読み込みます）。

ワークフローを読んだ後は、それに正確に従ってください。

計画の階層（各レベルは前のレベルに基づいて構築されます）：

BRIEF.md          → Human vision (you read this)
    ↓
ROADMAP.md        → Phase structure (overview)
    ↓
RESEARCH.md       → Research prompt (optional, for unknowns)
    ↓
FINDINGS.md       → Research output (if research done)
    ↓
PLAN.md           → THE PROMPT (Claude executes this)
    ↓
SUMMARY.md        → Outcome (existence = phase complete)

ルール：

• ロードマップにはブリーフが必要です（または作成を促します）
• フェーズ計画にはロードマップが必要です（フェーズの範囲を把握します）
• PLAN.md が実行プロンプトそのものです
• SUMMARY.md の存在がフェーズの完了を示します
• 各レベルはコンテキストのために上位を参照できます

<output_structure> すべての計画関連ファイルは .planning/ に格納します。

.planning/
├── BRIEF.md                    # Human vision
├── ROADMAP.md                  # Phase structure + tracking
└── phases/
    ├── 01-foundation/
    │   ├── 01-01-PLAN.md       # Plan 1: Database setup
    │   ├── 01-01-SUMMARY.md    # Outcome (exists = done)
    │   ├── 01-02-PLAN.md       # Plan 2: API routes
    │   ├── 01-02-SUMMARY.md
    │   ├── 01-03-PLAN.md       # Plan 3: UI components
    │   └── .continue-here-01-03.md  # Handoff (temporary, if needed)
    └── 02-auth/
        ├── 02-01-RESEARCH.md   # Research prompt (if needed)
        ├── 02-01-FINDINGS.md   # Research output
        ├── 02-02-PLAN.md       # Implementation prompt
        └── 02-02-SUMMARY.md

命名規則：

• 計画：{phase}-{plan}-PLAN.md（例：01-03-PLAN.md）
• サマリー：{phase}-{plan}-SUMMARY.md（例：01-03-SUMMARY.md）
• フェーズフォルダー：{phase}-{name}/（例：01-foundation/）

ファイルは時系列順に並びます。関連するファイル（計画とサマリー）は隣り合わせに配置します。 </output_structure>

<reference_index> すべて references/ にあります：

構成： directory-structure.md、hierarchy-rules.md 形式： handoff-format.md、plan-format.md パターン： context-scanning.md、context-management.md 計画： scope-estimation.md、checkpoints.md、milestone-management.md プロセス： user-gates.md、git-integration.md、research-pitfalls.md ドメイン： domain-expertise.md（コンテキスト効率の高いドメインスキルの作成ガイド） </reference_index>

<templates_index> すべて templates/ にあります：

テンプレート	用途
brief.md	現在の状態を含むプロジェクトビジョン文書
roadmap.md	マイルストーンごとにグループ化したフェーズ構成
phase-prompt.md	実行可能なフェーズプロンプト（PLAN.md）
research-prompt.md	リサーチプロンプト（RESEARCH.md）
summary.md	偏差を含むフェーズの成果（SUMMARY.md）
milestone.md	MILESTONES.md のマイルストーン項目
issues.md	後回しにした拡張機能の記録（ISSUES.md）
continue-here.md	コンテキスト引き継ぎ形式
</templates_index>

<workflows_index> すべて workflows/ にあります：

ワークフロー	用途
create-brief.md	プロジェクトビジョン文書を作成する
create-roadmap.md	brief からフェーズを定義する
plan-phase.md	実行可能なフェーズプロンプトを作成する
execute-phase.md	フェーズプロンプトを実行し、サマリーを作成する
research-phase.md	リサーチプロンプトを作成して実行する
plan-chunk.md	直近の次のタスクを計画する
transition.md	フェーズを完了としてマークし、次へ進む
complete-milestone.md	リリース済みバージョンとしてマークし、マイルストーン項目を作成する
handoff.md	一時停止に向けてコンテキストの引き継ぎを作成する
resume.md	引き継ぎを読み込み、コンテキストを復元する
get-guidance.md	計画の進め方を決めるためのガイダンスを得る
</workflows_index>

<success_criteria> 計画スキルは、次の条件を満たしたときに成功します：

• インテークの前にコンテキストスキャンが実行される
• 状態に基づいて適切なワークフローが選択される
• PLAN.md 自体が実行可能なプロンプトである（別ファイルではない）
• 階層が維持される（brief → roadmap → phase）
• 引き継ぎによって、再開に必要なコンテキスト全体が保持される
• コンテキストの上限が守られる（10% で自動引き継ぎ）
• 埋め込みルールに従って偏差が自動的に処理される
• すべての作業（計画済みおよび発見されたもの）が漏れなく文書化される
• ドメインの専門知識が適切に読み込まれる（すべてのファイルではなく、SKILL.md と必要な参照のみ）
• 計画の実行には /run-plan コマンドが使われる（スキルの呼び出しではない） </success_criteria>