tc-tracker

TC Tracker

すべてのコード変更を構造化された JSON レコード、強制されるステートマシン、前のセッションが終了したときに新しい AI セッションが作業をスムーズに再開できるセッション引き継ぎ形式で追跡します。

概要

Technical Change（TC）は、何が変わったか、なぜ変わったか、誰が変更したか、いつ変更したか、どのようにテストしたか、そして次のセッションに向けて作業がどの段階にあるかを記録する構造化レコードです。レコードは対象プロジェクト内の docs/TC/ に JSON として保存され、厳格なスキーマとステートマシンに照らして検証されます。

以下の場合にこのスキルを使用してください：

• 「この変更を追跡して」と依頼された場合や、コード変更の監査証跡が必要な場合
• 進行中の作業を今後の AI セッションに引き継ぎたい場合
• コミットメッセージより詳しい構造化リリースノートが必要な場合
• 既存のプロジェクトを導入し、過去の変更記録を作成したい場合
• /tc init、/tc create、/tc update、/tc status、/tc resume、/tc close を依頼された場合

以下の場合はこのスキルを使用しないでください：

• Git の履歴から変更履歴だけを作成したい場合（engineering/changelog-generator を使用してください）
• 技術的負債の項目だけを追跡したい場合（engineering/tech-debt-tracker を使用してください）
• 変更が動作に影響しない些細なもの（誤字や書式など）の場合

保存レイアウト

各プロジェクトでは、TC を {project_root}/docs/TC/ に保存します：

docs/TC/
├── tc_config.json          # Project settings
├── tc_registry.json        # Master index + statistics
├── records/
│   └── TC-001-04-05-26-user-auth/
│       └── tc_record.json  # Source of truth
└── evidence/
    └── TC-001/             # Log snippets, command output, screenshots

TC ID の規則

• 親 TC： TC-NNN-MM-DD-YY-functionality-slug（例：TC-001-04-05-26-user-authentication）
• サブ TC： TC-NNN.A または TC-NNN.A.1（文字は改訂、数字は副改訂を表します）
• NNN は連番、MM-DD-YY は作成日、slug はケバブケースです。

ステートマシン

planned -> in_progress -> implemented -> tested -> deployed
   |            |              |           |          |
   +-> blocked -+              +- in_progress <-------+
        |                          (rework / hotfix)
        +-> planned

遷移表と復旧フローの全容については、references/lifecycle.md を参照してください。

ワークフローコマンド

このスキルには、TC レコードに対して決定論的な処理を行う、標準ライブラリのみを使用する 5 つの Python スクリプトが含まれています。各スクリプトは --help と --json に対応しています。

1. プロジェクトで追跡を初期化する

python3 scripts/tc_init.py --project "My Project" --root .

docs/TC/、docs/TC/records/、docs/TC/evidence/、tc_config.json、tc_registry.json を作成します。冪等性があり、再実行すると現在の統計情報とともに「すでに初期化済み」と報告します。

2. 新しい TC レコードを作成する

python3 scripts/tc_create.py \
  --root . \
  --name "user-authentication" \
  --title "Add JWT-based user authentication" \
  --scope feature \
  --priority high \
  --summary "Adds JWT login + middleware" \
  --motivation "Required for protected endpoints"

次の連番の TC ID を生成し、レコードディレクトリを作成して、必要な項目がすべて入力された tc_record.json（ステータス planned、作成改訂 R1）を書き込み、レジストリを更新します。

3. TC レコードを更新する

# Status transition (validated against the state machine)
python3 scripts/tc_update.py --root . --tc-id TC-001-04-05-26-user-auth \
  --set-status in_progress --reason "Starting implementation"

# Add a file
python3 scripts/tc_update.py --root . --tc-id TC-001-04-05-26-user-auth \
  --add-file src/auth.py:created

# Append handoff data
python3 scripts/tc_update.py --root . --tc-id TC-001-04-05-26-user-auth \
  --handoff-progress "JWT middleware wired up" \
  --handoff-next "Write integration tests" \
  --handoff-next "Update README"

変更のたびに連番の R<n> 改訂エントリーを追加し、updated を更新してから、スキーマに照らして再検証し、アトミックに書き込みます（.tmp を経由してから rename）。

4. ステータスを表示する

# Single TC
python3 scripts/tc_status.py --root . --tc-id TC-001-04-05-26-user-auth

# All TCs (registry summary)
python3 scripts/tc_status.py --root . --all --json

5. レコードまたはレジストリを検証する

python3 scripts/tc_validator.py --record docs/TC/records/TC-001-.../tc_record.json
python3 scripts/tc_validator.py --registry docs/TC/tc_registry.json

バリデーターはスキーマを適用し、ステートマシン上の遷移が正当か確認し、R<n> と T<n> の ID が連番になっていることを検証し、承認の整合性（approved=true には approved_by と approved_date が必要）を確認します。

スキーマの全容については、references/tc-schema.md を参照してください。

スラッシュコマンドディスパッチャー

このリポジトリには、サブコマンドに応じてこれらのスクリプトを呼び出す /tc スラッシュコマンドが commands/tc.md に含まれています：

コマンド	アクション
/tc init	現在のプロジェクトで tc_init.py を実行
/tc create <name>	項目の入力を促し、tc_create.py を実行
/tc update <tc-id>	ユーザーが説明した変更を tc_update.py で適用
/tc status [tc-id]	tc_status.py を実行
/tc resume <tc-id>	引き継ぎ内容を表示し、前のセッションをアーカイブして、新しいセッションを開始
/tc close <tc-id>	deployed に遷移し、承認を設定
/tc export	派生アーティファクトをすべて再生成
/tc dashboard	レジストリのサマリーを再生成

スラッシュコマンドがユーザーインターフェースであり、Python スクリプトがエンジンです。

セッション引き継ぎ形式

引き継ぎブロックは各 TC 内の session_context.handoff にあり、AI の継続性にとって最も重要なフィールドです。以下の内容を含みます。

• progress_summary — 完了した作業
• next_steps — 残りのアクションを順番に並べたリスト
• blockers — 進行を妨げている事項
• key_context — 次のボットが把握しておくべき重要な決定事項、注意点、パターン
• files_in_progress — 編集中のファイルとその状態（editing、needs_review、partially_done、ready）
• decisions_made — 根拠とタイムスタンプを含むアーキテクチャ上の決定事項

全体の構造と記入ルールについては、references/handoff-format.md を参照してください。

検証ルール（常に適用）

1. ステートマシン — 有効な遷移のみ許可されます。
2. 連番 ID — revision_history は R1, R2, R3...、test_cases は T1, T2, T3... を使用します。
3. 追記のみの履歴 — リビジョンのエントリーは変更も削除もできません。
4. 承認の整合性 — approved=true の場合は、approved_by と approved_date が必要です。
5. TC ID の形式 — TC-NNN-MM-DD-YY-slug に一致する必要があります。
6. サブ TC ID の形式 — TC-NNN.A または TC-NNN.A.N に一致する必要があります。
7. アトミック書き込み — JSON を .tmp に書き込んでから名前を変更します。
8. レジストリの統計情報 — レジストリへの書き込みのたびに再計算されます。

ワークフローを妨げない記録パターン

TC の追跡によって、メインのワークフローを中断してはなりません。

• インラインで TC レコードを更新するために作業を止めないでください。 コーディングを続けてください。
• 自然な節目で、レコードを更新するバックグラウンドのサブエージェントを起動します。
• 質問は本当に必要な場合にのみ提示します（「この作業に該当するアクティブな TC がありません。作成しますか？」）。ファイルごとではなく、セッションごとに一度だけ尋ねてください。
• セッションの終了時に、終了する前に最終的な引き継ぎブロックを記入します。

既存プロジェクトの変更履歴を遡って一括作成

変更履歴が記録されていない既存プロジェクトをオンボーディングする場合は、retro_changelog.json（論理的な変更ごとに 1 エントリー）を作成し、ループ内で tc_create.py に渡すか、一括処理モードに対応するようスクリプトを拡張します。コミットはファイル単位ではなく、機能単位でまとめます。

アンチパターン

アンチパターン	問題点	代わりに行うこと
誤字を「修正」するために revision_history を編集する	履歴は追記のみです。改ざんすると監査証跡が損なわれます	フィールドを修正する新しいリビジョンを追加する
ステートマシンを省略する（「ステータスを deployed に設定するだけ」）	検証を回避し、省略したフェーズを隠します	in_progress -> implemented -> tested -> deployed の順に進める
変更したファイルごとに TC を 1 つ作成する	関連する作業が分断され、レジストリが膨れ上がります	論理単位（機能、修正、リファクタリング）ごとに TC を 1 つ作成する
コードを編集するたびに TC をインラインで更新する	メインエージェントの動作を遅くし、コンテキストを無駄に消費します	節目でバックグラウンドのサブエージェントを起動する
approved_by を指定せずに approved=true にする	バリデーターに拒否され、監査証跡が誤解を招きます	approved_by と approved_date を必ずセットで指定する
テキストエディターで tc_record.json を直接上書きする	書き込み途中で破損する危険があり、検証も省略されます	tc_update.py（アトミック書き込み＋スキーマチェック）を使用する
notes や証跡にシークレットを記載する	レコードがリポジトリにコミットされます	環境変数または外部のシークレットストアを参照する
削除後に TC ID を再利用する	連番の保証を損ない、履歴がわかりにくくなります	常に番号を進め、再利用しない
next_steps を古いままにする	引き継ぎの目的が損なわれます	「変更なし」の場合も、節目ごとに更新する

相互参照

• engineering/changelog-generator — Conventional Commits から Keep-a-Changelog 形式のリリースノートを生成します。TC tracker と組み合わせてください。TC は変更ごとの詳細な監査記録に、changelog はユーザー向けのリリースノートに使用します。
• engineering/tech-debt-tracker — 個別のコード変更ではなく、長期にわたる負債を追跡する場合に使用します。
• engineering/focused-fix — バグ修正で機能全体にわたる体系的な修復が必要な場合は、まず /focused-fix を実行し、その結果を TC として記録します。
• project-management/decision-log — TC の decisions_made ブロック内で下されたアーキテクチャ上の決定は、プロジェクト全体の決定ログに反映することもできます。
• engineering-team/code-reviewer — マージ前レビューは tested -> deployed への移行に自然に組み込めます。レビュー担当者は approval.approved_by に記録します。

このスキルの参考資料

• references/tc-schema.md — TC レコードとレジストリの完全な JSON スキーマです。
• references/lifecycle.md — ステートマシン、有効な状態遷移、復旧フローについて説明します。
• references/handoff-format.md — セッション引き継ぎの構成とベストプラクティスについて説明します。