| name | x-planning-implementation |
| description | 別のAIコーディングエージェントが実行できる粒度の実装計画を作成するスキル。 口頭説明・要件定義書・断片的な依頼など、曖昧なタスクを実行可能な計画ファイルに変換する。 「計画を立てて」「実装計画を作って」「要件を整理して」「これをプランに落として」 「タスクを整理して」「スコープを決めて」「何から手をつければいい」「どう実装する」 「設計してから進めたい」「計画を見直して」「計画をブラッシュアップして」 「計画を改善して」「実装直前だが一度整理したい」「要件が走り書きなので計画に落として」 のような依頼で使う。 明示的に「計画を」と言われなくても、依頼が大きすぎる・曖昧すぎてそのまま実装できない場合は 積極的にこのスキルを起動する。`x-grill-me` でユーザーへの確認を行い、 品質ゲートを通過するまでイテレーションする。
|
| allowed-tools | ["Bash","Read","Write","Glob","Grep","Skill","AskUserQuestion","TaskCreate","TaskUpdate","TaskList"] |
planning-implementation
実装計画を作るためのスキルです。口頭説明・要件定義書・断片的な依頼を入力として受け取り、別のAIコーディングエージェントがそのまま実行できる粒度の計画ファイルを出力します。
責務は「計画を作ること」だけです。実装しません。質問もこのスキル単体ではしません（必要なら x-grill-me を呼びます）。
このスキルを使う場面
- 曖昧な依頼を構造化して、実行可能な計画に落としたいとき
- 要件定義書やDesign Docを、AIコーディングエージェント向けに変換したいとき
- 口頭の打ち合わせ内容から計画を起こしたいとき
- 複数の前提が絡み合っていて、整理してから着手したいとき
- 既存の計画ファイルをレビューして、品質を高めたいとき
このスキルを使わない場面
- すでに完成した計画があり、改善も不要で実装に進みたいとき → 直接実装エージェントを起動します
- ワンライナーで終わるタスク → 計画を作るオーバーヘッドの方が大きいです
- 質問だけしたいとき →
x-grill-me を直接使います
中核原則
1. Investigate-first, Ask-second
まずコードベースとドキュメントを調査して不明点を自己解決します。質問するのはビジネス判断・スコープ判断・複数妥当解の選択など、調査しても決められないものだけです。
2. 機械検証可能な完了条件
Acceptance Criteriaはテスト・型・Lint・コマンド実行・MCP経由のブラウザ確認・E2Eなど、真偽が判定できる形で書きます。「適切に」「いい感じに」「ちゃんと」などの曖昧語が残っている計画は提出しません。
3. 品質ゲートを通過するまでループする
自己レビュー（Quality Gates）→ review-criteria.mdによるレビュー → ユーザー確認の3段で品質ゲートを通します。各ゲートで指摘が出たら修正してループします。ゲートを通らないまま提出しません。
4. 失敗を早期に可視化する
ループの上限に達してもゲートが通らない場合、隠さずに「何がブロッカーなのか」をユーザーに提示します。妥協した計画を黙って出すよりも、ブロッカーを共有する方が誠実で速いです。
プロセス（9フェーズ）
各フェーズの完了条件を満たさない限り次に進みません。
タスク登録（実行開始時に必ず実施）
フローを開始する前に、全ステップをTaskCreateで登録します。各ステップを開始するときTaskUpdateでin_progressへ、完了したときcompletedへ更新します。
| # | subject | blockedBy |
|---|
| 1 | Phase 1: Intake（入力の正規化） | — |
| 2 | Phase 2: Investigation（コードベース調査） | 1 |
| 3 | Phase 3: Gap analysis & Self-fill（自己充填） | 2 |
| 4 | Phase 3.5: Use Case Mapping（ユースケース洗い出し） | 3 |
| 5 | Phase 4: Clarification（x-grill-me連携） | 4 |
| 6 | Phase 5: Drafting（初稿） | 5 |
| 7 | Phase 6: Self-review（自己レビュー） | 6 |
| 8 | Phase 7: External Review（review-criteria.mdによるレビュー） | 7 |
| 9 | Phase 8: User Confirmation（ユーザー確認） | 8 |
| 10 | Phase 9: Handoff（引き渡し） | 9 |
Phase 1: Intake（入力の正規化）
入力を受け取り、以下を区別した内部メモを作ります（ユーザーに見せる必要はありません）。
| 分類 | 内容 |
|---|
| Explicit | 入力に明示的に書かれていること |
| Implicit | 入力から推測できるが書かれていないこと |
| Ambiguous | 解釈が複数ありえる箇所 |
| Unknown | 入力にも周辺にも書かれていないこと |
完了条件は、4分類すべてに少なくとも1項目入っているか、空であることが意図的に確認されていることです。
Phase 2: Investigation（コードベース調査）
調査範囲の詳細ルールは references/investigation-rules.md を参照してください。
要点は以下の通りです。
| 区分 | 対象 |
|---|
| 最低限読むもの | package.json、tsconfig.json、関連featureのREADMEとディレクトリ構造、類似実装、既存のADR |
| 読まないもの | node_modules、ビルド出力、lockfile、関連が薄いfeature |
完了条件は、「このコードベースで、このタスクをやるなら、どこをどう触るか」を言語化できる状態になっていることです。詳細は references/investigation-rules.md の「完了判定」を参照してください。
Phase 3: Gap analysis & Self-fill（自己充填）
Phase 1のAmbiguousとUnknownを、Phase 2の調査結果から答えられるものは埋めます。この段階で大半を埋められることを期待します。埋められないものだけPhase 4に進みます。
各項目を以下のいずれかに分類します。
| 分類 | 内容 |
|---|
| Decided by code | コードベースを根拠に決定（根拠を併記） |
| Decided by default | 業界標準・既存パターンのデフォルトを採用 |
| Needs user input | ユーザー判断が必要 |
完了条件は、全項目がいずれかに分類済みであることです。「Needs user input」は3個以下が望ましく、それを超える場合は依頼の粒度が大きすぎるサインです。
Phase 3.5: Use Case Mapping（ユースケース洗い出し）
x-designing-usecases スキルを使ってユースケースを洗い出します。目的は「Acceptance Criteriaとテストで検証すべきシナリオの抜けを防ぐこと」です。
x-designing-usecases スキルへの引き渡し
以下の情報を添えてスキルを呼び出してください。
- 対象システムのタイプ（B2C / コンポーネントライブラリ / 管理ツール等）
- Phase 2で特定した関連ファイル・機能の概要
- このタスクがUI実装・関数実装・運用機能のどれに当たるか
タスクA / タスクB の選択基準
| 状況 | 呼ぶタスク |
|---|
| ユースケース表がまだ存在しない（このタスクが初回） | タスクB（ゼロからテスト計画を生成） |
| ユーザーが既存のユースケース表を持ち込んだ | タスクA → タスクB の順 |
x-designing-usecases が使えない場合
スキルが利用不可の場合は、x-designing-usecases の観点に準じて自前でユースケースを展開してください。最低限、系統（E/D/O）ごとに「正常系・異常系・境界値」を列挙した箇条書きで代替します。この場合はDecisions Logに「x-designing-usecases未使用、自前展開」と記録します。
このフェーズの使い方
洗い出したユースケースはそのままAcceptance Criteriaにする必要はありません。「Acceptance Criteriaには含めないが、テスト観点として実装者に伝えるべき」と判断したものは Open Questions for Implementation に流します。
このフェーズの成果物は計画ファイルの Use Cases セクションになります（Output Template参照）。
完了条件は、系統（E/D/O）のうち対象タスクに該当するもののユースケースが揃っており、各系統の正常系・異常系・境界値が網羅されていること。
Phase 4: Clarification（x-grill-me連携）
Needs user inputの項目があるときだけ x-grill-me を使って質問します。
質問の作り方（詳細は下記「x-grill-me連携の運用」を参照）は以下の通りです。
- YES/NO質問ではなく、選択肢A/B/Cと各選択肢の影響を提示します
- 一度にする質問は5個以下です
- 各質問に「なぜAIで決められなかったか」の理由を添えます
完了条件は、全質問に回答が得られていることです。
Phase 5: Drafting（初稿）
下記「Output Template」にしたがって計画を書きます。Phase 1〜4で得た情報とPhase 3.5のユースケースを全項目に反映します。
完了条件は、テンプレートの全項目が埋まっており、空欄や「TBD」が残っていないことです。
Phase 6: Self-review（自己レビュー）
下記「Quality Gates」のチェックリストを上から順に通します。失敗したら修正してリトライします。
ループ上限は3回です。3回で通らないなら、ブロッカーを言語化してPhase 8でユーザーに相談します。
完了条件は、全Quality Gatesがパスしているか、上限到達でブロッカーが特定されていることです。
Phase 7: External Review（review-criteria.mdによるレビュー）
references/review-criteria.md の観点リストにしたがって計画をレビューします。このファイルはAIコーディングエージェント向け実装計画固有の観点（Context正確性・Acceptance Criteria検証可能性・AI特有の思い込み発生ポイント等）が整理されており、Quality Gatesのセルフチェックでは見落としやすい箇所を補います。
指摘は以下に分類して対応します。
| 分類 | 内容 | 対応 |
|---|
| Critical | 計画が実行可能でなくなる | 必ず対応します |
| Major | 品質を下げる | 原則対応します。しない場合は理由をDecisions Logに記録します |
| Minor | 改善提案 | 取捨選択してよいです |
CriticalとMajorに対応した上でPhase 6に戻り、再度Quality Gatesを通します。
ループ上限はPhase 7の実行回数が3回です（Phase 6 → Phase 7のセットを1回と数えます）。3回目のPhase 7終了時点でまだCriticalが残っている場合は、計画の前提自体が揺れているサインなのでPhase 8でユーザーに相談します。
完了条件は、CriticalがゼロになっているかPhase 8でユーザーに相談済みであることです。
Phase 8: User Confirmation（ユーザー確認）
完成した計画をユーザーに提示します。提示する内容は以下の通りです。
- 計画ファイル本体
- Phase 6/7で対応しきれなかったブロッカー（あれば）
- ユーザーに最終判断を委ねた箇所のサマリ
提示後はユーザーの指摘を1点ずつ受け取り、確認してから次に進みます。複数の指摘をまとめて処理しません。
ユーザーから修正依頼が出た場合の対応は以下の通りです。
| 修正の種類 | 対応 |
|---|
| 小さい修正 | その場で適用してPhase 6から再走します |
| 前提が変わる修正 | Phase 1から作り直します |
完了条件は、ユーザーが計画を承認することです。
Phase 9: Handoff（引き渡し）
計画ファイルを保存します。保存先は docs/ 配下の既存ディレクトリ構造を確認した上で、タスクの対象領域に合致するサブディレクトリ内の plans/ に保存します。対応するサブディレクトリがない場合は新規作成します。複数領域にまたがる場合は docs/plans/ を使います。
<対象領域に対応する docs/ サブディレクトリ>/plans/<yyyymmdd>-<short-slug>.md
保存後、ユーザーに以下を伝えます。
- 保存したパス
- 実装エージェントを起動するコマンド例
- 実装中に前提が変わった場合の計画更新手順
Output Template（計画ファイルの構造）
各セクションの省略は不可です。該当なしの場合は「該当なし」と明記します。
# [タスク名（成果物単位で命名）]
## Context（前提・コードコンテキスト）
- 作業対象のリポジトリ/ディレクトリ: <パス>
- 関連するfeature/モジュール: <列挙>
- 新規作成・変更するファイルの配置先: <パス一覧>
- 技術スタックとバージョン: <列挙>
- 関連する既存ドキュメント・ADR: <リンク>
## Goal（目的・成果物）
[このタスクが完了したときに、何が観測可能になっているかを1〜3文で記述。
動機ではなく成果物を書く。「○○ページで△△ができるようになる」のレベルまで具体化する]
## Use Cases（ユースケース）
> Phase 3.5 で `x-designing-usecases` スキルが出力した内容をここに貼る。
### 系統E: エンドユーザー × UI（UIを持つ実装の場合）
- 正常系: [ユーザーが期待どおりに操作した場合]
- 異常系・エッジケース: [空・ゼロ・最大値・不正入力・通信失敗など]
- 境界値: [仕様で定義された上限・下限・変わり目]
### 系統D: 開発者 × コードAPI（関数・コンポーネント・フックを実装する場合）
- 正常な呼び出しパターン: [代表値・境界値・型バリアント]
- 異常な呼び出しパターン: [範囲外・想定外フォーマット・null/undefined]
- 副作用・戻り値: [型・構造・変換結果の確認]
### 系統O: 運用者 × 管理画面/CLI（運用機能を含む場合）
- 運用業務: [操作内容・影響範囲・権限境界]
- 監査: [ログ要件・ドライランの有無]
※ 該当しない系統は「該当なし」と明記する。
※ Acceptance Criteriaに含めない観点は Open Questions for Implementation に記載する。
## Non-goals（含めないこと・スコープ外）
- [スコープ外1: 具体的なファイル/機能名で]
- [スコープ外2: 具体的なファイル/機能名で]
- [スコープ外3: 具体的なファイル/機能名で]
## Constraints（制約）
- 守るべき設計原則: <既存のルール/ADRへの参照>
- 依存方向のルール: <例: features/からshared/への依存のみ許容>
- 変更禁止ファイル: <列挙>
- 影響するスキーマ・型: <変更・追加が必要な型定義やスキーマファイルのパス>
- 性能・セキュリティ要件: <具体的な閾値で>
- 使用してよい/してはいけないライブラリ: <列挙>
## References（参考実装・関連資料）
- 倣うべき類似実装: <ファイルパス>
- 参考になるPR/コミット: <リンク>
- スタイルガイド: <リンク>
## Acceptance Criteria（完了条件）
- [ ] [機械検証可能な条件1]
- 検証方法: `<コマンド>` または <手順>
- [ ] [機械検証可能な条件2]
- 検証方法: `<コマンド>` または <手順>
- [ ] [機械検証可能な条件3]
- 検証方法: `<コマンド>` または <手順>
## Decisions Log（判断記録）
- 判断: <内容> / 根拠: <コード参照やデフォルトの理由>
## Open Questions for Implementation（実装時の判断保留事項）
- もし<状況>なら、<こう判断する>
テンプレートの書き方の例
| セクション | 良い例 | 悪い例 |
|---|
| Goal | 「UserSettingsコンポーネントに通知設定タブを追加し、ユーザーがメール通知のON/OFFを切り替えてサーバーに保存できる状態にする」 | 「ユーザー体験を改善する」「設定機能を強化する」（観測可能でない） |
| Acceptance Criteria | 「pnpm test src/features/settings がすべてpassする / 検証方法: pnpm test src/features/settings」 | 「テストがちゃんと通ること」「いい感じにエラーハンドリングされていること」（曖昧語が残っている） |
| Constraints | 「features/settingsからfeatures/authへの直接importは禁止。共通処理はshared/経由にする（docs/architecture.md参照）」 | 「適切に依存関係を管理する」（具体性がない） |
Quality Gates（品質ゲート）
Phase 6で上から順にチェックします。1つでも失敗したら全体を不合格として修正に戻ります。
G1: 構造の完全性
G2: 具体性
G3: 検証可能性
- NG: 適切に / いい感じに / ちゃんと / きちんと / うまく / なるべく / 可能な限り / 必要に応じて
G4: 整合性
G5: サイズ
曖昧語チェック
grep -nE "適切|いい感じ|ちゃんと|きちんと|うまく|なるべく|可能な限り|必要に応じて" <計画ファイル>
ヒットした行はすべて修正対象です。
x-grill-me連携の運用
いつ呼ぶか
Phase 4で、Needs user inputに分類された項目があるときだけです。コードを読めばわかることを質問しません。
質問テンプレート
質問テンプレートの構成は以下の通りです。冒頭見出しは ## 計画作成中に判断できなかった項目があります とします。
各質問は以下の項目を含みます。
### Q1: [質問内容]- AIで決められなかった理由:[理由]
- 選択肢（各選択肢の影響を記載）
- A:[選択肢A]→[この選択を取った場合の影響]
- B:[選択肢B]→[この選択を取った場合の影響]
- C:[選択肢C]→[この選択を取った場合の影響]
- 推奨:[現時点での推奨と理由（あれば）]
やってはいけないこと
- コードを読めばわかることを質問すること
- 「どうしますか？」とオープンに丸投げすること（必ず選択肢を出します）
- 一度に5個以上の質問をすること
イテレーション制御のまとめ
| Phase | ループ上限 | 上限到達時の動き |
|---|
| Phase 6 (self-review) | 3回 | ブロッカーを言語化してPhase 8でユーザーに相談します |
| Phase 7 (review-criteria) | 3回 | 計画の前提が揺れている可能性を伝えPhase 8でユーザーに相談します |
| Phase 8 (user) | 上限なし | ユーザーが承認するまで継続します |
ユーザーの「もう十分」「これで進めて」という明示的指示があれば、Quality Gatesにまだ通っていない部分があっても提出してよいです。その場合は、通っていないGateを明記します。
アンチパターン
| アンチパターン | 内容 |
|---|
| 質問を先行させる | コードも読まずに x-grill-me を呼び出すことは、Investigate-firstの原則に反します。 |
| 未完成での提出 | Quality Gatesが未達のまま提出しません。 |
| 巨大な計画 | 1つの計画に10以上のAcceptance Criteriaを詰め込んでいる場合は分割します。 |
補足: 計画の階層化
依頼が大きすぎて1計画に収まらない場合、Epic計画とSubtask計画に分割します。
docs/plans/
├── 20260427-notification-feature/
│ ├── README.md # Epic計画（全体像とSubtaskへのリンク）
│ ├── 01-data-model.md # Subtask 1
│ ├── 02-api-endpoints.md # Subtask 2
│ └── 03-ui.md # Subtask 3
Epic計画とSubtask計画は、それぞれ独立してこのスキルのテンプレートとQuality Gatesを満たす必要があります。
補足資料
詳細ルールは以下を参照してください。
references/investigation-rules.md — Phase 2のコードベース調査ルール（Tier別読む対象、読まない対象、完了判定）references/review-criteria.md — Phase 7のレビュー観点（実装計画固有の11観点）
