parallel-debugging

Tổng quan về skill parallel-debugging

parallel-debugging làm gì

parallel-debugging là một quy trình gỡ lỗi có cấu trúc dành cho những trường hợp một bug có nhiều nguyên nhân khả dĩ và cách điều tra tuyến tính thông thường cứ liên tục bế tắc. Thay vì đuổi theo một giả thuyết duy nhất, skill này dùng các giả thuyết cạnh tranh, điều tra song song, thu thập bằng chứng và bước phân xử tường minh để xác định nguyên nhân gốc có khả năng cao nhất.

Ai nên cài skill này

parallel-debugging skill phù hợp với lập trình viên, AI agent và các nhóm thường xuyên phải debug những lỗi rối, trải dài qua nhiều file, nhiều service hoặc nhiều layer. Skill này đặc biệt hữu ích khi triệu chứng là có thật nhưng nguyên nhân chưa rõ, khi các lần debug trước không đi đến kết luận, hoặc khi nguy cơ thiên kiến xác nhận là cao.

Công việc phù hợp nhất để dùng skill này

Hãy dùng parallel-debugging for Debugging khi bạn cần trả lời câu hỏi: “Nguyên nhân gốc nào là phương án bảo vệ được nhất dựa trên bằng chứng?” Giá trị thực sự không chỉ nằm ở việc brainstorm nguyên nhân. Điểm mạnh của nó là biến một báo cáo bug còn mơ hồ thành các giả thuyết có thể bị bác bỏ, các hướng điều tra có phạm vi rõ ràng, bằng chứng ở cấp độ file và một kết luận có lập luận.

Điểm khác biệt so với prompt debug chung chung

Phần lớn prompt thông thường chỉ yêu cầu model “tìm bug”, và kết quả thường là một phỏng đoán nghe hợp lý. parallel-debugging mạnh hơn khi có nhiều nguyên nhân khác nhau đều có thể giải thích cùng một triệu chứng. Skill này buộc quá trình điều tra phải đi theo các nhóm kiểu lỗi, yêu cầu cả bằng chứng xác nhận lẫn bằng chứng bác bỏ, đồng thời có bước phân xử thay vì mặc định lời giải thích đầu tiên có vẻ ổn là đúng.

Phương pháp cốt lõi thể hiện trong repository

Repository lấy cách tiếp cận Analysis of Competing Hypotheses làm trung tâm và tổ chức việc debug quanh sáu nhóm lỗi: logic error, data issue, state problem, integration failure, resource issue và environment. Cách phân loại này rất thực dụng vì nó mở rộng phạm vi tìm kiếm mà không khiến việc điều tra bị lan man vô hạn.

Khi nào skill này không phù hợp

Hãy bỏ qua parallel-debugging usage với các bug đơn giản, cục bộ mà dòng gây lỗi đã quá rõ, với lỗi cú pháp thường gặp, hoặc khi bạn chỉ cần một gợi ý vá nhanh. Phương pháp này có thêm overhead, nên chỉ thật sự đáng giá khi vấn đề nằm ở sự bất định.

Cách dùng skill parallel-debugging

Bối cảnh cài đặt parallel-debugging

Cài từ repository wshobson/agents:

npx skills add https://github.com/wshobson/agents --skill parallel-debugging

Nếu môi trường của bạn dùng một skill loader khác, phần quan trọng là đường dẫn nguồn: plugins/agent-teams/skills/parallel-debugging.

Hãy đọc các file này trước lần dùng đầu tiên

Bắt đầu với:

• SKILL.md
• references/hypothesis-testing.md

SKILL.md giải thích quy trình và cách chia nhóm kiểu lỗi. references/hypothesis-testing.md là file có giá trị thực thi cao hơn trong lúc làm thật vì nó chứa các mẫu điều tra và mẫu báo cáo bằng chứng mà bạn có thể tái sử dụng trực tiếp.

Skill cần đầu vào gì để hoạt động tốt

Để parallel-debugging usage cho ra kết quả tốt, đừng chỉ đưa kiểu “X đang bị hỏng”. Skill hoạt động hiệu quả nhất khi bạn cung cấp:

• triệu chứng quan sát được
• hành vi kỳ vọng
• bối cảnh thay đổi gần đây hoặc bối cảnh triển khai
• các file, module hoặc service bị ảnh hưởng
• các bước tái hiện lỗi
• log, stack trace hoặc test đang fail
• các ràng buộc về những gì agent được phép kiểm tra hoặc chạy

Nếu thiếu các dữ liệu này, model vẫn có thể sinh giả thuyết, nhưng việc điều tra sẽ trở nên chung chung và khó kiểm chứng hơn.

Biến một báo cáo bug sơ sài thành lời gọi mạnh hơn

Đầu vào yếu:

• “Login is failing in production. Debug this.”

Đầu vào mạnh hơn:

• “Investigate intermittent login failures after yesterday’s auth middleware change. Symptom: users with valid credentials sometimes get 401 on first attempt but succeed on retry. Check src/middleware/auth.ts, session cache behavior, recent commits from the last 3 days, and tests under tests/auth/. Generate competing hypotheses, collect confirming and falsifying evidence, and rank the most likely root cause.”

Phiên bản thứ hai cho biết hình dạng của triệu chứng, khung thời gian, những bề mặt nghi ngờ và ranh giới bằng chứng cần xét.

Dùng skill như một quy trình theo giai đoạn

Một parallel-debugging guide thực tế thường như sau:

1. Nêu rõ triệu chứng và phạm vi.
2. Yêu cầu 3–5 giả thuyết cạnh tranh thuộc các nhóm lỗi khác nhau.
3. Với mỗi giả thuyết, xác định bằng chứng xác nhận và bằng chứng bác bỏ.
4. Điều tra song song hoặc mô phỏng các nhánh song song trong một câu trả lời.
5. So sánh chất lượng bằng chứng, không chỉ độ hợp lý bề ngoài.
6. Kết thúc bằng kết luận xếp hạng, mức độ tự tin và hành động tiếp theo.

Đây là lợi ích áp dụng lớn nhất: nó ngăn bạn chốt quá sớm vào một hướng giải thích.

Hãy yêu cầu bằng chứng file:line, không chỉ bản tóm tắt

Mẫu tham chiếu trong repository mặc định trông đợi trích dẫn file và chuỗi quan hệ nhân quả. Trên thực tế, bạn nên yêu cầu:

• bằng chứng file:line
• bằng chứng mâu thuẫn
• mức độ tự tin
• chỉ đề xuất cách sửa sau khi đã có kết luận

Thứ tự này rất quan trọng. Nếu bạn hỏi cách sửa quá sớm, model thường tối ưu sang viết patch trước khi đủ chắc về nguyên nhân gốc.

Dùng sáu nhóm lỗi để mở rộng tìm kiếm một cách có kiểm soát

Nếu danh sách giả thuyết đầu tiên còn hẹp, hãy yêu cầu model bao phủ toàn bộ các nhóm do repository định nghĩa:

• Logic Error
• Data Issue
• State Problem
• Integration Failure
• Resource Issue
• Environment

Đây là một trong những phần mạnh nhất của parallel-debugging skill: nó tạo ra một cách khám phá phương án thay thế có kỷ luật, thay vì suy đoán ngẫu nhiên.

Mẫu prompt gợi ý cho điều tra thực tế

Hãy dùng cấu trúc prompt như sau:

Use the parallel-debugging skill.

Issue:
{symptom, expected behavior, reproduction}

Scope:
{files, modules, tests, logs, recent commits}

Generate 4 competing hypotheses across different failure modes.
For each hypothesis, provide:
- falsifiable statement
- confirming evidence to seek
- falsifying evidence to seek
- likely files/tests to inspect

Then produce an evidence-based arbitration:
- confirmed, falsified, or inconclusive
- confidence
- causal chain
- recommended next step

Cấu trúc này bám khá sát các template trong repository để cải thiện chất lượng đầu ra mà không cần chép nguyên văn nội dung của skill.

Quy trình phù hợp nhất cho bug nhiều module

Với các bug băng qua frontend, backend, queueing và hạ tầng, hãy dùng parallel-debugging để gán một giả thuyết cho mỗi layer thay vì một giả thuyết cho mỗi file. Ví dụ:

• hồi quy state ở frontend
• lệch contract API
• lỗi invalidation cache
• lệch môi trường/cấu hình

Cách đóng khung này thường cho ra cuộc điều tra tốt hơn so với việc chia theo các vùng code một cách ngẫu nhiên.

Những ràng buộc thực tế cần lường trước

Skill này cải thiện cấu trúc lập luận, chứ không mở rộng quyền truy cập công cụ. Nếu agent không thể đọc log, chạy test, xem lịch sử git hoặc mở phần code liên quan, đầu ra vẫn có thể hợp lý nhưng độ tin cậy sẽ thấp hơn. Nó cũng không thay thế được việc tái hiện các lỗi không ổn định khi bằng chứng runtime là yếu tố bắt buộc.

Lộ trình đọc repository nếu bạn muốn tùy biến

Nếu bạn định điều chỉnh skill cho phù hợp với team:

1. Đọc SKILL.md để nắm workflow tổng thể.
2. Đọc references/hypothesis-testing.md để lấy các template có thể tái sử dụng.
3. Tách cấu trúc báo cáo bằng chứng vào prompt triage bug hoặc tài liệu nội bộ của riêng bạn.

Repository này không có nhiều helper script, nên phần lớn giá trị nằm ở phương pháp và bộ khung prompt.

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

parallel-debugging có tốt hơn prompt debug thông thường không?

Với bug đơn giản thì chưa chắc. Nhưng với bug mơ hồ có nhiều nguyên nhân nghe đều hợp lý, thì có. parallel-debugging skill tốt hơn khi rủi ro lớn nhất là bám nhầm vào một lời giải thích quá sớm.

Skill này có thân thiện với người mới không?

Có, miễn là người mới mô tả được triệu chứng rõ ràng và chia sẻ đúng ngữ cảnh liên quan. Cấu trúc của skill giúp người ít kinh nghiệm debug đặt câu hỏi tốt hơn. Tuy vậy, người mới vẫn cần đủ hiểu hệ thống để nhận ra file, test hoặc log nào là quan trọng.

Có cần nhiều agent để dùng parallel-debugging không?

Không. Repository mô tả phương pháp này theo hướng điều tra song song bằng nhiều agent, nhưng bạn vẫn có thể dùng hiệu quả với một model bằng cách yêu cầu nó duy trì các nhánh giả thuyết tách biệt rồi phân xử giữa chúng.

Khi nào không nên dùng parallel-debugging?

Tránh dùng cho lỗi quá nhỏ, các lỗi có thể sửa ngay từ stack trace, lỗi cú pháp thuần túy hoặc những tình huống mà quyền thực thi quan trọng hơn cấu trúc suy luận. Trong các trường hợp đó, phương pháp này có thể chậm hơn debug trực tiếp.

Bằng chứng tốt trong parallel-debugging usage trông như thế nào?

Bằng chứng tốt phải cụ thể, có thể bác bỏ được và có trích dẫn. Những đầu ra tốt nhất sẽ chỉ ra chính xác file, test hoặc log; giải thích vì sao bằng chứng đó ủng hộ hoặc mâu thuẫn với một giả thuyết; và nối nguyên nhân với triệu chứng thành một chuỗi rõ ràng.

Skill này có hỗ trợ root cause analysis sau sự cố không?

Có. parallel-debugging for Debugging rất hợp cho phân tích sau sự cố vì nó tách bạch giữa các câu chuyện nghe có vẻ hợp lý và các kết luận thật sự có bằng chứng chống lưng, đồng thời thể hiện rõ mức độ tự tin.

Cách cải thiện skill parallel-debugging

Cung cấp bằng chứng ban đầu tốt hơn

Cách nhanh nhất để cải thiện kết quả từ parallel-debugging là đưa vào các hiện vật cụ thể:

• stack trace
• tên test đang fail
• khoảng commit đáng nghi
• khác biệt môi trường
• thông điệp lỗi chính xác
• thời điểm hoặc mẫu gián đoạn

Những dữ liệu này giúp giảm mạnh việc sinh giả thuyết chung chung.

Buộc các giả thuyết phải cạnh tranh thật sự, không chồng lấn

Một kiểu lỗi phổ biến là tạo ra bốn biến thể của cùng một ý tưởng. Hãy yêu cầu các giả thuyết khác nhau theo nhóm lỗi hoặc theo layer hệ thống. Như vậy mới có cạnh tranh thực sự và bước phân xử mới có ý nghĩa.

Bắt buộc có phần bác bỏ, không chỉ xác nhận

Nếu bạn chỉ hỏi điều gì ủng hộ một giả thuyết, model sẽ dễ overfit. Tài liệu tham chiếu trong repository có giá trị chính vì nó yêu cầu rõ bằng chứng bác bỏ. Hãy giữ yêu cầu này trong prompt của bạn mỗi lần dùng.

Thu hẹp phạm vi điều tra khi đầu ra trở nên mơ hồ

Nếu lần chạy đầu còn quá rộng và nói chung chung, hãy chạy lại với ranh giới chặt hơn:

• “Only inspect auth middleware and session caching”
• “Use commits from the last 72 hours”
• “Prioritize evidence from failing integration tests”

Phạm vi tốt hơn thường hiệu quả hơn là chỉ yêu cầu “more detail.”

Yêu cầu định dạng kết luận kèm mức độ tự tin

Hãy insist vào các mục sau:

• Confirmed | Falsified | Inconclusive
• High | Medium | Low confidence
• danh sách bằng chứng
• danh sách mâu thuẫn
• chuỗi nhân quả

Điều này biến parallel-debugging guide thành một quy trình vận hành được, thay vì chỉ là khám phá ý tưởng.

Lặp lại sau câu trả lời đầu tiên

Một prompt vòng hai rất mạnh là:

• “Hypothesis 2 and 4 still look plausible. Compare them directly. What single observation would best distinguish them?”
  Câu hỏi kiểu này thường tìm ra bước debug tiếp theo tốt nhất nhanh hơn là yêu cầu model brainstorm lại từ đầu.

Theo dõi những failure mode phổ biến này

Các đầu ra yếu thường có những dấu hiệu sau:

• giả thuyết không có khác biệt nào kiểm thử được
• không có bằng chứng mâu thuẫn
• đề xuất cách sửa trước khi xem xét bằng chứng
• đưa ra độ tự tin nhưng không có cơ sở
• gắn nhãn category nhưng không làm thay đổi chiến lược điều tra

Nếu thấy các dấu hiệu này, hãy siết prompt chặt hơn thay vì chấp nhận một câu trả lời trau chuốt nhưng nông.

Tích hợp template vào workflow của team

Cách dùng dài hạn hiệu quả nhất của parallel-debugging skill là chuẩn hóa cách team điều tra bug. Hãy tái sử dụng các định dạng giả thuyết và báo cáo bằng chứng từ references/hypothesis-testing.md trong issue template, review sau sự cố hoặc playbook debug bằng AI để kết quả giữa các cuộc điều tra dễ so sánh hơn.