planning-patterns

計画の作成

概要

コードベースについての知識がまったくなく、判断力にも疑問のあるエンジニアを想定して、包括的な実装計画を作成します。各タスクで変更するファイル、コード、テスト、確認が必要なドキュメント、テスト方法など、必要な情報をすべて記載します。計画全体を、細かく実行できるタスクに分解します。DRY。YAGNI。TDD。こまめにコミットします。

計画はプロンプトです。 計画を実行するのは、事前知識がまったくない AI エージェントです。プロンプトを書くつもりで、具体的かつ完全で、あいまいさのない内容にします。別のエージェントが手順を誤解する可能性があるなら、その手順は具体性が不足しています。

熟練した開発者であることを前提としますが、ツールセットや問題領域についての知識はほとんどないものとします。適切なテスト設計についても、あまり詳しくないものと想定してください。

基本原則： 計画は、質問せずに実行できるものでなければなりません。

鉄則

NO VAGUE STEPS - EVERY STEP IS A SPECIFIC ACTION

「検証を追加する」は手順ではありません。「空のメールアドレスのテストを書き、実行し、チェックを実装し、再度実行して、コミットする」なら、これは5つの手順です。

細かいタスクへの分解

各手順は1つのアクション（2～5分）です。

• 「失敗するテストを書く」― 手順
• 「失敗することを確認するために実行する」― 手順
• 「テストが通るように最小限のコードを実装する」― 手順
• 「テストを実行し、通ることを確認する」― 手順
• 「コミットする」― 手順

手順ではないもの：

• 「認証を追加する」（あいまいすぎます）
• 「機能を実装する」（複数のアクションです）
• 「テストする」（どのテストを、どのように実行するのでしょうか？）

計画のフェーズは有向非巡回グラフとして扱います。各フェーズが依存できるのは前のフェーズだけで、後のフェーズには依存できません。plan-review-gate により、この順序が守られます。

分解の基準： 1つの手順で3つ以上のファイルに変更を加える場合、または手順の説明が1文を超える場合は、分割します。1つのフェーズに5つを超えるタスクがある場合は、フェーズの分割を検討します。個々の手順の所要時間は2～5分、タスクのまとまり（RED-GREEN-REFACTOR サイクル全体）は最大15分を目安にします。

計画ドキュメントのヘッダー

すべての計画は、必ず次のヘッダーから始めます。

# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED: Follow this plan task-by-task using TDD.
> **Design:** See `docs/plans/YYYY-MM-DD-<feature>-design.md` for full specification.

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

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

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

**Prerequisites:** [What must exist before starting]

**Durable Decisions:** [Foundational choices that apply across all phases — route structures, DB schema shape, key data models, auth approach, third-party service boundaries. Every phase references these.]

---

設計ドキュメントがある場合は、必ずヘッダーで参照します。

タスクの構成

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.ts`
- Modify: `exact/path/to/existing.ts:123-145`
- Test: `tests/exact/path/to/test.ts`

**Step 1: Write the failing test**

```typescript
test('specific behavior being tested', () => {
  const result = functionName(input);
  expect(result).toBe(expected);
});

ステップ2：テストを実行して失敗することを確認する

実行：npm test tests/path/test.ts -- --grep "specific behavior" 期待される結果：functionName is not defined による FAIL

ステップ3：最小限の実装を書く

function functionName(input: InputType): OutputType {
  return expected;
}

ステップ4：テストを実行して成功することを確認する

実行：npm test tests/path/test.ts -- --grep "specific behavior" 期待される結果：PASS

ステップ5：コミットする

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

## Context is King (Cole Medin Principle)

**The plan must contain ALL information for a single-pass implementation.**

A developer with zero codebase context should be able to execute the plan WITHOUT asking any questions.

### Context References Section (MUST READ!)

**Every plan MUST include a Context References section:**

```markdown
## Relevant Codebase Files

### Patterns to Follow
- `src/components/Button.tsx` (lines 15-45) - Component structure pattern
- `src/services/api.ts` (lines 23-67) - API service pattern

### Configuration Files
- `tsconfig.json` - TypeScript settings
- `.env.example` - Environment variables needed

### Related Documentation
- `docs/architecture.md#authentication` - Auth flow overview
- `README.md#running-tests` - Test commands

理由： Claude はコンテキストを忘れます。外部ドキュメントは古くなります。ファイルと行番号の参照は常に正確です。

蒸留のルール

計画では、要約ではなく蒸留した内容を使わなければなりません。蒸留とは、すべての要素、関係性、決定事項、制約を保ったまま、情報を損なわずに圧縮することです。要約は情報を失う圧縮であり、具体的な内容が抜け落ちます。計画のセクションを短くしても、実装者に必要な事実が失われないなら、蒸留します。短くすることで事実が失われるなら、完全な内容を残します。判断基準：実装エージェントは、ソースファイルを読み直さずにこの計画だけで実行できますか？ できないなら、計画の蒸留が不十分です。

検証レベル

計画の複雑さに合わせて検証の深さを調整します。

レベル	名前	コマンド	適用場面
1	構文とスタイル	npm run lint、tsc --noEmit	すべてのタスク
2	単体テスト	npm test	リスクが低～中程度の場合
3	統合テスト	npm run test:integration	リスクが中～高程度の場合
4	手動検証	ユーザーフローの一連の操作を確認	リスクが高～重大な場合

各タスクの手順には、具体的な検証コマンドを含めます。

本番に近い検証計画

実際の API、シードデータ、ブラウザーフロー、バックグラウンドジョブ、またはストレス／負荷動作が必要なリクエストの場合は、計画を確定する前に references/live-verification-strategy.md を読んでください。

このリファレンスを使用して、以下を明記した ### Live Verification Strategy セクションを追加してください。

• ハーネスマニフェストのパス
• セットアップ、リセット、シード、ヘルスチェック、クリーンアップのコマンド
• ファーストパーティシステムの境界と外部依存関係
• Given／When／Then を使った、名前付きの検証シナリオ
• 負荷動作が重要な場合のストレスプロファイルと合格しきい値

本番に近い検証を、リプレイのみ、単体テストのみ、または手動のみの手順に、黙って格下げしないでください。ライブハーネスがまだ存在しない場合は、その不足を計画内で明示してください。

要件チェックリスト

計画を作成する前に、以下を確認してください。

• 問題の説明が明確である
• ユーザーが特定されている
• 機能要件が列挙されている
• 非機能要件（パフォーマンス、セキュリティ、規模）が列挙されている
• 制約が文書化されている
• 成功基準が定義されている
• 既存のコードパターンを把握している
• file:line 参照を含む Context References セクションを準備している

計画の完全性ゲート

保存する前に、すべてのフェーズが以下の基準を満たしていることを確認してください。

基準	テスト
完了の定義	終了基準が実証可能かつテスト可能である（「基盤の完成」ではない）
測定可能な成果物	各タスクで、作成／変更する正確なファイルを file:line とともに示している
現実的な見積もり	5 分を超えるタスクがなく、1 時間を超えるフェーズがない
依存関係が明確	フェーズ N が参照するのは前のフェーズのみで、後続のフェーズを参照していない
リスク軽減策がある	Score > 8 のすべてのリスクに軽減策の行がある
各フェーズでテスト可能	各フェーズの終了基準をコマンドの実行で検証できる
フェーズ間の契約	フェーズ N の終了基準に、フェーズ N+1 が必要とする正確なデータ形式、API 契約、またはファイル構成が含まれている

いずれかの行が欠けている計画は不完全です。保存する前に修正してください。

終了基準の例：「認証が動作したらフェーズ 1 完了」と書かないでください。「curl -X POST /api/auth/login -d '{"email":"[email protected]","password":"pass"}' が {token: string}` とともに 200 を返したらフェーズ 1 完了」と書いてください。具体的な入出力の例により、解釈の誤りを防げます。

リスク評価表

スコアを付ける前に、各リスクを以下の 4 つの側面のいずれかに分類してください。

側面	評価項目
技術	チームの経験を超える複雑さ、未知のライブラリ、統合に関する不明点
スケジュール	見積もりの不確実性、リソースの確保状況、外部依存関係の納期
品質	テストの不足、回帰の範囲、手動のみの検証手順
セキュリティ	脆弱性への露出、認証の対象範囲、データの機密性、コンプライアンス要件

特定したリスクごとに、以下の表を使用してください。

リスク	発生確率（1-5）	影響（1-5）	スコア	軽減策
API タイムアウト	3	4	12	バックオフを伴う再試行
無効な入力	4	2	8	バリデーション層
認証のバイパス	2	5	10	セキュリティレビュー

スコア = 発生確率 × 影響。スコアが 8 を超えるリスクから優先して対処してください。

リスクベースのテストマトリクス

タスクのリスクに応じてテストの深さを調整してください。

タスクのリスク	例	必要なテスト
ごく軽微	誤字修正、ドキュメント更新	なし
低	単一ファイルの変更、ユーティリティ関数	単体テストのみ
中	複数ファイルにまたがる機能、新しいコンポーネント	単体テスト + 統合テスト
高	サービス間連携、認証、状態管理	単体テスト + 統合テスト + E2E テスト
重大	決済、セキュリティ、データ移行	すべてのテスト + セキュリティ監査

リスクの評価方法：

• 変更するファイル数はいくつですか？（1 = 低、3 以上 = 中、サービス間にまたがる = 高）
• 認証／決済／セキュリティに関わりますか？（常に高または重大）
• ユーザー向けですか？（最低でも中）
• データ損失を引き起こす可能性はありますか？（高または重大）

テスト手順を計画する際は、このマトリクスを使用してください。ごく軽微な変更を過剰にテストせず、重大な変更を過少にテストしないでください。

機能フローのマッピング

計画を立てる前に、すべてのフローを文書化します。

ユーザーフロー：

1. User clicks [button]
2. System shows [form]
3. User enters [data]
4. System validates [input]
5. System saves [data]
6. System shows [confirmation]

管理者フロー：

1. Admin opens [dashboard]
2. Admin selects [item]
3. System shows [details]
4. Admin changes [setting]
5. System applies [change]

システムフロー：

1. Request arrives at [endpoint]
2. Middleware validates [auth]
3. Controller calls [service]
4. Service queries [database]
5. Response returns [data]

アーキテクチャ決定記録（ADR）

複数のアプローチを比較するときは、決定を正式に記録します。

計画で複数の有効なアプローチから選択する場合は、次の形式を使用します。

## ADR: [Decision Title]

**Context:** What situation or requirement prompted this decision?

**Decision:** What approach did we choose?

**Consequences:**
- **Positive:** [benefits of this choice]
- **Negative:** [tradeoffs we accept]
- **Alternatives Considered:** [what we didn't choose and why]

ADR を使用するタイミング：

• アーキテクチャの選択（モノリスとマイクロサービス）
• ライブラリ／フレームワークの選定（React と Vue）
• データベースの決定（SQL と NoSQL）
• 認証方式の選択（JWT とセッション）

ADR の保存先： docs/decisions/ADR-NNN-title.md

危険信号 — 作業を止めて修正してください

次のような状態に気づいたら：

• 正確なファイルパスを示さずに「機能を追加する」と書いている
• テストの手順を省略している
• 複数の操作を 1 つの手順にまとめている
• 明確な手順の代わりに「など」や「同様」と書いている
• 既存のコードパターンを理解せずに計画を立てている
• 5 分以上かかる手順を作成している
• テストコマンドの期待される出力を記載していない

作業を止めて、より具体的な手順で計画を修正してください。

言い訳を防ぐ

言い訳	実態
「言いたいことは伝わるはず」	伝わりません。明確に書いてください。
「詳細すぎると煩わしい」	曖昧な計画はバグの原因になります。
「テストは言うまでもない」	テストコマンドを書いてください。
「ファイルパスは調べればわかる」	正確なパスを書いてください。
「コミットするのは当然」	いつコミットするかを書いてください。
「エッジケースは自分で考えられる」	すべてのエッジケースを列挙してください。
「計画はまだ完璧ではない」	今すぐ実行できる良い計画は、いつまでも実行されない完璧な計画に勝ります。まずリリースして、実行しながら改善してください。

出力形式

# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED: Follow this plan task-by-task using TDD.

**Goal:** [One sentence]

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

**Tech Stack:** [Technologies]

**Prerequisites:** [Requirements]

**Durable Decisions:** [Foundational choices that apply across all phases — route structures, DB schema shape, key data models, auth approach, third-party service boundaries]

---



## Phase 1: [Demonstrable Milestone]

> **Exit Criteria:** [What must be true when this phase is complete - e.g., "User can log in and receive JWT"]

### Task 1: [First Component]

**Files:**
- Create: `src/path/file.ts`
- Test: `tests/path/file.test.ts`

**Step 1:** Write failing test
[code block with test]

**Step 2:** Run test, verify fails
Run: `[command]`
Expected: FAIL

**Step 3:** Implement
[code block with implementation]

**Step 4:** Run test, verify passes
Run: `[command]`
Expected: PASS

**Step 5:** Commit
```bash
git add [files]
git commit -m "feat: [description]"

タスク 2：[2 つ目のコンポーネント]

...

---

リスク

リスク	P	I	スコア	軽減策
...	...	...	...	...

---

成功基準

• すべてのテストに合格する
• 仕様どおりに機能する
• リグレッションがない
• コードレビューが完了している

## Save the Plan (MANDATORY)

**One direct save is required - the plan file. Memory indexing is router-owned.**

### Step 1: Save Plan File (Use Write tool - NO PERMISSION NEEDED)

最初にディレクトリを作成する

Bash(command="mkdir -p docs/plans")

次に Write ツールで計画を保存する（権限不要）

Write(file_path="docs/plans/YYYY-MM-DD--plan.md", content="[上記の出力形式に従った計画の全文]")

自動コミットしない — コミットするタイミングはユーザーに任せる

### Step 2: Emit Router-Owned Memory Intent (CRITICAL)

Do **NOT** edit `.cc10x/v10/*.md` from this skill.

Instead, use the planner agent's existing `MEMORY_NOTES` contract only for durable learnings, deferred items, or verification context that is not already derivable from the planner contract.

**WHY BOTH:** The plan file is the artifact. Router-owned memory finalization derives plan indexing from `PLAN_FILE` and workflow state, so this skill must not invent a second memory serialization path.

## Router-Owned Task Tracking

The planner does **not** create execution tasks. Its job is to create the plan artifact and emit a router contract.

After planning:
- Save the plan file.
- Update memory with the plan reference.
- Let the router create workflow and execution tasks from the approved plan.

Do not instruct the planner to call `TaskCreate` or `TaskUpdate` for phase tracking.

## Plan-Task Linkage (Context Preservation)

**The relationship between Plan Files and Tasks:**

┌─────────────────────────────────────────────────────────────────────┐ │ 計画ファイル（永続的 — 信頼できる唯一の情報源） │ │ 場所：docs/plans/YYYY-MM-DD-{feature}-plan.md │ │ 内容：実装の詳細、TDD の手順、ファイルパス │ │ 保持：セッション終了後、コンテキスト圧縮後、会話のリセット後も保持 │ └─────────────────────────────────────────────────────────────────────┘ ↕ タスクの説明には計画ファイルのパスを含める ┌─────────────────────────────────────────────────────────────────────┐ │ タスク（実行エンジン） │ │ 内容：ステータス、依存関係、進捗の追跡 │ │ 保持：コンテキスト圧縮後も保持。タスクリスト設定を使ってセッション間で共有可能 │ │ （公式の Claude Code） │ └─────────────────────────────────────────────────────────────────────┘

**Plan path-in-description is CRITICAL:** If context compacts mid-execution, the task description contains enough info to:
1. Find the plan file
2. Locate the exact phase/task
3. Continue without asking questions

**Phase Exit Criteria are CRITICAL:** Each phase MUST have a demonstrable milestone (not arbitrary naming):
- ❌ "Phase 1: Foundation" - Vague, when is it done?
- ✅ "Phase 1: User can authenticate" - Demonstrable, testable

## Execution Handoff

After saving the plan, offer execution choice:

**"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:**

**1. Subagent-Driven (this session)** - Fresh subagent per task, review between tasks, fast iteration

**2. Manual Execution** - Follow plan step by step, verify each step

**Which approach?"**