writing-plans

name	writing-plans
description	ソフトウェア開発の複数ステップ作業について、実装前に具体的な計画書を書くスキル。機能実装、バグ修正、リファクタ、移行、テスト追加、運用変更、ドキュメント改修などで、ユーザーが「計画して」「実装方針を作って」「planを書いて」「作業を分解して」「実装前に整理して」と言ったら使う。コードに触る前、またはサブエージェントや別セッションへ委譲する前には積極的に使う。

Writing Plans

目的

ソフトウェア開発の作業を、実装者がそのまま進められる計画書に落とし込む。 実装者はコードベースや問題領域の文脈をほとんど知らないが、開発者としては有能だと仮定する。 テスト設計や分割判断は計画側で補い、実装時の推測を減らす。

計画の核はこれに尽きる。

Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Plan-only のルール

このスキルを使うターンでは計画だけを作る。

• 実装コード、設定、テスト、ドキュメント本文は編集しない。
• 編集してよいのは計画ファイルだけ。
• 調査に必要な read-only 操作、検索、テストコマンドの確認はしてよい。
• mutating command、commit、push、外部サービスの変更操作はしない。
• 依頼が曖昧で、計画の成否に関わる未確定点がある場合だけ短く確認する。

計画を保存した後、必要なら「この計画を task-by-task に実装できます」と伝える。実装へ進むかはユーザーに確認する。

保存先

ユーザーが保存先を指定した場合は、そのパスを優先する。 指定がない場合は、作業中のリポジトリに次の形式で保存する。

docs/plans/YYYY-MM-DD-<slug>.md

<slug> は計画対象を短く表す英数字・ハイフンの名前にする。既存ファイルを上書きしない。

作成手順

1. 要件、会話履歴、関連ドキュメント、既存コードを読んで、何を達成する計画かを決める。
2. 対象が複数の独立したサブシステムにまたがる場合は、1つの巨大計画にせず分割を提案する。
3. 実装前にファイル構成を決める。どのファイルが何を担当するか、既存パターンとどう揃えるかを書く。
4. タスクを順序づける。各タスクは、独立してレビューでき、実装後に検証できる単位にする。
5. 各タスクを 2〜5 分程度の行動ステップへ分ける。
6. 実装系タスクでは TDD を基本にし、失敗するテスト、失敗確認、最小実装、成功確認を書く。
7. 計画を書き終えたら自己レビューし、プレースホルダー、未定義の名前、仕様漏れ、検証漏れを直す。
8. 複雑な計画、委譲前の計画、ユーザーがレビューを求めた計画では references/plan-document-reviewer-prompt.md を使って第三者レビューを依頼する。

計画書の構成

計画書は次の構成を基本にする。不要な項目は短くしてよいが、実装者が推測する必要が出る情報は省かない。

# [Feature or Change Name] Implementation Plan

> **For implementers:** Execute this plan task-by-task. Complete each checkbox step, run the listed validation, and commit after each task.

**Goal:** [何を作る・直すかを一文で書く]

**Architecture:** [方針、責務分割、既存設計との接続を 2〜3 文で書く]

**Tech Stack:** [主要言語、フレームワーク、テストツール、関連ライブラリ]

## Global Constraints

仕様に明記された制約は、要約で丸めず exact value をそのまま写す。各タスクはこの制約を暗黙に継承する。

- [バージョン制約、依存追加の可否、互換性、命名、運用上の制約など]

## Current Context

- [確認した既存コード、仕様、前提]
- [未確認だが計画上の仮定として置くこと]

## File Structure

- Create: `exact/path/to/new_file.ext` — [責務]
- Modify: `exact/path/to/existing_file.ext` — [変更内容]
- Test: `exact/path/to/test_file.ext` — [検証対象]

## Tasks

### Task 1: [Descriptive Name]

**Objective:** [このタスクで達成すること]

**Files:**
- Create: `exact/path/to/file.ext`
- Modify: `exact/path/to/existing.ext:line-range` （分かる場合）
- Test: `exact/path/to/test.ext`

**Interfaces:**
- Consumes: [前タスクから使う関数、型、設定、ファイル]
- Produces: [後続タスクが依存する関数、型、設定、ファイル]

- [ ] **Step 1: Write the failing test**

[必要なテストコード、入力、期待値]

- [ ] **Step 2: Run test to verify it fails**

Run: `[exact command]`
Expected: `[期待する失敗内容]`

- [ ] **Step 3: Write minimal implementation**

[変更するコードを、実装者がそのまま使える粒度で書く。コードを変更するステップでは、要点だけでなく必要なコードブロックを含める]

- [ ] **Step 4: Run test to verify it passes**

Run: `[exact command]`
Expected: `[期待する成功内容]`

- [ ] **Step 5: Commit**

```bash
git add [exact files]
git commit -m "type: concise description"
```

## Validation

- `[全体検証コマンド]` — [期待する結果]
- [手動確認が必要なら、画面・API・ログなどの確認手順]

## Risks, Tradeoffs, and Open Questions

- [実装前に注意すべきリスク]
- [採用した設計判断のトレードオフ]
- [未解決の質問。計画を実行できないほど重大なら、計画作成前にユーザーへ確認する]

ファイル構成の考え方

タスクを書く前に、ファイルの責務を決める。

• 既存コードの配置、命名、テスト構成に合わせる。
• 大きすぎるファイルへ無理に追記しない。変更対象がすでに肥大化しているなら、分割を計画に含める。
• ただし、既存設計を無視した大規模な再編はしない。
• 技術レイヤーだけで分けず、変更理由と責務で分ける。
• 一緒に変わるものは近くに置く。
• 後続タスクが依存するインターフェースは、名前、引数、戻り値、型を明示する。

タスク分割の基準

タスクは「レビューできる最小の成果物」にする。 セットアップ、設定、スキャフォールド、ドキュメント更新は、それ単体で意味が薄いなら、必要とするタスクへ含める。

各タスクは次を満たす。

• 目的が一文で言える。
• 変更ファイルとテストファイルが具体的に分かる。
• 実行前に何へ依存し、実行後に何を提供するかが分かる。
• テストまたは確認手順で完了を判定できる。
• 実装者がそのタスクだけを読んでも着手できる。

書かないもの

次の表現は計画の失敗として扱い、保存前に直す。

• TBD, TODO, 後で, 適宜, 必要に応じて だけで中身がない記述
• 「バリデーションを追加する」「エラーハンドリングする」だけで条件や期待動作がない記述
• 「テストを書く」だけでテストケース、入力、期待値がない記述
• 「Task N と同様」だけで、実装者がその場で使うコードや手順がない記述
• コード変更ステップなのに、complete / copy-pasteable code ではなく要点だけで済ませる記述
• 未定義の関数、型、設定名、ファイル名への参照
• 実行コマンドだけで expected output がない検証手順

自己レビュー

計画を保存する前に、次を確認して直す。

1. 仕様カバレッジ: 要件ごとに、対応するタスクや検証手順を指せるか。
2. プレースホルダー: 曖昧語、TODO、未定義名、丸投げ表現が残っていないか。
3. 型と名前の整合性: 前のタスクで定義した関数、型、設定名を後続タスクで同じ名前で使っているか。
4. テスト可能性: 各タスクと全体に、実行できる検証手順があるか。
5. 実装可能性: コード変更ステップに、実装者がそのまま使える complete / copy-pasteable code があるか。
6. スコープ: YAGNI に反する将来用の抽象化や、要件外の再設計が混ざっていないか。
7. DRY: 同じ処理を複数箇所に増やす計画になっていないか。
8. 引き継ぎ性: 実装者が推測しないと進めない箇所がないか。

保存後は、保存パスと計画の要点だけを短く伝える。