Sửa Bug Có Hệ Thống

Bug là sự gián đoạn tốn thời gian nhất trong bất kỳ dự án outsourcing nào. Một báo cáo bug từ khách hàng thường bao gồm một screenshot, một mô tả mơ hồ, và một deadline. QA regression sheet có 20 dòng và không có stack trace. Incident production cần một bản fix trước standup sáng của khách hàng. Sun Agent Kit biến mọi bug — từ một typo đơn giản trong validation message đến một race condition trong payment worker — thành một cuộc điều tra có cấu trúc với một bản fix có thể truy vết được.

Tổng Quan

Mục tiêu: Xác định root cause, triển khai bản fix, và xác minh mà không làm hỏng các hành vi liền kề
Thời gian: 5–20 phút mỗi bug (so với 1–4 giờ thủ công)
Agents sử dụng: debugger, tester, reviewer
Commands: /sk:fix, /sk:fix --quick, /sk:debug, /sk:test

Yêu Cầu Trước Khi Bắt Đầu

  • Sun Agent Kit đã cài đặt và dự án đã được index (chạy /sk:scout ít nhất một lần với codebase phức tạp)
  • Mô tả bug có thể tái hiện — error message, các bước tái hiện, hoặc một test case đang fail
  • Test suite đã sẵn sàng (rất nên có trước khi sửa bất cứ thứ gì trong production code)
  • Quyền truy cập log nếu đó là production issue (/sk:debug có thể đọc log file trực tiếp)

Quy Trình Từng Bước

Bước 1: Quick Fix Cho Bug Đơn Giản, Rõ Ràng

Đối với những bug có mô tả rõ ràng — validation error, status code sai, typo trong error message:

/sk:fix --quick "the POST /api/users endpoint returns 500 instead of 422 when the email field is missing from the request body"

Điều gì xảy ra: Agent thực hiện:

  1. Xác định route handler và controller liên quan cho endpoint bị ảnh hưởng
  2. Chẩn đoán root cause — thường là thiếu validation, status code sai, hoặc unhandled path
  3. Áp dụng bản fix tối thiểu và xác minh hành vi đúng

Bước 2: Deep Fix Cho Bug Phức Tạp

Đối với những bug cần phân tích root cause trên nhiều file hoặc module:

/sk:fix "users report that after resetting their password, they're immediately logged out when they try to sign in with the new password — this is intermittent, happens about 1 in 5 times"

Điều gì xảy ra: Agent thực hiện:

  1. Đọc các service file liên quan và trace toàn bộ password reset flow
  2. Xác định root cause — thường là race condition, thiếu session invalidation, hoặc vấn đề token lifecycle
  3. Triển khai bản fix trên tất cả các file bị ảnh hưởng (service, middleware, migration)
  4. Viết regression test để ngăn bug tái phát

Bước 3: Debug Lỗi Production Từ Log

/sk:debug "production logs show: UnhandledPromiseRejection: Cannot read properties of undefined (reading 'stripe_customer_id') — this started at 14:32 UTC yesterday, affecting the checkout flow"

Điều gì xảy ra: Agent thực hiện:

  1. Tìm kiếm tất cả call site cho property hoặc variable được tham chiếu
  2. Trace crash path từ HTTP request đến dòng bị lỗi
  3. Xác định trigger — thường là một migration hoặc deploy gần đây đã thay đổi một constraint
  4. Tạo khuyến nghị fix với các thay đổi code cụ thể cần thiết

Bước 4: Fix Lỗi CI/CD Pipeline

/sk:fix "GitHub Actions build is failing on the test step — error: ECONNREFUSED 127.0.0.1:5432 in the auth integration tests"

Điều gì xảy ra: Agent thực hiện:

  1. Đọc file CI configuration và xác định bước bị lỗi
  2. Chẩn đoán root cause — thường là vấn đề timing, thiếu service dependency, hoặc environment mismatch
  3. Áp dụng bản fix trực tiếp vào file CI configuration

Bước 5: Fix Bug UI (Visual + Functional)

/sk:fix "the mobile nav menu doesn't close when a user taps outside of it on iOS Safari — it just stays open"

Điều gì xảy ra: Agent thực hiện:

  1. Xác định component liên quan và trace logic event handler
  2. Chẩn đoán root cause — thường là vấn đề xử lý event theo browser cụ thể
  3. Áp dụng bản fix tương thích cross-browser với các fallback pattern phù hợp

Ví Dụ Thực Tế: QA Báo Cáo 5 Bug Từ Vòng Test Mới Nhất

Tình huống: QA gửi một spreadsheet vào chiều thứ Sáu với 5 bug từ regression testing trên dự án của khách hàng. Sprint review là thứ Hai. Các bug dao động từ trivial đến một race condition tinh vi.

Danh sách bug từ QA:

  1. POST /api/orders trả về HTML error page thay vì JSON khi payload không hợp lệ
  2. Email đặt lại mật khẩu không gửi đến địa chỉ Gmail (Yahoo hoạt động tốt)
  3. Tổng giỏ hàng hiển thị sai ký hiệu tiền tệ cho người dùng ở locale EU
  4. Trang xác nhận đơn hàng crash trên Safari 16 với lỗi JS
  5. Webhook từ Stripe đôi khi kích hoạt hai lần, gây ra bản ghi đơn hàng trùng lặp

Chiều thứ Sáu — fix tất cả 5:

# Bug 1: validation/response format issue trivial
/sk:fix --quick "POST /api/orders returns HTML error page instead of JSON 400 when request body is malformed"

# Bug 2: email delivery — cần điều tra
/sk:fix "password reset emails not delivered to Gmail addresses — Yahoo works fine. Check SendGrid config, DKIM, and any email filtering happening in the notification service"

# Bug 3: i18n display bug
/sk:fix --quick "cart total shows wrong currency symbol for EU locale users — should be € not $ — check the currency formatting utility and locale detection"

# Bug 4: Safari JS crash
/sk:debug "order confirmation page crashes on Safari 16 with: TypeError: undefined is not an object (evaluating 'e.dataset.orderId'). Find the component and the Safari-incompatible pattern."
# Sau đó apply fix từ debug report:
/sk:fix --quick "apply the fix recommended in the debug report for the Safari 16 crash on the order confirmation page"

# Bug 5: idempotency — cái khó nhất
/sk:fix "Stripe webhook fires twice causing duplicate order records. Implement idempotency key checking so the same webhook event can never create two orders"

# Chạy full test suite sau tất cả các fix
/sk:test "run all tests and flag any regressions from today's fixes"

Kết quả: Tất cả 5 bug đã được fix, tests đang pass, và một commit sạch sẵn sàng cho sprint review thứ Hai. Bản fix idempotency (Bug 5) một mình đã mất nửa ngày để nghiên cứu và triển khai thủ công.

So Sánh Thời Gian

Loại BugThủ côngVới Sun Agent Kit
Validation / response fix đơn giản30–60 phútvài phút
Race condition không liên tục3–6 giờ15–30 phút
Điều tra log production1–2 giờvài phút
Fix CI/CD pipeline30–60 phútvài phút
Tương thích iOS Safari1–2 giờvài phút
Idempotency / ngăn trùng lặp4–8 giờ20–40 phút
Batch QA 5 bug8–16 giờdưới 2 giờ

Các Thực Hành Tốt Nhất

1. Dùng —quick cho bug có mô tả rõ ràng ✅

Nếu bạn có thể giải thích bug trong một câu và biết endpoint hoặc component nào bị ảnh hưởng, --quick bỏ qua phân tích sâu và áp dụng fix trực tiếp. Để dành /sk:fix đầy đủ cho những bug cần điều tra.

2. Đưa vào các bước tái hiện trong prompt fix ✅

“Tổng giỏ hàng bị sai” tạo ra một bản fix nông cạn. “Cart total shows $ instead of € when the user’s Accept-Language header is de-DE and they have 3+ items in the cart” giúp agent xác định chính xác điểm lỗi.

3. Luôn chạy /sk:test sau một batch fix ✅

Các fix riêng lẻ được cô lập, nhưng fixing 5 bug liên tiếp có thể gây ra regression. Một lượt test đầy đủ sau batch sẽ phát hiện các vấn đề cross-cutting trước khi chúng đến review.

4. Apply fix mà không đọc diff trước ❌

Agent hiển thị cho bạn những gì đã thay đổi. Hãy đọc nó. Một bản fix 4 dòng chỉnh sai function có thể đưa vào một bug tệ hơn. Một phút review ngăn chặn một vụ escalation với khách hàng.

5. Nhờ /sk:fix fix triệu chứng thay vì nguyên nhân ❌

“Make the 500 go away” có thể dẫn đến việc error bị nuốt chửng thay vì xử lý. Mô tả hành vi đúng phải là gì: “return 422 with a JSON error body when the email field is missing.”

Xử Lý Sự Cố

Vấn đề: /sk:fix —quick thực hiện thay đổi nhưng bug vẫn tái hiện

Giải pháp: Quick mode đi theo con đường ngắn nhất. Chuyển sang full mode: /sk:fix "..." không có --quick để chạy điều tra sâu hơn và một bản fix toàn diện hơn.

Vấn đề: /sk:debug không thể tìm root cause từ log snippet

Giải pháp: Paste toàn bộ stack trace, không chỉ error message. Stack trace bao gồm tên file và số dòng mà debug agent sử dụng để trace execution path.

Vấn đề: Bản fix gây ra TypeScript error

Giải pháp: Chạy /sk:fix --quick "fix the TypeScript error introduced in src/services/billing.ts:89 — expected string, got string | null". Agent có thể resolve các side effect do chính nó tạo ra.

Vấn đề: Một bug nằm trong third-party integration và source code không có trong repo

Giải pháp: Dùng /sk:ask để hiểu ranh giới integration, sau đó fix adapter layer trong code của bạn. Agent không thể sửa code của bên thứ ba nhưng có thể sửa cách bạn gọi nó.

Bước Tiếp Theo

Điểm mấu chốt: Một QA sheet với 5 bug nên xử lý xong trong một chiều thứ Sáu, không phải cả một sprint — /sk:fix cho bạn root cause và một bản fix đã kiểm tra trong vài phút, không phải vài giờ.