debugger

Tổng quan về debugger skill

debugger skill dùng để làm gì

debugger skill là một quy trình gỡ lỗi có cấu trúc, giúp tìm ra nguyên nhân gốc nhanh hơn nhiều so với một prompt chung chung kiểu “đang lỗi gì vậy?”. Skill này phù hợp cho các tình huống code ném lỗi, chạy sai kỳ vọng, bị hồi quy sau khi thay đổi, hoặc chỉ hỏng ở một số môi trường nhất định. Thay vì lao ngay vào sửa, debugger skill buộc bạn đi theo đúng thứ tự quan trọng trong công việc Debugging thực tế: tái hiện, cô lập, phân tích, sửa và xác minh.

Ai nên cài debugger skill này

debugger skill này phù hợp với lập trình viên, AI coding agent và các đội kỹ thuật muốn có một quy trình Debugging lặp lại được, thay vì xử lý sự cố theo kiểu tùy cơ ứng biến. Nó đặc biệt hữu ích nếu bạn thường phải lần theo stack trace, log, báo lỗi chưa đầy đủ hoặc các bước tái hiện còn mơ hồ. Trọng tâm của skill này không phải kiến thức chuyên sâu cho một framework cụ thể, mà là nâng kỷ luật Debugging trên nhiều dự án khác nhau.

Nó giúp bạn hoàn thành công việc gì

Công việc thực sự cần giải quyết không phải là “giải thích thông báo lỗi”. Mà là biến một lỗi mơ hồ thành một lộ trình điều tra rõ ràng: có gì đã thay đổi, tái hiện bằng cách nào, nên thu hẹp phạm vi ở đâu, cần thu thập bằng chứng gì, và kiểm chứng bản sửa cuối cùng ra sao. Vì vậy, việc cài debugger sẽ đáng giá hơn khi cả nhóm đang mất thời gian vì đoán mò hoặc liên tục chữa triệu chứng thay vì xử lý đúng nguyên nhân.

Vì sao debugger skill này nổi bật

Điểm khác biệt hữu ích nằm ở cách nó được tổ chức để dùng thật. Repository này gồm có:

• một quy trình Debugging theo từng giai đoạn trong SKILL.md
• các tài liệu hỗ trợ tra cứu nhanh cho Debugging trong references/checklist.md, references/errors.md, và references/patterns.md
• một script tạo báo cáo thực tế trong scripts/debug_report.py

Tổ hợp này khiến debugger skill phù hợp với các phiên xử lý sự cố đang diễn ra hơn một prompt template thông thường. Bạn có quy trình, checklist, các nhóm lỗi phổ biến và cả một đầu ra để bàn giao.

Nó không cố làm gì

Đây không phải debugger chuyên cho một ngôn ngữ, không phải extension cho IDE, cũng không phải nền tảng tracing. Nó sẽ không thay thế các runtime tool, profiler hay tài liệu framework. Nếu nhu cầu chính của bạn là step-through tương tác, soi memory hoặc tracing ở mức protocol, hãy dùng các công cụ đó trực tiếp và xem hướng dẫn debugger này như lớp tư duy bao quanh chúng.

Cách dùng debugger skill

Ngữ cảnh cài đặt và đường dẫn repo

Skill này nằm ở skills/debugger trong zhaono1/agent-playbook. Nếu bạn dùng skill loader có hỗ trợ nguồn GitHub, hãy cài từ repository đó và nhắm tới skill debugger. Một cách làm phổ biến là:

npx skills add https://github.com/zhaono1/agent-playbook --skill debugger

Nếu cách thiết lập của bạn khác, điều quan trọng là phải nạp đúng thư mục skills/debugger để agent có thể truy cập SKILL.md cùng các file hỗ trợ trong references/ và scripts/.

Hãy đọc các file này trước

Để vào việc nhanh, hãy đọc theo thứ tự sau:

1. skills/debugger/SKILL.md
2. skills/debugger/references/checklist.md
3. skills/debugger/references/patterns.md
4. skills/debugger/references/errors.md
5. skills/debugger/scripts/debug_report.py

Lộ trình này bám sát cách debugger được dùng ngoài thực tế: bắt đầu từ workflow, rồi đến heuristics điều tra, sau đó là nhóm lỗi, cuối cùng là phần hỗ trợ tài liệu hóa.

debugger skill được kích hoạt như thế nào trong thực tế

Repository này được thiết kế để kích hoạt khi người dùng báo:

• có lỗi hoặc exception
• hành vi bất thường
• “debug cái này”
• “sao cái này không chạy?”

Trong thực tế, debugger skill hoạt động tốt nhất khi bạn nói rõ đây là một tác vụ Debugging và đưa kèm bằng chứng. Ví dụ:

“Use the debugger skill. This API returns 500 only in staging. Expected 200. Started after yesterday’s deploy. Here is the stack trace, the endpoint, and the last 3 commits.”

Prompt như vậy mạnh hơn rất nhiều so với chỉ nói “fix this bug”.

debugger skill cần những đầu vào gì

Dùng debugger hiệu quả phụ thuộc nhiều vào đầu vào cụ thể. Hãy cung cấp càng nhiều mục sau càng tốt:

• nguyên văn lỗi
• stack trace
• hành vi kỳ vọng so với hành vi thực tế
• các bước tái hiện được
• thay đổi mã nguồn hoặc cấu hình gần đây
• thông tin môi trường
• log liên quan
• phạm vi file hoặc component đã được thu hẹp

Workflow của skill này giả định rằng sẽ có bước thu thập bằng chứng, nên nếu thiếu bước tái hiện hoặc thiếu đầu ra thực tế thì chất lượng kết quả sẽ giảm mạnh hơn cả việc thiếu chi tiết triển khai.

Biến một yêu cầu mơ hồ thành prompt debugger mạnh hơn

Prompt yếu:
“Why does this fail?”

Prompt tốt hơn:
“Use the debugger skill to diagnose this failure. After upgrading dependencies, npm test fails in auth.spec.ts with TypeError: Cannot read properties of undefined. Expected tests to pass. Actual behavior: 6 failures on CI, 0 locally. Recent changes: lockfile update and config edit. Please help reproduce, isolate likely causes, rank hypotheses, and suggest the smallest safe fix.”

Vì sao cách này hiệu quả:

• nêu rõ mục tiêu Debugging
• cho biết hành vi kỳ vọng và hành vi thực tế
• có thông tin chênh lệch môi trường
• nêu thay đổi gần đây
• yêu cầu điều tra trước khi vá lỗi

Quy trình debugger được khuyến nghị

Một hướng dẫn debugger thực dụng cho tình huống dùng thật:

1. Tái hiện lỗi chính xác.
2. Ghi lại hành vi kỳ vọng so với hành vi thực tế.
3. Kiểm tra các thay đổi gần đây bằng git log --oneline -10.
4. Thu thập log hoặc trace.
5. Cô lập bằng minimal repro hoặc binary search.
6. Ánh xạ lỗi vào một nhóm lỗi phù hợp.
7. Đưa ra các giả thuyết về nguyên nhân gốc.
8. Thử bản sửa nhỏ nhất có khả năng đúng.
9. Xác minh bằng regression coverage.

Đây gần như chính là những gì skill đã mã hóa sẵn, nhưng làm rõ từng bước như vậy sẽ rất hữu ích khi agent bắt đầu đề xuất cách sửa quá sớm.

Dùng các file tham chiếu như công cụ hỗ trợ ra quyết định

Các file hỗ trợ đều ngắn, nhưng ảnh hưởng rõ đến chất lượng đầu ra:

• references/checklist.md giúp cả phiên làm việc không đi chệch hướng: tái hiện, cô lập, nguyên nhân gốc, sửa, regression coverage.
• references/patterns.md hữu ích khi vấn đề quá rộng hoặc nhiều nhiễu; nó gợi ý binary search, logging có chủ đích và cách thu nhỏ minimal repro.
• references/errors.md giúp phân loại các lỗi thường gặp như truy cập null, race condition, lệch cấu hình và sai lệch shape dữ liệu.

Hãy dùng chúng khi đầu ra debugger đầu tiên còn chung chung. Chúng hữu ích hơn cho việc làm sắc nét hướng điều tra, hơn là để học cú pháp.

Tạo báo cáo debug có thể tái sử dụng

Nếu bạn muốn có một artifact điều tra được ghi lại rõ ràng, hãy dùng:

python skills/debugger/scripts/debug_report.py --name "Checkout timeout in staging" --owner payments

Lệnh này tạo một mẫu báo cáo markdown với các phần như tóm tắt, môi trường, bước tái hiện, log, nguyên nhân gốc, bản sửa, kiểm thử hồi quy và các việc theo sau. Với Debugging theo nhóm, đây là một trong những phần thực tế nhất của repository vì nó biến quá trình điều tra vốn dễ trôi mất thành thứ có thể review lại được.

Trường hợp phù hợp nhất để dùng debugger cho Debugging

debugger skill này hữu ích nhất khi:

• bug tái hiện được nhưng không rõ nguyên nhân
• có log nhưng quá nhiều nhiễu
• lỗi bắt đầu xuất hiện sau một thay đổi
• vấn đề trải dài qua code, config và môi trường
• bạn cần một luồng triage có kỷ luật trước khi sửa code

Nó kém thuyết phục hơn với các lỗi cú pháp rất nhỏ có thể nhìn ra ngay, hoặc các sự cố đặc thù miền nghiệp vụ đòi hỏi bối cảnh vận hành riêng mà agent không thể truy cập.

Mẹo thực tế để dùng debugger hiệu quả hơn

Hãy yêu cầu skill tách riêng:

• facts
• hypotheses
• next checks
• proposed fix
• verification steps

Cấu trúc này giúp tránh kết luận quá sớm. Bạn cũng nên yêu cầu nó xếp hạng các nguyên nhân khả dĩ và nói rõ bằng chứng nào có thể bác bỏ từng giả thuyết. Khi đó debugger skill sẽ bớt là một “cỗ máy đoán thông minh” và trở thành đối tác điều tra tốt hơn.

Câu hỏi thường gặp về debugger skill

debugger skill này có tốt hơn một prompt bình thường không

Thường là có, nhất là khi vấn đề gồm nhiều bước. Prompt chung chung thường nhảy từ triệu chứng sang một bản sửa được đoán ra. debugger skill tốt hơn khi bạn cần thu hẹp có hệ thống, thu thập bằng chứng và xác minh. Nếu bug rất nhỏ và lộ rõ hoàn toàn trong một đoạn code, một prompt bình thường có thể đã đủ.

Việc cài debugger có thân thiện với người mới không

Có, vì workflow cốt lõi khá đơn giản và cụ thể. Người mới sẽ hưởng lợi từ quy trình theo giai đoạn và checklist. Điểm cần lưu ý là skill này giả định bạn có thể cung cấp một số bằng chứng như log, stack trace hoặc bước tái hiện. Nếu thiếu các dữ liệu đó, bất kỳ hướng dẫn debugger nào cũng sẽ trở nên nặng tính phỏng đoán.

Tôi có thể dùng debugger skill này với mọi ngôn ngữ hoặc stack không

Phần lớn là có. debugger skill này định hướng theo quy trình, không gắn với một ngôn ngữ cụ thể. Các ví dụ lỗi trong đó thiên về dạng phổ quát thay vì phụ thuộc framework. Điều đó giúp nó dễ mang đi nhiều nơi, nhưng cũng có nghĩa là để đạt kết quả tốt nhất bạn có thể phải tự bổ sung thêm chi tiết riêng của stack mình đang dùng.

Khi nào không nên dùng debugger skill này

Hãy bỏ qua nó khi:

• bạn cần debug runtime tương tác nhiều hơn là hỗ trợ suy luận
• vấn đề hoàn toàn thuộc vận hành hệ thống và agent không thể truy cập hệ thống đó
• bug chỉ là một lỗi gõ nhầm một dòng đã xác định rõ
• bạn cần chuyên môn rất đặc thù theo vendor mà repository này không có

Trong các trường hợp đó, hãy ưu tiên công cụ trực tiếp hoặc tài liệu chuyên ngành trước.

Nó có giúp cho bàn giao trong nhóm và theo dõi sau sự cố không

Có. Script debug_report.py là dấu hiệu rõ nhất cho thấy debugger skill này không chỉ được thiết kế cho các cuộc chat dùng một lần. Nó giúp biến một phiên Debugging thành báo cáo có thể tái sử dụng, với người phụ trách, bước tái hiện, nguyên nhân gốc, bản sửa và các đầu việc tiếp theo.

Cách cải thiện debugger skill

Hãy cung cấp bằng chứng cho debugger skill, đừng chỉ nêu triệu chứng

Cách nhanh nhất để cải thiện đầu ra của debugger là đưa vào bằng chứng thô:

• câu lệnh đã chạy chính xác
• nguyên văn đầy đủ của lỗi
• input gây lỗi
• môi trường nơi lỗi xuất hiện
• khoảng commit gần đây
• những gì bạn đã thử

“Here is the stack trace and the last good commit” luôn tốt hơn nhiều so với “it’s broken after my changes.”

Buộc tạo minimal repro từ sớm

Một kiểu thất bại phổ biến khi dùng debugger là điều tra trên phạm vi quá rộng. Hãy yêu cầu skill hỗ trợ tạo ca tái hiện nhỏ nhất có thể. Việc này thường loại bỏ bớt nhiễu từ phần setup framework, các service không liên quan hoặc state cũ còn sót lại, từ đó nguyên nhân gốc hiện ra nhanh hơn.

Yêu cầu xếp hạng giả thuyết

Khi có nhiều nguyên nhân đều có vẻ hợp lý, hãy bảo debugger skill xếp hạng chúng theo xác suất và theo độ dễ kiểm chứng. Như vậy bạn sẽ có thứ tự điều tra tốt hơn. Ví dụ:

“List the top 3 root-cause hypotheses, what evidence supports each, and the next cheapest check to confirm or reject them.”

Cách này đặc biệt hữu ích với flaky test, lỗi integration và tình trạng config drift.

Tách nguyên nhân gốc khỏi chất lượng bản sửa

Một vấn đề phổ biến khác là chấp nhận ngay bản sửa đầu tiên khiến triệu chứng biến mất. Hãy dùng hướng dẫn debugger để hỏi:

• vì sao chuyện này xảy ra
• điều kiện nào đã cho phép nó xảy ra
• regression test nào sẽ chứng minh lỗi thực sự được giữ ở trạng thái đã sửa

Điều đó rất quan trọng với các lỗi tái diễn như xử lý null, race condition và cấu hình không khớp.

Cải thiện đầu ra đầu tiên bằng bối cảnh repository

Nếu bug nằm trong codebase của chính bạn, hãy cung cấp:

• các file bị nghi ngờ
• ranh giới package hoặc service
• thời điểm deploy
• các file config liên quan
• lỗi chỉ xảy ra ở local, CI, staging hay production

debugger skill sẽ làm việc tốt hơn nhiều khi nó có thể nối bằng chứng với ranh giới hệ thống, thay vì chỉ suy luận từ một stack trace được dán vào.

Dùng các tài liệu tham chiếu để làm sắc nét câu trả lời còn yếu

Nếu câu trả lời đầu tiên vẫn chung chung, hãy yêu cầu agent dùng rõ ràng:

• references/checklist.md để đảm bảo đủ quy trình
• references/patterns.md cho các phương pháp cô lập lỗi
• references/errors.md để đối chiếu theo nhóm lỗi

Đây là cách thực tế để cải thiện kết quả từ debugger mà không cần viết lại toàn bộ prompt.

Lặp lại sau vòng Debugging đầu tiên

Cách dùng debugger tốt luôn mang tính lặp. Sau đầu ra đầu tiên:

1. chạy một bước kiểm tra được gợi ý
2. mang kết quả quay lại
3. yêu cầu skill cập nhật các giả thuyết
4. chỉ sau đó mới chỉnh sửa code

Chính vòng lặp này khiến debugger skill hữu ích hơn một hướng dẫn debugger tĩnh. Nó giúp bạn hội tụ dần thay vì tạo ra một câu trả lời dài nhưng nhiều suy đoán.

Thêm bằng chứng hồi quy trước khi kết thúc

Checklist trong repository nêu rõ regression coverage, và đó cũng là điểm nên kết thúc. Hãy yêu cầu debugger skill đề xuất test, assertion hoặc kiểm tra monitoring nhỏ nhất có thể bắt lại lỗi này vào lần sau. Một bản sửa không có xác minh thường vẫn là Debugging chưa trọn vẹn, đặc biệt với các lỗi chập chờn hoặc phụ thuộc môi trường.