ロードマップの生成
ロードマップとは、次に引き継ぐ人が、会話の内容を知らなくてもそのまま実行できる計画です。プロジェクトが何を目指しているか、どの順序で進めるか、各要素が完了したかどうかをどう判断するか、そしてまだ未解決の質問は何かを示します。ロードマップはコードの隣にリポジトリ内に置かれるため、他のすべてのファイルと同様にレビューされ、バージョン管理されます。
ロードマップは決定を記録します。決定を下すわけではありません。何かが未決定の場合、ロードマップはその旨を明記します。
リポジトリの規則が優先
何かを書く前に、リポジトリ独自の規約を確認してください：AGENTS.md、CLAUDE.md、CONTRIBUTING.md、ドキュメントやWikiのスキーマ、既存のロードマップなどです。これらがロードマップの保存場所、メタデータ、Issueのリンク方法、実行すべきチェックを決定します。これらの規約とこのスキルが矛盾する場合は、リポジトリの規約が優先されます。新しい形式を導入するのではなく、既存のロードマップの形式に従ってください。
ワークフロー
1. 依頼を明確にする
ユーザーが何を望んでいるかを特定します。それぞれに必要な作業量が異なります：
- 新しいロードマップ： プロジェクト、機能、移行、テスト作業などについて。
- 更新： 項目の追加・変更、フェーズの並び替え、決定事項の記録。
- リコンサイル： 既存のロードマップを実際にリリースされたものと整合させる。
- レビュー： ロードマップを読み、書き換えずにギャップを報告する。
2. 質問する前に証拠を集める
プロジェクトがすでに知っている情報を読み込みます：関連するコードとテスト、オープンおよび最近クローズされたIssue、マージ済みおよびオープンのPR、既存のドキュメント、その領域のコミット履歴。今日何が存在するか、何がすでに進行中か、以前に何が試みられたかをメモします。
この方法で学習できることは、ユーザーに質問しないでください。
3. 判断が必要な点について質問する
ロードマップの質はその背後にある判断に依存し、そのほとんどはユーザーに属します。長いリストではなく、短いラウンドで質問し、トレードオフが明白でない場合はなぜその質問が重要なのかを説明します。良いテーマ：
- ゴール： この取り組みを行う価値がある結果は何か、そしてそれが達成されたことを誰がどうやって知るのか？
- スコープ： 明確に除外するものは何か？変更してはいけないものは何か（API、データ形式、振る舞い）？
- 制約： 締め切り、リリース、人員、予算、プラットフォーム。
- 優先順位： この半分しかリリースできない場合、どちらを優先するか？
- リスク： 最も理解が進んでいない部分はどこか？最初に取り組むべきか？
- 完了条件： どのテスト、メトリクス、レビューを証拠とみなすか？
証拠が裏付ける場合は推奨事項を提案します。常にユーザーが「まだ決まっていない」と回答できるようにします。その回答は未解決の決定事項に記載し、推測で書いてはいけません。
小さな更新の場合は、すぐに作成に進みます。新しいロードマップの場合は、2〜3ラウンドの質問を想定してください。
4. 構造を選ぶ
- 1つのファイル（
ROADMAP.md、またはリポジトリに合った名前）がほとんどのロードマップに適しています。 - ディレクトリ（
roadmaps/<slug>/README.mdと補助ページ）は、計画に調査メモ、デザインスケッチ、テストマトリックスなど、作業項目を埋もれさせるような長い補足資料が必要な場合のみ使用します。メインページはすべての作業項目IDを保持します。
5. 作成する
以下のテンプレートを使用します。長期にわたって有用性を保つためのルール：
- 安定したID。 すべての作業項目に
R-001のようなIDを付与します。IDの番号を振り直したり、再利用したりしてはいけません。中止した作業はファイル内にdroppedとして理由とともに残します。 - フェーズには終了条件がある。 各フェーズは、完了したときに何が真になるかを示します。フェーズは依存関係を優先し、次にリスク、その次に価値の順に並べます。
- 完了条件は確認可能である。 誰かが検証可能な条件（通過するテスト、成功するコマンド、測定可能な数値）を書きます。「堅牢」「改善」「クリーン」などの言葉は避けます。
- 依存関係は明示的である。 IDでリストします。チームのコントロール外のもの（別のリポジトリ、ベンダー、決定事項など）は明記します。
- 証拠は完全なURLまたはリポジトリ相対パスでリンクし、他の場所にコピーされてもリンクが機能するようにします。
- 計画を説明し、会議を説明しない。 現在形、現在の状態で記述します。履歴は変更履歴に記載します。
6. 確認する
引き渡す前に：
- すべての項目にID、ステータス、少なくとも1つの完了条件がある。
- すべての依存関係が存在するIDを指している。
- 後のフェーズに依存するフェーズがない。
- 未決定の質問はすべて未解決の決定事項にあり、項目内に隠れていない。
- リンクが解決し、ファイルパスが存在する。
- リポジトリのフォーマットとドキュメントチェックが通過する。
- 変更履歴に今回の変更のエントリがある。
7. 報告する
作成または変更した内容、記録した決定事項、まだ未解決の質問をユーザーに伝えます。
ロードマップを現実と整合させる
作業が完了するにつれてロードマップは古くなります。整合させるには：
doneまたはdroppedではない項目をリストアップします。- 各項目について、マージされたPR、クローズされたIssue、完了条件を満たすコードを探します。
- すべての条件が満たされた場合のみ、項目を
doneとマークします。証拠をリンクします。 - 作業が計画と異なる形でリリースされた場合、実際に起こったことを反映するように項目を更新し、変更履歴に違いを記載します。
- 発見した新しい作業は、新しいIDを持つ新しい項目として追加します。
- 変更内容をユーザーに要約します。何かを削除する前には確認を取ってください。
ロードマップのレビュー
レビューのみを依頼された場合、書き換えはしません。重要度の高い順に報告します：
- 完了を判断する方法がないゴールやフェーズ
- 曖昧な完了条件を持つ項目
- 欠落している、または循環している依存関係
- 証拠が裏付けていないのに確定済みとして提示されている決定
- コードやIssueトラッカーがすでに完了または無関係であることを示している項目
- 欠落しているリスク：最も難しい、または最も理解が進んでいない部分が後半にスケジュールされている
テンプレート
# <プロジェクトまたは機能> ロードマップ
**ゴール：** <1～2文で結果を説明>
**ステータス：** <draft | active | complete | superseded>
**最終更新日：** <YYYY-MM-DD>
## コンテキスト
この作業が今重要な理由、現在の状況、証拠へのリンク。
## スコープ
- **含む：** …
- **含まない：** …
- **変更しない：** …
## ステータス凡例
| ステータス | 意味 |
| ---------------- | -------------------------------------------- |
| `planned` | 合意済み、未着手 |
| `in-progress` | 誰かが作業中 |
| `blocked` | 依存関係または決定を待っている（どちらかを明記）|
| `done` | すべての完了条件が証拠とともに満たされた |
| `dropped` | 実施しない（理由を明記） |
## フェーズ1: <名前>
**終了条件：** <このフェーズが完了したときに真になること>
### R-001: <短いタイトル>
- **ステータス：** planned
- **理由：** <これが解決する問題>
- **完了条件：**
- [ ] <確認可能なステートメント>
- **依存関係：** <ID、または「なし」>
- **証拠：** <Issue、PR、またはファイルへのリンク>
## フェーズ2: <名前>
…
## 未解決の決定事項
| ID | 質問 | 選択肢 | ブロック | 担当者 |
| ----- | ---- | ------ | ------- | ------ |
| D-001 | … | … | R-004 | … |
## リスク
| リスク | 可能性 | 影響度 | 緩和策 |
| ------ | ------ | ------ | ------ |
## 変更履歴
- <YYYY-MM-DD>: <変更内容と理由>
該当しないセクションは削除してください。小規模なロードマップは、ゴール、1つのフェーズ、変更履歴だけで十分かもしれません。
やってはいけないこと
- ロードマップが不完全に見えるからといって、決定をでっち上げること。
- 具体的な成果のない汎用的な項目（「ドキュメントを追加」「テストを改善」）で計画を水増しすること。
- 項目の番号を振り直したり、削除した項目を消すこと。
- PRのタイトルだけで完了条件を確認せずに
doneとマークすること。 - ロードマップの内容全体をIssueにコピーしたり、その逆をすること。代わりにリンクしてください。