Quy trình 4 bước tìm nguyên nhân gốc rễ (Root cause tracing) thay vì sửa mò trong claude code

Việc ném một đoạn log lỗi (stack trace) vào Claude Code và ra lệnh "Sửa lỗi này cho tôi" là cách nhanh nhất để tạo ra code rác. AI có xu hướng "chiều chuộng" người dùng bằng cách đoán mò (guesswork), thêm các câu lệnh if/else bọc tạm bợ (patching), hoặc nuốt lỗi (swallow exceptions) chỉ để làm mất dòng báo đỏ.

Để tận dụng tối đa năng lực phân tích mã nguồn nguyên bản (codebase-aware) của Claude Code CLI, bạn cần ép AI tuân thủ quy trình Root Cause Tracing (Truy tìm nguyên nhân gốc rễ) gồm 4 bước nghiêm ngặt dưới đây.

Bước 1: Đóng băng trạng thái và Thu thập Context (Snapshot & Gather)

Đừng cố gắng thay đổi bất kỳ dòng code nào khi lỗi vừa xảy ra. Mục tiêu đầu tiên là phải cung cấp cho Claude Code toàn cảnh bức tranh (context) tại đúng thời điểm hệ thống "chết".

Thay vì copy-paste thủ công, hãy tận dụng quyền truy cập file của Claude Code trong terminal.

Thao tác với Claude Code:

"Hệ thống vừa văng lỗi 500 khi user thực hiện checkout. Hãy mở file storage/logs/laravel.log (hoặc /var/log/nginx/error.log), đọc 100 dòng cuối cùng. Sau đó, phân tích nội dung Request Payload và Stack Trace hiện tại. Tuyệt đối chưa được đề xuất giải pháp."

Kết quả kỳ vọng: Claude Code sẽ liệt kê chính xác file bị crash, dòng code gây lỗi, và các tham số đầu vào (input) đã dẫn đến exception đó.

Bước 2: Truy vết luồng thực thi ngược (Reverse Execution Tracing)

Lỗi hiển thị ở dòng số 50 của file checkout.service.ts chưa chắc đã do hàm đó sai. Nguyên nhân gốc rễ có thể nằm ở Middleware đã truyền sai định dạng dữ liệu, hoặc Database trả về null thay vì mảng rỗng. Bạn phải yêu cầu AI vẽ lại toàn bộ luồng đi của dữ liệu.

Thao tác với Claude Code:

"Dựa vào dòng lỗi ở checkout.service.ts, hãy truy vết ngược (trace back) vòng đời của request này. Bắt đầu từ Route, qua Middleware, vào Controller, xuống Service, và cuối cùng là Database query. Chỉ ra ranh giới (boundary) nơi dữ liệu bắt đầu bị biến dạng hoặc sai type."

Kết quả kỳ vọng: AI sẽ không tập trung vào chỗ văng lỗi nữa, mà dùng các công cụ tìm kiếm trong repo (như grep hoặc AST search) để chỉ ra chính xác tầng kiến trúc (layer) nào đã vi phạm Data Contract.

Bước 3: Ép buộc đặt giả thuyết và Chứng minh (Hypothesis Testing)

Đây là bước quan trọng nhất để chống lại căn bệnh "sửa mò" của AI. Tuyệt đối không cho phép Claude Code sinh ra code sửa lỗi (fix implementation) ngay. Hãy buộc nó phải đóng vai một thanh tra kỹ thuật.

Thao tác với Claude Code:

"Từ luồng thực thi trên, hãy liệt kê 3 nguyên nhân cốt lõi (Root Causes) có khả năng xảy ra nhất. BẮT BUỘC: Không viết code sửa lỗi. Với mỗi giả thuyết, hãy viết một câu lệnh log (console.log, Log::info), hoặc một đoạn Unit Test ngắn để chứng minh giả thuyết đó là đúng hay sai. Đợi tôi chạy test và phản hồi kết quả."

Kết quả kỳ vọng: Claude Code sẽ đưa ra các giả thuyết có cơ sở, ví dụ:

• Giả thuyết 1: Redis cache bị miss dẫn đến việc lấy giá sản phẩm bị null.

• Giả thuyết 2: Race condition do 2 request checkout đến cùng lúc trong 1ms.

• Giả thuyết 3: Kiểu dữ liệu amount từ Frontend gửi lên là String thay vì Integer.

Sau khi bạn chạy đoạn test chẩn đoán mà AI cung cấp, bạn sẽ biết chính xác 100% nguyên nhân nào là thủ phạm thực sự.

Bước 4: Triệt tiêu gốc rễ và Đóng gói (Eradicate & Seal)

Khi thủ phạm đã lộ diện (ví dụ: lỗi do thiếu validation ép kiểu ở Controller), lúc này bạn mới cho phép AI tiến hành sửa đổi. Tuy nhiên, việc sửa lỗi phải đi kèm với "niêm phong" bằng Unit Test để đảm bảo lỗi này vĩnh viễn không quay lại (Regression prevention).

Thao tác với Claude Code:

"Kết quả test xác nhận Giả thuyết 3 là đúng (Frontend gửi String). Bây giờ, hãy thực hiện 2 việc:

1. Cập nhật file Validation/DTO để chặn triệt để lỗi ép kiểu này ngay từ cổng API.

2. Viết một Unit Test mới trong file checkout.controller.spec.ts truyền vào amount: "100" dạng string để đảm bảo hệ thống quăng lỗi BadRequest 400 thay vì sập 500. Hãy thực thi và hiển thị git diff."

Việc thiết lập kỷ luật 4 bước này biến Claude Code từ một cỗ máy sinh code thụ động thành một người đồng nghiệp phân tích hệ thống. Bạn không còn chữa triệu chứng (fix symptoms) bằng cách vá víu, mà thực sự loại bỏ hoàn toàn căn nguyên của vấn đề ra khỏi kiến trúc phần mềm.