writing-plans

計画の作成

Agent Skills™ の一部です。googleadsagent.ai™

説明

Writing Plans は、あらゆる実装タスクを、各ステップを2～5分で完了できる一連の原子的な手順に分解します。各手順には、正確なファイルパス、完全なコードブロック、検証コマンドが含まれます。計画は自己完結型の実行スクリプトであり、別のエージェントでも、同じエージェントの将来のバージョンでも、元の会話のコンテキストがなくても実行できます。

計画とTODOリストの決定的な違いは、具体性です。計画では「APIハンドラーを更新する」とは書きません。「src/api/routes/users.ts の47行目に、theme、locale、notifications フィールドを持つ UserPreferences オブジェクトを返し、src/api/schemas.ts で定義された preferencesSchema で検証する GET /users/:id/preferences ハンドラーを追加する」と記します。各ステップは、機械的に実行できるほど明確です。

計画には、各実装ステップの後に検証手順が含まれます。実行するテスト、実行する curl コマンド、確認する UI の状態などです。この短いフィードバックループにより、エラーが後続のステップに波及する前に、すぐに検出できます。

使用する場面

• タスクで3つ以上のファイルを変更する場合
• 実装の進め方は分かっているものの、実行が容易ではない場合
• 作業を別のエージェントに引き継ぐ、または後で再開する必要がある場合
• ユーザーから計画、ロードマップ、または段階的な手順を求められた場合
• 実装に着手する前に作業量を見積もる必要がある場合
• 複雑なリファクタリングで、変更の順序を正確に決める必要がある場合

動作の仕組み

graph TD
    A[Task Description] --> B[Identify Affected Files]
    B --> C[Determine Change Order]
    C --> D[Write Step 1: File + Code + Verify]
    D --> E[Write Step 2: File + Code + Verify]
    E --> F[Write Step N: File + Code + Verify]
    F --> G[Add Rollback Instructions]
    G --> H[Estimate Total Duration]
    H --> I[Present Plan for Approval]
    I -->|Approved| J[Save as plan.md]
    I -->|Needs Revision| B

各計画ステップは、変更するファイル、正確なコード変更（変更前後のコンテキストを含む）、ステップの成功を確認する検証コマンドという、厳密な構成に従います。各チェックポイントでコードベースが動作する状態を保てるよう、ステップは順序付けされています。

実装

# Plan: Add User Preferences API

**Estimated Duration**: 15 minutes (5 steps × 3 min avg)
**Affected Files**: 4 files modified, 1 file created

## Step 1: Define Schema (2 min)
**File**: `src/api/schemas.ts`
**Action**: Add after line 23

  export const preferencesSchema = z.object({
    theme: z.enum(["light", "dark", "system"]).default("system"),
    locale: z.string().regex(/^[a-z]{2}-[A-Z]{2}$/).default("en-US"),
    notifications: z.boolean().default(true),
  });
  export type UserPreferences = z.infer<typeof preferencesSchema>;

**Verify**: `npx tsc --noEmit` exits 0

## Step 2: Add Database Migration (3 min)
**File**: `src/db/migrations/004_user_preferences.sql` (CREATE)

  CREATE TABLE user_preferences (
    user_id TEXT PRIMARY KEY REFERENCES users(id),
    theme TEXT NOT NULL DEFAULT 'system',
    locale TEXT NOT NULL DEFAULT 'en-US',
    notifications BOOLEAN NOT NULL DEFAULT true
  );

**Verify**: `npx wrangler d1 migrations apply buddy-brain --local`

## Step 3: Add Route Handler (3 min)
**File**: `src/api/routes/users.ts`
**Action**: Add after the existing GET /users/:id handler

  // ... [complete handler code here]

**Verify**: `curl localhost:8787/users/test-id/preferences` returns 200

ベストプラクティス

• 各ステップの完了後も、コードベースがコンパイル可能かつ実行可能な状態を保つ必要があります
• 各変更のコードをすべて記載してください。「上記と同様」とは書かないでください
• 依存関係を先に解決できるよう、ステップを順序付けしてください（ハンドラーより先にスキーマ、実装より先に型）
• 破壊的な変更（マイグレーション、削除）には、ロールバック手順を追加してください
• 各ステップを2～5分で完了できる範囲に収めてください。それ以上かかるものは分割してください
• 挿入箇所を正確に特定できるよう、行番号または前後のコンテキストを含めてください

プラットフォームの互換性

プラットフォーム	サポート	備考
Cursor	完全対応	計画はワークスペースファイルとして保存されます
VS Code	完全対応	Markdown の計画ファイル
Windsurf	完全対応	計画して実行するワークフロー
Claude Code	完全対応	TodoWrite + 計画ファイル
Cline	完全対応	タスクベースの計画
aider	完全対応	ステップごとのコミットによる実行

関連スキル

• ブレインストーミング - 計画の作成元となる設計概要をまとめる、ソクラテス式の設計改善
• 計画の実行 - 作成した計画を検証とロールバックを通じて実行するバッチ実行エンジン
• サブエージェント主導の開発 - 計画のステップを個別のサブエージェント仕様に変換するタスク分解

キーワード

planning task-decomposition step-by-step implementation-plan file-paths verification-steps atomic-steps handoff-ready

---

© 2026 googleadsagent.ai™ | Agent Skills™ | MIT License