md-review

Tổng quan về md-review skill

md-review dùng để làm gì

md-review là một Code Review presentation skill, dùng để biến phần ghi chú PR viết bằng markdown thành một trang review HTML một file, bố cục hai cột. Skill này kỳ vọng đầu vào là review markdown có các khối fenced diff theo định dạng unified diff, kèm nhận xét được gắn mức độ nghiêm trọng như > [!BLOCKER], > [!MAJOR], > [!MINOR], hoặc > [!NIT]. Kết quả đầu ra đặt phần diff đã render ở bên trái, các thẻ chú thích ở bên phải, thanh điều hướng nhanh tới các findings ở phía trên, và phần chân trang bắt buộc có tên reviewer.

Người dùng và workflow phù hợp nhất

md-review skill phù hợp nhất với các nhóm đã có thói quen viết ghi chú code review có cấu trúc bằng markdown và muốn có một artifact HTML dễ chia sẻ, lưu trữ hoặc bàn giao bên ngoài nền tảng PR. Skill này hợp với engineering lead, reviewer, documentation maintainer, cũng như các workflow dùng agent để chuyển phân tích PR thành một trang review hoàn chỉnh. Nó đặc biệt hữu ích khi mức độ nghiêm trọng của review, việc neo theo dòng code, và khả năng truy cập quan trọng hơn một bản tóm tắt markdown thuần túy.

Điểm khác biệt của md-review

Khác với một prompt chung chung kiểu “làm cho review này đẹp hơn”, md-review có pipeline rõ ràng: diff_parser.py trích xuất các hunk unified diff, annotation_extractor.py gắn các callout mức độ nghiêm trọng vào diff block gần nhất phía trước, và review_html_renderer.py tạo HTML cuối cùng. Repository cũng ghi lại các lựa chọn render trong references/diff_rendering_canon.md, references/pr_annotation_ux.md, và references/severity_coding.md, nhờ đó đầu ra dễ dự đoán hơn so với việc để LLM tự định dạng tùy hứng.

Các ràng buộc chính khi áp dụng

Rào cản lớn nhất là hình dạng đầu vào. md-review không dành cho các trang markdown thông thường, release notes, hay báo cáo dạng kể chuyện không có diff hunk. Skill sẽ từ chối render nếu thiếu tên reviewer rõ ràng, và được thiết kế để không mã hóa mức độ nghiêm trọng chỉ bằng màu sắc; badge có cả icon và văn bản aria-label để đáp ứng WCAG 1.4.1. Nếu nguồn của bạn không có unified diff thật, hãy chuyển tác vụ sang một document-rendering skill thay vì dùng md-review.

Cách sử dụng md-review skill

Cài đặt md-review và các file repository cần kiểm tra

Với các skill manager tương thích Claude, hãy cài từ đường dẫn GitHub repository, ví dụ:

npx skills add alirezarezvani/claude-skills --skill md-review

Sau khi cài đặt, đọc SKILL.md trước để hiểu quy tắc gọi skill, rồi kiểm tra các file sau trước khi dùng trong production:

• scripts/diff_parser.py để biết các định dạng diff fence được chấp nhận và --infer-diff
• scripts/annotation_extractor.py để hiểu cách parse callout và hành vi gắn chú thích
• scripts/review_html_renderer.py để biết các flag bắt buộc của renderer như --reviewer
• assets/md_review_template.html để xem cấu trúc trang cuối cùng
• references/severity_coding.md để xem các tầng severity mặc định và tùy chỉnh

Chuẩn bị đầu vào mà md-review có thể parse

Một cách dùng md-review hiệu quả là bắt đầu với markdown trong đó mỗi finding nằm gần đoạn diff mà nó mô tả:

# Review: payment retry change

```diff
--- a/src/retry.py
+++ b/src/retry.py
@@ -14,6 +14,8 @@ def retry_payment():
-    attempts = 1
+    attempts = 5
+    timeout = None
```

> [!BLOCKER]
> This can retry indefinitely if the provider never returns. Add a bounded timeout.

Hãy dùng các fenced block diff khi có thể. Parser có thể suy luận một số fence không gắn nhãn chỉ khi dùng --infer-diff, nhưng fence rõ ràng sẽ giảm nhập nhằng. Chỉ đặt nhận xét chung trước bất kỳ diff nào nếu bạn muốn chúng được render thành nhận xét không neo vào diff cụ thể.

Gọi md-review trong workflow dùng agent

Skill có thể được kích hoạt khi một markdown-html orchestrator phân loại đầu vào là REVIEW, hoặc gọi trực tiếp bằng /cs:md-review. Một prompt đầy đủ nên cung cấp markdown nguồn, tên reviewer, và mọi thay đổi về quy ước severity:

/cs:md-review
Convert this markdown code review into a single-file HTML review.
Reviewer: Jane Doe
Use the default BLOCKER/MAJOR/MINOR/NIT severity convention.
Keep all diff hunks and attach annotations to the nearest preceding hunk.
[Paste review markdown here]

Nếu dùng trực tiếp các script, flow thực tế là: parse các diff block thành JSON, trích xuất annotation dựa trên các hunk đó, rồi render HTML với --reviewer. Các script chỉ dùng Python stdlib, nên dễ chạy hơn trong CI bị hạn chế hoặc automation cục bộ.

Mẹo thực tế để cải thiện chất lượng đầu ra

Để neo annotation chính xác hơn, hãy đặt từng callout ngay sau diff block liên quan. Để triage tốt hơn, chỉ dùng BLOCKER cho vấn đề bắt buộc phải sửa và tránh gắn mọi mối lo thành MAJOR. Để dễ quét hơn, hãy viết câu đầu tiên của mỗi annotation như điểm cần ra quyết định, vì jump-nav dùng các preview ngắn. Nếu đội của bạn dùng nhãn khác, hãy truyền quy ước bốn tầng tùy chỉnh theo thứ tự từ nghiêm trọng nhất đến ít nghiêm trọng nhất, chẳng hạn critical,important,suggestion,nit.

FAQ về md-review skill

md-review chỉ dành cho Code Review phải không?

Đúng. md-review for Code Review được thiết kế có chủ đích với phạm vi hẹp: chuyển các PR review bằng markdown có diff hunk và annotation severity thành một trang review HTML. Đây không phải trình tạo website markdown tổng quát, không phải công cụ tạo PR diff, và cũng không thay thế việc tự viết review.

Nếu markdown của tôi không có diff block thì sao?

Đó là trường hợp không phù hợp. Bố cục cốt lõi của skill phụ thuộc vào unified diff hunk, số dòng, phần thêm, phần xóa, và việc gắn annotation. Nếu không có diff block, kết quả sẽ dễ gây hiểu nhầm, nên hành vi mong muốn là từ chối hoặc chuyển tác vụ sang một markdown-to-HTML skill thiên về tài liệu.

md-review tốt hơn một prompt thông thường ở điểm nào?

Một prompt thông thường có thể tạo HTML trông bắt mắt, nhưng thường sẽ tự bịa quy tắc layout, bỏ sót quy ước số dòng, hoặc dựa vào màu sắc đơn thuần để biểu thị severity. md-review dùng các script parse và render cụ thể, một UX review hai cột được ghi chép rõ ràng, cùng các ràng buộc accessibility minh bạch. Vì vậy, skill này phù hợp hơn khi tính nhất quán và ngữ nghĩa review là điều quan trọng.

md-review có thân thiện với người mới không?

Có, nếu bạn đã hiểu markdown code fence và unified diff. Người mới chỉ có nhận xét dạng văn xuôi có thể cần tạo hoặc dán một PR diff thật trước. Cách bắt đầu dễ nhất là chạy các sample mode trong script, rồi điều chỉnh cấu trúc markdown mẫu theo review của bạn.

Cách cải thiện md-review skill

Cải thiện đầu vào md-review trước khi render

Cách nhanh nhất để cải thiện đầu ra của md-review là cải thiện chính bản review nguồn. Hãy đưa file path vào header unified diff chuẩn, giữ nguyên các hunk header @@, và giữ đủ dòng ngữ cảnh để reviewer hiểu thay đổi. Khi có thể, dùng một finding cho mỗi callout; gộp các vấn đề không liên quan vào cùng một thẻ MAJOR sẽ làm jump-nav kém hữu ích.

Tránh các lỗi thường gặp

Các lỗi thường gặp gồm thiếu --reviewer, diff fence sai định dạng, nhãn severity nằm ngoài quy ước đã cấu hình, và annotation đặt quá xa đoạn diff mà nó tham chiếu. Một lỗi tinh vi khác là dùng severity như sắc thái giọng điệu thay vì mức ưu tiên. Một góp ý style viết gay gắt vẫn chỉ nên là NIT; một lỗi correctness được viết bình tĩnh vẫn có thể là BLOCKER.

Lặp lại sau bản HTML đầu tiên

Sau lần render đầu tiên, hãy kiểm tra ba điểm: mọi finding có xuất hiện trong jump-nav phía trên không, annotation có gắn vào đúng hunk mong muốn không, và các nhận xét không neo có thực sự là nhận xét chung không. Nếu một annotation rơi sai vị trí, hãy di chuyển nó lại gần diff block liên quan thay vì cố sửa HTML thủ công.

Tùy chỉnh mà không phá vỡ mô hình review

Hãy tùy chỉnh để khớp với quy ước của đội, không phải để làm yếu cấu trúc. Danh sách severity tùy chỉnh là hợp lý nếu tổ chức của bạn dùng các nhãn như critical, important, suggestion, và nit. Việc biến đầu ra thành báo cáo văn xuôi, ẩn icon severity, hoặc bỏ footer reviewer sẽ làm suy yếu điều mà md-review được thiết kế để đảm bảo: đầu ra review có trách nhiệm rõ ràng, accessible, và xoay quanh diff.