ai-dev-plan · git:20261007.5c933b5 · 2026-10-07 · sha256 44f379df168f375d
ai-dev-plan git:20261007.5c933b5A
Immutable. This exact content never changes and is served at /api/v1/blob/44f379df168f375d.
---
name: ai-dev-plan
description: "PBI INPUT PACKAGE から PlanGate の plan.md / todo.md / test-cases.md を B-1→B-2→B-3 フローで作成する。Use when: docs/working/TASK-XXXX/pbi-input.md を元に実行計画を作りたい時。"
---
# AI-Driven Plan (PlanGate / Codex 共用)
PlanGate ワークフローの **plan フェーズ（WF-02〜WF-03）** を Codex / Claude Code 両方で実行する skill。skill が担うのは読む順序と入出力規約であり、**機械化された実行ロジックは上流リポジトリ（`s977043/plangate`）の `scripts/ai-dev-workflow` / `bin/plangate` CLI 側にある**。
> **その CLI は導入先には配布されない**（Human 決定 #1144: plugin が配るのは読み物層のみで、CLI と enforcement 層〔`scripts/hooks/`〕は含めない）。**plan フェーズ自体は CLI 非依存で完結する**（本 skill の手順どおり `plan.md` / `todo.md` / `test-cases.md` を手で作る）。CLI が必須なのは `plan_hash` の機械検証など一部に限られ、その分離と代替手順は下記「CLI 呼び出し」節と「CLI 不在時のフォールバック」節を正本とする。
> 本スキルは **bundled resources**（`references/`）で自己完結する。
>
> **パス表記の規約（重要）**: 本 SKILL.md 中の `references/…` は、すべて **本スキル
> ディレクトリからの相対パス**（= `<skill_dir>/…`）であって、導入先リポジトリのルートからの
> 相対パスではない。実行時はまず `<skill_dir>`（このファイルが置かれているディレクトリ）を
> 解決してから使う:
>
> | 環境 | `<skill_dir>` |
> | --- | --- |
> | plugin 導入先（Claude marketplace） | `<plugin_root>/skills/ai-dev-plan/` |
> | `install.sh --claude` 導入先 | `.claude/skills/ai-dev-plan/` |
> | Codex 導入先 | `.codex/skills/ai-dev-plan/` |
> | 上流リポジトリ（正本側） | `.agents/skills/ai-dev-plan/` |
>
> 導入先が独自の正本（上流リポジトリの `docs/` 配下に相当するもの）を別途保持している
> 場合は、そちらを優先すること。
## Read First
### 参照解決順（導入先で必ずこの順に探す）
本 Skill は **上流リポジトリ基準の `docs/**` パスを直接参照しない**（#1232）。`docs/**` は
`install.sh --claude` / plugin（Claude marketplace）/ Codex の **3 経路とも配布対象外**であり、
書いた時点で導入先では必ず空振りするためである。参照の解決は次の順で行う:
1. **`<skill_dir>` 配下の同梱物（`references/`）を第一に読む** — 契約 doc・テンプレートは
本スキルに同梱されている（「同梱リファレンス」節の一覧）
2. 導入先リポジトリが独自の正本（上流の `docs/` 配下に相当するもの）を保持していれば、
そちらを優先する
3. **rules（`rules/*.md`）だけは配布経路によって着地が異なる**ため、次の順で探す:
1. 導入先リポジトリの相対パス（例: `.claude/rules/mode-classification.md`）
2. 無ければ plugin root 配下（例: `${CLAUDE_PLUGIN_ROOT}/rules/mode-classification.md`）
- **解決は Bash で `ls "${CLAUDE_PLUGIN_ROOT}/rules/"` を実行して確認する**。
Read ツールは絶対パスを要求し環境変数を展開しないため、`${CLAUDE_PLUGIN_ROOT}/...`
という文字列をそのまま Read しても必ず失敗する
- **変数が空・未設定なら glob（`~/.claude/plugins/cache/**` 等）で推測せず次へ進む**。
キャッシュには複数バージョンが並存しうるため、当て推量は版の取り違えを招く
4. いずれでも解決できなければ **「正本 `<path>` を参照できなかった」と明示**し、本 Skill 内の
記述と同梱 `references/` を代替正本として扱い、推測で内容を補わない
**plugin root 直下に `docs/` を探しに行かないこと**: plugin が配布するのは
`agents` / `commands` / `skills` / `rules` 等の定義ディレクトリのみで `docs/` を配布対象として
認識せず、plugin root 配下に相当する配布物が存在しないため必ず空振りする（クラス A の rules
参照が plugin root 配下で解決できるのは `rules/` が実際に配布されるからであり、この非対称を
`docs/**` に持ち込まない）。
導入経路は 3 つあり、配置されるものが違う（**「同じ 4 ディレクトリが配られる」わけではない**）:
- **`install.sh --claude` 経由**: コピー対象は `agents` / `skills` / `commands` / `rules`
の 4 ディレクトリのみ（一次ソース: `install.sh` の `for dir in agents skills commands rules`）
- **plugin（Claude marketplace）経由**: バンドルは `agents` / `assets` / `commands` /
`hooks` / `rules` / `scripts` / `skills` + `README.md` / `.claude-plugin/`。ただし
`scripts/` の中身は `install-plangate-skills.sh` のみで、**`ai-dev-workflow` も
`bin/plangate` も含まれない**
- **Codex（`install.sh --codex` / marketplace）経由**: 配置されるのは **skills だけ**。
`install_codex()` は `install-plangate-skills.sh` を呼ぶのみで、同スクリプトは
`rules` を一切扱わない（`.claude/rules/` は作られない）。`${CLAUDE_PLUGIN_ROOT}` も
Claude Code の変数であり Codex には無い
| 参照 | `install.sh --claude` 経由 | plugin（Claude marketplace）経由 | Codex 経由 |
|------|---------------------------|----------------------------------|-----------|
| `rules/*.md` | `.claude/rules/` に着地（解決可） | `${CLAUDE_PLUGIN_ROOT}/rules/` で解決 | **未配置（解決不可 → 手順 4 へ）** |
| 契約 doc・テンプレート | **`<skill_dir>/references/` に同梱（解決可）** | **`<skill_dir>/references/` に同梱（解決可）** | **`<skill_dir>/references/` に同梱（解決可）** |
| `bin/**` | コピー対象外（解決不可） | バンドル対象外（解決不可） | 未配置（解決不可） |
| `scripts/**` | コピー対象外（解決不可） | `${CLAUDE_PLUGIN_ROOT}/scripts/` は存在するが `install-plangate-skills.sh` のみ（目的の CLI は解決不可） | 未配置（解決不可） |
> **例外（上流リポジトリ内のドッグフーディング経路 / #1249 MINOR-3）**: 上表「Codex 経由」の
> 「同梱（解決可）」が成立するのは **配布物経由**（`plugin/plangate/scripts/install-plangate-skills.sh`。
> source は `plugin/plangate/skills/`）に限る。上流リポジトリ自身が `.codex/skills/` を作る
> `scripts/install-plangate-skills-to-codex.sh` は source が `.agents/skills/` であり、そこには
> 本 skill の `references/` が **存在しない**（`references/` は `scripts/sync-plugin-plangate.sh` が
> `plugin/plangate/skills/**` にだけ生成する）。したがって上流 repo の
> `.codex/skills/<skill>/references/` は **構造上つねに不在**であり、この経路では契約 doc・
> テンプレートは手順 4（解決できなかったと明示）に落ちる。上流では `docs/**` の正本を直接
> 読めるため実害は無いが、上表の「解決可」を上流の `.codex/` にまで拡大解釈しないこと。
> 経路自体の是正（source の一本化）は #1086 の裁定待ち。
**Codex 経路では rules の解決順 3-1・3-2 とも成立しない**ため、rules 参照は手順 4
（解決できなかったと明示）に落ちる。その場合、正本の内容は **同梱 `references/` と本 skill の
記述で代替**し、plan.md の Questions / Unknowns に「正本 `<path>` を参照できなかった」旨を
記録する。
### 同梱リファレンス（`<skill_dir>/references/`）
| ファイル | 役割 |
|---------|------|
| `references/ai-driven-development.md` | ワークフロー全体像・モード分岐・ゲート条件・Prompt 1 の正本 |
| `references/plan-metrics-verification.md` | 事前メトリクス検証（B-1 → B-2 mandatory gate）の正本 |
| `references/core-contract.md` | 実行契約（Iron Law / Stop rules / Output discipline）の正本 |
| `references/plangate.md` | PlanGate 概要ガイド |
| `references/plan-template.md` | `plan.md` の雛形（**配布先ではこの名前**。理由は下記注記） |
| `references/todo.md` | `todo.md` の雛形 |
| `references/test-cases.md` | `test-cases.md` の雛形 |
| `references/INDEX.md` | `INDEX.md` の雛形 |
| `references/current-state.md` | `current-state.md` の雛形 |
| `references/review-self.md` | `review-self.md`（C-1 全項目）の雛形・項目定義の正本 |
| `references/review-external.md` | `review-external.md`（C-2 / R-NNN 集約）の雛形 |
| `references/pbi-input.md` | `pbi-input.md` の雛形 |
> **`plan.md` の雛形が `plan-template.md` である理由**: 承認境界 hook（EH-3）は
> **basename `plan.md`** を block 対象として判定する（パスではなく basename）。雛形を
> `plan.md` の名前で同梱すると、hook を配線した導入先で雛形そのものが編集不能になる。
> 配布名だけを変えており、**生成する成果物のファイル名は `plan.md` のまま**。
### 読む順序
> 下記 3〜5 の fallback にある `<plugin_root>` は、上の「参照解決順」手順 3-2 のとおり
> **Bash で `${CLAUDE_PLUGIN_ROOT}` を展開して得た絶対パス**を指す（変数を含む文字列を
> そのまま Read しない）。
1. `CLAUDE.md`
2. `AGENTS.md`
3. `.claude/rules/working-context.md` → fallback `<plugin_root>/rules/working-context.md`
（B フェーズ 3 ファイル同時生成・段階別出力・ゲート条件の正本）
4. `.claude/rules/mode-classification.md` → fallback `<plugin_root>/rules/mode-classification.md`
（5 段階 mode + `lite_eligible` 派生属性の正本）
5. `.claude/rules/hybrid-architecture.md` → fallback `<plugin_root>/rules/hybrid-architecture.md`
（Rule 1〜5 / handoff 必須化）
6. `references/ai-driven-development.md`（**同梱**。導入先が独自正本を持つ場合はそちらを優先）
- 最低限: `## ワークフロー全体像`、`### タスク規模によるモード分岐（5 モード）`、`## ゲート条件`、`### Prompt 1: Plan + ToDo + Test Cases生成`
7. `docs/working/TASK-XXXX/pbi-input.md`（**導入先で作成する入力**。配布物ではない。無ければ plan を開始しない）
## Output
- `docs/working/TASK-XXXX/plan.md`
- `docs/working/TASK-XXXX/todo.md`
- `docs/working/TASK-XXXX/test-cases.md`
- `docs/working/TASK-XXXX/INDEX.md`（任意・無ければ生成）
- `docs/working/TASK-XXXX/decision-log.jsonl`（初期化）
## Rules
### フロー（詳細は正本参照）
- **B-1 / B-2 / B-3** フローおよび plan.md 必須セクション（確認事項 / アプローチ比較 / Mode判定 / lite_eligible 等）は同梱 `references/ai-driven-development.md` の `### Prompt 1: Plan + ToDo + Test Cases生成` と `.claude/rules/mode-classification.md` を **正本** とする。skill は順序のみを示す。生成物の雛形は同梱 `references/plan-template.md` / `references/todo.md` / `references/test-cases.md` を使う。
- Planの**設計判断**は上流正本 `docs/ai/plan-design-principles.md` を基準とし、導入先では下記「Plan Design Principles」節を配布用の実行サマリとして使う。新しい bundled reference を増やさず、既存の SKILL.md 同期経路を再利用する。
- Principles は常に判断へ利用するが、artifactへは material な判断だけを残す。ultra-light / light で空セクションや儀式的 `N/A` を増やさない。
- B-1（最大 3 問の確認質問）→ **事前メトリクス検証 (mandatory gate)** → B-2（2〜3 案の trade-off 比較）→ B-3（3 ファイル同時生成）
### Plan Design Principles（#1335 / 配布用実行サマリ）
上流の詳細正本は `docs/ai/plan-design-principles.md`。`docs/**` が届かない plugin / Codex / install.sh 導入先でも同じ判断を実行できるよう、必要最小限の規範を本SKILLへ埋め込む。本SKILLは既存 `scripts/sync-plugin-plangate.sh` の skill 同期で配布される。
Plan作成では次の6原則を使う。Review checklistへ個別展開せず、作成時の判断ガイドとして適用する。
1. **Evidence Before Design** — 推測より現行実装・テスト・docs・履歴・実測を優先する
2. **Minimum Sufficient Design** — 現在のACを満たす最小十分な設計をbaselineにする
3. **Explicit Responsibility & Boundary** — Task / module / workflow等の責務を1文で説明できる粒度にする
4. **Abstraction Requires Evidence** — code similarityだけで共通化せず、knowledge/invariant/change reason/current needを確認する
5. **Extension Is Conditional** — OCP/DIP/Compositionは実在する境界・variationがある場合だけ発火する
6. **Design for Verification** — Design Decisionをobservable Behavior / Contract / Invariantと検証方法へ接続する
新しい abstraction / interface / dependency / extension point と Contract / Invariant は、AC / current constraint / existing behavior / domain rule / architecture constraint / measured evidence の現在根拠へ trace できなければ採用しない。
### 事前メトリクス検証 (B-1 → B-2 mandatory gate / #351 TASK-0117)
> 正本: 同梱 `references/plan-metrics-verification.md`
> （導入先が独自正本を保持する場合はそちらを優先。どちらも解決できない環境では以下の要約に従い、正本未参照である旨を plan に記録する）
「全部 / 全件 / 残り N 件」系の対象は **実数を取得** してから B-2 へ進む。
**検証コマンド例** (.git / node_modules 等を除外):
```sh
grep -rln --exclude-dir={.git,node_modules,dist,docs/working} <symbol> --include='*.md' -- . | wc -l
find . -name <pattern> -not -path './.git/*' -not -path './node_modules/*' | wc -l
# 推奨: rg --files <path> | wc -l
```
**判定基準** (実数 / AI 見積もり):
- ≥ 3 倍 → **スコープ縮小 or 別タスクへ切替**
- 1〜3 倍 → 採用、plan の Risks に記録
- < 1 倍 → 採用、Mode を 1 段下げる候補
**plan.md template に `## Metrics Evidence` 欄を必須化** (実数 / 見積もり / ratio / 判定 を残す出力契約 / AC-8)。
**未取得時の分岐 (安全側 / R-001/R-004)**: 実数取得不能 / Plan Health 未算出 / 「全件」系の対象が曖昧な場合は **必ず Mode 引き上げ側に倒す** (`mode-classification.md` AC-8 安全側不変条件と一貫)。
### todo.md 規約
- タスク粒度 2-5 分、`Owner: agent / human` 必須、`depends_on` / `files` 必須
- L-0〜V-4・PR 作成は workflow-conductor が自動制御するため含めない
- 各タスクに `rollback:` を記載（戻し手順）。**必須=high-risk / critical の実装タスク**。standard 以下は任意、検証/読取のみは `rollback:不要` と明記可
- rollback 手順が長い場合はタスク直下に補助ブロックで記述してよい
### test-cases.md 規約
- 各 AC → テストケースのマッピング必須、Edge case を含める
- AC以外の重要な Contract / Invariant / Regression / Conditional Requirement を検証する場合は `Verification Trace` に**存在理由とSource/Evidence**を残す
- Contract / Invariant はテストを作るために後付けで発明しない。AC / 既存挙動 / Domain Rule / Architecture Constraint / 実測 Evidence の最低1つへ trace する
- `Trace`（なぜtestが存在するか）と `期待値の出所`（なぜexpectedが正しいか）を分離する
- **各ケースの期待値に出所を明記する**（`デザイン実測` / `規約` / `既存実装`）
- 出所が `規約` の期待値は、`## Convention Evidence` に **規約の記述 / 実値 / 一致 / 判定** を残す（#934）。
事前メトリクス検証が「全部 / 全件」系に実数を要求するのと同じ理由で、**規約由来の期待値には実値との突合を要求する**
- **不一致（規約 ≠ 実値）のときは AC に採用しない**。安全側に倒して plan の 🚩 人間確認ポイントへ落とし、
規約と実装のどちらを正とするかは人間の設計判断に委ねる（`mode-classification.md` の安全側不変条件と一貫）。
AI が黙って片側へ寄せて一括変更しない
### Minimum Sufficient Test Set（#936 → #960 / #1335）
Test Case は現在の要求を証明する**最小十分な集合**へ収束させる。
- 各 Test Case は distinct な `Trace ID`、または同じ Trace に対する distinct な failure / boundary / compatibility / security evidence を説明する
- 同じ Trace + 同じ failure mode を実質的に重複して証明するケースは、差に意味がなければ統合する
- 「念のため」「生成できるから」「ケース数を増やすため」だけでは追加しない
- hard な件数上限は置かない。高リスク変更で distinct な検証要求が増えることは許容する
- mode は Test Case 件数の cap ではなく、materiality / 記述密度に使う
> Minimize redundant proofs, not meaningful coverage.
### 変更タイプ別 Verification / TDD
`Always RED first` を一般則にしない。変更タイプに適した事前証拠を持ち、変更後に同じ契約を再検証する。
- **new behavior**: failing test (RED) → minimum implementation → GREEN → refactor
- **bug fix**: regression test reproduces failure (RED) → fix → GREEN
- **behavior-preserving refactor**: characterization / existing tests GREEN → refactor → GREEN + behavior-preservation evidence
- **docs / config / generated artifact**: deterministic baseline → change → deterministic validation
RefactorではRedの状態で構造変更を進めない。Characterization Test / Preparatory Refactoring / Knowledge Deltaの詳細は #867 の責務とし、本skillで再定義しない。
### 監査
- decision-log.jsonl に B-1/B-2/B-3 の主要判断を append-only で記録
- mode が `critical` で `lite_eligible=true` の場合は人間の C-3 明示承認記録が前提（`mode-classification.md` AC-11）
## 計画の構造化観点（river-review rr-upstream-create-plan-001 由来 / #517 受け入れ）
plan.md 生成時、以下の観点を Work Breakdown / Risks に反映する:
1. **仮説と確定事項の分離** — 判断に必要な事実が欠けていれば Questions / Unknowns に
質問として先出しし、仮説（未確認の前提）と確定事項を混ぜない。情報不足のまま
推測で進めない
2. **リスクの 3 点セット** — Risks には `内容 / 検証手段 / Fallback` を揃える。
不確実性（互換性・性能・移行・セキュリティ）ごとに検証方法が無いリスクを残さない
3. **人間ゲートの明示** — 設計確認・仕様確認など人間レビューが必要なブレーキ
ポイントを Work Breakdown の 🚩 チェックポイントとして明示する（自己設置 Gate は
勝手に解除しない — responsibility-classes.md 準拠）
4. **速く学べる順** — ステップは検証が早く回る順に並べ、クリティカルパスを明示。
並列可能な作業はまとめて示す
> 出典: river-review `rr-upstream-create-plan-001`（skill インベントリ監査で
> 「plan を作る側 = PlanGate の責務」と整理され移管。s977043/river-review#1105）
## CLI 呼び出し
> **配布と対象 project root は別の問題（#962 / #1144）**: plugin / `install.sh --claude` / Codex は
> `bin/plangate` と enforcement scripts を導入先へ配布しない。そのため CLI を使うには
> PlanGate の clone と、その `bin/plangate` への PATH または絶対パスが必要。
> ただし #1497 以降、CLI が利用できる場合の対象 project root は全コマンド共通で
> **`--project-root` → `PLANGATE_PROJECT_ROOT` → cwd の git root → CLI root fallback**
> の順に解決される。導入先の git repo で PATH 上の `plangate` を実行すれば、その導入先が
> 既定の対象になる。CLI が無いことを理由にゲートや検証を黙って省略してはならない。
>
> #1497 で downstream 契約を明示検証したのは `status` / `validate` / `approve` /
> read-only `doctor`（および work-dir を明示する `render`）。`doctor --fix` は #1144 の
> enforcement 配布が解決するまで downstream では **rc=2 / no-write** で fail-closed。
> script-relative helper に委譲するコマンドは、root resolver が存在しても自動的に
> downstream 対応になるとは扱わず、下表・フォールバックの個別契約に従う。
**呼び出し表記**: 上流 clone の cwd では `bin/plangate`、導入先で PATH を通している場合は
`plangate` を使う。別の対象を明示する場合は `plangate --project-root <dir> ...`。
`./scripts/ai-dev-workflow` はこの project-root resolver の対象外で、引き続き上流 clone 基準。
| 実行環境 | plan 生成 | plan_hash 機械検証 |
|---------|----------|-------------------|
| 上流リポジトリの cwd | `./scripts/ai-dev-workflow TASK-XXXX plan` | `bin/plangate validate TASK-XXXX` |
| 導入先 + PATH に `plangate` あり | `plangate plan` は script-relative workflow に委譲するため **#1497 の downstream 保証外** → 手動生成 | `plangate validate TASK-XXXX`（cwd git root を対象。必要なら `--project-root <dir>`） |
| 導入先 + PATH に無い（**既定**） | 手動生成 | 次節のフォールバック（sha256 突合） |
> **project root 契約**: `plangate` の `TASK-XXXX` は選択済み project root の
> `docs/working/TASK-XXXX` を基準に解決する。これは `scripts/ai-dev-workflow` の
> script-relative root 解決とは別契約である。
### CLI 不在時のフォールバック### CLI 不在時のフォールバック（導入先では既定）
`scripts/ai-dev-workflow` と `bin/plangate` は **3 経路のいずれでも導入先に
配置されない**。根拠は経路ごとに異なる:
- `install.sh --claude` 経由: コピー対象が `agents` / `skills` / `commands` / `rules` の
4 ディレクトリに限られ、`bin/` も `scripts/` も対象外
- plugin（Claude marketplace）経由: `${CLAUDE_PLUGIN_ROOT}/scripts/` は存在するが中身は
`install-plangate-skills.sh` のみ。`bin/` はバンドルに無い
- Codex 経由: 配置されるのは skills のみ
上表の「導入先 + PATH に無い（既定）」に該当する場合は次に従う:
1. **手動生成に切り替える** — 「Output」の 5 ファイルを skill の手順どおり手で作る。
B-1 →（事前メトリクス検証）→ B-2 → B-3 の順序と出力契約は **CLI の有無に関わらず不変**
2. **`plan_hash` 整合検証は標準コマンドで代替する（スキップしない）** — `plangate validate`
の plan_hash 検査は **`plan.md` の素の sha256**（正規化・前処理なし）と `c3.json` の
`plan_hash` から `sha256:` prefix を除いた値の単純比較なので、CLI 無しで再現できる:
```sh
# 算出（sha256sum が無い環境では shasum -a 256 を使う）
sha256sum docs/working/TASK-XXXX/plan.md | awk '{print $1}'
# 突合先: docs/working/TASK-XXXX/approvals/c3.json の "plan_hash": "sha256:<この値>"
```
**不一致なら C-3 承認後に plan が改変されている** → exec に進まず、再承認
（`c3.json` の `plan_hash` 更新）または plan の revert を行う。
`sha256sum` / `shasum` の**両方とも無い場合に限り**スキップし、その事実を
`decision-log.jsonl` と plan.md に記録して **「機械検証済み」と書かない**
（未検証を検証済みと誤記しない）
3. **ゲートは人手で維持する** — plan_hash を照合する hook も導入先には配線されないため、
item 2 の突合は **exec 開始前に自分で実行する**。C-3 は人間の明示承認記録
（`docs/working/TASK-XXXX/approvals/c3.json` 相当）で成立させ、CLI が無いことを理由に
C-3 を省略しない
4. CLI による機械検証が必要なら PlanGate の clone を用意し、導入先 repo の cwd から
`plangate validate TASK-XXXX` を実行するか、任意の cwd から
`plangate --project-root <導入先repo> validate TASK-XXXX` を実行する。
既存の `validate --dir <TASKディレクトリ>` も明示パス指定として利用できる
## 次フェーズへ
plan 完了後は `plan-review-gate` skill で C-1 → C-2 → C-3（c3.json APPROVED）。exec は `ai-dev-exec` skill。