writing-plans

計画の作成

熟練したエンジニアが、事前知識がほとんどなくても安全に作業できる実装計画を作成します。計画では、個別に検証可能な各タスクに必要な正確なファイル、インターフェース、動作、テスト、ドキュメント、コマンドを指定します。 計画はチャット内だけのチェックリストではなく、リポジトリに残す成果物です。各タスクの最後には、コンパイル、差分レビュー、Conventional Commit のゲートも設けます。

担当者は熟練した開発者であるものの、私たちのツールセットや問題領域についてはほとんど知らないものとします。また、適切なテスト設計についても、あまり詳しくないものとします。

開始時に宣言する内容： "I'm using the writing-plans skill to create the implementation plan."

コンテキスト： 隔離されたワークツリーで作業する場合は、実行時にリポジトリのワークツリーのワークフローを使用してください。計画がチャット履歴に依存しないようにしてください。

計画の保存先： .agents/plans/YYYY-MM-DD-<feature-name>.md

すべての計画は、YAML フロントマターを含む Markdown 形式にします。フロントマターは、セッションをまたいだ追跡に使う機械可読なインデックスです。

---
id: YYYY-MM-DD-<feature-name>
name: <Feature Name> implementation plan
kind: plan
category: implementation
status: pending
description: <one-sentence purpose>
---

次のステータスを使用してください。

ステータス	意味	遷移
draft	計画の作成中、または自己レビュー中	→ pending、blocked
pending	計画が完成し、実装の準備ができている	→ running、superseded
running	実装を開始した	→ blocked、done、superseded
blocked	文書化が必要な決定事項、または不足している入力があり、作業を進められない	→ pending、running、superseded
done	実装と検証が完了した	終端
superseded	新しい計画に置き換えられた。置き換え先へのリンクを記載する	終端

draft として開始し、自己レビュー後にのみ pending に変更し、実装開始時に running に変更してください。検証完了後にのみ done に変更してください。具体的な決定事項や入力が不足している場合は blocked を使用し、新しい計画に置き換えられた場合は superseded を使用してください。同じ計画ファイルを更新し、ステータス用のファイルを別に作成しないでください。

計画を追跡するには、次を使用します。

find .agents/plans -maxdepth 1 -type f -name '*.md' -print | sort
rg -n '^status:' .agents/plans
rg -l '^status: (pending|running|blocked)$' .agents/plans

作業をワーカー、セッション、またはコンテキストの境界を越えて継続する必要がある場合は、delegation-mode を使用してください。実装後に完全な品質レビューが必要な場合は、code-review-axes-and-quality を使用してください。これらは別々の段階として扱います。計画では契約を定め、実装ではその契約を満たしたことを示し、レビューでは結果を確認します。

スコープの確認

仕様が互いに独立した複数のサブシステムを対象としている場合は、別々の計画に分割してください。各計画は、それだけで動作し、テスト可能な段階的成果を生み出す必要があります。実装計画に無関係なクリーンアップを紛れ込ませないでください。

ファイル構成

タスクを定義する前に、作成または変更するファイルと、それぞれの役割を整理してください。ここで分割方針を確定します。

• 明確な境界と適切に定義されたインターフェースを備えた設計単位にしてください。各ファイルには、明確な責務を一つだけ持たせてください。
• コンテキスト内で扱えるコードについては、より的確に推論できます。また、ファイルの責務が明確であるほど、編集の信頼性も高まります。大きなファイルに多くの役割を持たせるのではなく、小さく、焦点を絞ったファイルを優先してください。
• 一緒に変更するファイルは、近くに配置してください。技術レイヤーではなく、責務ごとに分割してください。
• 既存のコードベースでは、確立されたパターンに従ってください。コードベースで大きなファイルが使われている場合は、一方的に再構成しないでください。ただし、変更対象のファイルが扱いにくいほど大きくなっている場合は、分割を計画に含めてもかまいません。

この構成をもとにタスクを分解します。各タスクは、それ単体で意味のある変更を生み出す必要があります。

タスクの適切な粒度

タスクとは、独自のテストサイクルを持ち、新しいレビュアーによるゲートを設ける価値のある最小単位です。タスクの境界を決める際は、セットアップ、設定、足場作り、ドキュメント作成の各ステップを、その成果物を必要とするタスクに含めてください。隣接するタスクの一方を承認し、もう一方を却下することに、レビュアーが実質的な意味を見いだせる場合にのみ分割してください。各タスクの最後には、独立してテスト可能な成果物が必要です。

一口サイズのタスク粒度

各ステップは1つのアクションで、通常2～5分です：

• 「失敗するテストを書く」— ステップ
• 「失敗することを確認するために実行する」— ステップ
• 「テストを通すために必要最小限のコードを実装する」— ステップ
• 「テストを実行し、成功することを確認する」— ステップ
• 「影響を受けるプロジェクトまたはパッケージをコンパイルする」— ステップ
• 「差分全体を確認し、git diff --check を実行する」— ステップ
• 「検証済みの変更を、規約に沿ったメッセージでコミットする」— ステップ

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

すべての計画は、このフロントマターとヘッダーで必ず始めてください：

---
id: YYYY-MM-DD-<feature-name>
name: [Feature Name] implementation plan
kind: plan
category: implementation
status: draft
description: [One-sentence purpose]
---

# [Feature Name] Implementation Plan

> **For agentic workers:** Use `delegation-mode` for resumable or multi-worker execution. Steps use checkbox (`- [ ]`) syntax for tracking.

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

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

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

**Spec:** [path to the spec/design doc this plan implements — the plan
argues from the spec, so the spec travels with it; executors read both]

## Global Constraints

[The spec's project-wide requirements — version floors, dependency limits,
naming and copy rules, platform requirements — one line each, with exact
values copied verbatim from the spec. Every task's requirements implicitly
include this section.]

---

タスクの構成

### Task N: [Component Name]

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

**Interfaces:**
- Consumes: [what this task uses from earlier tasks — exact paths and signatures]
- Produces: [what later tasks rely on — exact paths, names, parameters, and
  return types. This block is the contract for an implementer who sees only
  this task.]

- [ ] **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: Compile the affected project or package**

Run the narrowest real compile/build command that proves the changed
interfaces are valid. Record the exact command and result in the task handoff.

```bash
<project compile or build command>
```

Expected: exit 0 with no compile errors.

- [ ] **Step 6: Review the complete diff**

```bash
git diff --check
git diff -- <files owned by this task>
git status --short
```

Confirm there are no unrelated files, generated artifacts, secrets, or
unreviewed edits. If the diff is not scoped, fix it before committing.

- [ ] **Step 7: Commit the verified increment**

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

Record the commit hash and verification evidence in the task result. Do not
mark the task `done` before the compile, diff, and commit gates pass.

プレースホルダー禁止

各ステップには、エンジニアが必要とする実際の内容をすべて記載してください。以下は計画の不備にあたるため、決して記述しないでください：

• 「TBD」「TODO」「後で実装する」「詳細を記入する」
• 「適切なエラー処理を追加する」／「検証を追加する」／「エッジケースに対応する」
• （実際のテストコードなしの）「上記のテストを書く」
• 「タスクNと同様」（タスクを読む順番が前後する場合があるため、コードを繰り返し記載してください）
• 方法を示さず、実行内容だけを説明するステップ（コードのステップではコードブロックが必要です）
• どのタスクにも定義されていない型、関数、メソッドへの参照

セルフレビュー

計画全体を書き終えたら、改めて仕様と照らし合わせてレビューしてください。 これは自分で行うチェックリストであり、サブエージェントへの依頼ではありません。

1. 仕様の網羅性： 仕様の各セクション／要件に目を通してください。各要件を実装するタスクを示せますか？抜けがあれば列挙してください。

2. プレースホルダーの確認： 計画内に、上記の「プレースホルダー禁止」セクションに記載されたパターンなど、問題となる記述がないか検索してください。見つかった場合は修正してください。

3. 型の整合性： 後続タスクで使う型、メソッドシグネチャ、プロパティ名が、先行タスクで定義した内容と一致しているか確認してください。タスク3では clearLayers() と呼び、タスク7では clearFullLayers() と呼んでいるなら、それはバグです。

問題を見つけたら、その場で修正してください。再レビューする必要はありません。修正して先に進んでください。タスクに対応する仕様要件が見つからない場合は、そのタスクを追加してください。

実行の引き継ぎ

計画を保存したら、実行方法を選べるようにしてください。保存先はリポジトリの .agents/plans/ 配下にしてください：

「計画を完了し、.agents/plans/<filename>.md に保存しました。実行方法は2つあります：

1. 委任実行（推奨） — タスクごとに新しいワーカーを割り当て、 各結果を .agents/plans/ に記録し、タスク間でレビューします。

2. インライン実行 — このセッション内でチェックポイントを設けてタスクを実行し、 作業の進捗に合わせて計画のステータスを更新します。

どちらの方法にしますか？」

委任実行では、delegation-mode を使用し、安定したタスク ID、タスクごとの結果ファイル、明示的な再開状態を設定し、すべてのタスクが完了したと確認できてから最終的な集約を行ってください。インライン実行では、同じタスクの境界を保ち、計画内のチェックボックスとステータスを更新してください。

計画または実装を完了とする前に、新たな証拠を求めてください。関連するコンパイル／ビルドとテストを実行し、差分全体を確認して、git diff --check を実行し、意図したファイルだけをステージし、ステージ済みの差分を確認して、検証済みの変更をコミットしてください。意図やエージェントの成功報告だけを根拠に done としてはいけません。コンパイル結果、差分レビュー、コミットハッシュの記録がないタスクは未完了です。