simplify-parallel

コードベースの並列簡素化

コードベースを論理的な単位に自動分割し、依存関係の順序を適切に考慮しながら並行処理することで、大規模なコードベース全体のコードを簡素化します。

クイックリファレンス

コマンド	説明
/simplify-parallel	コードベース全体を分析して簡素化します
/simplify-parallel --dry-run	分析のみを行い、実行せずに計画を表示します
/simplify-parallel --focus=lib	対象を特定の領域に限定します
/simplify-parallel --segments=4	並列エージェントの最大数を設定します

使用方法

/simplify-parallel [options]

オプション

オプション	デフォルト	説明
--dry-run	false	分析のみを行い、ファイルは変更しません
--focus=AREA	all	対象を領域に限定します：api、lib、components、hooks、pages
--segments=N	3	並列エージェントの最大数
--max-files=N	20	セグメントあたりの最大ファイル数
--verbose	false	詳細な進捗を表示します

---

重要：変更してはいけないもの

このセクションが最優先です。 ここに記載されたルールに違反すると、簡素化の価値が損なわれます。 ワーカーは変更を加える前に、必ずこのセクションを読む必要があります。

コメントは絶対に削除しない

ワーカーは以下のいずれも絶対に削除してはいけません。

削除禁止	例
セクション区切り	// ===== Types =====、// ===== Helpers =====、// ===== Component =====
JSDoc/TSDoc のドキュメントコメント	/** Computes the current project step... */
ファイルヘッダーコメント	ファイルの目的を説明する、ファイル先頭のブロックコメント
「理由」を説明するコメント	// Only truly block when mutation is actively in flight
ビジネスロジックのコメント	// While any query is loading, trust the server-provided step
エラー処理の根拠	// Check if error is retryable based on status code
TODO/FIXME/NOTE コメント	技術的負債の追跡に使用されます
Biome の無視ディレクティブ	// biome-ignore lint/style/useNamingConvention: reason
再エクスポートの注釈	// Re-export types for convenience、// Production hooks use tRPC
フェーズ／セクションのマーカー	// Phase 14.16、// Step 1: Fetch and validate

次のコードパターンは絶対に削除しない

削除禁止	理由
意図を明示するパターン	if (x) { return x; } return undefined; は、暗黙的な return x; と異なり、意図を示します
名前付きの中間変数	const isMutationPending = mutation.isPending は、インライン化するよりも明確です
エラー処理の構造	異なるエラーの種類を処理する try/catch ブロックをまとめないでください
手動テストの出力	*.integration.ts または manual.*.ts ファイル内の console.log は意図的なものです

ルール

コメントの削除や簡素化によって_意図_が明確でなくなる場合は、変更しないでください。

簡素化とは、_不要な複雑さ_を取り除くことであり、_ドキュメント_を削除することではありません。

---

動作の仕組み

フェーズ 1：コードベースの分析

オーケストレーターがコードベースの構造を分析します。

1. Directory Tree Scan     -> Identify top-level modules
2. File Metrics Collection -> Count files, LOC, complexity per directory
3. Dependency Graph        -> Parse imports to build file->file dependency map
4. Cluster Formation       -> Group tightly-coupled files into processing units

フェーズ 2：セグメントの作成

ファイルは次の基準に基づいてセグメントにグループ化されます。

• 自然な境界：src/app/api/、src/lib/、src/components/
• 依存関係の結びつき：互いにインポートし合うファイルは同じグループにまとめます
• サイズ制限：セグメントあたり 10～25 ファイルを目標とします

フェーズ 3：並列実行

Orchestrator (Main Agent)
  |-- Worker Agent (Segment A)
  |-- Worker Agent (Segment B)
  |-- Worker Agent (Segment C)

フェーズ 4：検証と統合

すべてのセグメントが完了した後、次を実行します。

1. 型チェックを実行します（npm run typecheck）
2. リントを実行します（npm run lint）
3. 単体テストを実行します（npm run test:run）
4. コメントが削除されていないことを確認します（必須）
5. 統合コミットを作成します

ワークフローの手順

ステップ 1：分析の実行

npx tsx scripts/analyze-codebase.ts --verbose

注： 分析スクリプトは .github/worktrees/ ディレクトリを自動的に除外します。

ステップ 2：並列グループの確認

分析結果には、同時に実行できるセグメントが表示されます。

重要な原則： グループは順番に処理されますが、グループ内のセグメントは並列に実行されます。

ステップ 3：簡素化を実行する

各並列グループについて：

1. Task ツールを使用してワーカーエージェントを起動します
2. 各ワーカーには、変更対象のファイルの重複しない一覧を渡します
3. ワーカーは重複なく同時に実行します
4. 次のグループに進む前に、すべてのワーカーの完了を待ちます

ステップ 4：検証してコミットする

すべてのグループが完了したら、完全な検証スイートを実行します：

npm run typecheck
npm run lint
npx vitest run --exclude='.github/worktrees/**'
npm run build

ステップ 5：コメントの保持を確認する（必須）

コミットする前に、コメントが削除されていないことを確認します：

# Check diff for removed comments
git diff HEAD -- '*.ts' '*.tsx' | grep -E '^\-\s*//' | grep -v '^\-\s*//\s*$'

役立つコメントが削除されている場合は、コミットする前に復元してください。

手動検証チェックリスト：

• セクション区切り（// ===...）が変更したファイルに残っている
• 関数の前にある JSDoc/TSDoc ブロックが保持されている
• インラインの「理由」を示すコメントが保持されている
• Biome の無視ディレクティブが保持されている

適用する簡素化パターン

ワーカーは次の変換を適用します：

パターン	変換前	変換後
ネストした三項演算子	a ? b ? c : d : e	ヘルパー関数
デバッグログ	console.log('debug')	削除（本番コードのみ）
繰り返しのパターン	同じコードが3回以上	関数に切り出す
複雑な条件	if (a && b || c && d)	名前付きブール値
長い関数	100行以上	小さな関数に分割

競合の防止

戦略	実装
ファイルの所有権	各セグメントに重複しないファイル一覧を割り当てます
依存関係の順序	基盤モジュールを依存モジュールより先に処理します
逐次グループ	グループは1つずつ実行し、グループ内のセグメントは並列実行します
検証ゲート	グループ間で型チェックを行い、問題を早期に検出します

失敗時の処理

• 失敗したセグメントは、より小さなバッチで最大3回再試行します
• 他のセグメントは処理を続行します
• 必要に応じて、最終レポートに部分的な完了状況を表示します