Tại sao tôi xây dựng TracerKit: Chuẩn hóa quy trình phát triển với AI

Tại sao tôi xây dựng TracerKit: Chuẩn hóa quy trình phát triển với AI

Trong một bài viết trước, tôi đã mô tả một quy trình làm việc (workflow) để xây dựng tính năng với Claude Code: lập kế hoạch qua hội thoại, lưu kế hoạch vào tệp SPEC.md, triển khai từng nhiệm vụ một, và sử dụng lệnh /clear giữa các phiên làm việc. Tệp spec đóng vai trò là bộ nhớ, còn phiên làm việc là nơi thực thi.

Tôi đã kết thúc bài viết đó bằng nhận định rằng quy trình này sẽ thay đổi. Và quả thật là như vậy.

Điểm gãy của quy trình thủ công

Cách tiếp cận dùng tệp SPEC.md trước đây hoạt động tốt, nhưng ba vấn đề thường xuyên nảy sinh:

1. Thông số kỹ thuật không nhất quán. Mỗi tính năng đều bắt đầu từ con số không. Một số tệp spec có phần đưa ra quyết định, số khác thì không. Có tệp chứa danh sách kiểm tra công việc, trong khi tệp khác lại viết văn xuôi. Chất lượng phụ thuộc hoàn toàn vào mức độ kỷ luật của tôi vào ngày đó.
2. Không có bước xác minh. Tôi tự đánh dấu các nhiệm vụ là hoàn thành [x] bằng tay. Đôi khi là trước khi bài kiểm tra (test) passes. Đôi khi tôi quên cập nhật tệp spec hoàn toàn. "Nguồn sự thật" dần drift away xa khỏi thực tế mã nguồn.
3. Thiếu vòng đời. Các tệp spec đã hoàn thành nằm lăn lóc ở thư mục gốc dự án bên cạnh những cái đang hoạt động. Không có kho lưu trữ, không có theo dõi trạng thái, và không có cách nào để xem cái gì đang trong quá trình triển khai.

Tôi liên tục vá lỗi những vấn đề này bằng các câu lệnh prompt tốt hơn và sự kỷ luật cao hơn. Sau đó, tôi nhận ra chính quy trình làm việc đó cần phải trở thành một công cụ.

Quy trình làm việc mới với TracerKit

TracerKit là kết quả của sự nhận thức đó. Đó là một tập hợp các kỹ năng (skills) cho tác nhân AI (tại thời điểm này hỗ trợ Claude Code), sử dụng thuần Markdown và không có phụ thuộc thời gian chạy (zero runtime deps), giúp thay thế quy trình spec thủ công bằng một quy trình có cấu trúc.

Dưới đây là ví dụ về tính năng Dark Mode từ bài viết trước, nhưng lần này được thực hiện qua TracerKit.

1. Định hướng (Orient)

Lệnh:

/tk:brief

Đầu bất kỳ phiên làm việc nào, lệnh này sẽ hiển thị những gì đang "trên không":

Feature	Status	Age	Progress	Next
dark-mode	in_progress	1d	4/7	Add accessible toggle label

Focus -> dark-mode

Chỉ cần một lệnh duy nhất để định hướng. Không cần đào bới qua hàng tá tệp tin để nhớ mình đã dừng lại ở đâu.

2. Định nghĩa PRD (Product Requirements Document)

Lệnh:

/tk:prd enable dark mode

Kỹ năng này sẽ khám phá codebase trước, sau đó phỏng vấn tôi từng câu hỏi một. Nó sẽ phản bác những câu trả lời mơ hồ, chỉ ra các mâu thuẫn và buộc tôi phải xác định rõ phạm vi (scope) trước khi viết bất cứ thứ gì.

Kết quả đầu ra là một tệp PRD có cấu trúc tại .tracerkit/prds/dark-mode.md với frontmatter theo dõi trạng thái:

---
created: 2026-04-06T10:00:00Z
status: created
---

# Dark Mode

## Problem Statement
...

## User Stories
1. As a user, I want to toggle between light and dark themes...

## Implementation Decisions
...

## Out of Scope
...

Mọi PRD đều tuân theo cùng một cấu trúc. Không còn những tệp spec phụ thuộc vào cảm hứng của người viết nữa.

3. Lập kế hoạch theo kiểu Tracer-Bullet Slices

Lệnh:

/tk:plan dark-mode

Kỹ năng này đọc PRD, khám phá codebase và chia nhỏ tính năng thành các lát cắt dọc tracer-bullet, một khái niệm từ cuốn sách The Pragmatic Programmer (Lập trình viên thực dụng).

Thay vì xây dựng từng lớp một (tất cả schema, sau đó tất cả services, rồi mới đến UI), mỗi giai đoạn sẽ cắt một đường mỏng qua mọi tầng và có thể demo riêng biệt. Các vấn đề tích hợp sẽ xuất hiện ở giai đoạn 1, không phải vào lúc kết thúc.

## Phase 1 — Theme toggles end-to-end

### Done when
- [ ] `useTheme` hook reads/writes localStorage
- [ ] `ThemeProvider` applies theme class on mount
- [ ] Toggle button in Header switches theme
- [ ] No flash of wrong theme on reload

---
## Phase 2 — Polish and accessibility

### Done when
- [ ] System preference used as default when no localStorage value
- [ ] Toggle has accessible label and keyboard support
- [ ] All tests pass

Điểm khác biệt chính so với danh sách nhiệm vụ phẳng: mỗi giai đoạn đều có thể kiểm chứng độc lập. Các mục "Done when" là các điều kiện có thể kiểm tra (testable), không phải văn xuôi. Một tác nhân AI có thể xác minh chúng bằng cách đọc tệp hoặc chạy lệnh.

4. Triển khai theo từng giai đoạn

Lệnh:

@.tracerkit/plans/dark-mode.md do phase 1

Giống như trước đây: tham chiếu kế hoạch, triển khai, chạy test. Nhưng kế hoạch giờ đây có cấu trúc giúp nó tồn tại ngay cả khi ngữ cảnh (context) bị mất. Mỗi giai đoạn có tiêu chí chấp nhận (acceptance criteria) rõ ràng. Tôi không cần giải thích lại thế nào là "hoàn thành".

Giữa các giai đoạn, sử dụng /clear. Kế hoạch chính là bộ nhớ.

5. Xác minh và Lưu trữ

Lệnh:

/tk:check dark-mode

Đây là bước chưa từng tồn tại trước đây. Kỹ năng này khởi chạy một tác nhân review dạng read-only kiểm tra từng mục "Done when" dựa trên codebase thực tế. Nó chạy bộ test, so sánh các user story từ PRD với hành vi của ứng dụng và báo cáo kết quả:

## Verification: dark-mode

### Status: done

### Progress
Phase 1 — Theme toggles end-to-end: 4/4
Phase 2 — Polish and accessibility: 3/3
Total: 7/7

### BLOCKERS
- None

### SUGGESTIONS
- None

Khi trạng thái là done, nó sẽ lưu trữ PRD và kế hoạch vào .tracerkit/archives/dark-mode/ và dọn dẹp các tệp đang hoạt động. Không còn những tệp spec cũ kỹ nằm lăn lóc ở thư mục gốc dự án.

Điều gì đã thay đổi, điều gì thì không

Trước đây (SPEC.md thủ công)	Sau đây (TracerKit)
Cấu trúc spec thay đổi theo từng tính năng	Cấu trúc nhất quán mọi lúc qua quy trình phỏng vấn
Đánh dấu nhiệm vụ hoàn thành bằng tay	Tác nhân xác minh kiểm tra dựa trên codebase
Các tệp spec đã xong bị chất đống	Tự động lưu trữ khi hoàn thành
Không có cái nhìn tổng quan giữa các tính năng	Bảng điều khiển /tk:brief
Danh sách nhiệm vụ phẳng	Các giai đoạn tracer-bullet theo từng pha
Quyết định kiến trúc bị trôi tuột đi giữa phiên	Quyết định kiến trúc được khóa trong phần đầu kế hoạch

Những gì không thay đổi:

• CLAUDE.md vẫn định nghĩa cách làm việc. TracerKit định nghĩa cái gì cần xây dựng.
• Lệnh /clear giữa các giai đoạn. Kế hoạch là ngữ cảnh, không phải cuộc hội thoại.
• TDD (Test Driven Development) trong quá trình triển khai. TracerKit cấu trúc công việc spec, không phải công việc viết code.
• Tệp spec vẫn là tệp Markdown. Không có database, không có server, không bị khóa vào nền tảng nào.

Thói quen cốt lõi vẫn vậy: viết xuống những gì bạn đang xây dựng trước khi bạn xây dựng nó. TracerKit làm cho thói quen đó nhất quán và thêm vào bước xác minh mà tôi quá lười để làm thủ công.

Ý tưởng cốt lõi

Giống như trước đây, nhưng có thêm một điểm:

Tệp spec là bộ nhớ. Phiên làm việc là nơi thực thi. Xác minh đóng vòng tròn.

Nếu không có xác minh, các tệp spec sẽ trở thành danh sách điều ước. Các nhiệm vụ được đánh dấu hoàn thành mà không có bằng chứng. Lệnh /tk:check buộc phải trung thực: hoặc là codebase khớp với kế hoạch, hoặc là không.

Điểm cộng thêm nữa là vòng đời (lifecycle). Các tính năng có một lộ trình rõ ràng: created -> in_progress -> done -> archived. Bất kỳ lúc nào, /tk:brief đều cho thấy mọi thứ đang đứng ở đâu.

Không phải mọi nhiệm vụ đều cần quy trình đầy đủ. Một sửa đổi một dòng hay thay đổi config nhỏ không cần PRD hay kế hoạch từng pha. Hãy dùng phán đoán của bạn. Tuy nhiên, tôi đã có thành công nhất quán khi tuân theo quy trình đầy đủ ngay cả với những nhiệm vụ ban đầu có vẻ nhỏ. Những nhiệm vụ nhỏ có xu hướng phát triển lớn, và tệp spec sẽ bắt được điều đó sớm.

Bắt đầu sử dụng

TracerKit là mã nguồn mở và không phụ thuộc vào công nghệ (stack-agnostic). Hiện tại nó hỗ trợ Claude Code, với kế hoạch hỗ trợ Cursor và Copilot trong tương lai.

npm install -g tracerkit
tracerkit init

Kho lưu trữ: github.com/helderberto/tracerkit

Ý tưởng về TracerKit ra đời từ khóa học Claude Code for Real Engineers của Matt Pocock. Cách tiếp cận thực hành (hands-on) để xây dựng các thứ thực tế với Claude Code đã khiến những ma sát trong quy trình thủ công của tôi trở nên không thể bỏ qua.

Toàn bộ dự án được xây dựng sử dụng chính quy trình làm việc của nó. Dog-fooding (tự dùng sản phẩm của mình) từ ngày đầu tiên. Ví dụ walkthrough ở trên là một ví dụ thực tế, không phải bản demo.

Ý tưởng, phản hồi và yêu cầu tính năng đều được chào đón dưới dạng GitHub issues.

Quy trình làm việc trước đây là một trực giác đúng đắn: cấu trúc các phiên AI của bạn xung quanh một tệp spec "sống". TracerKit là điều xảy ra khi bạn ngừng duy trì cấu trúc đó bằng tay và để công cụ thực thi nó.

Công cụ AI sẽ tiếp tục phát triển. Thói quen quy định rõ trước khi xây dựng sẽ không bao giờ thay đổi.

Nếu bạn thử TracerKit, tôi rất muốn nghe nó phù hợp với quy trình của bạn như thế nào. Hãy chia sẻ những gì hiệu quả, những gì không và những gì còn thiếu. Những tính năng tốt nhất cho đến nay đều đến từ việc sử dụng thực tế, không phải phỏng đoán. Hãy mở một issue với các ý tưởng, điểm khó khăn, hoặc quy trình dẫn dắt bởi spec của riêng bạn. Xây dựng công khai sẽ hiệu quả hơn khi vòng lặp phản hồi được mở.