plan-crafting

計画の作成

明確に定義された作業範囲から、実行可能な計画書を作成します。タスクを「worker-validator」のペアとして並行して割り当てられるよう設計されています。

基本原則

計画書は、コードベースに関する知識がまったくない作業者が、追加の質問をせずに実行できるものでなければなりません。あいまいさはすべて計画段階で解消する必要があります。

必須条件

1. すべての手順を実行可能にする必要があります。 プレースホルダー（TBD、TODO、「後で実装」）は一切認められません。
2. タスク間の競合を防ぐ必要があります。 同じファイルを変更するタスクを並行して実行してはいけません。依存関係のあるタスクは、前提となるタスクの完了を待つ必要があります。
3. セルフレビューは必須です。 計画書の作成後、自分で完全性を検証してください。
4. タスクは最小限の機能単位に分割します。 1つのタスクから、明確な成果物を1つ作成します。

使用する場合

• clarification スキルの完了後、Context Brief ファイルが生成されている場合
• ユーザーが明確なプロンプトで計画の作成を明示的に依頼した場合
• 複数の手順による実装が必要で、依存関係を考慮してタスクの順序を定義する必要がある場合

入力

このスキルでは、入力として Context Brief ファイルを使用します。clarification スキルで生成された Context Brief を使って、計画書のヘッダーを作成します。

Context Brief の項目	計画書ヘッダーへの対応
Goal	目標
Scope (In/Out)	作業範囲（含む／除外）
Technical Context	アーキテクチャ＋技術スタック＋ファイル構成の対応付けの根拠
Constraints	タスク分割時の制約として反映
Success Criteria	セルフレビューの基準として使用
Open Questions	計画書の前提として反映し、その後ユーザーに確認

Context Brief ファイルがない場合（ユーザーが直接計画を依頼した場合）は、計画書を作成する前に、目標、作業範囲、技術スタックなどの必須情報をユーザーに確認してください。

使用しない場合

• 作業範囲がまだあいまいな場合（clarification スキルに戻ります）
• 単一ファイルの編集、単純なバグ修正、その他の単一手順のタスク
• ユーザーが「計画は省略して、すぐに実行してください」と明示した場合

計画書の構成

保存場所

docs/engineering-discipline/plans/YYYY-MM-DD-<feature-name>.md

（計画の保存場所に関するユーザーの希望は、この既定値より優先されます。）

ヘッダー

# [Feature Name] Implementation Plan

> **Worker note:** Execute this plan task-by-task using the run-plan skill or subagents. Each step uses checkbox (`- [ ]`) syntax for progress tracking.

**Goal:** [One sentence describing what this plan builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

**Work Scope:**
- **In scope:** [What will be implemented]
- **Out of scope:** [What is explicitly excluded]

---

ファイル構成の対応付け

タスクを定義する前に、作成または変更するファイルを洗い出します。分割方針はこの段階で確定します。

• 各ファイルには、明確な責務を1つ持たせます。
• 一緒に変更されるファイルは、同じ場所に配置します。技術レイヤーではなく、責務ごとに分割します。
• 既存のコードベースのパターンに従います。コードベースに大きなファイルが使われている場合、独断で再構成してはいけません。ただし、変更対象のファイルが扱いにくいほど大きくなっている場合は、計画に分割を含めても構いません。
• ファイル構成をもとにタスクを分割します。各タスクは、それ単独で意味を成す、自己完結した変更を成果物とします。

検証方法の確認

タスクを分解する前に、プロジェクトで利用できる最も包括的な検証方法を確認します。これにより、すべての計画を締めくくる最終検証タスクが決まります。

確認順序（最初に該当したものを使用）：

1. 既存の E2E テスト — e2e/、tests/e2e/、cypress/、playwright/、package.json 内の test:e2e、Makefile/Taskfile 内の e2e ターゲットを検索します
2. 統合テスト — tests/integration/、integration_test、test:integration スクリプトを検索します
3. 検証スキルまたはエージェント — .claude/skills/、.claude/agents/、インストール済みプラグインを確認し、verify、validate、e2e、test という名前のものを探します
4. プロジェクトのテストスイート — 幅広いカバレッジを持つテストランナー（pytest、jest、go test、cargo test など）を探します
5. ビルド + リント — テストが存在しない場合は、ビルドの成功とリントのパスが、利用可能な最も包括的な検証方法になります

意味のある検証方法が存在しない場合（レベル 5 のみ）： この計画に必要な最小限の検証環境を整備するタスク 0：検証基盤の作成を追加します。

• プロジェクトの技術スタックと適切なテストフレームワークを特定します
• 計画の主要な成功基準をテストする E2E テストまたは統合テストを作成します
• このテストは実装前に失敗し、すべてのタスクの完了後に成功する必要があります

確認結果を計画ヘッダーに記録します：

**Verification Strategy:**
- **Level:** [e2e | integration | skill/agent | test-suite | build-only]
- **Command:** [exact command to run the verification]
- **What it validates:** [what passing this verification proves]

プロジェクト機能の確認

タスクを分解する前に、作業者が活用できるプロジェクトレベルのエージェントとスキルも確認します。

1. プロジェクトエージェント — .claude/agents/ を確認し、タスクの領域に関連するエージェント（例：test-runner エージェント、db-migration エージェント）を探します
2. プラグインエージェント — インストール済みプラグインを確認し、専門エージェント（例：build-validator、lint-fixer）を探します
3. プロジェクトスキル — .claude/skills/ を確認し、タスクの操作に合うスキルを探します

役立つエージェントやスキルが見つかった場合は、該当するタスクの手順で参照します。

- [ ] **Step N: Run migration**

Use the project's `db-migration` agent for this step if available.
Run: `<migration command>`

作業者は、見つかったエージェントを使用する必要はありません。効率化のためのヒントとして扱います。エージェントが利用できない場合や適切でない場合、作業者は手順を直接実行できます。

タスクの分解

タスクを分解するときは、次の点を考慮します。

1. 並列処理と依存関係

タスクは、できる限り並列に実行できるよう設計します。ただし、次の場合は先行タスクの完了を待つ必要があります。

• 同じファイルを変更するタスク（ファイルの競合を防ぐため）
• あるタスクの出力を別のタスクが参照する場合（インターフェースの依存関係）
• 共有状態（データベーススキーマ、設定ファイルなど）を変更するタスク

依存関係はタスクヘッダーに記載します。

### Task N: [Task Name]

**Dependencies:** Runs after Task K completes
**Files:**
- Create: `path/to/file`
- Modify: `path/to/existing-file` (anchor: `functionName`)
- Test: `path/to/test-file`

依存関係のないタスクには、並列実行可能と記載します。

### Task N: [Task Name]

**Dependencies:** None (can run in parallel)
**Files:**
- Create: `path/to/file`
- Test: `path/to/test-file`

2. 作業者と検証者の構成

各タスクは、独立した作業者（サブエージェント）が実行し、別の検証者が確認できるように設計します。

• 作業者： タスクの手順を実行します。タスクの目標と受け入れ基準が拘束力のある契約であり、手順は想定される実施方法です。コードベースが手順と矛盾する場合、作業者は受け入れ基準を満たすために最小限の調整を行います（run-plan の適応ルールを参照）。
• 検証者： コードベースを基準として、タスクの受け入れ基準を各基準ごとに合否判定します。それ以外は行いません。回帰チェックと計画全体の成功基準は、後続の検証レイヤーで扱います。

この構成により、個別に検証できる複数のタスクを同時に開始できます。ただし、基準が解釈なしで判定できるように記述されている必要があります。詳しくは、以下の受け入れ基準ルールを参照してください。

3. タスクの粒度

各手順は 1 つのアクションとし、所要時間は 2～5 分とします。

• 「失敗するテストを書く」— 1 つの手順
• 「失敗することを確認するために実行する」— 1 つの手順
• 「テストに合格するための最小限のコードを書く」— 1 つの手順
• 「テストを実行し、合格することを確認する」— 1 つの手順
• 「コミットする」— 1 つの手順

タスク形式

### Task N: [Component Name]

**Goal:** [One sentence stating what this task accomplishes — written to be copied verbatim into the validator prompt]
**Dependencies:** [Predecessor task or "None (can run in parallel)"]
**Files:**
- Create: `exact/path/to/file`
- Modify: `exact/path/to/existing-file` (anchor: `functionOrSectionName`)
- Test: `tests/exact/path/to/test-file`

**Acceptance Criteria:**
- [ ] [binary-decidable condition, e.g., "`pytest tests/path/test.py::test_name` passes"]
- [ ] [binary-decidable condition, e.g., "`function(input)` returns `expected` for the null-brand case"]

- [ ] **Step 1: Write the failing test**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

- [ ] **Step 2: Run test to verify it fails**

Run: `pytest tests/path/test.py::test_name -v`
Expected: FAIL with "function not defined"

- [ ] **Step 3: Write minimal implementation**

```python
def function(input):
    return expected
```

- [ ] **Step 4: Run test to verify it passes**

Run: `pytest tests/path/test.py::test_name -v`
Expected: PASS

- [ ] **Step 5: Commit**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```

ファイル参照には行番号ではなく、シンボルアンカーを使用してください。 行範囲（file.ts:123-145）は、先行するタスクがファイルを編集した時点で古くなります。編集後も維持されるもの、つまり関数名、クラス名、設定キー、セクション見出しをアンカーにしてください。

受け入れ条件のルール

受け入れ条件はタスクの契約です。作業者は状況に応じて手順を調整しますが、条件は譲れません。バリデーターはほかの点を評価しません。

1. すべてのタスクに、少なくとも1つの条件を設定してください。 完了を条件として表現できないものはタスクではなく、願望です。
2. すべての条件は、二値で判定できなければなりません。 独立したバリデーターがコードを読み、記載されたコマンドを実行すれば、判断を迷うことなく「満たしている／満たしていない」と回答できる必要があります。条件に解釈が必要なら、それは計画の失敗です。書き直してください。
   • 計画の失敗：「コードがきれいであること」「エラーを適切に処理すること」「正しく動作すること」「十分に高速であること」
   • 二値で判定可能：「pytest tests/api/test_users.py が成功する」「メールアドレスを指定せずに POST /api/users を実行すると 400 が返る」「grep -r 'legacyParser' src/ で一致が見つからない」
3. タスク全体の判定は、各条件の論理積です。 部分点や「ほぼ完了」はありません。未達の条件が1つでもあれば、タスクは未完了です。
4. 条件には実装方法ではなく、結果を記載してください。 「内部で HashMap を使用する」は条件ではありません。「合格するテストで検索結果が返る」が条件です。条件は、作業者が手順と異なる方法を選んでも適用できる必要があります。

最終検証タスク

すべての計画には、検出された最上位の検証を実行する最終検証タスクを設けてください。これは必ず最後のタスクとし、ほかのすべてのタスクに依存し、並列化できません。

### Task N (Final): End-to-End Verification

**Dependencies:** All preceding tasks
**Files:** None (read-only verification)

- [ ] **Step 1: Run highest-level verification**

Run: `[verification command from Verification Strategy]`
Expected: ALL PASS

- [ ] **Step 2: Verify plan success criteria**

Manually check each success criterion from the plan header:
- [ ] [criterion 1]
- [ ] [criterion 2]
- ...

- [ ] **Step 3: Run full test suite for regressions**

Run: `[full test suite command]`
Expected: No regressions — all pre-existing tests still pass

最終検証に失敗した場合、計画は未完了です。run-plan のワーカーとバリデーターのループで、失敗時の応答（run-plan の E2E Failure Response Protocol を参照）が処理されます。

プレースホルダーを使わない

すべての手順に、作業者が必要とする具体的な内容を記載してください。次のようなものは計画の失敗にあたるため、決して記載しないでください。

• 「TBD」「TODO」「後で実装する」「詳細を記入する」
• 「適切なエラー処理を追加する」「バリデーションを追加する」「エッジケースに対応する」
• 「上記のテストを書く」（実際のテストコードを示さない場合）
• 「タスク N と同様」（コードを再掲してください。作業者がタスクを順不同で読んでいる可能性があります）
• 方法を示さずに実施内容だけを説明する手順（コードの手順にはコードブロックが必要です）
• どのタスクにも定義されていない型、関数、メソッドへの参照
• 二値で判定できない受け入れ条件（「正しく動作する」「クリーンなコード」）

覚えておくこと

• ファイルパスは必ず正確に記載する
• すべての手順に完全なコードを記載する。コードを変更する手順では、変更後のコードを示す
• 期待される出力を含め、コマンドを正確に記載する
• DRY、YAGNI、TDD、頻繁なコミット

セルフレビュー

計画をすべて書き終えたら、仕様を新たな視点で見直し、計画と照らし合わせて確認します。これは自分で実施するチェックリストであり、サブエージェントへの依頼ではありません。

1. 仕様の網羅性： 仕様の各セクション／要件をざっと確認します。それぞれを実装するタスクを示せますか？不足があれば列挙してください。

2. プレースホルダーの確認： 計画内を検索し、前述の「プレースホルダーなし」セクションにあるパターンなど、問題の兆候がないか確認します。見つかった場合は修正してください。

3. 型の一貫性： 後続のタスクで使用している型、メソッドシグネチャ、プロパティ名は、先行タスクで定義したものと一致していますか？タスク 3 で clearLayers()、タスク 7 で clearFullLayers() と呼ばれている関数があると、バグになります。

4. 依存関係の検証： 並列タスクが同じファイルを変更しないことを確認します。依存関係の連鎖に抜けがないことも確認します。

5. 検証範囲： 計画に最終検証タスクがありますか？特定した検証コマンドを参照していますか？検証方法が見つからなかった場合、検証インフラを作成するタスク 0 はありますか？

6. 基準の判定可能性： すべてのタスクに目標と受け入れ基準がありますか？敵対的な検証者の視点で、各基準を読んでください。コードを読み、コマンドを実行するだけで、達成／未達成を判定できますか？解釈が必要な基準は書き直してください。

問題が見つかった場合は、その場で修正します。再確認は不要です。修正して先に進んでください。仕様要件に対応するタスクがない場合は、タスクを追加してください。

実行への引き継ぎ

計画を保存したら、実行方法を選べるようにします。

「計画が完成し、docs/engineering-discipline/plans/<filename>.md に保存されました。」

「どのように進めますか？」

1. サブエージェントによる実行（推奨） — タスクごとに新しいサブエージェントを割り当て、タスク間でレビューを行い、すばやく反復します。

2. インライン実行 — このセッションで run-plan スキルを使用し、チェックポイントを設けてタスクをまとめて実行します。

アンチパターン

アンチパターン	問題点
同じファイルを変更するタスクを並列実行としてマークする	ファイルの競合が発生し、変更をマージできなくなります
依存関係を示さずにタスクを列挙する	実行順序が混乱し、インターフェースに不整合が生じます
「作業者が判断して進める」ことを前提とするステップ	作業者の独自解釈により、仕様から逸脱する可能性があります
プレースホルダーが残った計画を承認する	実行段階で作業が止まり、計画に戻る必要が生じます
セルフレビューを行わずに計画を完成させる	仕様の網羅性不足、型の不一致、依存関係の誤りが見逃されます

最小チェックリスト

計画を書き終えたら、次の項目をセルフチェックします。

• すべてのタスクに正確なファイルパスがありますか？
• すべてのタスクに目標と、二択で判定できる受け入れ基準がありますか？
• すべてのステップに実行可能なコード／コマンドが含まれていますか？
• 並列実行するタスク間にファイルの競合はありませんか？
• 依存関係の連鎖は正確に記載されていますか？
• 計画は仕様のすべての要件を網羅していますか？
• プレースホルダーは残っていませんか？
• 計画のヘッダーに検証戦略がありますか？
• 最終検証タスクは計画の最後にありますか？

移行

計画の承認後：

• 計画を実行する準備ができた場合 → run-plan スキル
• 作業範囲に曖昧さが見つかった場合 → 問題を解消するため clarification スキルに戻る

このスキル自体が次のスキルを呼び出すことはありません。計画書を提示し、次のステップをユーザーに選んでもらって終了します。