tc-tracker

tc-tracker skill 概覽

tc-tracker 的用途

tc-tracker skill 是一個用於結構化 Technical Change 追蹤的工程技能：它能協助 AI agent 在專案的 docs/TC/ 底下建立、更新、驗證、恢復進度與關閉 JSON 變更紀錄。它不依賴聊天記憶、零散筆記或 commit message，而是把變更內容、變更原因、受影響檔案、測試證據、狀態、阻礙事項，以及 session handoff 情境都記錄下來。

最適合的使用者與專案

tc-tracker skill 很適合使用 AI coding session 的團隊，特別是工作可能跨越多段對話、交接或 review 週期時。當你需要像 issue 一樣追蹤實作工作、為程式碼變更留下稽核軌跡，或在 feature、bugfix、refactor、infrastructure、documentation、hotfix、enhancement 等工作之間產出可重複的狀態摘要時，它特別有用。

相較於 Issue Tracking 的主要差異

tc-tracker 不只是一般「幫我做一個 issue tracker」prompt。它提供具體的儲存結構、TC ID 命名慣例、append-only revision history 模型、驗證 script，以及 lifecycle state machine。它不是 GitHub Issues 或 Jira 的替代品；更接近一套放在 repository 內的實作紀錄，用來連結程式碼檔案、測試、決策與 AI handoff notes。

不適合使用 tc-tracker 的情境

如果只是修正簡單 typo、只調整格式，或單次從 git history 產生 changelog，就不建議使用 tc-tracker。若你的專案已經有成熟且嚴格執行的 issue workflow，而且不希望在 repository 裡增加額外 JSON 紀錄，它也可能顯得太重。

如何使用 tc-tracker skill

tc-tracker 安裝與第一批應閱讀的檔案

在相容的 skills 環境中安裝：

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

接著查看來源目錄 engineering/skills/tc-tracker。先讀 SKILL.md，了解 agent 的觸發規則與工作流程；再讀 README.md 看 script 範例；接著閱讀 references/lifecycle.md、references/tc-schema.md 和 references/handoff-format.md。scripts/ 裡的 Python helpers 是實際可用的工具，不只是範例。

在專案中初始化追蹤

tc-tracker 的核心用法，是先在 repository 內建立本地追蹤區：

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

這會建立 docs/TC/，其中包含設定、registry、records 與 evidence 位置。initializer 是 idempotent，因此重複執行時應該回報既有狀態，而不是重複建立設定。請從目標專案根目錄執行，或明確傳入 --root /path/to/project。

建立與更新 Technical Change

好的第一個 prompt 會提供 agent 足夠資訊，讓它不用猜測也能建立有效紀錄：

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.

對應的 script 流程如下：

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"

隨著工作推進，應持續加入受影響檔案、測試案例、決策與狀態變更，而不是等到最後才補。

善用 handoff 與 status 指令

使用 tc-tracker 時最有價值的習慣，是在 session 結束前寫出有用的 handoff。內容應包含具體進度、足夠小且可執行的下一步、阻礙事項、已做決策，以及正在處理的檔案：

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 .

若要讓 agent 接續工作，resume prompt 應要求它讀取 docs/TC/records/<TC-ID>/tc_record.json，尤其是 session_context.handoff，再依照紀錄中的下一步繼續。

tc-tracker skill 常見問題

tc-tracker 是完整的 issue tracker 嗎？

不是。用於 Issue Tracking 的 tc-tracker 是 repository-local 且聚焦於變更本身。它追蹤實作狀態、檔案、測試、決策與 handoff 情境。團隊指派、討論、labels、boards，以及外部利害關係人的流程，仍應使用 GitHub Issues、Linear 或 Jira。

它比一般 prompt 好在哪裡？

一般 prompt 可以摘要工作，但通常不會強制 schema、lifecycle transitions、append-only revisions，或可重複使用的目錄結構。tc-tracker 提供 AI agent 一套可持久保存的格式，以及用來建立、更新、驗證與列出變更紀錄的 scripts。

tc-tracker 適合初學者嗎？

適合，前提是你能接受執行 Python scripts 並提交 JSON 檔案。初學者應先從 README.md 的 quick-start commands 開始，在理解 references/tc-schema.md 和 references/lifecycle.md 之前，避免手動編輯 TC JSON。

導入時可能遇到什麼阻礙？

主要導入成本是流程負擔。每個有意義的變更都需要 TC record、狀態更新，以及清楚的 handoff 文字。如果團隊不維護這些紀錄，registry 可能會變得過期。這個 skill 最適合把 TC 更新納入 coding workflow，而不是事後才補。

如何改進 tc-tracker skill 的使用效果

提供更完整的 tc-tracker 輸入

tc-tracker 在 prompt 包含專案根目錄、變更目標、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。」

讓 lifecycle transitions 符合實際進度

請遵守 state machine：planned、in_progress、blocked、implemented、tested 和 deployed。沒有測試證據時，不要把 TC 標成 tested；也不要從初期規劃直接跳到 deployed。如果工作出現回退，請帶著原因移回 in_progress。

每個 session 後提升 handoff 品質

最常見的失敗模式，是 handoff 文字太含糊。不要寫「finish tests」，改成具體動作，例如「Add tests/test_auth.py::test_expired_token_returns_401 and run pytest tests/test_auth.py -q。」只有在事項確實阻礙進度時才列為 blocker；決策也應記錄理由，避免下一個 AI session 重新爭論同一件事。

透過驗證與 review 持續迭代

第一次輸出後，先執行 status 與 validator scripts，再請 agent 修正缺漏欄位、無效 transitions、過期的檔案清單，或薄弱的測試證據。若要取得更好的長期效果，請檢視 references/tc-schema.md，並調整你的 prompts，確保每個 TC 在關閉前都包含可供 review 的摘要、受影響檔案、測試案例與 session context。