track-session

セッションの進捗

概要

プロジェクトのルートにある SESSION_PROGRESS.md で複数セッションにわたる作業を追跡し、コンテキストを再構築することなく作業を一時停止して再開できるようにします。このファイルに価値があるのは、実際の状況と一致している場合に限られます。そのため、保存するよう指示されるのを待つのではなく、タスクの完了後、計画の変更後、失敗後、ユーザーに質問する前など、作業の節目ごとにチェックポイントを記録してください。

cc-dash ダッシュボードはこのファイルを取り込むため、以下のフロントマターのスキーマと HTML の id マーカーは装飾ではなく、機能上不可欠です。

ファイル形式

---
schema: cc-dash/session@1
project: project-name
session_id: s_YYYY-MM-DD_topic-slug
roadmap_ref: r_XXXXX          # optional — links a roadmap feature
started: YYYY-MM-DDTHH:MM:SS-TZ
last_updated: YYYY-MM-DDTHH:MM:SS-TZ
status: in-progress           # in-progress | paused | completed | blocked
---

# Session Progress

## Plan

- [ ]  Task: description
- [x]  Task: description

## Current Status

Working on: <current task>
Next: <specific next action — name files and functions, not "fix the bug">

## Decisions

-  Durable choice + why, so it isn't relitigated on resume

## Failed Attempts

-  Tried X: failed because Y, trying Z instead

## Completed Work

-  What was done

## Plan と ## Current Status は必須です。## Decisions、## Failed Attempts、## Completed Work は省略可能です。記録すべき内容がある場合に追加してください。

長さ： タスクごとに 1 行とし、Decision と Failed Attempts はそれぞれ 1～2 文にします。このファイルは状況を記録するものであり、物語ではありません。内容のないセクションや、要約の繰り返し、Completed Work にすでに記載された作業の再説明は避けてください。

コンテキストのリセット後も残すべき情報は、優先度順に、発生した問題とその解決方法（Failed Attempts）、提示・試行・却下した選択肢とその理由（Decisions）、ユーザーから依頼されたこと、除外されたこと、制約として指定されたこと（ユーザー自身の言葉にできるだけ近い表現で記述）、現在の正確な状況（Current Status）、未完了または約束したこと（Plan）、そして再構築が難しい詳細情報（名前、数値、正確な表現、リンクなど。変更せず記載）です。これらについては、長くなっても漏れなく記録してください。自分自身の推論は、結論だけにまとめてください。

ID： t_（タスク）または f_（失敗した試行）の後に、[a-z0-9_-] の文字を 1～20 個続けます。デフォルトではランダムな 5 文字を使うか、t_redis-mw、t_authfix のような意味のあるスラッグを使います。同じ形式は task: と ref: にも適用され、それぞれ ID を 1 つだけ指定します。roadmap_ref に指定するロードマップ ID も 1 つだけです。1 つのセッションで複数の機能を進める場合は、その他の機能を ## Current Status に記載します。ID は一度記載したら固定してください。dep: の参照先になるためです。計画項目にはすべて id と dep（dep:none または dep:t_XXXXX）を指定します。

失敗したアプローチは、理由とともにすべて記録してください。 そうすれば、理由もなく再試行することを避けられます。MCP サーバーに接続できなかった、認証情報がなかった、サービスが停止していたなど、環境に起因する失敗の場合は、その旨を項目に記載してください。後続のセッションでは環境が異なる可能性があるため、再確認しても同じ試行の繰り返しにはなりません。

ワークフロー

引数なしでの振り分け

/track-session を引数なしで実行した場合、最初に該当する分岐を選び、そこで停止します。

1. プロジェクトのルートに SESSION_PROGRESS.md がない場合 → Start。ロードマップや git 履歴からファイルを再構築してはいけません。それは recover の役割であり、依頼された場合に限って行います。
2. ファイルが存在し、この会話でファイルにまだ記録されていない作業が発生している場合（last_updated 以降の編集、テスト実行、決定など）→ checkpoint を行ってから作業を続けます。
3. ファイルの status: completed が設定されている場合 → 前回のセッションが終了したことと、完了した内容を伝えてから、次の機能を選ぶため /track-roadmap resume に引き継ぎます。ユーザーがすでに新しい作業を指定している場合は、Start に進みます。
4. それ以外の場合（新しいコンテキストで、ファイルだけが記録として残っている場合）→ Resume。

判断の基準は、ファイルの見た目がどれだけ完成しているかではなく、現在の会話に未記録の作業があるかどうかです。2 と 4 の両方に当てはまりそうな場合は、決め手として checkpoint を選んでください。ほとんど内容のない差分を書いても 1 ターンで済みますが、未記録の作業を残したまま再開すると、その作業がファイルから抜け落ち、次のセッションに古い計画を引き継ぐことになります。

開始モード

上書きしようとしているファイルから引き継ぐのではなく、リポジトリ（フォルダー名、package.json、pyproject.toml）から project: を導き出します。時計（チェックポイントを参照）に基づいて started と last_updated を設定し、status: in-progress にして、少なくとも ## Plan と ## Current Status を記述します。

すでに SESSION_PROGRESS.md がある場合は、それを読んでから、git が追跡しているか確認します。これによって、置き換えを元に戻せるかどうかが決まります。

git ls-files --error-unmatch SESSION_PROGRESS.md   # exit 0 = tracked; non-zero = untracked or ignored

• 同じ作業が未完了 → これは開始ではなく、再開です。ここで止めます。
• 追跡対象で、前回のセッションが completed／paused であり、無関係 → ユーザーに確認してからファイルを置き換えます。古いコピーは git に残っています。
• 追跡対象外、または gitignore 対象 → まず SESSION_ARCHIVE_<topic>.md にアーカイブしてから、新しいファイルを作成します。追跡対象外のファイルを置き換えると、永久に失われます。公開リポジトリでは、意図的に SESSION_PROGRESS.md を gitignore に指定していることがよくあります。その場合は、アーカイブが情報漏えいの原因にならないよう、.gitignore に SESSION_ARCHIVE_*.md も追加することを提案します。

チェックポイント（引数なしでの呼び出し）と保存

どちらも、現在の状態をファイルに書き込みます。完了したタスクにチェックを付け、## Current Status を更新し、決定事項と失敗した試行を追記して、last_updated を再設定します。異なるのは、その後の動作だけです。/track-session を引数なしで実行するとチェックポイントを記録して作業を続けますが、/track-session save はチェックポイントを記録して停止します。

推測した時刻は数時間ずれる可能性があり、ダッシュボードの経過状況表示はその値を信頼するため、時刻は推測せず、必ず時計から取得します。

date +%Y-%m-%dT%H:%M:%S%z | sed -E 's/([0-9]{2})$/:\1/'   # 2026-09-22T11:19:48-06:00

最後の計画タスクにチェックを付けたら、同じ書き込みで status: completed に設定し、セッションが終了したことをユーザーに伝えます。完了したファイルを in-progress のままにすると、ダッシュボードではいつまでも作業中として表示されます。

再開モード

ファイルを読んだら、新たな分析を始める前に、実際の現在の状態を先に伝えます。status、完了タスク数と総タスク数、作業ツリーの状態、最後のコミット、次のアクションを示します。「これからセッションファイルを読み、テストを確認します」のような説明から始めると、ユーザーが確認したかった状態が後回しになり、ユーザー自身がそれを再確認することになります。

再開は、実際の状態との整合性を取る自然な機会でもあります。project: または status: が実態と食い違っていたら、その場で修正します。

検証と復元 — 必要に応じて読み込み

• /track-session verify は、[x] が付いたタスクが実際に要件を満たしているか確認します。ファイルを読み、テストを実行し、それぞれの主張を今回の実行で得られた証拠に結び付けて、## Verification Results セクションを追記します。cc-dash はこのセクションをセッションページに表示します。ユーザーから検証を求められた場合、またはチェック済みのボックスだけが作業完了の証拠である場合は、reference/VERIFICATION.md を読み込みます。
• /track-session recover は、Claude Code のトランスクリプトから削除された SESSION_PROGRESS.md を復元します。ファイルが見つからず、ユーザーが復元を希望している場合は、reference/RECOVERY.md を読み込みます。このファイルには、トランスクリプトのスラッグの導出方法と、テスト済みの Python 復元スクリプトが記載されています。また、トランスクリプトを jq が誤って解析するため、この方法が必要であることも説明しています。

例

✅ 具体的で、再開しやすい例：

## Plan
- [x]  Phase 1: choose session store (picked Redis)
- [ ]  Phase 2: add session middleware

## Current Status
Working on: Phase 2
Next: add Redis client in src/auth/session.ts, then wire middleware in app.ts

❌ 曖昧すぎて、再開しにくい例：

## Plan
- [ ] Do auth stuff
- [ ] Fix sessions
Working on auth. Tried some things that didn't work.

✅ 状態から始まる再開時の返信：

Paused, 4 of 7 plan tasks done, working tree clean, last commit 3cf23e0 "add session middleware".
Next: add the Redis client in src/auth/session.ts, then wire it in app.ts.

❌ 説明から始まる再開時の返信：

Let me start by reading your SESSION_PROGRESS.md to understand the context.
Then I'll check the git log and look through the auth directory...

✅ 失敗した試行を記録し、無条件に再試行しない例：

## Failed Attempts
-  Tried `ioredis` autoReconnect for the session store: reconnect storms under the test harness's socket limit. Switched to a single shared client in src/auth/redisClient.ts.
-  Ran the e2e suite against staging: env-scoped — STAGING_URL unset in this shell. Re-check before treating this as a real failure.

❌ 失敗した試行が再び実行されてしまう例：

## Failed Attempts
- Redis didn't work, trying something else

✅ 適切な記述にはすべてファイル名、ID、理由が含まれます。情報が不十分な記述では、読み手が一から状況を把握し直すことになります。

注意点

• 解析されるのは最上部の frontmatter ブロックのみです。 2つ目の --- より下は cc-dash から見えないため、セッションが連続して記録されたファイルでは、最新のセッションだけが黙って報告されます。
• 多くの公開リポジトリでは SESSION_PROGRESS.md が gitignore されています。「置き換えればよい、Git に履歴があるから」という考えは成り立ちません。置き換える前に git ls-files --error-unmatch を確認し、終了コードが0以外の場合はまずアーカイブしてください。
• cc-dash は id が一致しない項目を警告とともに除外し、残りは保持します。 ref: や roadmap_ref にカンマ区切りのリストを指定した場合や、スペースまたは大文字を含む id を指定した場合、該当する項目またはリンクはダッシュボードから除外されます。不正な値は修正しますが、有効な覚えやすい id を無作為なトークンに書き換えないでください。id を変更すると、それを参照するすべての dep: が孤立します。
• 書き込むたびに last_updated を更新してください。 ダッシュボードの停滞状況ビューはこの値を基準にするため、チェックポイントで更新を省くと、進行中の作業が放置されているように見えます。
• save は作業を停止します。 チェックポイントのつもりで作業中に入力すると、作業が止まったことに困惑します。チェックポイントを作成して作業を続けるのは、引数なしの /track-session です。
• サブエージェントの実行中に save を使っても、サブエージェントは停止しません。 停止したと伝えた後に結果が届くことがあります。## Current Status の下に実行中のエージェントをそれぞれ記載し、何をしているのかを明記してください。また、結果は引き続き届くことをユーザーに伝え、次のセッションで確認できるようにしてください。
• ほかの見出しは保持されますが、表示されません。 cc-dash に表示されるのは Plan、Current Status、Decisions、Failed Attempts、Completed Work、Verification Results です。## Notes セクションはディスク上には残りますが、ダッシュボードには表示されません。セッション後も残すべき調査結果は、独自のセクションを作るのではなく、リンク先のロードマップ項目に引用形式のメモとして記載してください（track-roadmap を参照）。
• リポジトリごとに、ルートに1つだけ置いてください。 サブディレクトリ（godot/ や web/ など）で作業しても、チェックポイントはルートのファイルに記録されます。ツリーの下層に2つ目の SESSION_PROGRESS.md を作ると記録が分散し、ダッシュボードは一方しか読み込みません。
• ファイルの書き込みには Bash のヒアドキュメントや sed -i ではなく、Edit または Write を使ってください。 recover はトランスクリプトの Edit および Write の呼び出しを再生してファイルを再構築するため、Bash 経由で行った更新は認識されません。
• 復旧時に、きれいにまとまった内容が見つかることはほとんどありません。 更新は段階的な Edit で行われるため、トランスクリプトに完全な Write が残っていないことがほとんどです。コピーを1つ取り出すのではなく、最新のスナップショットに編集を再適用することを想定してください。

統合

• track-roadmap — ロードマップから機能を選び、roadmap_ref: r_XXXXX で実装をここにリンクします。このセッションを超えて重要な調査、未解決の質問、却下した代替案は、セッション終了前に引用形式のメモとして該当するロードマップ項目に戻してください。
• コミットやテストのフェーズの間にチェックポイントを作成し、ファイルの状態を後のセッションで git show できるコミット境界に合わせてください。

再開時の失敗、セッションファイルの肥大化、verify のエッジケースについては、reference/TROUBLESHOOTING.md を参照してください。