roadmap

ロードマップ

概要

ロードマップは、大きすぎるアイデアを永続的で、チェックポイントに分割された構成に変換します。つまり、チェック可能なステップで構成され、各ステップはアプリを壊さずに単独でリリースできるほど小さく、チケットまで追跡できるドキュメントです。これは拡張版の仕様書ではありません。仕様書は一貫性のある1つの変更を記述しますが、ロードマップは順序付けられた変更の連続と、その間の状態を記述します。

このスキルは、ロードマップ関連のすべてを起動する唯一のトリガーです。保存場所、命名、状態ファイルの規約（以下に記載。すべてのリファレンスファイルで共通）を管理し、実際のプロセスに適したリファレンスへ案内します。

状況	読むファイル
新しいロードマップを作成する	references/writing.md
「ロードマップを続けましょう」という一般的な依頼で、ドキュメントの追加を意味するのか、実装の開始を意味するのかが不明な場合	references/resuming-work.md
ユーザーが特定のチェックポイント／タスクを指定して、着手または開始を依頼する	references/executing-checkpoints.md
複数のステップの仕様書／計画をまとめて作成・検証する（このロードマップから、または明示されたタスク一覧から）	references/batch-plan-validate.md
最新のデフォルトブランチ、オープン PR の状態の反映、ブランチ内の他のロードマップの非表示（上記すべてに共通）	references/sync-and-isolate.md

上記のいずれかを行う前に（新しいロードマップの作成を除く）、references/sync-and-isolate.md のセクション A と B を実行してください。フェッチし、デフォルトブランチで変更された内容を確認して（デフォルトブランチとロードマップ関連ブランチのどちらから作業する場合も）、ロードマップのデータを読み取った後、オープン PR にすでに含まれるロードマップ作業の状態を反映します。同じファイルのセクション C（作業ツリーから他のロードマップを取り除く）は、チェックポイントを選択してそのブランチを作成した後に一度実行します。

状況に応じたリファレンスのみを読んでください。どのリファレンスも、このファイルに記載された保存場所、命名、状態ファイルの規約を共通の前提としているため、リファレンスごとにその内容を再導出する必要はありません。

厳守事項。例外はありません： このスキルで作成するロードマップファイル、すべての設計／仕様書、すべての実装計画（直接作成する場合も、superpowers:brainstorming／superpowers:writing-plans を介する場合も）は、依頼がどの言語で書かれているかにかかわらず、すべてロシア語で記述します。見出し、本文、タスクの説明も例外ではありません。コードブロック、識別子、ファイルパス、チケット ID は元の表記のままにします。実装計画では、superpowers のマークアップは英語のままにします（task-brief スクリプトで解析される ### Task N: <русское название> 形式の見出しに加え、チェックボックス、および Step／Files／Interfaces／Global Constraints のラベル）。プロジェクト独自の rules/skills/writing-plans.md／rules/skills/brainstorming.md が存在する場合は、同じルールを優先事項として定めています。このルールは、そのファイルの有無に左右されません。

ワークフローレシピ

ロードマップ規模の機能は、3 つのフェーズを経て進みます。それぞれのフェーズは、ここで参照する 1 つのドキュメントだけで完結し、別途オーケストレーターを用意する必要はありません。

• フェーズ 1 — ロードマップ： references/writing.md。機能を分析し、チェックポイントに分解します（基本原則：各ステップの完了後もアプリをビルド可能な状態に保つ）。そのうえでロードマップを作成します。機能の目標と要件はロードマップ自体の Context セクションに記載し、個別の PRD ドキュメントは作成しません。
• フェーズ 2 — ステップごとの仕様、検証済み： ロードマップのチェックリストを対象に references/batch-plan-validate.md を使い、タスクごとの下書きモードを brainstorming、設計のみ に設定します。ここでは、まだ実装計画を作成しません。結果として、各ステップについて、標準の EnterPlanMode → ExitPlanMode → Plannotator ループを通じてレビューされた、検証済みの設計／仕様（brainstorming）が作成されます。これには、そのステップの要件と成功基準も含まれます。
• フェーズ 3 — 必要な時点で作成するステップごとの実装計画： 実際に作業に着手するステップについて references/executing-checkpoints.md を呼び出します。その時点で、ステップの承認済み仕様を見つけ、実装計画（superpowers:writing-plans）を作成します。ロードマップを最初に分解した時点ではなく、作業開始時のリポジトリの状態を反映した計画にするためです。

フェーズ 2 で全ステップの実装計画を先に作成しないでください。それを防ぐために、フェーズ 2 の設計のみモードがあります。

保存先

• 場所：リポジトリのルートにある docs/<feature-slug>/。Git で追跡し、移行／ロールアウトの履歴として恒久的に保存します。tmp/ には保存せず、チェックポイントのリリース直後に削除することもありません。
• ここに書き込むには、brainstorming／writing-plans と同様に、最初にネイティブの Plan Mode を使用する必要があります。

保存先の優先順位

上記で定義したステップフォルダーの保存先（docs/<feature-slug>/steps/<step-slug>/...、恒久保存、Git 追跡）は、writing-plans／brainstorming に対するプロジェクトレベルの一般的な保存先の上書き設定（例：「計画／仕様はプロジェクトのルートに保存し、実装後に削除する」）よりも、ロードマップのステップに属する成果物について優先されます。プロジェクトの計画／仕様の保存先に関する上書き設定は、ロードマップのステップ外で作成する単独の計画や仕様には、そのまま適用されます。この優先順位のルールが対象とするのは、ロードマップのステップに属する成果物のみです。references/writing.md では、プロジェクト独自の規約と既定値が矛盾する場合はプロジェクト独自の規約が優先されるとすでに述べています。このセクションは、ステップレベルの成果物に対する明示的な例外です。

PRD ドキュメントは作成しない

ロードマップとそのステップには PRD を含めません。機能レベルの目標、現在の状態／目標状態、厳守すべき制約はロードマップの Context セクションに記載します。ステップの要件と成功基準は、専用の要件セクションを設けた設計／仕様（-design.md）に記載します。どちらのレベルでも *-prd.md ファイルを作成しないでください。

ファイル名

ファイル	目的
docs/<feature-slug>/YYYY-MM-DD-<feature-slug>-roadmap.md	ロードマップ本体です。各チェックポイント／ステップは、最上位のチェックボックスとして記述します：- [ ] <TICKET> <short name>。プロジェクトで実際に使われている課題トラッカーのプレフィックス（例：SCB-NNN）を使用します。チケットがまだない場合は、その箇所にプレースホルダーの TBD をそのまま使用します。
docs/<feature-slug>/roadmap-state.json	各チェックポイントの機械可読な進捗状態です。下記の ## State File を参照してください。
docs/<feature-slug>/steps/<step-slug>/YYYY-MM-DD-<step-slug>-design.md	ステップの仕様です。brainstorming によって作成される、ステップの要件、成功基準、および必要な場合はアーキテクチャ上の決定を記載します。
docs/<feature-slug>/steps/<step-slug>/YYYY-MM-DD-<ticket>-<name>.md	writing-plans によって作成される、ステップの詳細な実装計画です。

各ステップには、docs/<feature-slug>/steps/ の下に、そのステップ固有のスラッグで名前を付けたフォルダー（例：steps/general-information/）を作成します。単なる番号にはしません。各ステップの 2 つのドキュメント（仕様、計画）は同じフォルダーに保存します。アーキテクチャ上の決定が不要なステップには計画だけを置き、-design.md は作成しません。

状態ファイル

docs/<feature-slug>/roadmap-state.json は、ロードマップ全体の進捗を追跡します。各チェックポイントに仕様書、検証済みの仕様書、計画があるか、実装済みか、完了しているかを記録するため、進捗管理を Markdown のチェックボックスだけに頼らずに済みます。保存ポリシーはロードマップ自体と同じです。Git で追跡し、恒久的に保持し、ロードマップ自体が削除されるまで削除しません（下記「ロードマップのすべての項目にチェックが付いたとき」を参照）。

{
  "feature": "<feature-slug>",
  "roadmapPath": "docs/<feature-slug>/<date>-<feature-slug>-roadmap.md",
  "updatedAt": "<ISO-8601>",
  "steps": [
    {
      "id": "A1",
      "title": "...",
      "ticket": "TBD",
      "dependsOn": [],
      "stepFolder": "docs/<feature-slug>/steps/<step-slug>/",
      "status": "not-started",
      "specPath": null,
      "planPath": null
    }
  ]
}

status は次のいずれかをこの順番で取ります：not-started → spec-drafted → spec-validated → plan-drafted → implemented → closed。設計ドキュメントがないステップ（writing-plans を直接使って作成した場合や、アーキテクチャ上の判断が不要なステップ）では、spec-* の段階を省略します。ステータスは not-started から specPath: null のまま plan-drafted に直接進みます。

ファイルを更新する担当者とタイミング：

• references/writing.md はロードマップを保存した直後にファイルを作成します。各チェックポイントにつき 1 つのエントリーを作成し、status: "not-started" とします。stepFolder は、すぐにフォルダーが作成されたチェックポイントにのみ入力します（ほとんどのチェックポイントは Phase 2/3 で着手するまでフラットな状態のままです）。
• references/batch-plan-validate.md は、タスクのフェーズが移行するたびにファイルを更新します。Phase 1 で設計／計画を作成した場合は spec-drafted と specPath を設定します。writing-plans を直接選択した場合は plan-drafted と planPath を設定します。Phase 2 で承認されたら spec-validated に更新します（計画を直接検証した場合は plan-drafted のままです）。stepFolder がまだ空の場合は、これも入力します。
• references/executing-checkpoints.md は、ステップに着手したとき（Phase 3）にファイルを更新します。実装計画を作成した後に plan-drafted と planPath を設定し、実装の最終検証に合格した後に implemented に更新します。完了処理時（チェックボックスにチェックを付け、計画ファイルを削除した後）に closed と planPath: null を設定します。

依存関係

チェックポイントの Markdown 行の末尾には、機械可読な依存関係タグ (depends: <id>[, <id>...]) を付けられます。このタグには、先に完了しておく必要があるチェックポイントを列挙します。単独の <id> は同じロードマップ内のチェックポイントを指し、<feature-slug>:<id> は隣接するロードマップ内のチェックポイントを指します。<feature-slug> は、そのロードマップの docs/<feature-slug>/ フォルダー名です。チェックポイントに依存関係がない場合は、タグを完全に省略します。ほとんどのチェックポイント、特に別のステップにあり、それぞれ独自の設計が整うのを待つだけのチェックポイントには、依存関係がありません。認証やユーザーに関する前提条件、無関係な PR のマージなど、その他の外部依存関係は、チェックポイント自体の行、またはロードマップの Context／Зависимости от ... セクションに自由形式の文章として記載します。

- [ ] 1.1b — [backend] ... (Jira: ACD-59) (depends: 1.1a)
- [ ] A1 — [ui-kit] ... (Jira: TBD) (depends: ui-kit-e2e:B1, ui-kit-e2e:B2)

docs/<feature-slug>/roadmap-state.json には、同じ情報が機械可読な形式で反映されます。各ステップの項目には "dependsOn": string[] フィールドが設定されます（タグと同じ表記のチェックポイント ID を配列に記述します。例："A1" または "ui-kit-e2e:B1"。依存関係がない場合は空の配列です）。references/writing.md は、状態ファイルの作成時に Markdown のタグからこの情報をそのまま設定します（上記の ## State File を参照）。

チェックポイントが着手可能となるのは、未チェック (- [ ]) であり、dependsOn のすべての項目が満たされている場合です。単独の ID は、このロードマップの roadmap-state.json で該当ステップの status: "closed" が設定されていれば満たされています。<slug>:<id> の項目は、同じ方法で docs/<slug>/roadmap-state.json を参照し、次のように判定します。

• docs/<slug>/ が存在しなくなっている場合は、満たされています。すべてのチェックが完了したロードマップは削除されるためです（「ロードマップのすべてのチェックが完了したとき」を参照）。
• フォルダーは存在するものの、状態ファイルがない場合は、そのロードマップの Markdown にある依存先のチェックボックスを参照します（- [x] = 満たされています）。
• 状態ファイルは存在するものの、その ID のステップがない場合、参照は無効です。推測で判断せず、タグを修正するようユーザーに伝え、チェックポイントをブロック状態として扱います。

ロードマップをまたぐ参照は一方向で読み取り専用です。チェックポイントが別のロードマップのファイルを編集することはありません。複数のチェックポイントが同時に着手可能な場合もあります。これにより、安全に並行して進められます。references/executing-checkpoints.md は、常に厳密な上から下への順序を前提とするのではなく、この仕組みに基づいて提示可能なチェックポイントを判断します。

コミットポリシー

ユーザーから明示的な依頼がない限り、ロードマップ／仕様／計画のファイルは自動的にコミットしません。他のすべての成果物と同様に、ユーザーから明示的に依頼された場合にのみコミットします。

ロードマップのすべてのチェックが完了したとき

ロードマップ内のすべてのチェックボックスが - [x] になったら、ロードマップファイルと、空になった場合は docs/<feature-slug>/ フォルダーも、不要なファイルとして残さず削除します。この処理が実行される正確なタイミングについては、references/executing-checkpoints.md を参照してください。