Debug với AI: tìm root cause bằng Claude Code (2026)

Jasmine, dev dùng Claude Code để debug hằng ngày.

Debug với AI là gì?

Debug với AI là cách dùng một AI agent - ở đây là Claude Code - để điều tra nguyên nhân gốc của lỗi bằng cách đọc code, đọc log và lần theo luồng thực thi, chứ không chỉ gợi ý một đoạn sửa. Khác biệt nằm ở vai trò: bạn không hỏi "sửa lỗi này giúp tôi", bạn giao cho AI nhiệm vụ của một điều tra viên: "tìm xem vì sao nó hỏng".

Điểm quan trọng nhất mà đa số hướng dẫn bỏ qua là phân biệt triệu chứng và root cause. Stack trace chỉ cho bạn thấy nơi chương trình sụp đổ - nhưng nơi ném exception thường không phải nơi bug thật. Một NullPointerException nổ ở tầng view có thể bắt nguồn từ một truy vấn ở repository trả về null vì thiếu điều kiện lọc, cách đó ba file. Nếu bạn chỉ dán dòng lỗi cuối và xin fix, AI sẽ "vá triệu chứng": thêm một câu kiểm tra null ngay chỗ nổ. Lỗi biến mất trên màn hình, nhưng dữ liệu sai vẫn chảy ngầm - và sẽ nổ lại ở chỗ khác.

Debug với AI làm đúng là để AI đi ngược từ triệu chứng về nguồn, dựng giả thuyết, kiểm chứng bằng bằng chứng trong code, rồi mới đề xuất sửa. Đây là điều tra, không phải đoán. Muốn hiểu cách tiếp cận này nằm trong bức tranh lớn hơn, xem quy trình vibe coding với AI.

Vì sao Claude Code giỏi tìm root cause?

Điểm mạnh của Claude Code trong root cause analysis đến từ khả năng làm việc với cả codebase, không chỉ một đoạn code dán vào ô chat. Theo tài liệu Claude Code của Anthropic (truy cập 08/2026), agent có thể tự đọc file, tìm kiếm trong repo và chạy lệnh - nghĩa là nó lần được một lỗi xuyên nhiều file: từ controller xuống service, xuống repository, chứ không kẹt ở một khung nhìn hẹp.

Cụ thể, có ba việc Claude Code làm tốt khi truy nguyên nhân:

• Trace execution xuyên tầng. Đưa nó một stack trace, nó tự mở các file trong trace, đọc hàm gọi qua lại và dựng lại đường đi của dữ liệu - thứ mà bạn phải nhảy tab thủ công.
• Phát hiện bug tinh vi đa tầng. Những lỗi như một biến bị mutate ngoài ý muốn, một điều kiện async chạy sai thứ tự, hay một mismatch giữa schema DB và model code - Claude Code đối chiếu được vì nó đọc được cả hai đầu.
• Điều tra trong ngữ cảnh cô lập. Bạn có thể giao việc dò lỗi cho một phiên/subagent riêng để hội thoại chính không bị loãng bởi hàng chục dòng log.

Ngoài ra, vì Claude Code chạy được lệnh, nó có thể tự đóng vòng lặp điều tra: sửa thử một chỗ, chạy lại test tái hiện, đọc kết quả, rồi điều chỉnh giả thuyết dựa trên bằng chứng mới. Đây là khác biệt lớn so với một trợ lý chỉ trả lời văn bản - nó kiểm chứng được thay vì chỉ phán đoán.

Nói thẳng cho cân bằng: "đọc được cả codebase" không có nghĩa "luôn đúng". Claude Code vẫn có thể đề xuất một nguyên nhân nghe hợp lý mà sai, đặc biệt khi context thiếu hoặc trace bị cắt. Sức mạnh thật chỉ phát huy khi bạn ép nó chứng minh giả thuyết bằng code - phần dưới sẽ chỉ cách.

Chuẩn bị trước khi debug với AI

Một phiên debug với AI thất bại thường vì thiếu nguyên liệu đầu vào, không phải vì AI "kém". Trước khi mở phiên, chuẩn bị checklist sau:

• Tái hiện được lỗi. Bạn cần một lệnh, một test, hoặc một bước bấm cụ thể làm lỗi xuất hiện ổn định. Lỗi "thỉnh thoảng mới bị" khó gấp bội - hãy tìm cách làm nó nổ đều trước đã.
• Có full stack trace hoặc log đầy đủ. Không phải một dòng cuối, mà toàn bộ trace kèm các frame gọi. Đây là bản đồ để AI lần ngược.
• Cấp quyền chạy test/lệnh. Cho phép Claude Code chạy test suite hoặc lệnh reproduce để nó tự kiểm chứng thay vì đoán. Nếu chưa cài, xem hướng dẫn cài đặt Claude Code.
• Biết hành vi mong đợi. Ghi rõ "đáng ra phải trả về X, nhưng đang trả về Y" - không có mốc đúng thì không có gì để so.

6 bước tìm root cause với Claude Code

Đây là quy trình mình dùng lặp đi lặp lại. Điểm khác biệt so với "hỏi AI sửa lỗi" là có một bước xác minh giả thuyết trước khi chạm vào code.

Bước 1: Tái hiện lỗi và lấy full stack trace

Chạy lệnh làm lỗi nổ và copy toàn bộ trace, không chỉ dòng cuối. Càng nhiều frame, AI càng có manh mối. Nếu lỗi chỉ xuất hiện qua UI, hãy viết một script reproduce nhỏ để nó nổ đều trong terminal - vừa nhanh hơn, vừa cho AI một điểm bám ổn định để chạy lại sau khi sửa. Kèm luôn giá trị đầu vào gây lỗi (payload, tham số) để AI không phải đoán dữ liệu.

npm test -- users.spec.ts
# hoặc chạy trực tiếp kịch bản reproduce
node scripts/reproduce-bug.js

Bước 2: Nạp context đầy đủ

Dán full stack trace vào Claude Code và trỏ tới các file liên quan. Đừng bắt AI đoán file - chỉ đường cho nó. Kèm mô tả hành vi mong đợi so với hành vi thực tế ("đáng ra tổng phải dương, nhưng đang ra âm") để AI có mốc so sánh. Nếu lỗi liên quan dữ liệu, dán thêm mẫu bản ghi hoặc schema; AI đối chiếu được giữa code và dữ liệu thật sẽ khoanh vùng nhanh hơn nhiều.

Đây là stack trace đầy đủ (dán nguyên). Lỗi xuất hiện khi
gọi POST /orders. Các file liên quan: src/orders/order.service.ts,
src/orders/order.repository.ts, src/payments/payment.client.ts.
Đừng sửa gì vội - đọc trước đã.

Bước 3: "Investigate first, do not edit"

Đây là câu lệnh quyết định. Bạn buộc AI chuyển từ chế độ "vá" sang chế độ "điều tra": đọc code, giải thích luồng, chỉ ra chỗ nghi ngờ - trước khi đề xuất bất kỳ thay đổi nào. Không có bước này, AI có xu hướng sửa ngay dòng đầu tiên nó thấy khả nghi. Yêu cầu AI liệt kê 2-3 giả thuyết xếp theo khả năng, mỗi giả thuyết kèm dòng code làm bằng chứng - cách này lộ ra ngay khi AI đang suy đoán mà không có căn cứ trong code thật.

Bước 4: Xác minh giả thuyết root cause

Khi AI đưa ra một nguyên nhân, đừng tin ngay. Dùng phương pháp 5 Whys (hỏi "vì sao" liên tiếp tới khi chạm gốc) và yêu cầu bằng chứng cụ thể trong code cho từng bước. Với lỗi hồi quy khó, nhờ AI dựng lệnh git bisect để khoanh vùng commit gây lỗi.

Vì sao biến `total` bị âm? Chỉ cho tôi đúng dòng code gán giá trị đó,
và giá trị đầu vào đến từ đâu. Chứng minh bằng code, đừng suy đoán.

Bước 5: Áp dụng fix nhỏ nhất an toàn kèm test tái hiện

Khi root cause đã rõ và có bằng chứng, yêu cầu fix nhỏ nhất giải quyết đúng nguyên nhân - không refactor kèm, không "tiện tay dọn". Fix càng nhỏ, diff càng dễ review và càng ít khả năng đẻ bug mới. Đồng thời viết một test tái hiện lỗi: test này phải fail trước khi sửa và pass sau khi sửa, đó là bằng chứng khách quan rằng bạn đã chạm đúng gốc chứ không phải may mắn. Nếu bạn muốn đi xa hơn theo hướng viết test dẫn dắt, xem TDD với AI.

Bước 6: Ghi lại pattern lỗi

Sau khi fix, note lại pattern vào file CLAUDE.md của dự án - ví dụ "repo trả null khi thiếu tenantId; luôn kiểm tra filter theo tenant". Lần sau, AI đọc được ghi chú này và tránh vấp lại. Đây là cách biến mỗi lần debug thành tài sản lâu dài của codebase.

Phiên debug thật: từ stack trace tới root cause

Kể một ca thật gần đây để thấy vì sao "nơi lỗi nổ" khác "nơi bug nằm". API POST /orders thỉnh thoảng trả về tổng tiền âm. Stack trace không crash - chỉ log một cảnh báo ở tầng payment: giá trị amount không hợp lệ. Bản năng đầu tiên là thêm if (amount < 0) amount = 0 ngay tại payment client. Đó chính là vá triệu chứng.

Thay vì vá, mình dán full log và ép điều tra. Claude Code đọc ngược từ payment client → order service → order repository, và chỉ ra: một mã giảm giá hết hạn không bị lọc ở repository, nên một dòng discount cũ vẫn được cộng vào giỏ với dấu ngược. Root cause nằm ở tầng repository, cách chỗ log cảnh báo hai tầng. Fix nhỏ nhất là thêm điều kiện lọc expired = false ở truy vấn discount - không phải kẹp giá trị ở payment.

Trung thực một chỗ: ở lần chạy đầu, Claude Code suýt đi sai - nó đề xuất một nguyên nhân ở tầng service (làm tròn số) nghe rất hợp lý. Chỉ khi mình bắt nó chứng minh bằng dữ liệu thật (Bước 4), giả thuyết đó sụp và nó mới lần đúng xuống repository. Đó là lý do bước xác minh không thể bỏ.

Bài học rút ra và đáng ghi lại: nơi log cảnh báo xuất hiện là nơi hậu quả lộ ra, không phải nơi nguyên nhân sinh ra. Nếu hôm đó mình vá ngay ở payment client, tổng tiền trên hóa đơn sẽ đúng, nhưng bản ghi discount hết hạn vẫn nằm sai trong giỏ và sẽ gây lệch báo cáo doanh thu về sau - một lỗi âm thầm tốn hơn nhiều so với dòng log ban đầu.

Dùng /debug và subagent để cô lập context

Một phiên debug tạo ra rất nhiều "tiếng ồn": hàng chục dòng log, nhiều lần đọc file. Nếu để chung với hội thoại đang làm feature, context chính bị loãng và chất lượng câu trả lời tụt. Giải pháp là cô lập việc điều tra.

Claude Code cho phép định nghĩa slash command tùy biến và giao việc cho subagent chuyên trách. Bạn có thể tạo một lệnh /debug của riêng dự án - một prompt đóng gói sẵn quy trình 6 bước ở trên (điều tra trước, chứng minh root cause, đề xuất fix nhỏ nhất) - rồi gọi mỗi khi cần. Hoặc giao toàn bộ việc dò lỗi cho một subagent debug riêng: nó chạy trong ngữ cảnh tách biệt, trả về kết luận gọn, còn phiên chính của bạn giữ nguyên độ sạch.

Lợi ích kép: context không bị nhiễm log, và bạn tái dùng đúng một quy trình chuẩn cho mọi bug thay vì gõ lại prompt mỗi lần. Một mẹo thực chiến: đặt subagent debug ở chế độ chỉ-đọc trong lúc điều tra, chỉ mở quyền sửa sau khi bạn duyệt kết luận root cause. Như vậy phần "điều tra" và phần "sửa" được tách bạch rõ, đúng tinh thần Bước 3 - và bạn luôn là người bấm nút cho thay đổi thật sự xảy ra.

Mẫu prompt debug hiệu quả (copy được)

Đây là bộ prompt mình tái dùng. Copy, thay phần trong ngoặc, dán vào Claude Code.

# 1. Điều tra trước, không sửa
Đọc [các file] và giải thích luồng dẫn tới lỗi trong stack trace này:
[dán full trace]. ĐỪNG sửa gì. Chỉ liệt kê 2-3 giả thuyết root cause,
xếp theo khả năng, kèm dòng code làm bằng chứng cho mỗi giả thuyết.

# 2. Trace root cause
Đi ngược từ chỗ lỗi nổ về nguồn. Với mỗi bước, trả lời "vì sao"
(5 Whys) và trích đúng dòng code chứng minh. Dừng khi chạm nguyên nhân
không thể hỏi "vì sao" thêm.

# 3. Đề xuất fix nhỏ nhất an toàn
Root cause đã xác nhận là [X]. Đề xuất thay đổi NHỎ NHẤT sửa đúng
nguyên nhân này. Không refactor kèm. Kèm 1 test tái hiện lỗi.

# 4. Giải thích vì sao lỗi xảy ra
Tóm tắt trong 3 câu: lỗi là gì, root cause ở đâu, vì sao fix này an toàn -
để tôi ghi vào CLAUDE.md.

Sai lầm thường gặp khi debug với AI

• Tin fix đầu tiên. Đề xuất đầu tiên thường vá triệu chứng. Luôn hỏi "đây là root cause hay chỉ là chỗ lỗi nổ?".
• Dán thiếu trace. Chỉ đưa dòng lỗi cuối cắt mất bản đồ; AI buộc phải đoán và đoán sai.
• Để AI sửa khi chưa rõ nguyên nhân. Sửa mù có thể che lỗi hoặc đẻ thêm bug ở chỗ khác.
• Bỏ qua khả năng AI hallucinate nguyên nhân. AI có thể dựng một chuỗi lý luận nghe rất chắc mà sai - nên mới cần bắt chứng minh bằng code.
• Không viết test tái hiện. Fix xong không có lưới an toàn, lỗi quay lại vài sprint sau chẳng ai biết.

Nhiều trong số này trùng với các lỗi Claude Code thường gặp - đọc thêm để tránh vấp. Với lỗi liên quan bảo mật, nên tách riêng sang quy trình security audit với Claude Code.

Tăng tốc debug bằng skill root-cause dựng sẵn (AgentKit)

Nếu bạn muốn khỏi phải tự gõ lại quy trình 6 bước mỗi lần, Engineer Kit của AgentKit có sẵn skill debug hệ thống đóng gói đúng tư duy này - bắt chứng minh root cause trước khi đề xuất sửa, thay vì nhảy thẳng vào vá. Nó không "thông minh hơn" Claude Code; nó chỉ chuẩn hóa kỷ luật điều tra để bạn không quên bước xác minh. Engineer Kit có giá $99 (trang không nêu phí định kỳ). Nếu quy trình trong bài hợp với bạn, có thể xem Engineer Kit cho Claude Code — giảm 20%, còn $79.20 để dùng luôn.

Câu hỏi thường gặp (FAQ)

AI có tự sửa đúng root cause không?

Không tự động. AI có thể lần đúng nguyên nhân nếu bạn cung cấp full stack trace, trỏ đúng file và buộc nó điều tra trước khi sửa. Bỏ qua bước xác minh, nó thường vá triệu chứng thay vì gốc.

Cần dán bao nhiêu stack trace cho AI?

Dán toàn bộ trace, không chỉ dòng cuối. Các frame gọi phía trên là bản đồ để AI lần ngược về nguồn. Kèm luôn log xung quanh thời điểm lỗi và câu lệnh tái hiện.

Debug với AI khác dùng ChatGPT thế nào?

ChatGPT thường chỉ đọc đoạn code bạn dán vào ô chat. Claude Code là agent chạy trong dự án: tự mở file, tìm trong repo, chạy test - nên trace được lỗi xuyên nhiều file thay vì đoán trong ngữ cảnh hẹp.

Claude Code chạy trên Windows debug được không?

Được. CLI ak và Claude Code chạy native trên Windows, macOS và Linux. Quy trình 6 bước trong bài không phụ thuộc hệ điều hành; chỉ khác lệnh tái hiện lỗi theo stack của bạn.

AI có làm hỏng code khi sửa không?

Có rủi ro nếu để AI sửa khi chưa rõ nguyên nhân. Giảm rủi ro bằng cách yêu cầu fix nhỏ nhất, review kỹ diff trước khi chấp nhận, và luôn có test tái hiện lỗi làm lưới an toàn.

Công cụ nào tốt cho lỗi đa file?

Lỗi trải nhiều tầng (controller → service → repository) cần agent đọc được cả codebase, như Claude Code. Công cụ chỉ nhận một đoạn code dán vào sẽ khó nối các mảnh xuyên file.

Kết luận + bước tiếp theo

Chốt lại một câu: tìm root cause trước, fix sau. Sức mạnh của debug với AI không nằm ở việc xin một đoạn vá nhanh, mà ở việc biến Claude Code thành điều tra viên - buộc nó điều tra, chứng minh giả thuyết, rồi mới sửa nhỏ nhất kèm test. Sau khi fix xong, nên để AI review lại code và cân nhắc viết test trước khi sửa theo hướng TDD để chống hồi quy. Muốn chuẩn hóa kỷ luật này thành một bộ workflow dùng ngay, hãy dùng thử AgentKit (giảm 20% qua link).