Bản tương tác
Bài có kèm một trang tương tác: sơ đồ, tình huống và session minh hoạ. Link mở được tạo mới mỗi lần bấm.
Tóm tắt nhanh: Việc có phạm vi rộng thì dùng
--deep, có hành vi cũ phải giữ thì thêm--tdd, có cả hai rủi ro mới bật cả cặp.--deepcho kế hoạch một bản đồ đủ chi tiết cho từng giai đoạn,--tddbắt agent chụp lại hành vi hiện tại bằng test trước khi refactor. Việc nhỏ hoặc code mới hoàn toàn thì không cần cả hai.
Không phải việc nào cũng cần chế độ nặng. Một đợt refactor lớn hiếm khi hỏng ngay ở dòng code đầu tiên. Nó thường hỏng vì lúc lập kế hoạch chưa nhìn đủ phạm vi, rồi tới lúc /ak-cook chạy mới lộ ra test, migration hoặc tác vụ nền bị bỏ sót.
Công khai: mình là maintainer của AgentKit và có quan hệ affiliate: link AgentKit trong bài là link affiliate, mua qua link này bạn được giảm 30%.
Ghi chú: bản beta hiện tại của AgentKit (từ 3.0.0-beta.35, 21/10/2026) đã đổi format tên skill từ ak:<tên> sang ak-<tên>, nên lệnh trong bài đã cập nhật theo tên mới: Claude Code gõ /ak-plan, Codex gõ $ak-plan. Nếu bạn còn dùng bản cũ hơn, đổi ak- thành ak: là ra lệnh tương ứng.
/ak-plan là lệnh lập kế hoạch của AgentKit (trước đây là ClaudeKit). Tên lệnh trong bài theo AgentKit tại thời điểm tháng 10/2026; bản ClaudeKit cũ dùng tiền tố /ck: cho cùng các lệnh này. Mình dùng một ví dụ xuyên suốt, tách module thanh toán ra khỏi monolith, để tách rõ lúc nào hai tuỳ chọn này đáng chi phí và lúc nào chỉ làm chậm.
Ví dụ xuyên suốt: tách module thanh toán
Phần thanh toán (billing) đang nằm rải rác trong API (giao diện lập trình ứng dụng) route, model database, tác vụ nền, logic thử lại, trạng thái hoá đơn, bộ xử lý webhook và giao diện quản trị. Yêu cầu nghe đơn giản: "tách billing ra module riêng, giữ hành vi cũ". Nhưng khi agent bắt đầu chạy, các câu hỏi mới lộ ra:
- File nào thật sự thuộc phạm vi: API, tác vụ nền, database, giao diện hay webhook?
- Hành vi nào phải giữ nguyên: thử lại, tính idempotent (chạy lặp vẫn ra một kết quả), trạng thái hoá đơn, xử lý thanh toán lỗi?
- Test hiện có bao phủ được bao nhiêu?
- Giai đoạn này có phụ thuộc ngầm vào migration hoặc tác vụ nền không?
- Nếu code mới build được nhưng lệch ở trường hợp biên thì ai bắt?
Với việc nhỏ, /ak-plan --fast hoặc /ak-plan mặc định thường đủ. Với việc phức tạp nhưng chưa tới mức refactor lớn, --hard thường hợp hơn. Với việc lớn, thiếu ngữ cảnh ở đầu sẽ thành chi phí ở cuối: bước cook phải đoán lại phạm vi, file giai đoạn mơ hồ, test viết sau code, lỗi hồi quy chỉ lộ ra khi đã refactor xong.
Hai tuỳ chọn này không phải "chế độ mạnh hơn" theo nghĩa cứ bật là tốt hơn. Chúng giải hai rủi ro cụ thể: không biết đủ phạm vi và không bảo vệ được hành vi cũ.
| Tuỳ chọn | Dùng khi |
|---|---|
--deep | Phạm vi rộng, cần bản đồ cho từng giai đoạn |
--tdd | Cần giữ hành vi cũ khi refactor |
--deep --tdd | Có cả hai rủi ro |
Chế độ và cờ là hai thứ khác nhau
Trước khi đi tiếp, mình tách một điểm dễ nhầm: /ak-plan nhận hai loại tham số.
| Loại | Ví dụ | Tác dụng |
|---|---|---|
| Chế độ (mode) | --fast, --hard, --deep, --parallel, --two | Chọn quy trình lập kế hoạch. Mỗi lệnh chỉ dùng một chế độ. |
| Cờ ghép thêm (flag) | --tdd, --no-tasks | Phần cộng thêm, đi cùng chế độ nào cũng được. |
--deep là chế độ, tức là đổi cả quy trình lập kế hoạch. --tdd là cờ, tức là giữ chế độ bạn đã chọn nhưng thêm phần viết test trước vào file giai đoạn và vào bước cook.
Gợi ý tham số trong định nghĩa skill ghi như sau:
argument-hint: "[task] [--fast|--hard|--deep|--parallel|--two] [--tdd|--no-tasks]"Dấu | giữa các chế độ nghĩa là chọn một. --tdd nằm ở nhóm riêng nên ghép được. Vì vậy --deep --tdd hợp lệ, còn --deep --hard thì không.
--deep: khi kế hoạch cần bản đồ cho từng giai đoạn
Phần này nói --deep giải vấn đề gì, quy trình của nó gồm những bước nào và file giai đoạn có thêm gì.
Vấn đề mà --deep giải quyết
Việc lớn thường đụng nhiều vùng code cùng lúc. Với module thanh toán, phạm vi có thể trải qua:
- API route: tạo hoá đơn, thử lại thanh toán, hoàn tiền, webhook callback.
- Database: bảng hoá đơn, bảng lượt thanh toán, lịch sử trạng thái.
- Tác vụ nền: lịch thử lại, tác vụ đối soát, phát lại webhook.
- Giao diện quản trị: chi tiết hoá đơn, thử lại thủ công, nút hoàn tiền.
- Hợp đồng dùng chung: response API cho frontend, payload webhook, tên sự kiện.
Những việc này không chỉ cần danh sách bước. Chúng cần một bản đồ:
| Câu hỏi | Trong ví dụ thanh toán |
|---|---|
| File nào tạo mới, sửa hay xoá? | Route, dịch vụ, tác vụ nền, migration, thao tác trên giao diện |
| Test nào đang bảo vệ hành vi cũ? | Thử lại, idempotent, hoàn tiền, phát lại webhook |
| Giai đoạn nào phụ thuộc giai đoạn nào? | Migration đi trước dịch vụ, dịch vụ đi trước giao diện |
| Interface nào cần test bảo vệ? | Response API, payload webhook, đầu vào của tác vụ nền |
| Chỗ phụ thuộc nào rủi ro? | Tác vụ nền đọc trạng thái cũ trong khi dịch vụ đã đổi enum |
--deep hợp khi cái giá của một kế hoạch sai lớn hơn cái giá của việc lập kế hoạch kỹ. Quy tắc chọn chế độ trong skill ghi:
Major refactor, 5+ areas, architectural debt -> use --deepNghĩa là: refactor lớn, đụng từ năm vùng trở lên, có nợ kiến trúc thì dùng --deep. Nếu chỉ đụng ít file, --fast hoặc /ak-plan mặc định thường đủ. Nếu phạm vi phức tạp nhưng kiến trúc vẫn rõ, --hard hợp hơn. --deep đáng dùng khi một kế hoạch sai sẽ kéo theo nhiều giờ làm lại giai đoạn, test và phân vai.
Quy trình của --deep
Quy trình bắt đầu từ ngữ cảnh rộng rồi đi sâu dần vào từng giai đoạn:
- Lượt nghiên cứu (researcher): hai đến ba lượt nhìn kiến trúc và các vùng bị ảnh hưởng.
- Dò toàn vùng (scout): tài liệu, module chính, test hiện có, các phụ thuộc lớn.
- Dò từng giai đoạn: mỗi giai đoạn có bảng kê file, chỗ thiếu test, interface cần giữ.
- File giai đoạn: bên lập kế hoạch đưa dữ liệu dò được vào từng giai đoạn.
- Phản biện (red-team): bắt chỗ tràn phạm vi, thứ tự giai đoạn sai, rủi ro khi triển khai.
- Kiểm định: kiểm kế hoạch có đủ lệnh, phụ thuộc và tiêu chí hoàn thành.
- Danh sách việc: tạo danh sách việc, trừ khi dùng
--no-tasks. - Bàn giao cho cook: in ra lệnh
/ak-cook {path}/plan.md.
So với --hard, vốn thường dò một vòng cho cả kế hoạch, --deep đi thêm một lượt cho từng giai đoạn. Chi phí cao hơn, đổi lại file giai đoạn cụ thể hơn: file nào bị đụng, test nào còn thiếu, phụ thuộc nào rủi ro.
File giai đoạn có thêm gì khi dùng --deep
- Bảng kê file: thao tác tạo, sửa hay xoá, kích thước ước lượng, ảnh hưởng tới test.
- Ma trận kịch bản test: các luồng mức nghiêm trọng, cao, trung bình.
- Bản đồ phụ thuộc: giai đoạn này nối tới giai đoạn nào khác.
- Danh sách hàm và interface: hàm hoặc interface nào cần test bảo vệ.
Đây là khác biệt chính. Một giai đoạn không chỉ ghi "refactor billing service". Nó phải nói rõ file nào, test nào, trường hợp biên nào và giai đoạn này dựa vào giai đoạn nào.
--tdd: khi sợ refactor phá hành vi đang chạy
Phần này nói --tdd giải vấn đề gì, khi nào đáng dùng và nó đổi gì ở bước lập kế hoạch lẫn bước cook.
Vấn đề mà --tdd giải quyết
Luồng mặc định của bước cook khá quen: đọc kế hoạch, triển khai từng việc, kiểm kiểu sau mỗi file, rồi mới tới bước test riêng. Với code mới hoàn toàn thì ổn. Với refactor code đang chạy, cách đó chưa đủ an toàn.
Trong ví dụ thanh toán, hành vi cũ có thể là:
- Chỉ thử lại tối đa 3 lần, sau đó chuyển hoá đơn sang
failed. - Webhook cùng
event_idchỉ được áp dụng một lần. - Không được hoàn tiền nếu hoá đơn đã
voided. - Giao diện quản trị vẫn phải hiện đúng lịch sử trạng thái sau khi tách dịch vụ.
Luồng chính vẫn có thể chạy đúng, còn lỗi thường nằm ở trường hợp biên. --tdd dựng một cổng kiểm hồi quy (regression gate) trước khi đổi code. TDD (test-driven development, viết test trước) ở đây có nghĩa là chụp lại hành vi hiện tại trước khi refactor, chưa nói tới test cho tính năng mới.
Khi nào --tdd có giá trị nhất
| Tình huống | Có nên dùng? | Với ví dụ thanh toán |
|---|---|---|
| Code mới hoàn toàn | Thường không | Chưa có hành vi hoá đơn hay thử lại nào để chụp |
| Refactor module đang có người dùng | Có | Cần giữ thử lại, idempotent, chuyển trạng thái |
| Đổi nhà cung cấp thanh toán nhưng giữ hợp đồng cũ | Có | Dễ lệch response API hoặc hành vi webhook |
| Sửa 1 đến 2 dòng đã rõ nguyên nhân | Thường không | Ví dụ sửa lỗi chính tả nhãn trên giao diện quản trị |
| Bản thử dùng xong bỏ | Không | Chi phí dựng cổng test không đáng |
--tdd có giá trị nhất ở module có xử lý bất đồng bộ, luồng có trạng thái, transaction database hoặc hợp đồng API (giao diện lập trình) công khai. Module thanh toán có đủ cả: tác vụ nền, chuyển trạng thái, ranh giới transaction, payload webhook, thao tác quản trị.
Ở bước lập kế hoạch
| Phần trong file giai đoạn | Vai trò |
|---|---|
| Test trước refactor | Viết test hồi quy trước khi đổi code, để ghi lại hành vi hiện tại. |
| Refactor | Mô tả phần code được đổi, có các test trên bảo vệ. |
| Test bổ sung | Thêm test cho hành vi mới của giai đoạn, nếu có. |
| Cổng cuối giai đoạn | Lệnh compile và test cụ thể phải chạy qua sau refactor. |
Một giai đoạn dùng --tdd thường đi theo thứ tự:
- Viết test bảo vệ hành vi hiện tại.
- Tách một điểm phụ thuộc nhỏ nếu code cũ khó test.
- Refactor code.
- Chạy lại compile và test.
Bước làm cho code cũ test được thường bị bỏ qua. Có khi code cũ không test trực tiếp được: một hàm dài tự gọi database bên trong, không truyền phụ thuộc từ ngoài vào được, không tách riêng được đầu ra. Khi đó cần tách một điểm phụ thuộc nhỏ trước, vẫn giữ hành vi như cũ nhưng làm cho code test được. Sau đó mới refactor thật.
Ở bước cook
Khi /ak-cook chạy với --tdd, thứ tự là:
- Viết test trước: ghi lại hành vi hiện tại trước khi đổi code.
- Refactor: đổi cấu trúc, tách module, làm cho code cũ test được nếu cần.
- Chạy cổng kiểm: test bảo vệ hành vi cũ vẫn phải chạy qua cùng bước compile.
Hiểu đơn giản, test viết trước là mốc so sánh cho hành vi cũ. Sau refactor, nếu mốc này hỏng thì bước cook nên dừng để sửa phần hành vi bị lệch rồi mới đi tiếp.
Lúc viết bài, mình đối chiếu với mã nguồn của skill ak-plan và ak-cook trong một bản beta của Engineer Kit (xem phiên bản đang cài bằng ak --version). Nếu quy trình của hai skill này đổi về sau, các bảng chế độ trong bài có thể lệch.
Vì sao --deep và --tdd hay đi chung
Hai tuỳ chọn giải hai lớp rủi ro khác nhau. Việc có cả hai rủi ro thì bật cả hai.
| Rủi ro | Cần gì | Tuỳ chọn |
|---|---|---|
| Không biết đủ phạm vi | Dò từng giai đoạn, bảng kê file, bản đồ phụ thuộc | --deep |
| Refactor làm lệch hành vi cũ | Test trước refactor, cổng kiểm hồi quy lúc cook | --tdd |
--deep cho bản đồ, --tdd cho lớp kiểm chứng. Refactor lớn thường cần cả hai. Ví dụ một yêu cầu như sau:
Tách billing module ra khỏi monolith.
Giữ API contract hiện tại cho frontend.
Giữ behavior cũ cho retry, idempotency, invoice status.
Đụng database schema, background jobs, API routes, admin UI.Việc này cần --deep vì phạm vi rộng và nhiều phụ thuộc. Nó cũng cần --tdd vì thử lại, idempotent, hoàn tiền và webhook đều là hành vi cũ phải giữ.
Nếu chỉ bật --deep, kế hoạch có thể rất rõ nhưng refactor vẫn thiếu cổng kiểm hồi quy. Nếu chỉ bật --tdd, luồng test có thể đúng nhưng file giai đoạn vẫn mơ hồ: test gì, ở đâu, module nào bị ảnh hưởng, phụ thuộc nào phải đi trước.
Nhớ nhanh: việc rộng thì dùng
--deep. Có hành vi cũ phải giữ thì thêm--tdd. Có cả hai mới bật cả cặp.
Khi nào chạy /ak-brainstorm hoặc /ak-scout trước
Một lỗi dễ gặp: dùng --deep --tdd khi cách làm còn mơ hồ. Chế độ lập kế hoạch không tự gỡ chỗ chưa rõ. Nó chỉ biến cách làm đã chọn thành các bước cụ thể hơn.
Ví dụ, nếu bạn chưa quyết:
- Tách thành dịch vụ riêng thật hay chỉ chia module trong monolith?
- Dùng hàng đợi mới hay giữ tác vụ nền hiện tại?
- Giữ enum trạng thái hoá đơn hiện tại hay đổi sang máy trạng thái rõ ràng hơn?
- Viết lại luồng giao diện quản trị hay refactor từng phần?
Lúc đó nên chạy /ak-brainstorm trước để chốt cách làm, rồi mới lập kế hoạch.
Thêm một lớp nữa là /ak-scout. Xem nó như bước gom ngữ cảnh, không phải bước ra quyết định. Scout hợp khi bạn chưa chắc code nằm ở đâu, module nào liên quan, test nào đang bảo vệ hành vi hiện tại. Khi yêu cầu còn mơ hồ, đừng nhảy thẳng vào lập kế hoạch:
- Scout: tìm code thật, test thật, phụ thuộc thật.
- Brainstorm (động não): chọn cách làm và đánh đổi trước khi khoá kế hoạch.
- Lập kế hoạch: dùng
--deep --tddkhi cách làm đã đủ rõ.
/ak-scout "billing retry flow, invoice status, background jobs, admin UI"
/ak-brainstorm "Tách billing module nhưng giữ API contract hiện tại"
/ak-plan --deep --tdd "Refactor billing module theo approach đã chốt..."Khi đã nắm rõ vùng code liên quan và các đánh đổi chính, bạn có thể bỏ lượt /ak-scout riêng, vì /ak-plan --deep vẫn có bước dò trong quy trình. Nhưng khi yêu cầu còn quá chung, dò trước giúp tránh một lỗi âm thầm: agent lập luận nghe hợp lý nhưng đang bám vào một bản đồ dự án sai.
| Tình huống | Bắt đầu từ |
|---|---|
| Chưa rõ ngữ cảnh dự án, chưa biết code nằm đâu | /ak-scout rồi /ak-brainstorm |
| Biết rõ làm gì và làm thế nào | /ak-plan trực tiếp |
| Biết làm gì, chưa chắc làm thế nào | /ak-brainstorm rồi /ak-plan |
| Chưa biết có nên làm không | /ak-brainstorm, quyết định, rồi lập kế hoạch hoặc bỏ |
Bảng chọn lệnh
Gọn lại: chưa rõ phạm vi thì /ak-scout trước, chưa rõ cách làm thì /ak-brainstorm trước, refactor lớn thì /ak-plan --deep --tdd. Đầy đủ hơn:
| Tình huống | Lệnh |
|---|---|
| Chưa rõ ngữ cảnh dự án | /ak-scout trước, rồi brainstorm hoặc plan |
| Chưa chắc cách làm | /ak-brainstorm trước |
| Sửa nhỏ 1 đến 2 file | /ak-plan --fast |
| Tính năng mới cỡ vừa | /ak-plan (chế độ tự chọn) |
| Tính năng phức tạp, mảng nghiệp vụ lạ | /ak-plan --hard |
| Từ 3 module độc lập trở lên, làm song song | /ak-plan --parallel |
| Phân vân giữa 2 cách làm cụ thể | /ak-plan --two |
| Refactor từ 5 vùng trở lên, có nợ kiến trúc | /ak-plan --deep |
| Refactor code đang chạy hoặc đang dùng nội bộ, sợ lỗi hồi quy | Chế độ nào cũng được, thêm --tdd |
| Refactor lớn trên codebase có hành vi cần giữ | /ak-plan --deep --tdd |
Cặp --deep --tdd không phải một cơ chế duy nhất mà là hai việc khác nhau đi cùng nhau. Chi phí lập kế hoạch tăng, nhưng bước cook bớt phải đoán phạm vi và có cổng kiểm hồi quy rõ hơn.
Bên trong: hai tuỳ chọn tác động ra sao
Phần này đi sâu hơn vào cách --deep và --tdd tác động lúc lập kế hoạch, lúc cook và lên chi phí chạy.
--deep tốn hơn vì thêm lượt nghiên cứu và dò từng giai đoạn
| Chế độ | Lượt nghiên cứu | Phản biện | Kiểm định | Dò từng giai đoạn |
|---|---|---|---|---|
--fast | 0 | 0 | 0 | Không |
--hard | 2 | Có | Tuỳ chọn | Không |
--deep | 2 đến 3 | Có | Có | Có |
--parallel | 2 | Có | Tuỳ chọn | Không |
--two | Từ 2 | Sau khi chọn | Sau khi chọn | Không |
Chi phí của --deep chủ yếu đến từ hai đến ba lượt nghiên cứu kiến trúc tổng thể, lượt phản biện, bước kiểm định và lượt đọc lại theo từng giai đoạn. Nói đơn giản, mỗi giai đoạn được soi riêng trước khi chốt kế hoạch: đụng file nào, phụ thuộc giai đoạn nào, còn thiếu test gì, có trường hợp biên nào dễ sót.
Đừng hiểu sai chữ "scout" ở đây. Nó nói về việc phải đọc và kiểm lại theo từng giai đoạn, không cam kết lúc chạy luôn tạo một agent riêng. Ý chính là --deep bắt kế hoạch đi qua nhiều lượt kiểm nhỏ hơn, thay vì chỉ nhìn phạm vi một lần ở mức tổng quan.
--tdd không tạo agent mới
--tdd không đổi chế độ đã chọn. Nó là cờ cộng thêm: bạn vẫn chạy --fast, --hard hoặc --deep như bình thường, chỉ thêm cấu trúc viết test trước. Cờ này chỉ đổi hai thứ:
- File giai đoạn lúc lập kế hoạch. Một giai đoạn bình thường có tổng quan, yêu cầu, kiến trúc, file liên quan, các bước triển khai, tiêu chí hoàn thành, đánh giá rủi ro. Khi bật
--tdd, giai đoạn có thêm phần test trước refactor, test sau refactor và cổng cuối giai đoạn. - Thứ tự thực thi lúc cook. Viết test bảo vệ hành vi cũ trước, refactor sau, rồi chạy lại compile và test.
Chi phí của --tdd thấp hơn --deep nhiều, vì nó chủ yếu thêm cấu trúc vào file giai đoạn và đổi thứ tự thực thi lúc cook.
Cổng kiểm hồi quy cần lệnh cụ thể
Đặc tả của bước cook yêu cầu cổng kiểm hồi quy là một lệnh compile hoặc test cụ thể. Với dự án Go, ví dụ:
Regression Gate: go test ./... && go vet ./...Nếu file giai đoạn chỉ ghi chung chung "run tests to verify", bước kiểm chứng yếu đi vì cook không có lệnh chính xác để bám vào. Cờ --tdd không tự đảm bảo đoán đúng công cụ trong mọi repo. Nếu dự án dùng lệnh riêng, hãy ghi rõ ngay trong mô tả việc hoặc trong file kế hoạch:
Project dùng go test ./..., frontend dùng npm test, E2E dùng Playwright.Khi mô tả việc nêu rõ công cụ, kế hoạch có cơ sở để ghi đúng cổng kiểm cho từng giai đoạn.
Cách chạy và mẫu lệnh chung
Mẫu dưới đây bám theo mã nguồn skill của ak-plan và ak-cook: plan nhận mô tả việc cùng chế độ và cờ, cook nhận đường dẫn kế hoạch và giữ --tdd nếu kế hoạch đã bật cờ này.
/ak-plan [mode] [--tdd] "[Việc cần làm].
Phạm vi: [module/file/stack bị đụng].
Giữ nguyên: [API contract, behavior cũ, compatibility].
Đụng: [database, job, route, UI, shared type].
Tooling: [compile/test command cụ thể].
Known bugs / out of scope: [nếu có]."Nếu kế hoạch dùng --tdd, khi chạy cook cũng thêm --tdd:
/ak-cook /absolute/path/to/plan.md --tddÁp mẫu vào vài tình huống hay gặp.
--deep cho giai đoạn lập bảng kê
/ak-plan --deep "Lập plan inventory để chuẩn bị tách billing module ra package riêng.
Scope: API routes, invoice service, payment jobs, admin UI, database schema.
Output cần có: file inventory, dependency map, phase ownership, risk list.
Chưa refactor behavior đang chạy trong round này."--hard --tdd cho refactor code đang chạy
/ak-plan --hard --tdd "Refactor invoiceStatusService: tách transition rules
ra file riêng, giữ exact behavior cho retry, failed, refunded, voided."--deep --tdd cho refactor lớn có hành vi cần giữ
/ak-plan --deep --tdd "Tách billing module ra khỏi monolith.
Giữ API contract cho frontend, giữ behavior retry/idempotency/refund/webhook.
Đụng: database schema, payment jobs, API routes, admin UI. Project dùng
go test ./..., frontend dùng npm test."Một mô tả việc tốt thường có đủ:
- Phạm vi: file, module hay stack nào.
- Ràng buộc: không được phá gì, giữ tương thích gì.
- Công cụ: lệnh test, lệnh compile, rất quan trọng với
--tdd. - Kết quả mong muốn: ngắn gọn nhưng cụ thể.
Đầu vào quá mơ hồ, ví dụ "refactor billing", sẽ cho ra kế hoạch mơ hồ. Bước dò không có điểm neo cụ thể thì kết quả rất dễ chung chung.
Nên làm và cần tránh
Hai nhóm dưới đây là những chỗ hay vấp nhất khi dùng --deep --tdd: việc nên làm trước khi cook và các lỗi nên tránh.
Nên làm trước khi cook
Giữ worktree sạch trước khi lập kế hoạch
Nếu thư mục làm việc còn thay đổi chưa commit từ việc khác, bước dò dễ lẫn code hiện tại với code đang dở. Trước một kế hoạch lớn, hãy commit hoặc stash. Tốt hơn nữa là tạo worktree riêng bằng /ak-worktree.
Đọc lại file giai đoạn trước khi cook
Kế hoạch --deep --tdd chạy khá lâu, nên đừng cook ngay khi chưa đọc lại plan.md và các file giai đoạn nó tạo ra. Soát qua năm câu hỏi:
- Bảng kê file: có file nào bạn không muốn agent đụng?
- Ma trận kịch bản test: có sót race condition hay trường hợp biên như webhook gửi trùng?
- Thứ tự giai đoạn: các giai đoạn có thật sự độc lập, hay migration phải đi trước tác vụ nền?
- Cổng kiểm hồi quy: đúng công cụ và đúng nhóm test chưa?
- Lỗi đã biết: cần sửa hay cần giữ nguyên hành vi cũ?
Khai báo lệnh test trong mô tả việc
Với --tdd, nếu repo dùng công cụ lạ như bun thay cho npm, mise thay cho asdf, task thay cho make, hãy khai báo luôn:
Project dùng go test ./..., frontend dùng npm test, E2E dùng Playwright.Không khai báo thì agent sẽ đoán. Đoán sai lệnh làm cổng kiểm hồi quy yếu đi.
Chạy /clear giữa lập kế hoạch và cook
Ngữ cảnh lập kế hoạch của việc lớn thường rất nặng: kết quả nghiên cứu, dữ liệu dò, nhận xét phản biện. Luồng nên dùng: lập kế hoạch xong, chạy /clear, mở lại, rồi chạy /ak-cook {absolute-path}/plan.md --tdd. Bước cook đọc lại từ file kế hoạch, không cần ngữ cảnh lập kế hoạch cũ.
Cần tránh
| Lỗi dễ mắc | Vì sao hỏng | Nên làm |
|---|---|---|
Quên --tdd ở /ak-cook | Cook vẫn đọc phần test trước refactor nhưng không ép viết test trước, nên test có thể được viết sau code. | Dùng đúng lệnh cook mà kế hoạch gợi ý ở cuối. |
Dùng --deep cho việc nhỏ | Dưới khoảng năm file thì lượt dò từng giai đoạn thường thừa. | Dùng --hard hoặc --fast cho gọn. |
Dùng --tdd cho code mới hoàn toàn | Code mới chưa có hành vi để giữ, phần test trước refactor gần như rỗng, agent dễ viết test cho có. | Dùng --hard để test được viết theo luồng thường. |
| Tin tuyệt đối vào file giai đoạn | --deep dò kỹ hơn nhưng vẫn có thể sót phụ thuộc ngầm. | Trước khi cook, tự hỏi giai đoạn sau có đang ngầm cần thứ giai đoạn trước chưa tạo ra không. |
Để --tdd chụp luôn lỗi có sẵn | Nếu test chụp lỗi cũ (ví dụ webhook gửi trùng tạo hai lượt thanh toán) thành "hành vi hiện tại", refactor vô tình sửa lỗi sẽ làm cổng kiểm hỏng và agent có thể sửa ngược về lỗi cũ. | Khai báo lỗi đã biết trong mô tả việc, hoặc tách hai kế hoạch: sửa lỗi trước, refactor sau. |
Cố ghép --deep với --parallel | Cả hai đều là chế độ nên không ghép được. | Cần nhiều agent song song thì dùng --parallel --tdd và phân vai, phạm vi test thật rõ; chưa chắc thì bỏ --parallel, giữ --deep --tdd. |
Tóm lại
--deep --tdd không dành cho mọi việc. Nó dành cho nhóm việc có hai dấu hiệu:
- Phạm vi đủ lớn để một kế hoạch thường dễ thiếu bản đồ.
- Code hiện tại có hành vi cần giữ sau refactor.
--deep làm bước lập kế hoạch chậm hơn, đổi lại file giai đoạn rõ hơn: bảng kê file, chỗ thiếu test, bản đồ phụ thuộc, danh sách hàm và interface. --tdd làm bước cook chậm hơn, đổi lại refactor có cổng kiểm hồi quy: viết test trước, refactor, rồi kiểm lại.
Nếu bạn ở vai trò quản lý sản phẩm hay người sáng lập, chỉ cần biết hai tuỳ chọn này tồn tại. Khi đội chuẩn bị refactor một module lớn như thanh toán, hãy hỏi xem kế hoạch đã có bước dò từng giai đoạn và cổng kiểm hồi quy chưa.
Nếu bạn là lập trình viên, hãy thử ở việc lớn kế tiếp. Lần đầu có thể thấy tốn thêm thời gian. Nhưng chỉ cần một lần test viết trước bắt được một lỗi hồi quy ngầm, phần chi phí đó sẽ dễ chấp nhận hơn nhiều.
Một lưu ý cuối: về nguyên tắc --tdd đi được với mọi chế độ, nhưng ghép với --fast thường không đáng, vì bạn đã chọn đi nhanh.
Nếu bạn mới làm quen AgentKit, đọc thêm bài nhập môn AgentKit cho Claude Code. Muốn so ak-plan với Plan mode của Oh-my-pi (OMP), xem bài OMP Plan mode và AgentKit ak-plan.
Dùng bài này trong agent của bạn
Lấy API keyChép đoạn dưới, dán vào Claude Code, Codex hay agent bạn đang dùng. Agent đọc bài rồi đối chiếu với repo đang mở.
Đọc bài "Khi nào nên bật --deep và --tdd cho /ak-plan" trên modernEngineer rồi áp dụng vào repo này.
1. Gọi tool content_get của MCP server modernengineer với locale "vi", slug "ck-plan-deep-tdd-when-to-use". Nếu chưa nối MCP hoặc bị từ chối quyền, đọc thẳng trang https://modernengineer.dev/vi/library/ck-plan-deep-tdd-when-to-use.
2. Tóm tắt các bước chính của bài, chỉ ra bước nào áp dụng được cho repo này.
3. Đề xuất thay đổi cụ thể và hỏi tôi trước khi sửa file.Nối MCP cho Claude Code (một lần)
claude mcp add --transport http modernengineer \
https://api.modernengineer.dev/mcp \
--header "Authorization: Bearer <API key>"Bài mở cho mọi người: chưa nối MCP thì agent vẫn đọc được thẳng từ link bài.
- Phiên bản
- v1.0.0
- Cập nhật
- 22/05/2026
- Giấy phép
- Bảo lưu mọi quyền
- Slug
- ck-plan-deep-tdd-when-to-use
