tc-tracker

Tổng quan về tc-tracker skill

tc-tracker dùng để làm gì

tc-tracker là một engineering skill dành cho việc theo dõi Technical Change có cấu trúc: skill này giúp AI agent tạo, cập nhật, kiểm tra hợp lệ, tiếp tục và đóng các bản ghi thay đổi dạng JSON trong docs/TC/ của dự án. Thay vì phụ thuộc vào trí nhớ trong cuộc trò chuyện, ghi chú rời rạc hoặc commit message, tc-tracker ghi lại nội dung đã thay đổi, lý do thay đổi, các file bị ảnh hưởng, bằng chứng kiểm thử, trạng thái, điểm nghẽn và ngữ cảnh bàn giao giữa các phiên làm việc.

Người dùng và dự án phù hợp nhất

tc-tracker skill đặc biệt phù hợp với các nhóm dùng phiên coding bằng AI có thể kéo dài qua nhiều cuộc trò chuyện, nhiều lần bàn giao hoặc nhiều vòng review. Skill này hữu ích khi bạn cần cách theo dõi gần giống issue cho công việc triển khai, audit trail cho thay đổi mã nguồn, hoặc bản tóm tắt trạng thái có thể lặp lại cho feature, bugfix, refactor, infrastructure, documentation, hotfix và enhancement.

Điểm khác biệt chính cho Issue Tracking

Khác với một prompt chung kiểu “tạo issue tracker”, tc-tracker có sẵn bố cục lưu trữ cụ thể, quy ước TC ID, mô hình lịch sử revision chỉ ghi thêm, script kiểm tra hợp lệ và state machine cho vòng đời thay đổi. Đây không phải là công cụ thay thế GitHub Issues hay Jira; tc-tracker gần với một nhật ký triển khai nằm trong repository, kết nối các file code, kiểm thử, quyết định kỹ thuật và ghi chú bàn giao cho AI.

Khi không nên dùng tc-tracker

Không nên dùng tc-tracker cho các sửa lỗi chính tả rất nhỏ, chỉnh định dạng đơn thuần hoặc tạo changelog một lần từ lịch sử git. Skill này cũng có thể quá nặng nếu dự án của bạn đã áp dụng một quy trình issue trưởng thành và bạn không muốn thêm các bản ghi JSON vào repository.

Cách sử dụng tc-tracker skill

Cài đặt tc-tracker và các file nên đọc trước

Cài đặt skill trong môi trường skills tương thích bằng lệnh:

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

Sau đó kiểm tra thư mục nguồn tại engineering/skills/tc-tracker. Đọc SKILL.md trước để nắm quy tắc kích hoạt agent và workflow, đọc README.md để xem ví dụ script, rồi tiếp tục với references/lifecycle.md, references/tc-schema.md và references/handoff-format.md. Các helper Python trong scripts/ là tài nguyên thực tế để dùng trong workflow, không chỉ là ví dụ minh họa.

Khởi tạo tracking trong dự án

Cách dùng tc-tracker cốt lõi bắt đầu bằng việc tạo một khu vực tracking cục bộ trong repository:

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

Lệnh này tạo docs/TC/ cùng các vị trí cho cấu hình, registry, records và evidence. Trình khởi tạo có tính idempotent, nên khi chạy lại, nó nên báo trạng thái đã tồn tại thay vì nhân đôi cấu trúc thiết lập. Hãy chạy lệnh từ thư mục gốc của dự án đích hoặc truyền rõ --root /path/to/project.

Tạo và cập nhật một Technical Change

Một prompt tốt ngay từ đầu nên cung cấp đủ thông tin để agent tạo bản ghi hợp lệ mà không phải đoán:

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.

Luồng script tương ứng sẽ như sau:

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"

Khi công việc tiến triển, hãy bổ sung các file bị ảnh hưởng, test case, quyết định và thay đổi trạng thái trong quá trình làm, thay vì chờ đến cuối mới ghi lại.

Dùng handoff và lệnh trạng thái hiệu quả

Thói quen mang lại nhiều giá trị nhất khi dùng tc-tracker là viết handoff hữu ích trước khi kết thúc một phiên làm việc. Hãy bao gồm tiến độ cụ thể, các bước tiếp theo đủ nhỏ để có thể thực hiện ngay, blocker, quyết định và các file đang xử lý:

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"

Kiểm tra công việc bằng:

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

Với prompt để tiếp tục công việc, hãy yêu cầu agent đọc docs/TC/records/<TC-ID>/tc_record.json, đặc biệt là session_context.handoff, rồi tiếp tục từ các bước tiếp theo đã được ghi lại.

FAQ về tc-tracker skill

tc-tracker có phải là một issue tracker đầy đủ không?

Không. tc-tracker cho Issue Tracking hoạt động cục bộ trong repository và tập trung vào thay đổi kỹ thuật. Nó theo dõi trạng thái triển khai, file, kiểm thử, quyết định và ngữ cảnh bàn giao. Hãy dùng GitHub Issues, Linear hoặc Jira cho phân công trong nhóm, thảo luận, label, board và workflow với stakeholder bên ngoài.

Điều gì khiến tc-tracker tốt hơn một prompt thông thường?

Một prompt thông thường có thể tóm tắt công việc, nhưng thường không bắt buộc schema, transition vòng đời, revision chỉ ghi thêm hoặc bố cục thư mục có thể lặp lại. tc-tracker cung cấp cho AI agent một định dạng bền vững cùng các script để tạo, cập nhật, kiểm tra hợp lệ và liệt kê bản ghi thay đổi.

tc-tracker có thân thiện với người mới không?

Có, nếu bạn quen chạy script Python và commit file JSON. Người mới nên bắt đầu với các lệnh quick-start trong README.md và tránh chỉnh sửa thủ công JSON của TC cho đến khi hiểu references/tc-schema.md và references/lifecycle.md.

Điều gì có thể cản trở việc áp dụng?

Chi phí áp dụng chính là phần overhead về quy trình. Mỗi thay đổi đáng kể đều cần một TC record, cập nhật trạng thái và nội dung handoff tốt. Nếu nhóm của bạn không duy trì các bản ghi này, registry có thể bị lỗi thời. Skill hoạt động tốt nhất khi cập nhật TC là một phần của workflow coding, không phải việc làm sau cùng.

Cách cải thiện tc-tracker skill

Cung cấp input tốt hơn cho tc-tracker

tc-tracker hoạt động tốt nhất khi prompt của bạn có project root, mục tiêu thay đổi, scope, priority, motivation, các file có khả năng liên quan, kỳ vọng kiểm thử và những điểm còn chưa chắc chắn hiện tại. Input yếu là “track auth work.” Input mạnh là “create a high-priority feature TC for JWT auth, affecting these files, with tests for valid token, invalid token, and missing token.”

Giữ các transition vòng đời sát thực tế

Hãy tôn trọng state machine: planned, in_progress, blocked, implemented, tested và deployed. Đừng đánh dấu TC là tested nếu chưa có bằng chứng kiểm thử, và đừng nhảy thẳng từ giai đoạn lập kế hoạch ban đầu sang deployed. Nếu công việc bị lùi lại, hãy chuyển về in_progress kèm lý do.

Cải thiện chất lượng handoff sau mỗi phiên

Lỗi thường gặp nhất là handoff mơ hồ. Hãy thay “finish tests” bằng hành động cụ thể như “Add tests/test_auth.py::test_expired_token_returns_401 and run pytest tests/test_auth.py -q.” Chỉ ghi blocker khi chúng thực sự đang chặn tiến độ, và ghi lại quyết định kèm lý do để phiên AI tiếp theo không phải tranh luận lại từ đầu.

Lặp lại với validation và review

Sau output đầu tiên, hãy chạy các script status và validator, rồi yêu cầu agent sửa field còn thiếu, transition không hợp lệ, danh sách file đã lỗi thời hoặc bằng chứng kiểm thử còn yếu. Để có kết quả dài hạn tốt hơn, hãy review references/tc-schema.md và tinh chỉnh prompt sao cho mỗi TC đều có summary sẵn sàng cho review, file bị ảnh hưởng, test case và session context trước khi được đóng.