planning-with-files

ファイルを使った計画 — Manus 風のファイルベースの計画

Manus（Meta が買収した評価額 20 億ドルの AI エージェント）のように作業しましょう。「ディスク上の作業メモリ」として、永続的な Markdown ファイルを使います。

基本原則

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)

→ Anything important gets written to disk.

3 ファイルパターン

複雑なタスクでは、プロジェクトディレクトリに 3 つのファイルを作成します。

task_plan.md      → Track phases and progress
findings.md       → Store research and findings
progress.md       → Session log and test results

テンプレートの場所： .claude/templates/planning/

このパターンを使う場面

使う場面：

• 複数の手順があるタスク（3 手順以上）
• 調査タスク
• プロジェクトの構築・作成
• 多数のツール呼び出しにまたがるタスク
• 整理が必要なあらゆるタスク

使わない場面：

• 簡単な質問
• 単一ファイルの編集
• 簡単な検索

重要なタイミングルール

これらのルールは、適切なワークフローを確実にするためにフックを模倣します。

📌 タスク開始時（SessionStart）

ほかの作業に着手する前に、まず 3 つのファイルをすべて作成する必要があります。

1. テンプレートを使って task_plan.md を作成します
2. テンプレートを使って findings.md を作成します
3. テンプレートを使って progress.md を作成します
4. task_plan.md の Goal セクションに記入します

理由： 計画ファイルがないと、ツールを 50 回以上呼び出した後に目標を忘れてしまいます。

📌 重要な決定の前（PreToolUse）

次の作業を行う前に、task_plan.md を必ず読み直します。

• ファイルの作成または編集
• コマンドの実行
• アーキテクチャ上の決定
• 機能の実装

方法： Read ツールを使って、計画をコンテキストに読み込み直します。

理由： これにより、目標が注意の範囲内に保たれます（Manus の「注意の操作」）。

📌 ファイル操作の後（PostToolUse）

次の作業の直後に、ステータスを必ず更新します。

• ファイルの作成
• ファイルの編集
• タスクフェーズの完了

方法： task_plan.md を編集して、フェーズのステータスを更新します。

- **Status:** pending → in_progress → complete

理由： 進捗を記録し、完了した作業を見失わないようにします。

📌 タスク終了前（Stop）

完了を必ず確認します。

• すべてのフェーズが complete になっているか確認します
• 成果物のセクションを確認します
• 未解決のエラーが残っていないことを確認します

理由： 作業が不足したまま早々に完了してしまうのを防ぎます。

6 つの重要なルール

1. まず計画を作成する

複雑なタスクは、task_plan.md なしで始めてはいけません。これは必須です。

## Goal

[One sentence describing the end state]

## Current Phase

Phase 1

## Phases

### Phase 1: Requirements & Discovery

- [ ] Understand user intent
- [ ] Identify constraints
- **Status:** in_progress

2. 2 アクションルール

「表示／ブラウザー／検索の操作を 2 回行うごとに、重要な調査結果を直ちに findings.md に保存します。」

これにより、視覚情報やマルチモーダル情報が失われるのを防ぎます。

## Visual/Browser Findings

- Screenshot shows login form with email and password fields
- API documentation indicates JSON response format

3. 決定する前に読む

重要な決定を下す前に、計画ファイルを読みます。これにより、目標を注意の範囲内に保てます。

# Before implementing a feature:
Read tool → task_plan.md
# Now proceed with implementation

4. 行動の後に更新する

フェーズを完了した後は、次の作業を行います。

• フェーズのステータスを更新します：pending → in_progress → complete
• 発生したエラーを記録します
• 作成・変更したファイルを記録します

## Errors Encountered

| Error             | Attempt | Resolution             |
| ----------------- | ------- | ---------------------- |
| FileNotFoundError | 1       | Created default config |

5. すべてのエラーを記録する

すべてのエラーを計画ファイルに記録します。これにより知見が蓄積され、同じ失敗を繰り返さずに済みます。

6. 失敗を繰り返さない

if action_failed:
    next_action != same_action

試したことを記録し、アプローチを変えましょう。

3 ストライクエラープロトコル

ATTEMPT 1: Diagnose & Fix
  → Read error carefully
  → Identify root cause
  → Apply targeted fix

ATTEMPT 2: Alternative Approach
  → Same error? Try different method
  → Different tool? Different library?
  → NEVER repeat exact same failing action

ATTEMPT 3: Broader Rethink
  → Question assumptions
  → Search for solutions
  → Consider updating the plan

AFTER 3 FAILURES: Escalate to User
  → Explain what you tried
  → Share the specific error
  → Ask for guidance

ファイルの用途

ファイル	用途	更新するタイミング
task_plan.md	フェーズ、進捗、決定事項	各フェーズの後
findings.md	調査、発見事項	発見があったら必ず
progress.md	セッションログ、テスト結果	セッション中を通じて

読み取り／書き込み判断マトリックス

状況	対応	理由
ファイルを書いた直後	読み取らない	内容はまだコンテキスト内にある
画像／PDFを表示した	調査結果をすぐに書き込む	マルチモーダル情報を失う前にテキスト化する
ブラウザーからデータが返された	ファイルに書き込む	スクリーンショットは保持されない
新しいフェーズを開始する	計画／調査結果を読む	コンテキストが古い場合に状況を再確認する
エラーが発生した	関連ファイルを読む	修正には現在の状態を把握する必要がある
中断後に作業を再開する	計画ファイルをすべて読む	状態を復元する

5つの質問による再起動テスト

次の質問に答えられれば、コンテキスト管理は万全です。

質問	回答の参照先
今どこにいますか？	task_plan.md の現在のフェーズ
どこに向かっていますか？	残りのフェーズ
目標は何ですか？	計画内の目標ステートメント
何を学びましたか？	findings.md
何をしましたか？	progress.md

テンプレートの構成

task_plan.md テンプレート

# Task Plan: [Brief Description]

## Goal

[One sentence describing the end state]

## Current Phase

Phase 1

## Phases

### Phase 1: Requirements & Discovery

- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress

### Phase 2: Planning & Structure

- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending

### Phase 3: Implementation

- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending

### Phase 4: Testing & Verification

- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending

### Phase 5: Delivery

- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending

## Key Questions

1. [Question to answer]
2. [Question to answer]

## Decisions Made

| Decision | Rationale |
| -------- | --------- |
|          |           |

## Errors Encountered

| Error | Attempt | Resolution |
| ----- | ------- | ---------- |
|       | 1       |            |

findings.md テンプレート

# Findings & Decisions

## Requirements

_Add requirements captured from user request here._

## Research Findings

_Document key discoveries during exploration here._

## Technical Decisions

_Record decisions made with rationale._

| Decision | Rationale |
| -------- | --------- |
|          |           |

## Issues Encountered

_Document errors and how they were resolved._

| Issue | Resolution |
| ----- | ---------- |
|       |            |

## Resources

_Add URLs, file paths, and API references here._

## Visual/Browser Findings

_CRITICAL: Update after every 2 view/browser operations._

progress.md テンプレート

# Progress Log

## Session: [DATE]

### Phase 1: [Title]

- **Status:** in_progress
- **Started:** [timestamp]
- Actions taken:
- Files created/modified:

## Test Results

| Test | Input | Expected | Actual | Status |
| ---- | ----- | -------- | ------ | ------ |
|      |       |          |        |        |

## Error Log

| Timestamp | Error | Attempt | Resolution |
| --------- | ----- | ------- | ---------- |
|           |       | 1       |            |

## 5-Question Reboot Check

| Question             | Answer           |
| -------------------- | ---------------- |
| Where am I?          | Phase X          |
| Where am I going?    | Remaining phases |
| What's the goal?     | [goal statement] |
| What have I learned? | See findings.md  |
| What have I done?    | See above        |

鉄の掟

1. 必ず、複雑なタスクを始める前に task_plan.md、findings.md、progress.md を作成してください。ファイルシステム上の記憶はコンテキストのリセット後も残りますが、作業記憶は残りません。
2. 必ず、重要な決定を下す前に task_plan.md を読み直してください。コンテキストウィンドウは不安定ですが、ファイルはいつまでも残ります。
3. 決して、失敗した操作を同じ入力で再試行しないでください。失敗を計画ファイルに記録し、根本原因を診断して、アプローチを変更してください。
4. 必ず、マルチモーダルな調査結果（スクリーンショット、ブラウザデータ）は取得後すぐに findings.md に書き込んでください。視覚的なコンテキストは、アテンションウィンドウから外れると再取得できません。
5. すべてのフェーズが complete であり、すべての成果物が進捗ファイルに記載されていることを確認せずに、タスクを完了としてマークしてはいけません。

アンチパターン

アンチパターン	失敗する理由	正しいアプローチ
セッション内のタスクツールを永続化に使う	メモリ内のタスク追跡は不安定で、コンテキストのリセットで失われる	ディスク上に task_plan.md ファイルを作成する。リセット後も残る
目標を一度述べたきり忘れてしまう	コンテキストが埋まり、目標の軸がぶれてしまう	重要な決定の前に計画ファイルを読み直す
エラーを隠して黙って再試行する	黙って再試行すると、同じ失敗を延々と繰り返す	試行回数とともにすべてのエラーを計画ファイルに記録する
調査内容をすべてコンテキストに詰め込む	コンテキストウィンドウが埋まり、以前の内容が失われる	大量の内容や発見事項を findings.md に保存する
計画なしで実行を始める	範囲が定まらず、無駄な作業や手順の見落としにつながる	どんな作業よりも先に、まず3つの計画ファイルをすべて作成する

Manus の原則

原則	実践方法
ファイルシステムを記憶として使う	コンテキストではなく、ファイルに保存する
アテンションを調整する	決定の前に計画を読み直す
エラーを記録する	失敗を計画ファイルに記録する
目標を追跡する	チェックボックスで進捗を示す
完了を検証する	終了前にすべてのフェーズを確認する

---

覚えておいてください： 最初に集めたコンテキストを多くディスクに書き込むほど、実行の質が高まります。ファイルは永続的な記憶です。