tc-tracker

tc-tracker skill 概览

tc-tracker 适合用来做什么

tc-tracker 是一个用于结构化 Technical Change 跟踪的工程类 skill：它可以帮助 AI agent 在项目的 docs/TC/ 下创建、更新、校验、恢复和关闭 JSON 变更记录。它不依赖聊天记忆、零散笔记或 commit message，而是记录变更内容、变更原因、受影响文件、测试证据、状态、阻塞项，以及会话交接上下文。

最适合的用户和项目

tc-tracker skill 非常适合使用 AI coding session 的团队，尤其是工作可能跨多个聊天、多人交接或多轮 review 的场景。当你需要为实现工作提供类似 issue 的跟踪、为代码变更保留审计轨迹，或在 feature、bugfix、refactor、infrastructure、documentation、hotfix、enhancement 等工作中反复生成一致的状态摘要时，它会很有价值。

面向 Issue Tracking 的关键差异

tc-tracker 不同于泛泛而谈的“做一个 issue tracker”提示词，它自带明确的存储结构、TC ID 约定、只追加的修订历史模型、校验脚本，以及生命周期状态机。它不是 GitHub Issues 或 Jira 的替代品；它更像是一个存放在仓库内的实现日志，把代码文件、测试、决策和 AI 交接说明连接起来。

什么时候不适合使用 tc-tracker

对于简单的拼写修正、仅格式化的改动，或一次性从 git history 生成 changelog，不建议使用 tc-tracker。如果你的项目已经强制执行成熟的 issue 流程，并且不希望在仓库中增加额外的 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，查看脚本示例；接着阅读 references/lifecycle.md、references/tc-schema.md 和 references/handoff-format.md。scripts/ 里的 Python helper 是可以直接用于实际工作的工具，不只是示例代码。

在项目中初始化跟踪

tc-tracker 的核心用法，是先在仓库内创建本地跟踪区域：

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

这会创建 docs/TC/，其中包含配置、registry、records 和 evidence 等位置。初始化脚本是幂等的，因此重复运行时应报告已有状态，而不是重复创建结构。请在目标项目根目录运行，或显式传入 --root /path/to/project。

创建并更新一个 Technical Change

一个好的起始提示词，应该给 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.

对应的脚本流程如下：

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 skill 时，最有价值的习惯是在会话结束前写清楚交接信息。交接内容应包含具体进展、足够小且可执行的下一步、阻塞项、已做决策，以及正在处理的文件：

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 读取 docs/TC/records/<TC-ID>/tc_record.json，尤其是 session_context.handoff，然后从记录的下一步继续。

tc-tracker skill 常见问题

tc-tracker 是完整的 issue tracker 吗？

不是。用于 Issue Tracking 时，tc-tracker 是仓库本地、以变更为中心的工具。它跟踪实现状态、文件、测试、决策和交接上下文。团队分派、讨论、标签、看板以及外部干系人流程，仍应使用 GitHub Issues、Linear 或 Jira。

它比普通提示词好在哪里？

普通提示词可以总结工作，但通常不会强制 schema、生命周期转换、只追加修订，或可重复的目录结构。tc-tracker 为 AI agent 提供了持久化格式和脚本，用于创建、更新、校验和列出变更记录。

tc-tracker 对新手友好吗？

是的，前提是你能接受运行 Python 脚本并提交 JSON 文件。新手应从 README.md 的 quick-start 命令开始，在理解 references/tc-schema.md 和 references/lifecycle.md 之前，避免手动编辑 TC JSON。

什么会阻碍采用？

主要采用成本是流程开销。每个有意义的变更都需要 TC 记录、状态更新和高质量交接文本。如果团队不会持续维护这些记录，registry 可能会变得过时。tc-tracker 最适合把 TC 更新纳入编码流程，而不是事后补写的团队。

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

给 tc-tracker 更充分的输入

tc-tracker 在提示词包含项目根目录、变更目标、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.” 只有当阻塞项确实在阻止推进时才记录 blockers；记录决策时要写明理由，避免下一次 AI session 重新争论同一个问题。

通过校验和 review 持续迭代

第一次输出后，运行 status 和 validator 脚本，然后让 agent 修复缺失字段、非法状态转换、过期的文件列表或薄弱的测试证据。为了获得更好的长期效果，建议 review references/tc-schema.md，并调整你的提示词，确保每个 TC 在关闭前都包含可供 review 的摘要、受影响文件、测试用例和会话上下文。