track-roadmap

Track Roadmap

概要

プロジェクトのルートにある ROADMAP.md を継続的に更新する高レベルの機能計画として管理し、次に何を作るかを意図的に決められるようにします。**タスクではなく機能（ユーザーから見える能力）**に絞ってください。タスクレベルの作業は track-session に記載します。適切なロードマップは、確定した機能が5〜15件あり、2分以内で読めるものです。

ワークフロー

すべてのモードで、現状を読む、変更を提案する、ユーザーに確認する、ファイルに書き込むという同じ4段階を実行します。異なるのは中央の2段階だけです。

モード	コマンド	提案／確認
生成	/track-roadmap または generate	コードベースのスキャンを提案し、探索のための質問を4つ行い、機能リストを提案して、ユーザーの確認後に書き込みます
更新	/track-roadmap update	変更点（追加／削除／完了／表現の変更）を尋ね、確認後に反映します
監査	/track-roadmap audit	コードをスキャンして各機能に「完了／進行中／未着手／不明」のステータスを付け、ユーザーと関連性を確認して更新します
ブレインストーミング	/track-roadmap brainstorm	方向性を決める前にアイデアを広げます。実現可能なアイデアは status:idea として「今後のアイデア」に追加します
再開	/track-roadmap resume	セッションの状態を確認し、残っている機能を提示して、ユーザーに1つ選んでもらい、/track-session に引き継ぎます

最もよく使われるのは更新です。項目の追加、完了のマーク、リリース済みの作業の記録は、すべてこのモードで行います。save モードはありません。/track-roadmap save は更新として扱ってください。ユーザーがロードマップ全体を順に進めたい場合は、再開モードでファイル内の順序に従って未完了の機能を取り上げ、機能ごとに1つのセッションを実行します。各セッションが終了した後は確認を求めずに次へ進みます。更新と監査では、ファイル全体を作り直すのではなく、影響を受ける項目をその場で編集してください。そうすれば、ID、順序、変更のないテキストは維持され、同じ結果を得るためにファイル全体を書き換えるよりトークンを節約できます。ファイルを一から書き込むのは生成モードだけです。

モードごとの詳しい手順（探索のための質問、ブレインストーミング用の質問集、監査手順）については、reference/MODES.md を参照してください。

ROADMAP.md の形式

---
schema: cc-dash/roadmap@1
project: project-name-here
description: One-line project purpose
last_updated: YYYY-MM-DDTHH:MM:SS-TZ
---

# Roadmap

> Project purpose in one sentence.

## Core Features



-  **Feature Name** - What it does and why it matters.
  > Research finding, with its source link.
  > Open: the question still to settle.
-  **Feature Name** - Short description.

## Future Ideas



-  **Feature Name** - Short description.

## Completed



-  ~~**Feature Name**~~ - Short description. *(Completed: YYYY-MM-DD)*

形式のルール。 cc-dash ダッシュボードはこのファイルを解析するため、マーカーが欠落すると、その項目は通知されずにボードから削除されます。

• フロントマターには schema、project、description、last_updated が必要です。
• 各項目には id と status が必要です。ID は r_ + 2～10 文字の [a-z0-9_] で、永続的なものであり、変更しないでください。新しい ID は、デフォルトでランダムな 5 文字です。新しい ID を書き込む前にファイル内を grep してください。重複すると、ボード上で 2 つの項目を区別できなくなります。
• ステータスは idea／planned／in-progress／done に加え、（引き続き希望されているものの、今すぐではない場合の）deferred と、項目を削除する代わりに中止した理由を記録しておきたい場合の dropped／skipped／rejected／cancelled です。最後の 4 つは、ボードの「Closed」列に表示されます。
• 任意のメタデータとして、YYYY-MM-DD 形式の started: と completed:、および depends:r_abc12,r_def34 を指定できます。cc-dash はそれ以外の日付キー（at:、done_date:）を無視し、次回の書き込み時に削除するため、項目に手を加える際にそれらを completed: に変換してください。
• 各カテゴリの見出しの次の行には `` を記述します。カテゴリは自由に設定でき、プロジェクトに合ったグループを作成してください。
• 各機能は 1 行で記述します。太字のタイトルと、1～2 文の説明を含めてください。
• メモには、説明に書ききれない内容を記載します。参照元を明記した調査結果、未解決の質問、却下した代替案とその理由などです。項目の直下に > から始まる行として記述してください。cc-dash はカードにメモを表示し、独自の書き込み後も保持します。メモは項目ごとに 5 行程度までにしてください。調査内容がそれ以上になる場合は、docs/ 内のファイルに移し、そこへのリンクをメモに 1 つ残してください。調査内容をロードマップに直接書き連ねると、すぐに読みにくくなるためです。メモを説明に含めたり、項目の下に 2 つ目の段落として記述したりしないでください。ダッシュボードはどちらも読み取りません。
• 項目が「Completed」に移ったら、後日の監査に必要な内容（決定事項とその理由）だけを残すよう、メモを整理してください。調査の役目は終わっているためです。

ルール

• ロードマップの変更はユーザーが決めます。機能を独自の判断で追加、言い換え、削除するのではなく、変更案を提示して確認を待ってください。
• 概要レベルにとどめます。「ユーザー認証」のように記述し、「パスワードのハッシュ化に bcrypt を追加」のような実装の詳細は記載しないでください。
• ROADMAP.md が唯一の情報源です。ファイルに記載されていなければ、ロードマップ上の項目ではありません。
• 完了した機能は削除せず、移動します。削除する代わりに、completed: の日付を付けて「Completed」セクションに移動してください。監査ではこの履歴が証拠として使われるためです。

例

❌ 悪い例 — - tasks／- lists／- make it look good／- fix bugs：説明がなく、グループ分けもなく、機能とタスクが混在し、ID も目的もありません。上記の形式ブロックが✅の例に当たります。

✅ 良い例 — 更新モードで、ユーザーが 「昨日ダークモードをリリースした」 と伝えた場合：ID は維持し、ステータスを変更して日付を追加し、行を「Completed」に移動します。

-  ~~**Dark mode**~~ - System-level dark/light theme preference. *(Completed: 2026-03-14)*

generate、audit、update、brainstorm、resume モードの✅／❌の詳しい比較については、reference/EXAMPLES.md を参照してください。

統合

• track-session — 機能を選んだ後、track-session を使用して実装を計画・追跡してください。SESSION_PROGRESS.md では ROADMAP の項目 ID を参照します。
• 実地検証（プレイスルー、パリティゲート、リリース承認など）も、ここでは通常のロードマップ項目です。別のチェックリストファイルはないため、そこから何かを書き戻すこともありません。

注意点

• 機能の名前を変更しても、IDはそのままです。 タイトルのテキストを編集し、`` はそのままにしてください。SESSION_PROGRESS.md の roadmap_ref の値と cc-dash の履歴は、どちらもこのIDを参照しています。マージする場合は、残すIDを維持してください。分割する場合は、元のIDを片方に残し、もう片方には新しいIDを生成してください。
• roadmap_ref に設定できるIDは1つだけです。 cc-dash はカンマ区切りのリストを警告とともに破棄し、セッションとボードの紐付けを解除します。1つのセッションで複数の機能を進める場合は、主要な機能を紐付け、残りはセッションの ## Current Status に記載してください。
• 再開すると、アクティブなセッションの計画が上書きされます。 SESSION_PROGRESS.md に未完了のタスクがある場合は、ロードマップを提示する前に、そのセッションを続行するか確認してください。機能を切り替えるとこのファイルが置き換わるため、先に /track-session save を提案してください。
• 監査の証拠が曖昧な場合は、推測せず Unclear とします。 テストのない src/auth/ のような不完全なコードや実験的なコードは、完了として評価せず、判断を仰ぐためユーザーに提示してください。
• 30項目以上のロードマップは、維持すべき状態ではなく、見直しの合図です。 監査を行い、推測的な項目は status:idea として「Future Ideas」に移し、現状に合わないものは削除してください。履歴は git に残るため、ファイル内でアーカイブすると余計なノイズが増えるだけです。
• ロードマップのずれは想定内です。 ファイルの内容が実際の開発状況と合わなくなったら、記憶を頼りに個々の行を修正するのではなく、audit を実行して整合させてください。

コードベーススキャンのノイズ、ブレインストーミングの行き詰まり、優先順位を決められない状態、曖昧な機能説明の明確化など、さらに詳しいエッジケースについては、reference/TROUBLESHOOTING.md を参照してください。