Deep Work Workflow: ブレインストーム → リサーチ → 計画 → 実装 → テスト → 統合

v5.6.0 セッションフォーク

v5.6.0 新機能:

/deep-fork [session-id] [--from-phase=PHASE]

現在のセッションをフォークして別のアプローチを探索します。元のセッションは保持されます。

• Git環境: worktreeベースの完全複製。implement/testまで進行可能。
  • ダーティ状態検証: clean/commit/stash から選択
  • セッションID ベースのブランチサフィックス (race condition 防止)
  • Worktreeコンテキスト自動切り替え (FORK_PROJECT_ROOT)
• 非Git環境: 成果物のみ複製。plan フェーズまでのみ進行可能。
  • フェーズガードが implement/test への進入をブロック
• フォーク関係追跡:
  • fork_info: フォークされたセッションの状態ファイルに親関係を記録
  • fork_children: 親セッションの状態ファイルに子リストを記録
  • fork-snapshot.yaml: フォーク時点の状態スナップショット (比較基準点)
• 比較 & ビジュアライゼーション:
  • /deep-status --tree: フォーク関係ツリーをビジュアライズ
  • /deep-status --compare: フォーク関係を自動検出して比較
• エッジケース: 最大3世代フォーク (警告)、idle セッションのフォーク禁止、stale 親の検証

v5.5.2 堅牢な検出 & シグナル処理

v5.5.2 新機能:

• 拡張bash ファイル書き込み検出: perl、node -e、python -c、ruby -e、swift、awk、git destructive ops など20+ パターンを追加
• セキュリティ: file-write-first 検出順序: FILE_WRITE パターンを SAFE パターンより先に検査して回避防止
• 拡張言語サポート: Dart、Elixir、Lua、Vue テストパターン + fixtures/mocks ディレクトリ認識
• TDD 除外拡張: .toml、.ini、.cfg、.lock、.editorconfig、画像ファイルを除外
• splitCommands 改善: バッククォート、$() サブシェル深度追跡で中ネストされた式内の誤った分割を防止
• TDD 状態検証: 未知の状態値をブロック + ガイダンスメッセージ
• エラーロギング: /dev/null → .claude/deep-work-guard-errors.log ファイルに記録
• Node.js 25 互換性: file-tracker.sh argv インデックス修正 (receipt 生成の無音失敗を解決)
• Assumption Engine 修正: CLI バグ、threshold 引き渡し、重複排除順序 (keep-latest)、入力ガード

v6.0.2 フェーズレビューゲート & フォルダ名変更

v6.0.2 新機能:

• フェーズレビューゲート: すべてのフェーズ (0～3) 終了時に統合レビューゲートを自動実行。セルフレビュー + 外部レビュー (deep-review/codex/gemini/Opus) 後ユーザー確認
• フェーズ別フォールバックチェーン: フェーズ 0～2 (ドキュメント) は Structural+Adversarial、フェーズ 3 (コード) は deep-review を優先
• ユーザー確認UX: サマリー → 選択肢 (自動修正/現在進行/詳細表示)
• デグレード モード: 外部レビュアー失敗時に自動フォールバック
• セッションフォルダ名変更: deep-work/ → .deep-work/ (隠しフォルダ)。マイグレーション自動処理
• State スキーマ拡張: phase_review フィールド追加 (既存の review_results との後方互換性)

v5.5 レビューフロー強化

v5.5 新機能:

• リサーチクロスモデルレビュー: research フェーズにも codex/gemini クロスレビューを適用
• Claude 自己再検討: plan 作成直後に自動品質チェック (プレースホルダー、一貫性、漏れ)
• 総合判断プロトコル: クロスレビュー後にClaude判断 + ユーザー一括確認 (個別コンフリクト質問の代替)
• Structural Review 強化: auto-fix 基準 score < 5 → score < 7、スナップショットベースのロールバック
• デグレード モード: クロスモデルレビュアー失敗時に明示的なステータス表示 + graceful フォールバック
• State スキーママイグレーション: 新フィールドの自動初期化、resume 時にドキュメント-判断時間検証

v5.3 精密さ + エビデンス

/deep-work "task" で全ワークフローが自動進行します。 計画承認が唯一の必須インタラクションです。

v5.3 新機能:

• ドキュメント インテリジェンス: フィードバック適用時に重複/不要な内容を自動整理 (Apply → Deduplicate → Prune)
• セッション関連性検出: 現在のセッション範囲外のフィードバックを検出 → 新セッション分離を提案
• 計画忠実度スコア: 実装 vs 計画の忠実度を 0-100 スコアで算出
• セッション品質スコア: セッション終了時に品質スコアを自動計算 — 5コンポーネントシステム: テスト合格率 (25%)、リワークサイクル (20%)、計画忠実度 (25%)、センサークリーン率 (15%)、ミューテーション スコア (15%)。not_applicable の場合、センサー/ミューテーション コンポーネントを比例して除外。
• セッション間品質トレンド: /deep-status --history でセッション間の品質推移をビジュアライズ
• Assumption Engine 品質統合: 品質スコアに基づくルール自己最適化 (コホート分析、3セッション minimum gate)
• 品質バッジ: /deep-status --badge で shields.io バッジを生成

プライマリワークフロー (7): /deep-work、/deep-research、/deep-plan、/deep-implement、/deep-test、/deep-status、/deep-debug

特殊ユーティリティ (4): /deep-fork、/deep-mutation-test、/deep-phase-review、/deep-sensor-scan

品質ゲート (3): /drift-check、/solid-review、/deep-insight — /deep-test が自動実行。スタンドアロン呼び出しも可能。

内部 (6): /deep-brainstorm、/deep-finish、/deep-report、/deep-receipt、/deep-history、/deep-assumptions — オーケストレーターまたは /deep-status が内部参照。手動呼び出しも公式パス。

エスケープハッチ (1): /deep-slice — phase-guard が TDD をブロックしている場合にガイダンス (spike、reset)。

ユーティリティ (2): /deep-cleanup、/deep-resume — スタンドアロン機能。将来の移管後に削除予定。

コアメカニズム:

• フェーズガード (hook で強制されるコードブロッキング)
• TDD 強制 (状態マシン: PENDING → RED → GREEN → REFACTOR)
• スライスベース実行と receipt 収集
• プロファイル/プリセットシステム (ゼロ質問再開)
• フェーズ出口ゲート (v6.3.1): AskUserQuestion 経由でフェーズ間遷移をユーザー確認 — フェーズあたり「進行 / 再実行 / 一時停止」。current_phase の遷移はオーケストレーター出口ゲートで「進行」選択時にのみ発生。フェーズ 5 統合は除外 (インタラクティブループ自体がゲート役割)。

このワークフローが存在する理由

AI コーディングツールが構造なしに複雑なタスクに取り組むと、一般的なエラーモードが出現します:

1. アーキテクチャ無知: AI が既存パターンに従わないコードを生成
2. 重複実装: 同等のユーティリティが既に存在するのに新しいものを作成
3. 時期尚早なコーディング: 全体像を理解する前にコード記述を開始
4. スコープ蔓延: リクエストされていない「改善」を追加してバグを導入
5. 矛盾: コードベースの残りと異なる規約を使用

Deep Work ワークフロー は、ブレインストーム、分析、計画、コーディング、テスト、統合 を6つの異なるフェーズに厳密に分離することでこれらを防止します — 最初の5つはゲートが強制され、フェーズ5統合はテスト後の optional な推奨ループです。

6つのフェーズ

フェーズ 0: ブレインストーム (/deep-brainstorm) — オプション

ゴール: 「how の前に why」を探索 — 問題を定義、アプローチを比較、成功基準を確立します。

何が起こるか:

• ユーザーとの構造化設計会話
• 2-3 アプローチの比較と pros/cons
• spec-reviewer サブエージェントがブレインストーム ドキュメントを検証
• $WORK_DIR/brainstorm.md にドキュメント化
• フェーズレビューゲート: フェーズ完了時にセルフレビュー + 外部レビューを自動実行、ユーザー確認後に遷移

ブロックされるもの: すべてのコードファイル変更 (hook で強制) スキップ: --skip-brainstorm を使用してリサーチから直接開始します。

フェーズ 1: リサーチ (/deep-research)

ゴール: 何らかの決定を下す前に、関連するコードベースの完全なメンタルモデルを構築します。

何が起こるか:

• アーキテクチャ、パターン、規約の徹底的な分析
• すべての関連ファイル、依存関係、リスク領域の識別
• $WORK_DIR/research.md にすべてをドキュメント化
• 出力は executive summary と主要な発見で開始 (ピラミッド原則)
• フェーズレビューゲート: フェーズ完了時にセルフレビュー + 外部レビューを自動実行、ユーザー確認後に遷移

ブロックされるもの: すべてのコードファイル変更 (hook で強制)

主要原則: 「理解していないものを計画することはできず、読んでいないものを理解することはできません。」

機能:

• ゼロベース モード: 新規プロジェクトの場合、既存コードの代わりにテクノロジースタック、アーキテクチャパターン、スカフォルディングをリサーチします
• 部分的な再実行: /deep-research --scope=api,data で特定の領域のみを再分析
• リサーチキャッシング: 前のセッションのリサーチを基準として再利用、変更された領域のみ更新
• チームモード: 3人の specialist エージェント (arch-analyst、pattern-analyst、risk-analyst) が並列分析
• Structural Review 強化: score < 7 で auto-fix、スナップショットベースのロールバック
• クロスモデル レビュー: codex/gemini が research.md を独立評価 (計画と同じパターン)
• 総合判断: Claude がすべてのレビュー結果を分析、ユーザー一括確認後に修正

詳細なガイダンスについては、Research Guide または Zero-Base Guide を参照してください。

フェーズ 2: 計画 (/deep-plan)

ゴール: 詳細で検証可能で承認可能な実装計画を作成します。

何が起こるか:

• リサーチの発見を具体的なアクション計画に変換
• 計画サマリーを上部に配置 し、アプローチ、スコープ、リスクレベル、主要な決定を記載
• 変更するファイル、コードスニペット、実行順序を正確に定義
• コード完全性はスライスサイズに応じてティアリング: S=疑似コード可、M=シグネチャ+型は実際のコード、L=境界コード完全 (インターフェース、API、テスト)
• プレースホルダーなし: 計画は完全性ポリシーを通過する必要があります — TBD、TODO、または曖昧な指示はありません
• リサーチトレーサビリティ: アーキテクチャの決定は タグ付きリサーチ発見を参照 [RF-NNN]、[RA-NNN]
• $WORK_DIR/plan.md にチェックリスト形式のタスクリストを作成
• フェーズレビューゲート: フェーズ完了時にセルフレビュー + 外部レビューを自動実行、ユーザー確認後に遷移

ブロックされるもの: すべてのコードファイル変更 (hook で強制)

主要原則: 「計画は人間と AI の間の契約です。承認なしに実装はありません。」

機能:

• インタラクティブレビュー: チャットベースのフィードバックループ — 「3番項目を変更してください」と言うと plan.md が自動更新
• 計画テンプレート: 一般的なタスクタイプ (API エンドポイント、UI コンポーネント、DB マイグレーション等) のテンプレートを自動提案
• バージョン履歴: 前の計画を plan.v1.md、plan.v2.md として変更ログ付きでバックアップ
• モード再評価: 計画の複雑さに基づいて Team ↔ Solo 切り替えを提案
• 実装への出口ゲート (v6.3.1): ドキュメント最終承認後、オーケストレーター フェーズ出口ゲートが「進行 / 再実行 / 一時停止」を質問。「進行」選択で実装フェーズを自動呼び出し (手動 /deep-implement 不要)。
• Claude 自己再検討: 計画作成直後にプレースホルダー/一貫性/漏れを自動チェック & 修正
• Structural Review 強化: score < 7 で auto-fix、スナップショットベースのロールバック
• 総合判断: クロスレビュー後にClaude判断 + ユーザー一括確認 (個別コンフリクト質問の代替)
• チームリサーチ相互検証 (v5.5.1): team_mode: team の場合、部分リサーチファイル (research-architecture/patterns/dependencies.md) を補助参照として読み込んで合成漏れの詳細を相互確認

注記: 計画フェーズはチームモードを使用しません — 計画には1つのエージェントによって作成された一貫したドキュメントが必要です。

詳細なガイダンスについては、Planning Guide を参照してください。

フェーズ 3: 実装 (/deep-implement)

ゴール: 承認された計画を機械的に実行し、タスク ごとに実行します。

何が起こるか:

• 計画チェックリストを正確に従う
• 1つずつタスクを実装し、それぞれを完了とマーク
• 発生した問題をドキュメント化 — 絶対に即興はしません
• テストフェーズへの出口ゲート (v6.3.1): すべてのスライスが完了したら、オーケストレーターがフェーズ出口ゲートをマーク。「進行」選択でテストフェーズを呼び出し。実装スキル自体は implement_completed_at のみ記録し、current_phase の遷移はオーケストレーターが担当。
• 計算センサー: 各スライスが GREEN に達した後、計算センサー (linter、型チェッカー) が自動実行。失敗した場合、次のスライスに移動する前に AI が修正を試みる自己修正ループ (SENSOR_FIX 状態) をトリガー。結果は receipt の sensor_results フィールドに保存。
• スライス レビュー: センサーが合格した後、スライスあたりの独立した2段階のレビュー — 仕様適合性 (必須) とコード品質 (参考)。問題はすぐにキャッチされ、フェーズ 4 に先延ばしされません。
• 飛行前チェック: 各スライスの TDD サイクル前に、前提条件を確認 (ファイルが存在、コマンドが機能)。問題が AskUserQuestion で即座に発生。
• ステータスレポート: 各スライスは slice_confidence (done/done_with_concerns) と receipt の特定の懸念を記録。
• レッドフラグ: 実装とテストフェーズの合理化防止テーブル。hook ベースのハードゲートを補完するソフト行動ガイダンス。
• フェーズレビューゲート: フェーズ完了時にセルフレビュー + 外部レビューを自動実行、ユーザー確認後に遷移

許可されるもの: すべてのツール — コード変更は now が許可されます

主要原則: 「最高の実装は退屈な実装です。創意工夫もサプライズもなく、単に忠実に実行するだけです。」

機能:

• チェックポイント サポート: 中断された場合、最後の未完了タスクから再開
• チームモード: タスクはファイル所有権でクラスタリングされ、クロスレビューで並列エージェントに分散
• テストへの出口ゲート引き渡し (v6.3.1): スライス完了後、実装は完了マーカーのみを記録し、オーケストレーター出口ゲートに制御を返す。ユーザー「進行」選択でテストフェーズを呼び出し (手動 /deep-test 不要)。
• TDD 状態更新必須化 (v5.5.1): B-1/B-2 完了後、状態ファイル更新を必須として明示、未実行時にフェーズガード警告をブロック
• スライス レビュー: センサー合格後のスライスごとの2段階の独立レビュー (仕様適合性 → コード品質)。solo モードのみ。委任モードでは slice_review.mode: "self" として記録されたセルフレビューを使用

詳細なガイダンスについては、Implementation Guide を参照してください。

フェーズ 4: テスト (/deep-test)

ゴール: 包括的な自動テストを通じた実装を検証します。

何が起こるか:

• プロジェクト設定から検証コマンドを自動検出 (test、lint、typecheck)
• すべてのチェックを順序付きで実行し、結果を記録
• センサークリーンゲート: receipt からの sensor_results を読み込み (再実行なし) してすべてのスライスが計算センサーを合格したことを確認
• ミューテーション テスト: AI が生成したテストの品質をミューテーション分析 (stryker/mutmut) を実行して検証。生き残ったミュータント は実装フェーズへの自動戻りをトリガー — /deep-mutation-test がこの遷移を内部で処理
• クロス スライス一貫性 + バックフィル レビュー: フェーズ 4 は、フェーズ 3 で完了した スライスごとの適合性の代わりに、スライス間互換性を検証します。フェーズ 3 レビューをスキップしたスライスはここでバックフィル (補完) レビューを取得します。
• 合格: セッション完了、レポート生成
• 失敗: 実装フェーズに戻す (最大3回の再試行)

ブロックされるもの: すべてのコードファイル変更 (hook で強制)

主要原則: 「信頼しますが検証します。テストフェーズが実装が見逃したものをキャッチします。」

機能:

• 自動検出: package.json、pyproject.toml、Makefile、Cargo.toml、go.mod をスキャン
• 実装-テストループ: 詳細な失敗レポートで自動再試行サイクル
• 累積結果: すべての試行が $WORK_DIR/test-results.md に記録
• Git 統合: すべてのテストが合格後に commit を提案

詳細なガイダンスについては、Testing Guide を参照してください。

フェーズ 5: 統合 (v6.3.0、スキップ可能)

フェーズ 4 テスト完了後、option で呼び出される「次のステップ推奨ループ」。インストールされた deep-review/deep-docs/deep-wiki/deep-dashboard/deep-evolve プラグインのアーティファクトを読み込んで、AI が最大3つの次のステップを推奨し、ユーザーが選択・実行するか skip・finish します。--skip-integrate でスキップでき、/deep-integrate で明示的な再進入も可能。詳細な UX/データ契約は docs/superpowers/specs/2026-04-18-phase5-integrate-design.md を参照。

品質ゲート & ユーティリティ

計画アラインメント チェック (/drift-check) — 品質ゲート — /deep-test で自動実行。スタンドアロン: /drift-check [plan-file]

plan.md の項目を実際の git diff と比較します。実装済み、未実装、スコープ外、設計ずれをレポート。 スタンドアロン モード利用可: /drift-check [plan-file]。

SOLID 設計レビュー (/solid-review) — 品質ゲート — /deep-test で自動実行。スタンドアロン: /solid-review [target]

5つの SOLID 設計原則に対してコードを評価し、原則ごとのスコアカードを提示します。 スタンドアロン モード利用可: /solid-review [target]。SOLID Guide を参照。

コードインサイト分析 (/deep-insight) — 品質ゲート — /deep-test で自動実行。スタンドアロン: /deep-insight [target]

ファイル メトリクス、複雑さ指標、依存グラフを測定します。ワークフローをブロックしません。 スタンドアロン モード利用可: /deep-insight [target]。Insight Guide を参照。

セッション レポート (/deep-report) — 内部 — テスト合格後に自動生成。手動: /deep-report または /deep-status --report

包括的なセッションレポート (リサーチ、計画、実装、テスト成果、フェーズ期間) を生成します。 すべてのテストが合格後に自動生成。手動: /deep-report または /deep-status --report。

フェーズ強制

hook はフェーズ境界を強制し、アクティビティを追跡します:

• PreToolUse (phase-guard.sh): リサーチ、計画、テストフェーズ中 — Write/Edit ツールは $WORK_DIR/ ドキュメントと状態ファイル以外のすべてのファイルでブロック。実装フェーズ中 — すべてのツール利用可。セッションなし — 制限なし。
• PostToolUse (file-tracker.sh): 実装フェーズ中 — 変更されたファイル パスを自動ログイン $WORK_DIR/file-changes.log にタイムスタンプ付きで記録。/deep-report と /deep-insight で使用。
• Stop (session-end.sh): CLI セッション終了時 — deep-work セッションがアクティブな場合、リマインダー メッセージを出力。

これは提案ではなく — それはハード ゲートです。AI は計画が承認されるまでコードファイルを変更することはできず、テスト中にコード を変更することはできません。

クイックスタート

/deep-work "JWT トークンを使用してユーザー認証を追加"
# v6.3.1 フェーズ出口ゲート — 各フェーズ完了時にユーザー確認 (進行/再実行/一時停止)
# → ブレインストーム → [出口ゲート] → リサーチ →