tc-tracker

tc-tracker skillの概要

tc-trackerの用途

tc-tracker skillは、構造化されたTechnical Change追跡のためのエンジニアリングskillです。プロジェクト内のdocs/TC/配下で、AIエージェントがJSON形式の変更記録を作成、更新、検証、再開、クローズできるようにします。チャットの記憶、断片的なメモ、コミットメッセージだけに頼るのではなく、何を変更したのか、なぜ変更したのか、影響を受けるファイル、テスト根拠、ステータス、ブロッカー、セッション引き継ぎの文脈を記録します。

向いているユーザーとプロジェクト

tc-tracker skillは、複数のチャット、担当者間の引き継ぎ、レビューサイクルにまたがるAIコーディングセッションを扱うチームに特に適しています。実装作業をissueのように追跡したい場合、コード変更の監査証跡が必要な場合、feature、bugfix、refactor、infrastructure、documentation、hotfix、enhancementなどの作業で再利用しやすいステータス要約を残したい場合に有用です。

Issue Trackingにおける主な違い

汎用的な「issue trackerを作って」というプロンプトとは異なり、tc-trackerには具体的な保存レイアウト、TC IDの命名規則、追記型のrevision historyモデル、検証スクリプト、ライフサイクルの状態遷移が用意されています。GitHub IssuesやJiraの代替ではありません。むしろ、コードファイル、テスト、意思決定、AIへの引き継ぎメモを結びつける、リポジトリ内の実装ログに近いものです。

tc-trackerを使わないほうがよいケース

軽微なタイポ修正、フォーマットだけの変更、git履歴から単発でchangelogを生成する用途にはtc-trackerは向きません。また、すでに成熟したissue運用が厳格に定着していて、リポジトリ内に追加のJSON記録を増やしたくないプロジェクトでは、やや重く感じられる場合があります。

tc-tracker skillの使い方

tc-trackerのインストールと最初に読むファイル

対応するskills環境で、次のコマンドを使ってskillをインストールします。

npx skills add alirezarezvani/claude-skills --skill tc-tracker

その後、ソースディレクトリengineering/skills/tc-trackerを確認します。まずSKILL.mdでエージェントのトリガールールとワークフローを読み、次にREADME.mdでスクリプト例を確認してください。そのうえで、references/lifecycle.md、references/tc-schema.md、references/handoff-format.mdを読むと全体像をつかみやすくなります。scripts/内のPythonヘルパーは単なるサンプルではなく、実運用で使える実用的な資産です。

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

tc-trackerの基本的な使い方は、リポジトリ内に追跡用領域を作るところから始まります。

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

これにより、設定、registry、records、evidenceの配置を含むdocs/TC/が作成されます。initializerは冪等なので、再実行してもセットアップを重複作成するのではなく、既存状態を報告する想定です。対象プロジェクトのルートから実行するか、--root /path/to/projectで明示的に指定してください。

Technical Changeを作成・更新する

最初のプロンプトで十分な情報を渡すと、エージェントが推測に頼らず有効な記録を作成しやすくなります。

Use tc-tracker to create a TC for adding JWT authentication. Project root is .. Scope is feature, priority is high. Summary: add login endpoint, JWT signing, and auth middleware. Motivation: protected API routes need authenticated access. Initial files likely affected: src/auth.py, src/middleware.py, tests/test_auth.py.

対応するスクリプトの流れは次のようになります。

python3 scripts/tc_create.py --root . \
  --name "user-auth" \
  --title "Add JWT authentication" \
  --scope feature --priority high \
  --summary "Adds JWT login endpoint, signing, and middleware" \
  --motivation "Required for protected API endpoints"

python3 scripts/tc_update.py --root . --tc-id <TC-ID> \
  --set-status in_progress --reason "Starting implementation"

作業が進んだら、最後にまとめて書くのではなく、影響ファイル、テストケース、意思決定、ステータス変更をその都度追加していきます。

引き継ぎとステータス確認をうまく使う

tc-trackerの運用で最も価値が出る習慣は、セッション終了前に有用な引き継ぎを書くことです。具体的な進捗、実行可能な粒度の次の手順、ブロッカー、意思決定、作業中のファイルを含めます。

python3 scripts/tc_update.py --root . --tc-id <TC-ID> \
  --handoff-progress "Implemented JWT signing and wired middleware into router" \
  --handoff-next "Add integration test for invalid token returning 401" \
  --handoff-blocker "Need final test fixture shape for user records"

作業状況は次のコマンドで確認します。

python3 scripts/tc_status.py --root . --all
python3 scripts/tc_validator.py --root .

再開用プロンプトでは、エージェントにdocs/TC/records/<TC-ID>/tc_record.json、特にsession_context.handoffを読むよう依頼し、記録された次の手順から続行させます。

tc-tracker skill FAQ

tc-trackerは本格的なissue trackerですか？

いいえ。Issue Tracking向けのtc-trackerは、リポジトリ内で完結する変更中心の追跡ツールです。実装状態、ファイル、テスト、意思決定、引き継ぎ文脈を追跡します。チーム内の担当割り当て、議論、ラベル、ボード、外部ステークホルダーを含むワークフローには、GitHub Issues、Linear、Jiraを使うのが適しています。

通常のプロンプトより何が優れていますか？

通常のプロンプトでも作業を要約することはできますが、多くの場合、schema、ライフサイクル遷移、追記型revision、再現性のあるディレクトリ構成までは強制できません。tc-trackerは、AIエージェントが変更記録を作成、更新、検証、一覧化するための永続的な形式とスクリプトを提供します。

tc-trackerは初心者にも使いやすいですか？

はい。Pythonスクリプトの実行とJSONファイルのコミットに抵抗がなければ使えます。初心者はREADME.mdのquick-startコマンドから始め、references/tc-schema.mdとreferences/lifecycle.mdを理解するまでは、TC JSONを手作業で編集しないほうが安全です。

導入の障壁になり得るものは何ですか？

主な導入コストはプロセス上の手間です。意味のある変更ごとにTC recordを作り、ステータスを更新し、質の高い引き継ぎ文を書く必要があります。チームがこれらの記録を維持しない場合、registryは古くなりやすくなります。tc-trackerは、TC更新が後回しの作業ではなく、コーディングワークフローの一部として組み込まれているときに最も効果を発揮します。

tc-tracker skillを改善する方法

tc-trackerにより良い入力を与える

tc-trackerは、プロンプトにproject root、変更の目的、scope、priority、motivation、想定されるファイル、テスト期待値、現時点の不確実性が含まれていると最もよく機能します。弱い入力は「track auth work」です。強い入力は「create a high-priority feature TC for JWT auth, affecting these files, with tests for valid token, invalid token, and missing token」のように、目的、優先度、影響範囲、テスト観点まで明確です。

ライフサイクル遷移を現実的に保つ

状態遷移、つまりplanned、in_progress、blocked、implemented、tested、deployedを守ってください。テスト根拠なしにTCをtestedにしてはいけません。また、初期計画からいきなりdeployedへ飛ばすべきでもありません。作業が後戻りした場合は、理由を添えてin_progressへ戻します。

各セッション後の引き継ぎ品質を上げる

最もよくある失敗は、引き継ぎ文が曖昧なことです。「finish tests」ではなく、「Add tests/test_auth.py::test_expired_token_returns_401 and run pytest tests/test_auth.py -q」のように具体的な行動へ置き換えます。ブロッカーは実際に進捗を止めている場合にだけ記録し、意思決定には根拠も残してください。そうすることで、次のAIセッションが同じ判断を蒸し返すリスクを減らせます。

検証とレビューで継続的に整える

最初の出力後にstatusとvalidatorのスクリプトを実行し、不足フィールド、不正な遷移、古いファイル一覧、弱いテスト根拠を修正するようエージェントに依頼します。長期的な品質を高めるには、references/tc-schema.mdを確認し、各TCがクローズされる前に、レビュー可能な要約、影響ファイル、テストケース、セッション文脈を含むようプロンプトを調整してください。