write-plan

計画の作成

概要

コードベースについて何も知らず、好みも疑わしいエンジニアを想定して、包括的な実装計画を作成します。知っておくべきことをすべて記録してください。各タスクで変更するファイル、コード、テスト、確認が必要なドキュメント、テスト方法を記載します。計画全体を、取り組みやすい小さなタスクに分けてください。DRY。SOLID。YAGNI。TDD。頻繁にコミットします。すべての計画には、必須の テスト計画と検証 セクションとカバレッジ目標を最後に設け、コードを書く前に自動の二次エンジニアリングレビュー（/plan-eng-review）を実施します。

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

最初に宣言します： 「計画作成スキルを使って、実装計画を作成します。」

コンテキスト： ブレインストーミングスキルで作成した専用のワークツリーで実行してください。

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

• （計画の保存場所についてユーザーの指定がある場合は、こちらを優先します）

スコープの確認

仕様が複数の独立したサブシステムを対象としている場合は、ブレインストーミングの段階でサブプロジェクトの仕様に分割しておく必要があります。分割されていない場合は、サブシステムごとに個別の計画に分けることを提案してください。各計画は、それ単体で動作し、テスト可能なソフトウェアを実現する必要があります。

仕様がユーザー向け機能の場合は、計画のスコープを垂直スライスにします。つまり、その機能の動作に必要なすべての層（UI、API、ビジネスロジック、データ、テスト）を含むブランチを作成し、単独でリリース可能かつ安全に元に戻せるものにします（定義の全文は、superskills のインストール先にある DEVELOPER_WORKFLOW.md を参照してください）。バグ修正、リファクタリング、または単一レイヤーの変更の場合は、実際に変更する層だけを対象にします。スライスを完全に見せるために層を追加しないでください。それは YAGNI 違反です。

ファイル構成

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

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

この構成をもとに、タスクを分解します。各タスクでは、単独で意味のある、自己完結した変更を行ってください。

設計原則（計画で明示してください）

このスキルは、superskills の品質基準（TDD、DRY、SOLID、YAGNI）を計画段階で具体化し、/qa-full が出荷時に適用します。各原則は以下のセクション内で定義されています。そこに沿って進めてください。正式な文書は superskills のインストール先にある ENGINEERING_STANDARDS.md です（計画対象のプロジェクト内にはありません）。そのため、取得する必要はありません。

計画では、チェック項目としてではなく、ファイル構成とタスクのどこで各原則が適用されるかを明記し、原則を尊重していることを示す必要があります。

• DRY — コードを追加する前に、再利用する既存のヘルパー／モジュールを明記します（Grep で検索してください）。2つのタスクで似たロジックを導入する場合は、共有部分を切り出す独立した先行タスクを設けます。意図的に重複を許容する場合は、その旨と理由を記します。
• SOLID — 各単位には変更理由を1つだけ持たせます（SRP）。具象ではなく、インターフェース／抽象に依存します（DIP）。インターフェースは狭く保ちます（ISP）。安定したコアを編集するのではなく、新しいコードで拡張します（OCP）。ファイル構成に記載する新しい単位ごとに、単一の責務と、それが公開する接点（インターフェース／境界）を記します。
• YAGNI — 仕様で必要なものだけを構築します。将来に備えた拡張性や、「後で必要になるかもしれない」ためのフックは追加しません。

これらを満たすために既存コードの再構成が必要な場合は、その再構成を独立したタスクとして設定し、機能タスクに紛れ込ませないでください。

セキュリティと脅威モデル（機能が信頼境界を越える場合）

脅威モデリングは設計時に行う作業です。計画に反映し、出荷時のゲートで初めて見つけるようなことがあってはなりません。この機能が以下のいずれかに該当する場合は、タスクを書く前に設計に対して /cso（OWASP Top 10 + STRIDE）を実施し、その結果を計画に反映してください。

• 認証、認可、セッション、またはトークンを扱う
• 信頼できない入力（ユーザー入力、アップロード、Webhook、外部 API）を受け付ける
• 機密データまたは規制対象データ（PII、決済情報、認証情報、健康情報）を読み書きする
• 新しい公開エンドポイント、新しい外部連携、またはデシリアライズ処理を追加する
• 信頼境界を変更する（新しいサービス間呼び出し、新しいテナント間経路）

計画に反映する内容：

• 設計タスク — 重要な脅威ごとに、入力検証、境界での認可チェック、レート制限、出力エンコーディング、最小権限、シークレットの取り扱いなどのタスクを設けます。機能タスクの中に埋め込まず、独立したタスクとして記載してください。
• テスト計画の項目 — 脅威ごとに、悪用ケース／否定ケースを記載します（例：「偽造 JWT を拒否する」「/orders/:id で IDOR を阻止する」）。これにより、/qa-full の /defense ステップで具体的な検証対象を用意できます。

機能が信頼境界を一切越えない場合は、その旨を1行で記して省略してください。セキュリティタスクを無理に作らないでください（ここでも YAGNI が適用されます）。

タスクの適切な粒度

各ステップは1つのアクション（2～5分）にします。

• 「失敗するテストを書く」— 1ステップ
• 「失敗することを確認するためにテストを実行する」— 1ステップ
• 「テストを通すために最小限のコードを実装する」— 1ステップ
• 「テストを実行し、すべて通ることを確認する」— 1ステップ
• 「コミットする」— 1ステップ

計画書のヘッダー

すべての計画は、必ず次のヘッダーで始めてください。

# [Feature Name] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use subagent-driven-development (recommended) or executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

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

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

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

---

タスク構成

### 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`

- [ ] **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"
```

プレースホルダー禁止

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

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

テスト計画と検証（すべての計画に必須のセクション）

タスクの後には、すべての計画の最後に ## Test Plan & Verification セクションを必ず記載してください。このセクションがない計画は不完全です。このセクションは、/qa-full、/qa、/qa-only、/verify が参照する全体計画であり、成果物 /plan-eng-review でも再確認します。タスクごとの TDD 手順はそのまま各タスクに記載し、このセクションではそれらをテストカバレッジ、重要なパス、受け入れ基準と結び付けます。

## Test Plan & Verification

**Coverage target:** [concrete, e.g. "≥90% lines on new modules; every new public function and error path has a test"]

**Critical paths (must pass before ship):**
- [end-to-end flow] → [how it's verified]

**Edge cases & error paths:**
- [input/state] → [expected handling] → [test that covers it]

**Regression guards:**
- [existing behavior that must not break] → [test protecting it]

**Verification commands:**
- Unit: `[exact command]` — expected: all pass
- Coverage: `[exact command]` — expected: ≥ target above
- E2E (if applicable): `[exact command]`

**Acceptance criteria (from spec):**
- [ ] [criterion] → covered by [task / test name]

テストカバレッジ目標の行は、/qa-full のステップ 9 が確認し、/verify が検証する内容そのものです。「十分なカバレッジ」のような曖昧な表現ではなく、具体的に記載してください。

忘れないこと

• ファイルパスは常に正確に記載する
• 各ステップにコードを完全に記載する。ステップでコードを変更する場合は、そのコードを示す
• 期待される出力を含め、コマンドを正確に記載する
• DRY、SOLID、YAGNI、TDD、頻繁なコミット
• すべての計画の最後に ## Test Plan & Verification セクションとテストカバレッジ目標を記載する

セルフレビュー

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

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

2. プレースホルダーの確認： 計画を検索し、問題になりそうな記述を探してください。上記の「プレースホルダー禁止」セクションにあるパターンがないか確認し、見つけたら修正してください。

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

4. TDD とテスト計画の完全性： コードを書く各タスクに、失敗するテストを先に作成する手順がありますか？具体的なテストカバレッジ目標、重要なパス、エッジケース、正確な検証コマンドを含む ## Test Plan & Verification セクションがありますか？テストなしで出荷されるコードがある場合は修正してください。

5. 原則の確認（DRY／SOLID／YAGNI）： 新しい各ユニットについて、単一の責務（SRP）と再利用する既存ヘルパー（DRY）を説明できますか？タスク間でロジックが重複していませんか？巨大なオブジェクトや、先回りしすぎた拡張性（YAGNI）を持ち込んでいませんか？修正するか、計画内で理由を説明してください。

6. 信頼境界の確認： この機能は信頼境界（認証、信頼できない入力、機密データ、新しいエンドポイント／連携、デシリアライズ）を越えますか？越える場合、/cso を実行し、重要な脅威をそれぞれ設計タスクと否定テストに落とし込みましたか？越えない場合、その旨を明記していますか？不足があれば修正してください。セキュリティタスクのない信頼境界に関わる機能は、不完全な計画です。

問題を見つけたら、その場で修正してください。再レビューは不要です。修正したら先へ進んでください。タスクに含まれていない仕様要件を見つけた場合は、タスクを追加してください。

エンジニアリングレビュー（自動の二次レビュー — 省略しないこと）

セルフレビューに合格したら、コードを書く前に、計画を /plan-eng-review に渡して独立したエンジニアリング上の再確認を受けてください。これは自動で行います。許可を求めず、実行してください。

1. 保存した計画ファイルを対象に /plan-eng-review を実行します。アーキテクチャとデータフローを確定し、エッジケースとテストカバレッジを厳しく検証したうえで、/qa、/qa-only、/qa-full が主要なテスト入力として使用するテスト計画アーティファクトを作成します。
2. 問題があれば、推奨事項とともに一つずつ対話形式で提示されます。それぞれに対応し、見つかった ## Test Plan & Verification セクションや DRY／SOLID の構成上の不足も含め、解決策を計画ファイルに反映してください。
3. /plan-eng-review が承認してから、以下の実行への引き継ぎを提示してください。

全体の流れ：/write-plan（DRY・SOLID・YAGNI・TDD・テスト計画・テストカバレッジ）→ セルフレビュー → /plan-eng-review（二重確認＋テスト計画アーティファクト）→ 実行。

実行の引き継ぎ

計画を保存した後、実行方法を選んでもらいます。

「計画が完了し、docs/superpowers/plans/<filename>.md に保存されました。実行方法は2つあります。

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

2. インライン実行 - このセッションで executing-plans を使ってタスクを実行し、チェックポイントを設けながらまとめて進めます。

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

サブエージェントによる実行を選んだ場合：

• 必須のサブスキル： subagent-driven-development を使用します。
• タスクごとに新しいサブエージェントを割り当て、2段階でレビューします。

インライン実行を選んだ場合：

• 必須のサブスキル： executing-plans を使用します。
• レビュー用のチェックポイントを設けながら、まとめて実行します。