Tóm tắt nhanh:
ak-debugtìm nguyên nhân gốc của lỗi và chứng minh nó bằng bằng chứng, thay vì sửa theo phỏng đoán. Có nguyên nhân rồi thì nó chuyển choak-fix, hoặcak-brainstormkhi có nhiều cách sửa đáng cân nhắc. Nó không viết test mới cho code đang chạy đúng, việc đó thuộcak-test.
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%.
Tóm tắt
Dùng khi test đang xanh bỗng đỏ, CI đỏ mà máy bạn xanh, server trả lỗi hàng loạt, hệ thống chậm đi, hay có bug chập chờn chưa tái hiện ổn định. Không cần khi chưa có gì hỏng và bạn chỉ muốn viết thêm test, lúc đó dùng ak-test.
flowchart LR
S["ak-scout tìm code liên quan"] --> B["ak-debug"]
A["Test fail, lỗi, output sai"] --> B
B --> C["Nguyên nhân gốc có bằng chứng"]
C --> D["ak-fix"]
C --> E["ak-brainstorm khi có nhiều cách sửa"]
B --> F["Dừng: sửa hỏng 3 lần, xem lại kiến trúc"]Nó luôn giữ 4 nguyên tắc:
| Nguyên tắc | Câu hỏi | Ví dụ |
|---|---|---|
| Nguyên nhân gốc | Lỗi bắt đầu từ đâu, chứ không phải nó hiện ra ở đâu? | Trang thanh toán báo "undefined", nhưng gốc là hàm đọc cấu hình trả chuỗi rỗng ở ba tầng gọi phía trên. Sửa ở hàm cấu hình, không vá ở trang thanh toán. |
| Một giả thuyết một lần | Mình đang thử đúng một điều, và nói rõ vì sao nghĩ vậy chưa? | "Cache hết hạn sớm vì TTL tính bằng giây mà code truyền mili giây." Đổi đúng một biến đó để thử. Sai thì đặt giả thuyết mới, không chồng thêm bản sửa. |
| Bằng chứng mới | Lệnh nào chứng minh lời nói "đã xong", và vừa chạy nó chưa? | Chạy lại đúng test đã fail, thấy 0 failed. Với test hồi quy: gỡ bản sửa thì test phải đỏ, trả bản sửa lại thì xanh. |
| Mốc 3 lần sửa | Đã thử sửa bao nhiêu lần mà vẫn hỏng? | Lần sửa thứ 3 vẫn hỏng, và mỗi lần lại lộ ra một chỗ dùng chung trạng thái khác. Nó dừng và hỏi bạn có nên xem lại kiến trúc hoặc phạm vi không. |
Lỗi trong code (test, bug, build) đi qua 4 pha: điều tra, tìm mẫu đúng để so, thử giả thuyết, rồi mới sửa. Lỗi hệ thống (server, CI, DB, hiệu năng) đi qua 5 bước, từ đánh giá phạm vi tới đề xuất cách sửa.
Prompt mẫu cho test fail sau khi merge:
/ak-debug Test <tên test> trong <dự án> bắt đầu fail sau lần merge gần nhất.
Lỗi: <dán thông báo lỗi và stack trace>.
Kỳ vọng: <hành vi đúng>.
Xong khi: test đó pass và các test khác không hỏng.| Cờ | Để làm gì | Từ ak |
|---|---|---|
--ultra | 5 bản chẩn đoán độc lập, chọn bản tốt nhất | 2.13.0 |
Phần dưới đây là bản chi tiết: luồng chạy, 6 tình huống kèm prompt, giải thích từng cờ (dùng khi, không cần khi, nhận lại gì, đi kèm cờ nào), lịch sử thay đổi theo bản ak và các lỗi hay vấp. Bản chi tiết và trang trực quan dành cho subscriber. Agent của bạn cũng tìm được trong đó qua MCP của portal.
Mở khi tài khoản có quyền subscriber
Bài này dành cho subscriber
Khi tài khoản có quyền, toàn bộ bài, bản visual tương tác và lệnh gọi từ agent đều mở.
- Đăng nhập hoặc tạo tài khoản modernEngineerQuyền đọc gắn với email tài khoản.
- Chọn gói trên trang Bảng giáGói 1, 3 hoặc 12 tháng, trả bằng chuyển khoản VietQR. Quyền đọc mở khoảng một phút sau khi tiền về.
- Hoặc nhập mã Facebook subscriberNgười ủng hộ trang qua Facebook nhận mã kích hoạt qua tin nhắn mỗi tháng.
Đã là subscriber? Đăng nhập để đọc.
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 "ak-debug: chứng minh nguyên nhân gốc trước khi sửa lỗi" 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 "ak-debug". Nếu chưa nối MCP server modernengineer, dừng lại và hướng dẫn tôi nối theo https://modernengineer.dev/vi/mcp.
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>"Đọc trọn bài qua MCP cần API key của tài khoản subscriber hoặc đã mua guide này. Không có quyền, agent sẽ chỉ đọc được phần mở đầu.
- Phiên bản
- v1.0.0
- Cập nhật
- 22/10/2026
- Giấy phép
- Bảo lưu mọi quyền
- Slug
- ak-debug
