/plan-with-agent - 実装計画の作成

アイデアや要望を整理し、Plans.md に実行可能なタスクとして落とし込みます。完了後は /work ですぐに作業を開始できます。

こう言えばOK

「計画を作って」→ このコマンド
「今話してた内容を計画にして」→ 会話から要件を抽出して計画化
「何を作るか整理したい」→ ヒアリングから始めて計画化
「機能を洗い出して」→ 機能リスト→優先度→Plans.md
「TDDで計画して」→ TDD採用を強制、テストケース設計を先行
「テスト設計から始めて」→ 各機能のテストケースを先に設計

できること（成果物）

Plans.md - /work で実行可能なタスク一覧（必須）
機能優先度マトリクス - 必須/推奨/オプションの分類

⚠️ モード別の使い分け

モード	推奨コマンド	説明
ソロモード	`/plan-with-agent` (このコマンド)	Claude Code だけで計画→実行→レビュー
2エージェントモード	`/plan-with-cc` (Cursor側)	Cursor で計画 → Claude Code で実行

🔧 必須スキル（最初に呼び出すこと）

⛔ このコマンドを実行したら、最初に必ず Skill ツールを呼び出すこと

Skill ツールを呼び出さずに進めることは禁止です。

呼び出し必須のスキル：

スキル	完全修飾名	呼び出しタイミング
`adaptive-setup`	`claude-code-harness:setup:adaptive-setup`	最初に必ず呼び出す
`vibecoder-guide`	`claude-code-harness:vibecoder-guide`	ユーザーが非技術者の場合

呼び出し方法（必須）:

Skill ツールを使用:
  skill: "claude-code-harness:setup:adaptive-setup"

なぜ Skill 呼び出しが必須か:

Usage 統計に記録される（品質追跡）
スキル内のガードレールが適用される
プロジェクト状態の正確な把握ができる

❌ 禁止: コマンドドキュメントを読んで直接実行フローに進むこと ✅ 正解: 最初に Skill ツールで adaptive-setup を呼び出してから進むこと

実行フロー

Step 0: 会話コンテキストの確認（Skill 呼び出し後に実行）

AskUserQuestion ツールで確認:

📝 計画の作り方を選んでください

今までの会話を踏まえる - 壁打ちで話した内容から計画を作成

新しく始める - ゼロからヒアリングして計画を作成

「今までの会話を踏まえる」が選択された場合:

直近の会話から要件・アイデア・決定事項を抽出
抽出した内容をユーザーに確認
確認後、Step 3（技術調査）へスキップ

「新しく始める」が選択された場合:

Step 1 からヒアリングを開始

Step 1: やりたいことのヒアリング

ユーザーの入力を確認。入力がない場合は質問：

🎯 何を作りたいですか？

例：

「予約管理システム」

「ブログサイト」

「タスク管理アプリ」

「API サーバー」

ざっくりで大丈夫です！

回答を待つ

Step 2: 解像度を上げる（最大3問）

📋 もう少し教えてください：

誰が使いますか？（自分だけ？チーム？一般公開？）

似ているサービスはありますか？（参考になるもの）

どこまで作りたいですか？（MVP？フル機能？）

回答を待つ

Step 3: 技術調査（WebSearch）

ユーザーには聞かない。Claude Code が調査して提案。

WebSearch で調査:
- "{{プロジェクトタイプ}} tech stack 2025"
- "{{類似サービス}} architecture"

Step 4: 機能リストの抽出

要望から、具体的な機能リストを抽出します。

例: 「予約管理システム」の場合

ユーザー登録・ログイン
予約カレンダー表示
予約の作成・編集・キャンセル
管理者ダッシュボード
メール通知
決済機能
レビュー機能

Step 5: 機能優先度マトリクスの作成

各機能を以下の3つに分類します：

優先度	説明	基準
必須	MVP（最小限の製品）に必要	これがないと動かない
推奨	ユーザー体験を大幅に向上	あると嬉しいが、なくても動く
オプション	将来的に追加検討	時間に余裕があれば

例: 予約管理システムの場合

機能	優先度	理由
ユーザー登録・ログイン	必須	予約には認証が必要
予約カレンダー表示	必須	コア機能
予約の作成・編集・キャンセル	必須	コア機能
管理者ダッシュボード	推奨	運用効率が向上
メール通知	推奨	ユーザー体験が向上
決済機能	オプション	後から追加可能
レビュー機能	オプション	後から追加可能

Step 5.5: TDD採用判定と厳格なテスト設計（重要）

目的: 厳しいTDD ＝ユーザーの意図を正確に理解すること。テストは「仕様の明文化」であり、実装前に合意形成する。

TDD採用判定

以下の条件に1つでも該当すれば TDD を採用:

判定条件	理由
ビジネスロジックが含まれる	計算・判定・状態遷移は仕様の明文化が必須
データ変換・加工がある	入力→出力の変換は境界条件が多い
外部API連携がある	モック設計で仕様を明確化
複数の分岐・条件がある	エッジケースの洗い出しが必要
金銭・認証・権限に関わる	ミスが許されない（セキュリティ＋TDD）
ユーザーの言葉が曖昧	テストケースで認識合わせ

判定結果の記録:

機能「{{機能名}}」→ TDD採用理由: {{該当条件}}

意図深掘り質問（AskUserQuestion ツールで確認）

TDD採用が決まった機能について、必ず以下を質問:

🎯 「{{機能名}}」について、テストを書く前に確認させてください

正常系: 一番よくある使われ方は？（具体的なシナリオ）

境界条件: 「ギリギリOK」と「ギリギリNG」の境目は？

エラー時: エラーの場合、ユーザーにどう見せたい？

暗黙の期待: 「当たり前」だと思っていることは？（言語化されていないルール）

暗黙知を引き出す追加質問（必要に応じて）:

状況	追加質問
数値を扱う	「0や負の値は許可？」「小数点は何桁まで？」
日時を扱う	「タイムゾーンは？」「過去日は許可？」
文字列を扱う	「空文字は？」「最大文字数は？」「絵文字は？」
リストを扱う	「空リストは？」「上限は？」「重複は？」
状態遷移がある	「戻れる？」「途中キャンセルは？」「タイムアウトは？」
ユーザー操作	「連打されたら？」「途中で離脱したら？」

テストケース設計（Plans.md に含める）

TDD採用機能には、実装タスクの前にテスト設計を含める:

### {{機能名}} `[feature:tdd]`

#### テストケース設計（実装前に合意）

| テストケース | 入力 | 期待出力 | 備考 |
|-------------|------|---------|------|
| 正常系: 基本 | {{具体例}} | {{期待値}} | 最も一般的なケース |
| 正常系: 境界下限 | {{ギリギリOK}} | {{成功}} | 下限値テスト |
| 正常系: 境界上限 | {{ギリギリOK}} | {{成功}} | 上限値テスト |
| 異常系: 境界超え | {{ギリギリNG}} | {{エラー}} | バリデーション確認 |
| 異常系: null/空 | null, "", [] | {{エラー}} | 防御的プログラミング |
| エッジケース | {{特殊ケース}} | {{期待動作}} | 暗黙知の明文化 |

#### 実装タスク
- [ ] テストファイル作成（上記ケースを実装）
- [ ] 実装コード作成（テストが通るまで）
- [ ] リファクタリング（テストを維持しながら）

TDD非採用の場合

TDD判定条件に該当しない単純な機能（静的UI、設定ファイル生成など）は、通常の実装フローで進める。ただし、ユーザーから「テストも書いて」と依頼された場合は TDD を採用。

Step 6: 工数の見積もり（参考）

各機能の実装工数を参考として算出します。

見積もり基準（Claude Code 活用時）:

機能タイプ	工数（人日）
認証（Clerk使用）	0.5-1
CRUD（1テーブル）	1-2
管理画面（基本）	2-3
決済（Stripe使用）	2-3
メール通知	1-2
CI/CD構築	1
デプロイ設定	0.5

Step 7: Plans.md の生成（品質判定マーカー自動付与）

実装用の Plans.md を生成します。

品質判定マーカーの自動付与:

各タスクの内容を分析し、適切な品質マーカーを自動で付与：

タスク内容	マーカー	効果
認証/ログイン機能	`[feature:security]`	セキュリティチェックリスト表示
UI コンポーネント	`[feature:a11y]`	a11y チェック推奨
ビジネスロジック	`[feature:tdd]`	TDD 推奨
API エンドポイント	`[feature:security]`	入力検証チェック
バグ修正	`[bugfix:reproduce-first]`	再現テスト先行推奨

## 🎯 プロジェクト: {{プロジェクト名}}

### 概要
- **目的**: {{やりたいこと}}
- **対象**: {{誰が使うか}}
- **参考**: {{類似サービス}}
- **スコープ**: {{MVPか全機能か}}

### 技術スタック
- フロントエンド: {{技術}}
- バックエンド: {{技術}}
- データベース: {{技術}}
- デプロイ: {{技術}}

---

## 🔴 フェーズ1: 基盤構築 `cc:TODO`

- [ ] プロジェクト初期化
- [ ] 基本セットアップ（linter, formatter）
- [ ] データベース設計
- [ ] 環境変数の設定
- [ ] Git初期化 & 初回コミット

## 🟡 フェーズ2: コア機能（必須） `cc:TODO`

### {{必須機能1}} `[feature:tdd]`

#### テストケース設計（実装前に合意済み）
| テストケース | 入力 | 期待出力 | 備考 |
|-------------|------|---------|------|
| 正常系: 基本 | {{具体例}} | {{期待値}} | ユーザーヒアリング結果 |
| 境界条件 | {{境界値}} | {{期待動作}} | Step 5.5 で確認済み |
| 異常系 | {{異常入力}} | {{エラー}} | 暗黙知の明文化 |

#### 実装タスク
- [ ] テストファイル作成
- [ ] 実装コード作成
- [ ] リファクタリング

### {{必須機能2}} `[feature:tdd]`
（同様のテストケース設計）

### {{認証機能}} `[feature:security]`

## 🟢 フェーズ3: 推奨機能 `cc:TODO`

- [ ] {{UI機能}} `[feature:a11y]`
- [ ] {{推奨機能}}

## 🔵 フェーズ4: 仕上げ `cc:TODO`

- [ ] レビュー（`/harness-review`）
- [ ] デプロイ設定
- [ ] 動作確認

マーカー判定ロジック:

タスク内容を分析
    ↓
├── "認証" "ログイン" "auth" "API" → [feature:security] + TDD採用判定へ
├── "コンポーネント" "UI" "画面" → [feature:a11y]
├── "修正" "バグ" "fix" → [bugfix:reproduce-first]
├── "サービス" "ロジック" "core" → [feature:tdd] + Step 5.5 へ
├── "計算" "変換" "バリデーション" → [feature:tdd] + Step 5.5 へ
├── "決済" "金額" "課金" → [feature:security] + [feature:tdd] + Step 5.5 へ
└── その他 → マーカーなし

重要: [feature:tdd] マーカーが付いた機能は、必ず Step 5.5 のTDD採用判定フローを通過し、ユーザーへの意図深掘り質問とテストケース設計を行うこと。

Step 8: 次のアクションを案内

✅ 計画が完成しました！

📄 生成したファイル:

Plans.md - 実装タスク一覧

次にやること：

「/work」で実装を開始

「フェーズ1から始めて」と言ってもOK

💡 ヒント: 計画を調整したい場合は「{{機能名}}を追加して」「{{機能名}}は後回しにして」と言ってください。

出力例

例1: 壁打ちからの計画化

ユーザー: （壁打ちで「タスク管理アプリ作りたい、Notionみたいな」と話していた）
ユーザー: /plan-with-agent

Claude Code:
> 📝 計画の作り方を選んでください
> 1. 今までの会話を踏まえる
> 2. 新しく始める

ユーザー: 1

Claude Code:
> 会話から以下を抽出しました：
> - 作りたいもの: タスク管理アプリ
> - 参考: Notion
> - 機能候補: タスクCRUD, カンバン表示, タグ機能
>
> これで計画を進めてよいですか？

ユーザー: OK

→ Plans.md 生成

例2: 新規からの計画化

ユーザー: /plan-with-agent

Claude Code:
> 📝 計画の作り方を選んでください

ユーザー: 新しく始める

Claude Code:
> 🎯 何を作りたいですか？

ユーザー: ブログサイト

（ヒアリング継続）
→ Plans.md 生成

注意事項

Plans.md が最優先: /work で実行できる状態にすることが目的
柔軟に調整可能: 計画後も「〇〇を追加」「〇〇は削除」で変更可能
壁打ちの文脈を活用: Step 0 で「会話を踏まえる」を選べば、議論した内容を反映