task-decomposition

タスクの分解

使用するタイミング

次の場合にこのスキルを有効にします：

• 機能や目標の実現に、4つ以上の実装手順が必要な場合
• バックエンド層とフロントエンド層にまたがる複数のファイルを変更する場合
• ユーザーが「細分化して」「分解して」「サブタスクを作成して」「手順を教えて」と言った場合
• コンテキストウィンドウやセッションをまたいで進捗を追跡する必要がある場合
• project-planner の出力（モジュールマップ、リスク、受け入れ基準）を、実行可能な個別タスクに分解する必要がある場合
• 複数のエージェントや開発者に作業を並列化する必要がある場合

想定される入力： project-planner が作成した plan.md（または plan-<feature-name>.md）を読み込みます。このファイルには、モジュールマップ、リスク、受け入れ基準が含まれています。プランファイルがない場合は、概要レベルの目標を直接受け取り、それをもとに作業します。project-planner スキルは、どのモジュールがなぜ影響を受けるのかを示す戦略的なプランを作成します。このスキルは、そのプランを順序付けされた実行可能な個別タスクに変換し、永続的に追跡します。

次の場合はこのスキルを使用しないでください：

• プロジェクトの概要計画や機能のスコープ設定（project-planner を使用）
• アーキテクチャの決定や技術的なトレードオフの検討（system-architecture を使用）
• 実装コードの作成（python-backend-expert または react-frontend-expert を使用）
• テストの作成（pytest-patterns または react-testing-patterns を使用）

手順

分解のルール

このスキルで作成するすべてのタスクは、以下のルールに従う必要があります。

1. 作業範囲を最小限にする： 各タスクで変更するファイルは最大2～3個です。3個を超えるファイルの変更が必要な場合は、さらに分割してください。
2. 成果を1つに絞る： 各タスクには、明確で確認可能な成果を1つだけ設定します。
3. 個別に検証できるようにする： 完了を確認する具体的な検証コマンドを各タスクに含めます（例：pytest tests/unit/test_user.py -x、npm test -- --grep "Component"）。
4. 前提条件を明示する： 先に完了しておく必要がある他のタスクを、タスク ID で記載します。
5. サイズ上限： 変更が200行を超えるタスクは、より小さなタスクに分割します。
6. 依存関係のないタスクを作らない： 各タスクには前提条件がない（ルートタスク）か、プラン内の別のタスクへの依存関係が必要です。

タスクのテンプレート

すべてのタスクで次の形式を使用します。

### Task [N]: [Short descriptive title]
- **Files:** [list of files to create or modify]
- **Preconditions:** [task IDs that must be done first, or "None"]
- **Steps:**
  1. [Specific, unambiguous action]
  2. [Specific, unambiguous action]
- **Done when:** [verification command] → [expected result]
- **Complexity:** [trivial / small / medium / large]

タスクのサイズ基準

サイズ	ファイル数	変更行数	検証	目安の所要時間
ごく小規模	1	<20	簡単な確認	1回の作業
小規模	1-2	20-100	単体テスト	数ステップ
中規模	2-3	100-200	単体テスト＋統合テスト	複数ステップ
大規模	3+	>200	テストスイート全体	さらに分割

タスクのサイズが「大規模」の場合は、必ずより小さなタスクに分解します。

優先順位

タスクを並べる際は、次の優先順位に従います。

1. インフラストラクチャと設定 — 環境設定、設定変更、依存関係のインストール
2. データベースとマイグレーション — スキーマ変更、Alembic マイグレーション（新しいスキーマを使うコードより先に実施）
3. 共有型とインターフェース — レイヤー間で共有する TypeScript 型、Pydantic スキーマ
4. バックエンドサービス — リポジトリ層とサービス層の実装
5. バックエンドルート — API エンドポイントのハンドラー
6. フロントエンドのデータ層 — TanStack Query フック、API クライアント関数
7. フロントエンドコンポーネント — UI コンポーネントとページ
8. テスト — 各レイヤーの単体テスト、その後に統合テスト
9. 統合と E2E — フルスタックの統合検証

タスクファイルの永続化

コンテキストウィンドウをまたいで状態を維持するため、次のファイルを作成します。

task_plan.md

ステータス追跡を含むタスクの完全なリスト：

# Task Plan: [Feature Name]

## Status: IN_PROGRESS
## Total Tasks: [N]
## Completed: [M] / [N]

### Task 1: [Title] ✅ DONE
[task details]

### Task 2: [Title] 🔄 IN PROGRESS
[task details]

### Task 3: [Title] ⏳ PENDING
[task details]

タスクが完了したら、ステータスマーカーを更新します：

• ⏳ PENDING — 未着手
• 🔄 IN PROGRESS — 作業中
• ✅ DONE — 完了し、検証済み
• ❌ BLOCKED — 進行不可（理由を記載）

progress.md

コンテキストウィンドウのリセット後に作業を再開するための現在の状態：

# Progress: [Feature Name]

## Current State
- **Last completed task:** Task [N]: [Title]
- **Current task:** Task [M]: [Title]
- **Next task:** Task [P]: [Title]

## What's Been Done
- [Summary of completed work]

## What's Next
- [Immediate next steps]

## Blockers
- [Any issues preventing progress]

findings.md

作業中に得られたメモ、決定事項、発見事項：

# Findings: [Feature Name]

## Decisions Made
- [Decision 1: context and rationale]

## Discoveries
- [Unexpected finding 1]

## Blockers Encountered
- [Blocker 1: description and resolution]

依存関係グラフ

分解した後、タスクの順序を示すテキストベースの依存関係グラフを作成します。

Task 1 (migration) ──→ Task 2 (schema)
                                ↓
Task 3 (service) ──→ Task 4 (route) ──→ Task 6 (frontend)
                                ↓
                        Task 5 (tests)

循環依存がないことを確認します。見つかった場合は、タスクを再構成して循環を解消します。

分解のワークフロー

あらゆる目標を分解するには、次の手順に従います。

1. 目標を読む — 実施が必要な作業の全範囲を把握します
2. レイヤーを特定する — 影響を受けるバックエンドモジュール、フロントエンドコンポーネント、共有型、テストを特定します
3. ルートタスクを作成する — 前提条件のないタスク（通常はインフラストラクチャ、設定、移行）を作成します
4. 依存するタスクを連鎖させる — レイヤーごとに依存関係グラフを構築します
5. アトミック性を確認する — 各タスクを分解ルールに照らして確認します
6. 規模を確認する — どのタスクも「大規模」のしきい値を超えていないことを確認し、超えている場合は分割します
7. 永続ファイルを書き込む — task_plan.md、progress.md、findings.md を作成します
8. 計画を提示する — 依存関係グラフ付きのタスクリストをユーザーに提示します

例

references/decomposition-examples.md で、以下を含む完全な実例を確認してください。

• ユーザー認証の追加（8 タスク）
• 全文検索の追加（6 タスク）
• S3 ストレージを使ったファイルアップロードの追加（7 タスク）

簡単な例：メール認証を追加する

目標： ユーザー登録にメール認証を追加します。

Task 1: Add email_verified field to User model + migration
Task 2: Create email verification token schema and service
Task 3: Add /verify-email endpoint
Task 4: Modify registration to send verification email
Task 5: Add frontend verification page
Task 6: Write tests for verification flow

依存関係グラフ：

Task 1 ──→ Task 2 ──→ Task 3 ──→ Task 4 ──→ Task 6
                                    ↓
                              Task 5 ──→ Task 6

エッジケース

• 循環依存： タスク A がタスク B を必要とし、タスク B がタスク A を必要とする場合は、共有依存関係を新しいタスク C として切り出し、両方のタスクがそれに依存するように再構成します。

• 単独での検証が難しいタスク： 検証手順として、軽量な統合テストを追加します。自動テストが不可能な場合は、手動での検証手順を記録します。

• コンテキストウィンドウの残りが少ない場合： ウィンドウがリセットされる前に、現在の状態をすぐに progress.md に保存します。最後に完了したタスク、現在のタスクの状態、進行中の変更、および再開時に行う次の手順を含めます。

• 分解中のスコープクリープ： 分解の結果、機能が予想より大規模だと分かった場合は、その旨を明示します。管理できない単一の計画を作成するのではなく、個別のタスク計画を用意した複数のフェーズに分割することを検討します。

• 横断的な懸案事項： タスクが横断的なレイヤー（認証ミドルウェア、ロギング、エラー処理）に影響する場合は、後続のすべてのタスクが依存するルートタスクにします。横断的な変更を複数のタスクに分散させないでください。

• 再開時に一部完了しているタスク： progress.md から再開する場合は、現在のタスクの「完了条件」を確認します。条件を満たしていれば完了としてマークし、次のタスクに進みます。満たしていない場合は、進捗メモに記載された箇所から続行します。