/deepen-plan

プラン深化 - パワー強化モード

はじめに

注意: 現在の年は2025年です。 最新のドキュメントやベストプラクティスを検索する際にこれを使用してください。

このコマンドは既存のプラン（/workflows:planから）を取得し、並列リサーチエージェントで各セクションを強化します。各主要要素には専用のリサーチサブエージェントが割り当てられ、以下を検索します：

• ベストプラクティスと業界パターン
• パフォーマンス最適化
• UI/UXの改善（該当する場合）
• 品質強化とエッジケース
• 実際の実装例

結果として、具体的な実装詳細を含む、深く根拠のある本番環境対応のプランが得られます。

プランファイル

<plan_path> #$ARGUMENTS </plan_path>

上記のプランパスが空の場合：

1. 最近のプランを確認：ls -la plans/
2. ユーザーに質問：「どのプランを深化させますか？パスを提供してください（例：plans/my-feature.md）。」

有効なプランファイルパスが得られるまで進めないでください。

主要タスク

1. プラン構造の解析と分析

まず、プランを読み込んで解析し、リサーチで強化できる各主要セクションを特定します。

プランファイルを読み込み、以下を抽出：

• 概要/問題文
• 提案されたソリューションセクション
• 技術的アプローチ/アーキテクチャ
• 実装フェーズ/ステップ
• コード例とファイル参照
• 受け入れ基準
• 言及されているUI/UXコンポーネント
• 言及されている技術/フレームワーク（Rails、React、Python、TypeScriptなど）
• ドメイン領域（データモデル、API、UI、セキュリティ、パフォーマンスなど）

セクションマニフェストを作成：

セクション1: [タイトル] - [リサーチ内容の簡潔な説明]
セクション2: [タイトル] - [リサーチ内容の簡潔な説明]
...

2. 利用可能なスキルの発見と適用

利用可能なすべてのスキルを動的に発見し、プランセクションにマッチさせます。どのスキルが存在するかを仮定せず、実行時に発見します。

ステップ1: すべてのソースからすべての利用可能なスキルを発見

# 1. プロジェクトローカルスキル（最高優先度 - プロジェクト固有）
ls .claude/skills/

# 2. ユーザーのグローバルスキル（~/.claude/）
ls ~/.claude/skills/

# 3. compound-engineeringプラグインスキル
ls ~/.claude/plugins/cache/*/compound-engineering/*/skills/

# 4. 他のすべてのインストール済みプラグイン - すべてのプラグインでスキルをチェック
find ~/.claude/plugins/cache -type d -name "skills" 2>/dev/null

# 5. installed_plugins.jsonもチェックしてすべてのプラグインの場所を確認
cat ~/.claude/plugins/installed_plugins.json

重要： すべてのソースをチェックしてください。compound-engineeringが唯一のプラグインだと仮定しないでください。関連するすべてのインストール済みプラグインからスキルを使用します。

ステップ2: 発見された各スキルについて、SKILL.mdを読んで何をするか理解する

# 見つかった各スキルディレクトリについて、そのドキュメントを読む
cat [skill-path]/SKILL.md

ステップ3: スキルをプランコンテンツにマッチング

発見された各スキルについて：

• SKILL.mdの説明を読む
• プランセクションがスキルのドメインにマッチするか確認
• マッチがあれば、そのスキルの知識を適用するサブエージェントを起動

ステップ4: マッチした各スキルに対してサブエージェントを起動

重要: マッチした各スキルに対して、別々のサブエージェントを起動し、そのスキルを使用するよう指示します。

マッチした各スキルについて：

Task general-purpose: "[skill-name]スキルが[skill-path]で利用可能です。

あなたの仕事: このスキルをプランに使用すること。

1. スキルを読む: cat [skill-path]/SKILL.md
2. スキルの指示に正確に従う
3. このコンテンツにスキルを適用:

[関連するプランセクションまたは全プラン]

4. スキルの完全な出力を返す

スキルが何をすべきか教えてくれます - 従ってください。スキルを完全に実行してください。"

すべてのスキルサブエージェントを並列で起動：

• マッチしたスキルごとに1サブエージェント
• 各サブエージェントは割り当てられたスキルを読んで使用
• すべて同時に実行
• 10、20、30のスキルサブエージェントでも問題なし

各サブエージェント：

1. 自分のスキルのSKILL.mdを読む
2. スキルのワークフロー/指示に従う
3. プランにスキルを適用
4. スキルが生成するものを返す（コード、推奨事項、パターン、レビューなど）

起動例：

Task general-purpose: "~/.claude/plugins/.../dhh-rails-styleにあるdhh-rails-styleスキルを使用。SKILL.mdを読んで適用: [プランのRailsセクション]"

Task general-purpose: "~/.claude/plugins/.../frontend-designにあるfrontend-designスキルを使用。SKILL.mdを読んで適用: [プランのUIセクション]"

Task general-purpose: "~/.claude/plugins/.../agent-native-architectureにあるagent-native-architectureスキルを使用。SKILL.mdを読んで適用: [プランのエージェント/ツールセクション]"

Task general-purpose: "~/.claude/skills/security-patternsにあるsecurity-patternsスキルを使用。SKILL.mdを読んで適用: [全プラン]"

スキルサブエージェントの数に制限なし。関連する可能性のあるすべてのスキルに対して1つずつ起動してください。

3. 学習/ソリューションの発見と適用

/workflows:compoundからの文書化された学習をチェックします。これらはマークダウンファイルとして保存された解決済みの問題です。各学習に対してサブエージェントを起動し、関連性を確認します。

学習の場所 - これらの正確なフォルダをチェック：

docs/solutions/           <-- プライマリ: プロジェクトレベルの学習（/workflows:compoundで作成）
├── performance-issues/
│   └── *.md
├── debugging-patterns/
│   └── *.md
├── configuration-fixes/
│   └── *.md
├── integration-issues/
│   └── *.md
├── deployment-issues/
│   └── *.md
└── [other-categories]/
    └── *.md

ステップ1: すべての学習マークダウンファイルを見つける

すべての学習ファイルを取得するためにこれらのコマンドを実行：

# プライマリの場所 - プロジェクト学習
find docs/solutions -name "*.md" -type f 2>/dev/null

# docs/solutionsが存在しない場合、代替場所をチェック:
find .claude/docs -name "*.md" -type f 2>/dev/null
find ~/.claude/docs -name "*.md" -type f 2>/dev/null

ステップ2: フィルタリングのために各学習のフロントマターを読む

各学習ファイルにはメタデータを含むYAMLフロントマターがあります。各ファイルの最初の約20行を読んで取得：

---
title: "BriefsのN+1クエリ修正"
category: performance-issues
tags: [activerecord, n-plus-one, includes, eager-loading]
module: Briefs
symptom: "ページ読み込みが遅い、ログに複数のクエリ"
root_cause: "関連付けにincludesが欠落"
---

各.mdファイルについて、フロントマターを素早くスキャン：

# 各学習の最初の20行を読む（フロントマター + サマリー）
head -20 docs/solutions/**/*.md

ステップ3: フィルタリング - 関連性が高い学習にのみサブエージェントを起動

各学習のフロントマターをプランと比較：

• tags: - プランの技術/パターンにマッチするタグはあるか？
• category: - このカテゴリは関連性があるか？（例：プランがUIのみならdeployment-issuesをスキップ）
• module: - プランはこのモジュールに触れるか？
• symptom: / root_cause: - この問題はプランで発生する可能性があるか？

明らかに適用されない学習をスキップ：

• プランがフロントエンドのみ → database-migrations/ 学習をスキップ
• プランがPython → rails-specific/ 学習をスキップ
• プランに認証がない → authentication-issues/ 学習をスキップ

適用される可能性がある学習にサブエージェントを起動：

• プラン技術とのタグの重複
• プランドメインと同じカテゴリ
• 類似のパターンや懸念

ステップ4: フィルタリングされた学習にサブエージェントを起動

フィルターを通過した各学習について：

Task general-purpose: "
学習ファイル: [.mdファイルへのフルパス]

1. この学習ファイルを完全に読む
2. この学習は以前解決された問題を文書化

この学習がこのプランに適用されるか確認:

---
[全プランコンテンツ]
---

関連する場合:
- 具体的にどう適用されるか説明
- 重要な洞察やソリューションを引用
- どこに/どのように組み込むか提案

深い分析の後に関連しない場合:
- '適用不可: [理由]'と言う
"

フィルタリング例：

# 15の学習ファイルが見つかり、プランは「Rails APIキャッシング」について

# 起動（関連性が高い）:
docs/solutions/performance-issues/n-plus-one-queries.md      # tags: [activerecord] ✓
docs/solutions/performance-issues/redis-cache-stampede.md    # tags: [caching, redis] ✓
docs/solutions/configuration-fixes/redis-connection-pool.md  # tags: [redis] ✓

# スキップ（明らかに適用不可）:
docs/solutions/deployment-issues/heroku-memory-quota.md      # キャッシングについてではない
docs/solutions/frontend-issues/stimulus-race-condition.md    # プランはAPI、フロントエンドではない
docs/solutions/authentication-issues/jwt-expiry.md           # プランに認証がない

フィルタリングされたすべての学習に対してサブエージェントを並列で起動。

これらの学習は組織的な知識です - 適用することで過去の間違いを繰り返すことを防ぎます。

4. セクションごとのリサーチエージェントの起動

プランの各主要セクションについて、専用のサブエージェントを起動して改善をリサーチします。オープンエンドのリサーチにはExploreエージェントタイプを使用します。

特定された各セクションについて、並列リサーチを起動：

Task Explore: "[セクションのトピック]のベストプラクティス、パターン、実際の例をリサーチ。
検索:
- 業界標準と慣例
- パフォーマンスの考慮事項
- 一般的な落とし穴とその回避方法
- ドキュメントとチュートリアル
具体的で実行可能な推奨事項を返す。"

フレームワークドキュメントにはContext7 MCPも使用：

プランで言及されている技術/フレームワークについて、Context7にクエリ：

mcp__plugin_compound-engineering_context7__resolve-library-id: [フレームワーク]のライブラリIDを見つける
mcp__plugin_compound-engineering_context7__query-docs: 特定のパターンのドキュメントをクエリ

現在のベストプラクティスにはWebSearchを使用：

プラン内のトピックに関する最近の（2024-2025年）記事、ブログ投稿、ドキュメントを検索。

5. すべてのレビューエージェントの発見と実行

利用可能なすべてのエージェントを動的に発見し、プランに対してすべて実行します。フィルタリングせず、スキップせず、関連性を仮定しません。40以上の並列エージェントでも問題ありません。利用可能なすべてを使用します。

ステップ1: すべてのソースからすべての利用可能なエージェントを発見

# 1. プロジェクトローカルエージェント（最高優先度 - プロジェクト固有）
find .claude/agents -name "*.md" 2>/dev/null

# 2. ユーザーのグローバルエージェント（~/.claude/）
find ~/.claude/agents -name "*.md" 2>/dev/null

# 3. compound-engineeringプラグインエージェント（すべてのサブディレクトリ）
find ~/.claude/plugins/cache/*/compound-engineering/*/agents -name "*.md" 2>/dev/null

# 4. 他のすべてのインストール済みプラグイン - すべてのプラグインでエージェントをチェック
find ~/.claude/plugins/cache -path "*/agents/*.md" 2>/dev/null

# 5. installed_plugins.jsonをチェックしてすべてのプラグインの場所を見つける
cat ~/.claude/plugins/installed_plugins.json

# 6. ローカルプラグイン（isLocal: true）については、そのソースディレクトリをチェック
# installed_plugins.jsonを解析してローカルプラグインパスを見つける

重要： すべてのソースをチェック。以下からエージェントを含める：

• プロジェクト .claude/agents/
• ユーザーの ~/.claude/agents/
• compound-engineeringプラグイン（ただしworkflow/エージェントはスキップ - review/、research/、design/、docs/のみ使用）
• 他のすべてのインストール済みプラグイン（agent-sdk-dev、frontend-designなど）
• すべてのローカルプラグイン

compound-engineeringプラグインについて具体的に：

• 使用: agents/review/*（すべてのレビュアー）
• 使用: agents/research/*（すべてのリサーチャー）
• 使用: agents/design/*（デザインエージェント）
• 使用: agents/docs/*（ドキュメントエージェント）
• スキップ: agents/workflow/*（これらはワークフローオーケストレーター、レビュアーではない）

ステップ2: 発見された各エージェントについて、その説明を読む

各エージェントファイルの最初の数行を読んで、何をレビュー/分析するか理解。

ステップ3: すべてのエージェントを並列で起動

発見されたすべてのエージェントについて、並列でTaskを起動：

Task [agent-name]: "あなたの専門知識を使ってこのプランをレビュー。すべてのチェックとパターンを適用。プランコンテンツ: [全プランコンテンツ]"

重要なルール：

• 「関連性」でエージェントをフィルタリングしない - すべて実行
• 「適用されないかもしれない」からとエージェントをスキップしない - 判断はエージェントに任せる
• 複数のTask toolコールを含む単一のメッセージですべてのエージェントを起動
• 20、30、40の並列エージェントでも問題なし - すべてを使用
• 各エージェントは他が見逃すものをキャッチする可能性がある
• 目標は効率性ではなく最大カバレッジ

ステップ4: リサーチエージェントも発見して実行

リサーチエージェント（best-practices-researcher、framework-docs-researcher、git-history-analyzer、repo-research-analystなど）も関連するプランセクションに対して実行すべき。

6. すべてのエージェントを待ち、すべてを統合

すべての並列エージェントの完了を待ちます - スキル、リサーチエージェント、レビューエージェント、すべて。その後、すべての発見を包括的な強化に統合します。

すべてのソースから出力を収集：

1. スキルベースのサブエージェント - 各スキルの完全な出力（コード例、パターン、推奨事項）
2. 学習/ソリューションサブエージェント - /workflows:compoundからの関連する文書化された学習
3. リサーチエージェント - ベストプラクティス、ドキュメント、実際の例
4. レビューエージェント - すべてのレビュアーからのフィードバック（アーキテクチャ、セキュリティ、パフォーマンス、シンプルさなど）
5. Context7クエリ - フレームワークドキュメントとパターン
6. Web検索 - 現在のベストプラクティスと記事

各エージェントの発見から抽出：

• 具体的な推奨事項（実行可能なアイテム）
• コードパターンと例（コピー＆ペースト可能）
• 避けるべきアンチパターン（警告）
• パフォーマンスの考慮事項（メトリクス、ベンチマーク）
• セキュリティの考慮事項（脆弱性、緩和策）
• 発見されたエッジケース（処理戦略）
• ドキュメントリンク（参照）
• スキル固有のパターン（マッチしたスキルから）
• 関連する学習（適用される過去のソリューション - 間違いの繰り返しを防ぐ）

重複を排除し、優先順位付け：

• 複数のエージェントからの類似の推奨事項をマージ
• 影響度で優先順位付け（高価値の改善を最初に）
• 人間のレビューのために矛盾するアドバイスにフラグを付ける
• プランセクションごとにグループ化

7. プランセクションの強化

リサーチの発見をプランにマージし、元の構造を変えずに深さを追加します。

各セクションの強化フォーマット：

## [元のセクションタイトル]

[元のコンテンツを保持]

### リサーチインサイト

**ベストプラクティス：**
- [具体的な推奨事項1]
- [具体的な推奨事項2]

**パフォーマンスの考慮事項：**
- [最適化の機会]
- [目標とするベンチマークやメトリクス]

**実装の詳細：**
```[言語]
// リサーチからの具体的なコード例

エッジケース：

• [エッジケース1とその処理方法]
• [エッジケース2とその処理方法]

参照：

• [ドキュメントURL 1]
• [ドキュメントURL 2]

### 8. 強化サマリーの追加

プランの上部にサマリーセクションを追加：

```markdown
## 強化サマリー

**深化日:** [日付]
**強化されたセクション:** [数]
**使用したリサーチエージェント:** [リスト]

### 主要な改善
1. [主要な改善1]
2. [主要な改善2]
3. [主要な改善3]

### 発見された新しい考慮事項
- [重要な発見1]
- [重要な発見2]

9. プランファイルの更新

強化されたプランを書き込む：

• 元のファイル名を保持
• ユーザーが新しいファイルを希望する場合は-deepenedサフィックスを追加
• タイムスタンプやメタデータを更新

出力フォーマット

プランファイルをその場で更新（またはリクエストされた場合はplans/<original-name>-deepened.mdを作成）。

品質チェック

最終化前に：

• すべての元のコンテンツが保持されている
• リサーチインサイトが明確にマークされ、帰属が示されている
• コード例が構文的に正しい
• リンクが有効で関連性がある
• セクション間に矛盾がない
• 強化サマリーが変更を正確に反映している

強化後のオプション

強化されたプランを書き込んだ後、AskUserQuestion toolを使用してこれらのオプションを提示：

質問: "[plan_path]でプランを深化しました。次に何をしますか？"

オプション:

1. 差分を表示 - 追加/変更された内容を表示
2. /plan_reviewを実行 - 強化されたプランに対してレビュアーからフィードバックを取得
3. /workflows:workを開始 - この強化されたプランの実装を開始
4. さらに深化 - 特定のセクションに対して別のリサーチラウンドを実行
5. 元に戻す - 元のプランを復元（バックアップが存在する場合）

選択に基づいて：

• 差分を表示 → git diff [plan_path]を実行または前後を表示
• /plan_review → プランファイルパスで/plan_reviewコマンドを呼び出す
• /workflows:work → プランファイルパスで/workflows:workコマンドを呼び出す
• さらに深化 → より多くのリサーチが必要なセクションを尋ね、それらのエージェントを再実行
• 元に戻す → gitまたはバックアップから復元

強化例

前（/workflows:planから）：

## 技術的アプローチ

楽観的更新を伴うReact Queryをデータ取得に使用。

後（/workflows:deepen-planから）：

## 技術的アプローチ

楽観的更新を伴うReact Queryをデータ取得に使用。

### リサーチインサイト

**ベストプラクティス：**
- データの鮮度要件に基づいて`staleTime`と`cacheTime`を設定
- 一貫したキャッシュ無効化のために`queryKey`ファクトリを使用
- クエリ依存コンポーネントの周りにエラーバウンダリを実装

**パフォーマンスの考慮事項：**
- 安定したデータに対して`refetchOnWindowFocus: false`を有効にし、不要なリクエストを減らす
- クエリレベルでデータを変換しメモ化するために`select`オプションを使用
- 即座の知覚ローディングのために`placeholderData`を検討

**実装の詳細：**
```typescript
// 推奨クエリ設定
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 5分
      retry: 2,
      refetchOnWindowFocus: false,
    },
  },
});

エッジケース：

• コンポーネントのアンマウント時にcancelQueriesでレースコンディションを処理
• 一時的なネットワーク障害に対してリトライロジックを実装
• persistQueryClientでオフラインサポートを検討

参照：

• https://tanstack.com/query/latest/docs/react/guides/optimistic-updates
• https://tkdodo.eu/blog/practical-react-query

コードは書かないでください！リサーチとプランの強化のみ。