requesting-code-review

Tổng quan

Kỹ năng này làm gì

Kỹ năng requesting-code-review định nghĩa một quy trình rõ ràng, có thể lặp lại để yêu cầu một subagent AI chuyên review code kiểm tra thay đổi của bạn trước khi được đưa lên. Kỹ năng này được thiết kế cho các dự án dùng Git và giúp bạn:

• Quyết định khi nào nên yêu cầu review (sau các task, tính năng, và trước khi merge)
• Đóng gói ngữ cảnh chính xác cho người review bằng Git SHA và yêu cầu nghiệp vụ
• Giữ cho người review tập trung vào code diff, không phải lịch sử phiên làm việc riêng tư của bạn
• Phân loại phản hồi theo mức độ nghiêm trọng để biết cần sửa ngay hay có thể để sau

Cốt lõi của requesting-code-review là tư duy review sớm, review thường xuyên để phát hiện vấn đề trước khi chúng lan rộng trong codebase.

Đối tượng sử dụng

Kỹ năng này phù hợp nếu bạn:

• Làm việc với Git và thường xuyên tạo feature branch hoặc PR
• Muốn một cách có cấu trúc, lặp lại được để yêu cầu review code với trợ giúp AI
• Sử dụng mô hình phát triển dựa trên subagent (ví dụ: một agent riêng tên code-reviewer)
• Quan tâm đến mức độ sẵn sàng đưa vào production: tính đúng đắn, kiến trúc, kiểm thử và bám sát đặc tả

Đặc biệt hữu ích cho:

• Lập trình viên cá nhân cần một “lưới an toàn” đáng tin cậy
• Nhóm nhỏ không có người chuyên review code
• Dự án mà lịch sử commit và diff là nguồn sự thật chính

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

requesting-code-review có thể không phù hợp nếu:

• Bạn không dùng Git hoặc không truy cập được commit SHA
• Bạn cần trợ giúp sinh code hoặc refactor chung chung, chứ không phải review những thay đổi cụ thể
• Bạn không thể cung cấp kế hoạch, đặc tả hoặc bộ yêu cầu rõ ràng cho phần thay đổi cần review

Trong các trường hợp đó, có thể bạn cần một kỹ năng lập trình hoặc lập kế hoạch tổng quát hơn, thay vì một quy trình tập trung vào review.

Vấn đề nó giải quyết

Không có quy trình review nhất quán, lập trình viên thường:

• Quên yêu cầu review ở những mốc quan trọng
• Chia sẻ quá ít ngữ cảnh (hoặc quá nhiều lịch sử phiên làm việc)
• Nhận phản hồi thiếu cấu trúc, khó chuyển thành hành động cụ thể

Kỹ năng requesting-code-review giải quyết các vấn đề này bằng cách:

• Xác định các checkpoint review bắt buộc và tùy chọn
• Chuẩn hóa đầu vào cho review (Git range, yêu cầu, tóm tắt)
• Kết hợp với một subagent code-reviewer chuyên biệt trả về phản hồi được xếp hạng theo mức độ nghiêm trọng

---

Cách sử dụng

Cài đặt

Để cài đặt kỹ năng requesting-code-review từ repository obra/superpowers, dùng Skills CLI:

npx skills add https://github.com/obra/superpowers --skill requesting-code-review

Lệnh này sẽ kéo về định nghĩa kỹ năng cùng các file hỗ trợ, bao gồm template subagent code-reviewer.

Sau khi cài đặt, mở thư mục skill và xem lướt qua các file sau trước:

• SKILL.md – mô tả tổng quan và các bước workflow để yêu cầu review code
• code-reviewer.md – prompt/template cho agent thực hiện việc review code

Quy trình cốt lõi trong nháy mắt

Workflow requesting-code-review có ba giai đoạn chính:

1. Quyết định thời điểm review
   • Sau mỗi task trong workflow dựa trên subagent
   • Sau khi hoàn thành một tính năng lớn
   • Trước khi merge vào nhánh chính
2. Chuẩn bị ngữ cảnh review
   • Lấy phạm vi Git commit với BASE_SHA và HEAD_SHA
   • Tóm tắt những gì đã triển khai và hệ thống cần hoạt động thế nào
   • Điền các placeholder được định nghĩa trong code-reviewer.md
3. Chạy review và xử lý phản hồi
   • Gọi subagent superpowers:code-reviewer
   • Sửa ngay các vấn đề Critical, xử lý Important trước khi tiếp tục, và ghi lại Minor

Bước 1: Xác định thời điểm review phù hợp

Theo SKILL.md, hãy dùng requesting-code-review tại:

Checkpoint bắt buộc:

• Sau mỗi task trong quy trình phát triển dùng subagent
• Sau khi hoàn thành một tính năng lớn
• Trước khi merge vào nhánh chính (ví dụ main, master)

Checkpoint tùy chọn nhưng hữu ích:

• Khi bạn đang mắc kẹt và cần góc nhìn mới
• Trước khi refactor, như một bước kiểm tra baseline hành vi hiện tại
• Sau khi sửa một bug phức tạp, để đảm bảo không gây regression hoặc lỗi mới

Hãy xây dựng thói quen kích hoạt kỹ năng ở các thời điểm này để việc review trở thành phần mặc định của quy trình, không phải nghĩ sau.

Bước 2: Lấy phạm vi Git commit

Người review cần một diff gọn, có giới hạn rõ ràng. Dùng Git SHA để chỉ định phạm vi:

BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
HEAD_SHA=$(git rev-parse HEAD)

• BASE_SHA nên trỏ tới commit thể hiện điểm bắt đầu của bạn, như commit trước đó hoặc tip của origin/main.
• HEAD_SHA nên là commit bao gồm phần việc mới nhất của bạn.

Bạn có thể điều chỉnh HEAD~1 hoặc chọn base khác phù hợp chiến lược branch, miễn là phạm vi phản ánh chính xác những thay đổi bạn muốn được review.

Bước 3: Chuẩn bị template yêu cầu review

File code-reviewer.md định nghĩa cách trao đổi với Code Review Agent. Nó dùng các placeholder mà bạn cần điền trước khi gửi subagent.

Các placeholder chính:

• {WHAT_WAS_IMPLEMENTED} – Mô tả ngắn gọn những gì bạn vừa xây dựng hoặc thay đổi
• {PLAN_OR_REQUIREMENTS} – Đặc tả, ticket, hoặc yêu cầu nghiệp vụ mà phần triển khai cần đáp ứng
• {BASE_SHA} – SHA commit bắt đầu cho diff
• {HEAD_SHA} – SHA commit kết thúc cho diff
• {DESCRIPTION} – Tóm tắt ngắn gọn tập thay đổi (ví dụ: "Add verification function and tests for user signups")
• {PLAN_REFERENCE} – Tham chiếu tới tài liệu kế hoạch hoặc yêu cầu

Trong toolchain của bạn, hãy populate các placeholder này trước khi gửi subagent superpowers:code-reviewer bằng Task tool.

Bước 4: Gửi subagent code-reviewer

Khi đã có Git SHA và template được điền đầy đủ:

1. Sử dụng Task tool trong môi trường orchestration của bạn (như mô tả trong framework superpowers) với type superpowers:code-reviewer.

2. Truyền nội dung code-reviewer.md sau khi đã thay placeholder bằng giá trị thực tế.

3. Đảm bảo agent có thể truy cập Git diff cho phạm vi đó:

   git diff --stat {BASE_SHA}..{HEAD_SHA}
   git diff {BASE_SHA}..{HEAD_SHA}
   

   Template đã gợi ý các lệnh này để người review chỉ tập trung đúng vào các thay đổi giữa BASE_SHA và HEAD_SHA.

Thiết kế của kỹ năng đảm bảo agent review chỉ thấy kết quả công việc (commit và diff), chứ không phải lịch sử phiên làm việc tổng thể hay ngữ cảnh không liên quan.

Bước 5: Diễn giải và xử lý phản hồi

Template code-reviewer.md hướng dẫn agent:

• Đánh giá chất lượng code (tách bạch trách nhiệm, xử lý lỗi, DRY, edge case)
• Đánh giá kiến trúc (thiết kế, khả năng mở rộng, hiệu năng, bảo mật)
• Kiểm tra kiểm thử (coverage, điểm tích hợp, chất lượng test)
• Xác minh yêu cầu (bám sát đặc tả, không nở phạm vi, thay đổi phá vỡ được ghi nhận)
• Đánh giá mức sẵn sàng production (migration, tương thích ngược, tài liệu)

Phản hồi được phân loại thành:

• Critical (Must Fix) – Bug, lỗ hổng bảo mật, nguy cơ mất dữ liệu, chức năng bị hỏng
• Important (Should Fix) – Vấn đề kiến trúc, tính năng thiếu, xử lý lỗi kém, lỗ hổng test
• Minor (Nice to Have) – Style, tối ưu hóa, cải thiện tài liệu

Workflow tương ứng trong SKILL.md là:

• Sửa ngay các vấn đề Critical trước khi tiếp tục
• Sửa các vấn đề Important trước khi làm thêm hoặc merge
• Ghi chú các vấn đề Minor cho các đợt dọn dẹp hoặc task follow-up sau này
• Phản biện, kèm lý do, nếu người review sai hoặc thiếu ngữ cảnh

Bằng cách triage như vậy, bạn biến phản hồi từ AI thành danh sách hành động cụ thể, thay vì tập gợi ý mơ hồ.

Mẫu cách dùng thực tế

Một tình huống sử dụng điển hình của requesting-code-review có thể như sau:

1. Bạn hoàn thành "Task 2: Add verification function" trong feature branch.

2. Bạn lấy SHA:

   BASE_SHA=$(git rev-parse origin/main)
   HEAD_SHA=$(git rev-parse HEAD)
   

3. Bạn điền các placeholder trong code-reviewer.md với:

   • {WHAT_WAS_IMPLEMENTED} = "Verification function for user email flow"
   • {PLAN_OR_REQUIREMENTS} = Link hoặc tóm tắt ticket/yêu cầu
   • {BASE_SHA} và {HEAD_SHA} = Giá trị lấy từ Git
   • {DESCRIPTION} = "Implement email verification and add tests for edge cases"

4. Bạn gửi subagent superpowers:code-reviewer bằng Task tool của mình.

5. Bạn nhận về phản hồi có cấu trúc, được nhóm theo Critical, Important và Minor.

6. Bạn xử lý các vấn đề Critical và Important, rồi tùy chọn chạy lại quy trình trước khi merge.

---

Câu hỏi thường gặp (FAQ)

requesting-code-review có chỉ dùng cho repository trên GitHub không?

Không. Kỹ năng requesting-code-review dựa trên Git, không phụ thuộc riêng GitHub. Nó dùng commit SHA và lệnh git diff, nên có thể hoạt động với bất kỳ Git remote nào (GitHub, GitLab, Bitbucket hoặc self-hosted) miễn là bạn cung cấp được BASE_SHA và HEAD_SHA.

Tôi có cần chia sẻ toàn bộ lịch sử phiên phát triển của mình không?

Không. Một nguyên tắc thiết kế quan trọng của requesting-code-review là người review chỉ nhận ngữ cảnh được giới hạn chặt chẽ: những gì đã được triển khai, yêu cầu đặt ra và Git diff. Lịch sử phiên làm việc chung và suy nghĩ nội bộ của bạn vẫn riêng tư, trong khi reviewer tập trung vào chính các thay đổi trong code.

Tôi nên kích hoạt requesting-code-review vào lúc nào trong workflow?

Hãy dùng requesting-code-review:

• Sau mỗi task trong quy trình phát triển dùng subagent
• Sau khi hoàn thành một tính năng lớn
• Trước khi merge vào nhánh chính

Bạn cũng có thể kích hoạt khi đang bị kẹt, trước các đợt refactor lớn, hoặc sau khi sửa bug phức tạp để phát hiện sớm các rủi ro tiềm ẩn.

Kỹ năng này tích hợp thế nào với review pull request hiện tại của tôi?

requesting-code-review bổ trợ chứ không thay thế review PR của con người. Bạn có thể:

• Chạy kỹ năng trước khi mở PR để bắt các lỗi hiển nhiên
• Dùng song song với reviewer là người để tăng độ bao phủ và tính nhất quán
• Áp dụng cách phân loại phản hồi (Critical/Important/Minor) cho comment trong PR

Vì kỹ năng xoay quanh Git range, nó tích hợp rất tự nhiên với các workflow dựa trên PR.

Tôi có thể tùy chỉnh hành vi của code-reviewer agent không?

Có. File code-reviewer.md là một template có thể tùy chỉnh:

• Điều chỉnh checklist về chất lượng code, kiến trúc, kiểm thử hoặc bảo mật
• Thêm các mối quan tâm riêng của dự án (ví dụ: quy tắc domain, ngân sách hiệu năng)
• Tinh chỉnh định dạng output nếu bạn muốn mức độ nghiêm trọng khác hoặc thêm mục mới

Chỉ cần giữ lại cấu trúc cốt lõi (nhiệm vụ rõ ràng, Git range và các mức độ severity) để review vẫn tập trung và có thể hành động.

Nếu reviewer gợi ý điều gì đó sai thì sao?

Kỹ năng này khuyến khích bạn phản biện có cơ sở khi reviewer sai hoặc thiếu ngữ cảnh. Hãy coi review như một gợi ý mạnh mẽ, không phải phán quyết tuyệt đối. Làm rõ ràng ràng buộc, giải thích trade-off, hoặc cập nhật kế hoạch để các lần review sau khớp với thực tế hơn.

requesting-code-review có tự sinh test hoặc thay đổi code cho tôi không?

Không. Kỹ năng này tập trung vào review, không sinh code. Nó giúp bạn:

• Yêu cầu review có mục tiêu cho các thay đổi cụ thể
• Nhận phản hồi có cấu trúc về chất lượng, kiến trúc và kiểm thử

Bạn vẫn là người chịu trách nhiệm triển khai sửa lỗi và viết test, dù có thể kết hợp kỹ năng này với các kỹ năng sinh code hoặc sinh test khác trong toolchain.

Làm sao để bắt đầu nhanh?

1. Cài đặt kỹ năng:

   npx skills add https://github.com/obra/superpowers --skill requesting-code-review
   

2. Đọc SKILL.md để hiểu các checkpoint review.

3. Xem code-reviewer.md để nắm checklist và định dạng output của agent.

4. Thực hiện task hoặc tính năng tiếp theo, lấy BASE_SHA và HEAD_SHA, rồi gửi subagent superpowers:code-reviewer.

Từ đó, tinh chỉnh template và workflow để requesting-code-review phù hợp với thói quen làm việc và tiêu chuẩn chất lượng của nhóm bạn.