tc-tracker

TC Tracker

以结构化 JSON 记录追踪每一次代码变更，配合强制执行的状态机和会话交接格式，使前一个会话过期后，新的 AI 会话也能顺利接续工作。

概述

技术变更（TC）是一种结构化记录，用于记录改了什么、为何改、由谁改、何时改、如何测试，以及工作进展到哪一步，以便下一个会话接续。记录以 JSON 形式存放在目标项目的 docs/TC/ 目录中，并依据严格的 Schema 和状态机进行校验。

在以下情况使用此 Skill：

• 用户要求“追踪这次变更”，或需要代码修改的审计轨迹
• 用户希望将进行中的工作交接给未来的 AI 会话
• 需要超出提交信息范围的结构化发布说明
• 接入已有项目，并希望补充追溯性的变更文档
• 用户请求 /tc init、/tc create、/tc update、/tc status、/tc resume 或 /tc close

以下情况请勿使用此 Skill：

• 用户只想从 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 为 kebab-case 格式。

状态机

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

完整的状态转换表和恢复流程，请参阅 references/lifecycle.md。

工作流命令

该 Skill 附带五个 Python 脚本，对 TC 记录执行确定性的、仅依赖标准库的操作。每个脚本都支持 --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。该操作是幂等的，重复运行时会提示“already initialized”并显示当前统计信息。

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 再重命名）前重新依据 Schema 校验。

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

校验器会强制执行 Schema，检查状态机转换的合法性，验证 R<n> 和 T<n> ID 是否连续，并断言审批一致性（approved=true 时必须同时包含 approved_by 和 approved_date）。

完整 Schema 请参阅 references/tc-schema.md。

斜杠命令分发器

仓库在 commands/tc.md 中提供了 /tc 斜杠命令，它会根据子命令分发到上述脚本：

命令	操作
/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 — 下一个 bot 必须知道的关键决策、注意事项和模式
• 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 记录。 继续编码。
• 在自然的里程碑节点，启动后台子 Agent 更新记录。
• 仅在确实需要时提出问题（"这项工作不匹配任何活动中的 TC，是否创建一个？"），并且每个会话只问一次，而不是每个文件问一次。
• 会话结束时，在关闭前写入最终交接块。

回溯批量创建

对于包含未记录历史的现有项目，构建一个 retro_changelog.json（每个逻辑变更一条记录），并循环将其输入 tc_create.py，或扩展脚本以支持批处理模式。按功能而非按文件对提交进行分组。

反模式

反模式	问题所在	应采取的做法
为了"修正"错别字而编辑 revision_history	历史记录只能追加，篡改会破坏审计追踪	新增一条修订来更正字段
跳过状态机（"直接把状态设为 deployed"）	绕过校验并掩盖被跳过的阶段	依次经过 in_progress -> implemented -> tested -> deployed
为每个变更的文件创建一个 TC	割裂相关工作，使注册表膨胀	每个逻辑单元（功能、修复、重构）对应一个 TC
每次代码编辑之间都内联更新 TC	拖慢主 Agent，浪费上下文	在里程碑节点启动后台子 Agent
设置 approved=true 却不填写 approved_by	校验器会拒绝；审计追踪具有误导性	始终同时设置 approved_by 和 approved_date
用文本编辑器直接覆盖 tc_record.json	写入中途可能损坏，并跳过校验	使用 tc_update.py（原子写入 + 模式检查）
在 notes 或证据中放入机密信息	记录会提交到仓库中	引用环境变量或外部机密存储
删除后复用 TC ID	破坏顺序性保证并混淆历史	只向前递增，绝不回收
让 next_steps 过时	违背交接的初衷	每个里程碑都要更新，即使"没有任何变化"

交叉引用

• engineering/changelog-generator — 根据 Conventional Commits 生成 Keep-a-Changelog 格式的发布说明。可与 TC 追踪器搭配使用：TC 用于记录每个变更的细粒度审计轨迹，changelog 用于面向用户的发布说明。
• engineering/tech-debt-tracker — 用于追踪长期存在的技术债务条目，而非离散的代码变更。
• engineering/focused-fix — 当 bug 修复需要系统性的功能级修复时，先运行 /focused-fix，再将结果记录为 TC。
• project-management/decision-log — 在 TC 的 decisions_made 块中做出的架构决策，也可以提升到项目级决策日志中。
• engineering-team/code-reviewer — 合并前审查自然地适用于 tested -> deployed 转换阶段；请在 approval.approved_by 中记录审查者。

本 Skill 中的参考资料

• references/tc-schema.md — TC 记录与注册表的完整 JSON Schema。
• references/lifecycle.md — 状态机、有效转换与恢复流程。
• references/handoff-format.md — 会话交接的结构与最佳实践。