writing-plans — 実装プランを書く

要件 (依頼文・brainstorming で合意した内容・関連 ADR) を入力に、ゼロ context のエンジニアでも実行可能な実装プランを書く。spec は前提にしない。bite-size タスクに分解し、各タスクは「テスト書く → 失敗確認 → 最小実装 → 通過確認 → commit」の単位まで落とす。DRY / YAGNI / TDD / 頻繁な commit が原則。

エンジニアは熟練者だが「このプロジェクト固有のツール / ドメイン」は知らない前提。テスト設計も得意でないと仮定して書く。

モード: brainstorming で決めたモード (autonomous / guarded) を引き継ぐ。単独起動なら cross-review スキル (~/.claude/skills/cross-review/SKILL.md) の「モード判定」で決める。autonomous ではユーザーに質問せず、下記の cross-review ゲートを通して実装に引き継ぐ。

context: worktree 上で書くなら using-git-worktrees スキルで先に隔離環境を作っておくこと。

保存先: .claude/plans/YYYY-MM-DD-<feature-name>.md (PJ 側に独自の plan 配置規約 — 例: docs/plans/ — があればそれに従う)

スコープチェック

要件が複数の独立サブシステムを含んでいる場合、brainstorming 段階で分解しておくべきだった。もし分解せずにここまで来てしまったら plan を 1 つでも書く前にユーザーに decompose を提案 する (guarded)。autonomous では分解案を plan 冒頭に書き、最初のサブプロジェクトだけの plan を書いて進む (残りは自律判断ログの未決事項へ)。各 plan は単独で動くソフトウェアを生むサイズに収める。

ファイル構造を先に決める

タスクに分解する前に「どのファイルを作る / 触る」と「各ファイルの責務」をマップする。decomposition の判断はここで lock する。

• 各単位は明確な境界 + well-defined interface。1 ファイル 1 責務
• Claude は文脈に丸ごと載せられるコードに対して最も良く reason できる。小さく focused なファイルを優先する
• 一緒に変わるものは一緒に置く。技術レイヤではなく責務で割る
• 既存コードの慣習に従う。大きいファイルだらけの codebase をいきなり再構成しない。ただし触るファイルが既に大きすぎるなら、その plan の中で分割を含めるのは妥当

このファイル構造がタスク分解の根拠になる。各タスクは独立して意味を持つ自己完結変更を生むべき。

タスク粒度

タスクは「独立したテストサイクルを持ち、新鮮なレビュアーのゲートを通すに値する最小単位」。

• セットアップ / 設定 / scaffolding / ドキュメントは、それを必要とする deliverable のタスクに畳む
• 隣り合うタスクが片方だけ reject されうるなら分ける、そうでなければ統合
• 各タスクは「独立してテスト可能な deliverable」で終わる

bite-size step (各 step は 2〜5 分の 1 アクション)

• 「失敗するテストを書く」 — step
• 「実行して失敗確認」 — step
• 「最小実装」 — step
• 「テスト通過確認」 — step
• 「commit」 — step

plan ドキュメント header

全 plan は以下で始める:

# [機能名] 実装プラン

> **実装者向け:** このプランは下の「運用前提」に書いた実装方式 (SDD / 直列) で消化する。step は `- [ ]` チェックボックスで track する。

**Goal:** [1 文で「何を作るか」]

**Architecture:** [2〜3 文で approach]

**Tech Stack:** [使う主な技術 / ライブラリ]

## Global Constraints

以下の 3 種を **サブセクションに分離して** 列挙する。混ぜない。各タスクの要件にはこのセクションが暗黙に含まれる。**該当情報がないサブセクションは見出しを残し、本文に `該当なし` と 1 行書く** (見出しごと削除しない — テンプレート構造を読者が確認できるようにするため)。

### 要件由来 (依頼文・合意内容・ADR から逐語コピー)

[バージョン下限、依存制約、コピー文言、プラットフォーム要件、ADR で決めた設計判断など。値は出典から **逐語的に** コピーし、ADR なら path を添える。]

### PJ 恒久ルール (CLAUDE.md / `.claude/rules/` 由来)

[Fail Fast、命名規約、コミット規約、外部 API 利用方針など、この plan に関係するもの。PJ 恒久ルールと plan の設計責務が直接衝突する場合 (例: Fail Fast の再 throw vs API レイヤでのエラー応答変換) は、衝突する 1 行の直後に `※ 局所例外: <理由>` と 1 行で明示し、対応するコード step にもコメントとして理由を残す。]

### 運用前提 (brainstorming で確定した実装方式)

[モード (autonomous / guarded)、隔離方式 (worktree / branch)、ブランチ名、SDD / 直列、その他 brainstorming で固定された前提。実装フェーズへの引き継ぎ情報。]

---

plan の末尾 (完了後)

全 plan は最後のタスクの後に、次の節で終える。実装方式によらず同じ内容にする (SDD でも直列でも最終レビューは 1 回)。

## 完了後

1. `npm test` 等、PJ の全テストを実行して green を確認
2. whole-branch cross-review: `BASE=$(git merge-base main HEAD)` からの diff を 1 ファイルにまとめ、新しい subagent に subagent-driven-development の `reviewer.md` で「保守担当 + 攻撃者」視点のレビューをさせる。指摘は直して再レビュー (手順は cross-review スキル)
   - subagent を派遣できない環境では、自分で依頼・plan・ADR の各項目と diff を突き合わせ、攻撃者視点の入力例 (不正値・境界値・壊れた保存データ) を試して結果を記録する
3. branch 上の commit で停止。push / PR / merge はユーザーの指示を待つ

タスク構造

### Task N: [コンポーネント名]

**Files:** *(以下は Create / Modify / Test の 3 種別すべてが発生するケースの例。実際のタスクでは該当する種別行だけ書き、不要種別は **省略する** — 空行や `N/A` を残さない)*
- Create: `exact/path/to/file.mjs`
- Modify: `exact/path/to/existing.mjs:123-145`
- Test: `tests/exact/path/to/file.test.mjs`

**Gate:** *(リスク昇格リストに該当するタスクのみ `human` と書く。該当しなければ行ごと省略)*

**Interfaces:**
- Consumes: [このタスクが前タスクから使うもの — 正確な signature]
- Produces: [後続タスクが依存するもの — 正確な関数名、引数 / 返り値型]

- [ ] **Step 1: 失敗するテストを書く**

```javascript
import { test } from 'node:test';
import assert from 'node:assert/strict';

test('specific behavior', async () => {
  const result = await fn(input);
  assert.equal(result, expected);
});
```

- [ ] **Step 2: 実行して失敗を確認**

実行: `node --test tests/path/to/file.test.mjs`
期待: FAIL ("fn is not defined" など)

- [ ] **Step 3: 最小実装**

```javascript
export function fn(input) {
  return expected;
}
```

- [ ] **Step 4: 実行して通過を確認**

実行: `node --test tests/path/to/file.test.mjs`
期待: PASS

- [ ] **Step 5: commit**

```bash
git add tests/path/to/file.test.mjs src/path/to/file.mjs
git commit -m "feat: add specific feature"
```

Gate: human の付け方

cross-review スキルの「リスク昇格リスト」(本番データ / DB migration / データ削除 / 認証・認可 / 課金 / 個人情報 / 秘密情報 / デプロイ / 外部送信 / 公開 API の破壊的変更 / PJ 宣言で guarded 指定された領域) に触れるタスクには **Gate: human** を付ける。

• autonomous でも、SDD / 直列実行はこのタスクの 直前で止まり、タスク内容とリスクを示してユーザー承認を待つ。他のタスクは止まらない
• リスク部分だけを切り出せるならタスクを分け、Gate を付ける範囲を最小にする (例: migration ファイル作成と適用を分け、適用だけに Gate)
• 案件全体がリスク領域なら、個別の Gate ではなくモードごと guarded にする

placeholder 禁止

各 step は実装者が必要とする実体を持つ。以下は plan 失敗 — 絶対に書かない。

• "TBD" / "TODO" / "implement later" / "後で詳細"
• "appropriate error handling を追加" / "validation を追加" / "edge case を handle"
• "上記に対するテスト追加" (テストコード本体なし)
• "Task N と同様" (コードを再掲する — 実装者は順番通り読まないかもしれない)
• "何をするか" だけで "どうするか" を示さない step (コード step にはコードブロックが必須)
• どのタスクでも定義していない型 / 関数 / メソッドへの参照

守るべきこと

• 正確なファイルパスを毎回書く
• 各 step に完全なコードを置く (code を変える step なら code を書く)
• 正確なコマンド + 期待 output
• DRY / YAGNI / TDD / 頻繁な commit

セルフレビュー

plan を書き終わったら、新鮮な目で要件と plan を突き合わせる。これは subagent ではなく自分でやる。

1. 要件カバー率: 依頼文・合意内容・ADR の各要件について、対応するタスクを指せるか? 漏れを列挙
2. placeholder 走査: 上の「placeholder 禁止」リストに当てはまる箇所を検索 → fix
3. 型一貫性: 後タスクで使った型 / signature / プロパティ名が前タスクで定義したものと一致しているか? Task 3 で clearLayers() だったのに Task 7 で clearFullLayers() になっていたら bug
4. PJ 規約整合: PJ CLAUDE.md / .claude/rules/ 配下に定義された原則 (例: Fail Fast、命名規約、コミット規約、外部 API の利用方針など) を侵害していないか
5. Gate 付与漏れ: リスク昇格リストに触れるタスクに **Gate: human** が付いているか
6. 完了後節: plan の末尾に「完了後」節 (全テスト → whole-branch cross-review → branch 上で停止) があるか

問題を見つけたら直接 inline で fix する。再レビューは不要、直して進む。要件にタスクが対応していなければタスクを足す。

cross-review ゲート (plan)

セルフレビュー後に plan-reviewer.md の prompt で、新しい subagent に「ゼロ context の実装者」視点でレビューさせる。手順・ループ・停止条件は cross-review スキルに従う。

• autonomous: 必須。Approved になるまで実装に引き継がない (最大 3 往復)
• guarded: plan が 5 タスク以上、または複数サブシステムにまたがるときに実施。それ以外は任意
• 結果は plan 末尾の ## 自律判断ログ に 1 行追記する (autonomous のみ。ログの書式は cross-review スキル 4 節)

plan の commit

レビューが Approved になった直後 (レビューをしない guarded ではセルフレビュー直後) に、plan ファイル (自律判断ログを含む) を 1 コミット にする: docs(plans): <機能名> の実装プラン。各タスクの commit には plan を含めない (実装中に plan のチェックボックスを更新する場合も、タスクの commit とは分ける)。

branch / worktree がまだ無い場合 (brainstorming を経由しない単独起動) は、下の「実装への引き継ぎ」で branch / worktree を用意してから、その上でこの commit をする。main には commit しない。

実装への引き継ぎ

実装スタイルは brainstorming スキルの最後に決定済み が前提。直交 2 軸 (隔離: worktree or branch × 並列: SDD or 直列) で 4 択:

• A. worktree + SDD — 隔離環境 × subagent 駆動 (大規模 / 並列向け)
• B. branch + 直列 — branch のみ、このセッションで私が順に実装 (小〜中規模 / 1 本道)
• C. worktree + 直列 — worktree で隔離して直列、subagent なし
• D. branch + SDD — branch のみ、このセッションで SDD

ブランチ / worktree も brainstorming の段階で既に切られている。writing-plans はそれを前提に plan を書き、保存後はそのまま実装フェーズに引き継ぐ。

brainstorming を経由せず writing-plans 単独起動した場合

要件はあるが brainstorming スキップで来た場合、guarded ならここで AskUserQuestion で 4 択を提示する。autonomous なら聞かず、brainstorming の「autonomous での機械的決定」(独立タスク 3 つ以上 → SDD / 作業ツリーが汚れている・並行作業あり → worktree) で決めて進む:

plan を .claude/plans/<filename>.md に書きました。実装方式を選んでください (隔離 × 並列の 2 軸):

• A. worktree + SDD — 隔離環境 × subagent 駆動 (大規模 / 並列向け)
• B. branch + 直列 — branch のみ、このセッションで順に実装 (小〜中規模 / 1 本道)
• C. worktree + 直列 — worktree で隔離して直列 (隔離は欲しいが subagent 起動コストは払わない)
• D. branch + SDD — branch のみ、このセッションで SDD (worktree オーバーヘッドなしで並列だけ取る)

選択に応じた動作:

• A / C (worktree あり):
  1. using-git-worktrees スキルを呼んで worktree 作成 (新規ブランチ付き)
  2. cp .claude/plans/<filename>.md <worktree-path>/.claude/plans/<filename>.md で plan ファイルを worktree に複製
  3. main 作業ツリー側の .claude/plans/<filename>.md を rm (untracked なので git 影響なし)
  4. 以降の作業は worktree 上で進める (A は subagent-driven-development、C は私が直列消化)
• B / D (worktree なし):
  1. 現ディレクトリで git switch -c <branch> (main 直コミット禁止)
  2. plan ファイルはそのまま使う
  3. B はこのセッションで Task 1 から私が消化、D は subagent-driven-development を起動

直列 (B / C) で消化するときの注意

• タスク間でユーザーに「続けていい?」と聞かない。**Gate: human** のタスクの直前だけ止まる
• 全タスク完了後、plan 末尾の「完了後」節に従う (whole-branch cross-review を 1 回通し、指摘を直してから終える)

4 択の選び方早見表

判断軸の詳細は ~/.claude/skills/brainstorming/SKILL.md の「軸ごとの判断材料」参照。

main 直コミット禁止 — 必ず branch または worktree に切り替えてから実装に入る。

実装の終点: どのモードでも branch 上の commit まで。push / PR 作成 / merge はユーザーの指示を待つ。