tc-tracker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TC Tracker

TC跟踪器

Track every code change with structured JSON records, an enforced state machine, and a session handoff format that lets a new AI session resume work cleanly when a previous one expires.

通过结构化JSON记录、强制状态机以及会话交接格式跟踪每一项代码变更，当前AI会话过期后，新的AI会话可以无缝恢复工作。

Overview

概述

A Technical Change (TC) is a structured record that captures what changed, why it changed, who changed it, when it changed, how it was tested, and where work stands for the next session. Records live as JSON in

docs/TC/

inside the target project, validated against a strict schema and a state machine.

Use this skill when the user:

Asks to "track this change" or wants an audit trail for code modifications
Wants to hand off in-progress work to a future AI session
Needs structured release notes that go beyond commit messages
Onboards an existing project and wants retroactive change documentation

Asks for

/tc init

/tc create

/tc update

/tc status

/tc resume

, or

/tc close

Do NOT use this skill when:

The user only wants a changelog from git history (use
```
engineering/changelog-generator
```
)
The user only wants to track tech debt items (use
```
engineering/tech-debt-tracker
```
)
The change is trivial (typo, formatting) and won't affect behavior

技术变更（Technical Change，简称TC）是一种结构化记录，用于捕获变更内容、变更原因、变更人员、变更时间、测试方式以及后续会话的工作进展。记录以JSON格式存储在目标项目的

docs/TC/

目录下，并通过严格的schema和状态机进行验证。

在以下场景使用本技能：

用户要求“跟踪此变更”或需要代码修改的审计追踪
用户希望将进行中的工作交接给后续AI会话
需要超出提交信息范围的结构化发布说明
接入现有项目并需要追溯性变更文档

用户请求

/tc init

、

/tc create

、

/tc update

、

/tc status

、

/tc resume

或

/tc close

命令

请勿在以下场景使用本技能：

用户仅希望从git历史生成变更日志（使用
```
engineering/changelog-generator
```
）
用户仅希望跟踪技术债务项（使用
```
engineering/tech-debt-tracker
```
）
变更为微小修改（拼写错误、格式调整）且不会影响行为

Storage Layout

存储结构

Each project stores TCs at

{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记录存储在

{project_root}/docs/TC/

目录下：

docs/TC/
├── tc_config.json          # 项目设置
├── tc_registry.json        # 主索引 + 统计信息
├── records/
│   └── TC-001-04-05-26-user-auth/
│       └── tc_record.json  # 可信数据源
└── evidence/
    └── TC-001/             # 日志片段、命令输出、截图

TC ID Convention

TC ID命名规则

Parent TC:

TC-NNN-MM-DD-YY-functionality-slug

(e.g.,

TC-001-04-05-26-user-authentication

)

Sub-TC:
```
TC-NNN.A
```
or
```
TC-NNN.A.1
```
(letter = revision, digit = sub-revision)
```
NNN
```
is sequential,
```
MM-DD-YY
```
is the creation date, slug is kebab-case.

主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）。

State Machine

状态机

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

See references/lifecycle.md for the full transition table and recovery flows.

planned -> in_progress -> implemented -> tested -> deployed
   |            |              |           |          |
   +-> blocked -+              +- in_progress <-------+
        |                          (返工 / 热修复)
        +-> planned

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

Workflow Commands

工作流命令

The skill ships five Python scripts that perform deterministic, stdlib-only operations on TC records. Each one supports

--help

and

--json

本技能包含五个Python脚本，可对TC记录执行确定性、仅依赖标准库的操作。每个脚本均支持

--help

和

--json

参数。

1. Initialize tracking in a project

1. 在项目中初始化跟踪

bash

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

Creates

docs/TC/

docs/TC/records/

docs/TC/evidence/

tc_config.json

, and

tc_registry.json

. Idempotent — re-running reports "already initialized" with current stats.

bash

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

创建

docs/TC/

、

docs/TC/records/

、

docs/TC/evidence/

、

tc_config.json

和

tc_registry.json

目录及文件。支持幂等操作——重新运行会返回“已初始化”并显示当前统计信息。

2. Create a new TC record

2. 创建新的TC记录

bash

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"

Generates the next sequential TC ID, creates the record directory, writes a fully populated

tc_record.json

(status

planned

, R1 creation revision), and updates the registry.

bash

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. Update a TC record

3. 更新TC记录

bash

undefined

bash

undefined

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"


Every change appends a sequential `R<n>` revision entry, refreshes `updated`, and re-validates against the schema before writing atomically (`.tmp` then rename).

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. View status

4. 查看状态

bash

undefined

bash

undefined

Single TC

单个TC

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

All TCs (registry summary)

所有TC（注册表摘要）

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

undefined

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

undefined

5. Validate a record or registry

5. 验证记录或注册表

bash

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

Validator enforces the schema, checks state-machine legality, verifies sequential

R<n>

and

T<n>

IDs, and asserts approval consistency (

approved=true

requires

approved_by

and

approved_date

See references/tc-schema.md for the full schema.

bash

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。

Slash-Command Dispatcher

斜杠命令调度器

The repo ships a

/tc

slash command at

commands/tc.md

that dispatches to these scripts based on subcommand:

Command	Action
`/tc init`	Run `tc_init.py` for the current project
`/tc create <name>`	Prompt for fields, run `tc_create.py`
`/tc update <tc-id>`	Apply user-described changes via `tc_update.py`
`/tc status [tc-id]`	Run `tc_status.py`
`/tc resume <tc-id>`	Display handoff, archive prior session, start a new one
`/tc close <tc-id>`	Transition to `deployed` , set approval
`/tc export`	Re-render all derived artifacts
`/tc dashboard`	Re-render the registry summary

The slash command is the user interface; the Python scripts are the engine.

仓库提供了位于

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脚本是核心引擎。

Session Handoff Format

会话交接格式

The handoff block lives at

session_context.handoff

inside each TC and is the single most important field for AI continuity. It contains:

```
progress_summary
```
— what has been done
```
next_steps
```
— ordered list of remaining actions
```
blockers
```
— anything preventing progress
```
key_context
```
— critical decisions, gotchas, patterns the next bot must know

files_in_progress

— files being edited and their state (

editing

needs_review

partially_done

ready

)

```
decisions_made
```
— architectural decisions with rationale and timestamp

See references/handoff-format.md for the full structure and fill-out rules.

交接块位于每个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。

Validation Rules (Always Enforced)

始终强制执行的验证规则

State machine — only valid transitions are allowed.

Sequential IDs —

revision_history

uses

R1, R2, R3...

;

test_cases

uses

T1, T2, T3...

Append-only history — revision entries are never modified or deleted.
Approval consistency —
```
approved=true
```
requires
```
approved_by
```
and
```
approved_date
```
.
TC ID format — must match
```
TC-NNN-MM-DD-YY-slug
```
.
Sub-TC ID format — must match
```
TC-NNN.A
```
or
```
TC-NNN.A.N
```
.
Atomic writes — JSON is written to
```
.tmp
```
then renamed.
Registry stats — recomputed on every registry write.

状态机 — 仅允许合法的状态转换。

连续ID —

revision_history

使用

R1, R2, R3...

；

test_cases

使用

T1, T2, T3...

。

仅追加历史 — 修订条目永远不会被修改或删除。
审批一致性 —
```
approved=true
```
时必须填写
```
approved_by
```
和
```
approved_date
```
。
TC ID格式 — 必须匹配
```
TC-NNN-MM-DD-YY-slug
```
。
子TC ID格式 — 必须匹配
```
TC-NNN.A
```
或
```
TC-NNN.A.N
```
。
原子写入 — JSON先写入
```
.tmp
```
文件再重命名。
注册表统计 — 每次写入注册表时重新计算统计信息。

Non-Blocking Bookkeeping Pattern

非阻塞记账模式

TC tracking must NOT interrupt the main workflow.

Never stop to update TC records inline. Keep coding.
At natural milestones, spawn a background subagent to update the record.
Surface questions only when genuinely needed ("This work doesn't match any active TC — create one?"), and ask once per session, not per file.
At session end, write a final handoff block before closing.

TC跟踪不得中断主工作流。

切勿在代码编写过程中实时更新TC记录。继续编码。
在自然里程碑处，启动后台子代理来更新记录。
仅在真正需要时提出问题（“此工作与任何活跃TC不匹配——是否创建新TC？”），每个会话仅询问一次，而非每个文件都问。
会话结束时，在关闭前写入最终交接块。

Retroactive Bulk Creation

追溯性批量创建

For onboarding an existing project with undocumented history, build a

retro_changelog.json

(one entry per logical change) and feed it to

tc_create.py

in a loop, or extend the script for batch mode. Group commits by feature, not by file.

对于接入无文档历史的现有项目，可构建

retro_changelog.json

文件（每个逻辑变更对应一个条目），循环传入

tc_create.py

，或扩展脚本以支持批量模式。按功能而非文件对提交进行分组。

Anti-Patterns

反模式

Anti-pattern	Why it's bad	Do this instead
Editing `revision_history` to "fix" a typo	History is append-only — tampering destroys the audit trail	Add a new revision that corrects the field
Skipping the state machine ("just set status to deployed")	Bypasses validation and hides skipped phases	Walk through `in_progress -> implemented -> tested -> deployed`
Creating one TC per file changed	Fragments related work and explodes the registry	One TC per logical unit (feature, fix, refactor)
Updating TC inline between every code edit	Slows the main agent, wastes context	Spawn a background subagent at milestones
Marking `approved=true` without `approved_by`	Validator will reject; misleading audit trail	Always set `approved_by` and `approved_date` together
Overwriting `tc_record.json` directly with a text editor	Risks corruption mid-write and skips validation	Use `tc_update.py` (atomic write + schema check)
Putting secrets in `notes` or evidence	Records are committed to the repo	Reference an env var or external secret store
Reusing TC IDs after deletion	Breaks the sequential guarantee and confuses history	Increment forward only — never recycle
Letting `next_steps` go stale	Defeats the purpose of handoff	Update on every milestone, even if it's "nothing changed"

反模式	危害	正确做法
编辑 `revision_history` 以“修复”拼写错误	历史记录是仅追加的——篡改会破坏审计追踪	添加新的修订条目来修正字段
跳过状态机（“直接将状态设置为deployed”）	绕过验证并隐藏跳过的阶段	按 `in_progress -> implemented -> tested -> deployed` 流程执行
每个修改的文件创建一个TC	拆分相关工作并导致注册表膨胀	每个逻辑单元（功能、修复、重构）创建一个TC
每次代码编辑后实时更新TC	减慢主代理速度，浪费上下文	在里程碑处启动后台子代理
未填写 `approved_by` 就标记 `approved=true`	验证器会拒绝，且审计追踪存在误导性	始终同时设置 `approved_by` 和 `approved_date`
使用文本编辑器直接覆盖 `tc_record.json`	存在写入过程中损坏的风险，且跳过验证	使用 `tc_update.py` （原子写入 + schema检查）
在 `notes` 或证据中包含机密信息	记录会提交至仓库	引用环境变量或外部机密存储
删除后重用TC ID	破坏序列号保证并混淆历史记录	仅向前递增——绝不循环使用
让 `next_steps` 过时	失去交接的意义	每次里程碑都更新，即使是“无变更”

Cross-References

交叉引用

```
engineering/changelog-generator
```
— Generates Keep-a-Changelog release notes from Conventional Commits. Pair it with TC tracker: TC for the granular per-change audit trail, changelog for user-facing release notes.
```
engineering/tech-debt-tracker
```
— For tracking long-lived debt items rather than discrete code changes.
```
engineering/focused-fix
```
— When a bug fix needs systematic feature-wide repair, run
```
/focused-fix
```
first then capture the result as a TC.
```
project-management/decision-log
```
— Architectural decisions made inside a TC's
```
decisions_made
```
block can also be promoted to a project-wide decision log.
```
engineering-team/code-reviewer
```
— Pre-merge review fits naturally into the
```
tested -> deployed
```
transition; capture the reviewer in
```
approval.approved_by
```
.

```
engineering/changelog-generator
```
— 基于约定式提交生成Keep-a-Changelog格式的发布说明。可与TC跟踪器配合使用：TC用于细粒度的变更审计追踪，变更日志用于面向用户的发布说明。
```
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
```
中。

References in This Skill

本技能中的参考文档

references/tc-schema.md — Full JSON schema for TC records and the registry.
references/lifecycle.md — State machine, valid transitions, and recovery flows.
references/handoff-format.md — Session handoff structure and best practices.

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