Viết commit message và mô tả PR bằng giọng nói

Giải thích thay đổi bằng lời nói có thể tạo bản nháp hữu ích cho commit message hoặc mô tả pull request. Phần cần làm tiếp là kiểm tra lời giải thích có khớp code hay không. Câu “thay đổi này chắc sẽ sửa được retry” chưa phải bằng chứng lỗi đã được sửa.

Bài kết hợp quy trình biên tập với tài liệu Git, GitHub được kiểm tra ngày 11/09/2026. Các message là ví dụ minh họa, không phải transcript đã thu hoặc kết quả sửa lỗi sản phẩm thật. Với yêu cầu gửi trước khi sửa code, dùng hướng dẫn prompt Cursor bằng giọng nói.

Bắt đầu từ thay đổi thực tế

Trước khi viết commit message, xem file và phần diff đã stage. Message cần mô tả snapshot đó; nó có thể nhỏ hơn toàn bộ thay đổi còn trong working tree.

Sau khi stage đúng file theo quy trình thường dùng, hai lệnh chỉ đọc sau giúp kiểm tra phạm vi:

git diff --cached --stat
git diff --cached

Với mô tả PR, xem toàn bộ diff so với nhánh đích đã chọn. Không mặc định commit cuối bao gồm tất cả thay đổi trong PR. Đọc template và hướng dẫn đóng góp hiện có trước khi chọn định dạng.

Nói ba điều vào editor văn bản: tình huống gây lỗi, hành vi mới và lý do chọn hành vi đó. Gõ hoặc sao chép tên file, mã issue nếu dictation chưa giữ đúng.

Rút lời giải thích thành commit message rõ phạm vi

Giả sử patch thực sự dừng retry khi gặp HTTP 401, đồng thời giữ xử lý rate limit hiện tại. Bản nháp để nói có thể là:

Request vẫn bị thử lại khi xác thực đã thất bại. Thay đổi này dừng nhánh retry với phản hồi 401 và giữ cách xử lý rate limit hiện tại.

Nếu dự án dùng message tiếng Anh, bản đã đối chiếu cho patch minh họa có thể viết:

Stop retries after authentication rejection

Return the HTTP 401 response without another retry.
Preserve the existing rate-limit handling.

Chỉ dùng khi diff đã stage thực sự làm những việc đó. Ví dụ không khẳng định test đã đạt. Nếu patch đổi mã trạng thái, chính sách retry hoặc nhánh lỗi khác, sửa lời giải thích cho đúng thay vì giữ câu tóm tắt nghe hay.

Tải mẫu commit message rồi thay chỗ trống bằng thay đổi của bạn. Subject cần cụ thể; body bổ sung lý do có ích. Một sửa đổi nhỏ không cần đủ số đoạn cố định.

Theo quy ước commit của repository

Nếu dự án dùng Conventional Commits, subject có thể là fix(retry): stop retries after authentication rejection. Đặc tả phân biệt fix, feat và dấu breaking change; chọn theo hành vi thực tế và quy tắc dự án.

Không đọc feat chỉ vì thay đổi mới với bạn, hoặc thêm dấu breaking change để message có vẻ đầy đủ. Dự án dùng subject mệnh lệnh thông thường không cần đổi quy ước chỉ để áp dụng cách nhập này.

Nếu tên công cụ thường bị sai, dùng hướng dẫn dictionary cho developer. Vẫn kiểm tra dấu câu, scope, mã issue và chữ hoa/thường trong văn bản cuối.

Đưa message đã đọc lại vào Git qua file

Với ví dụ dưới, lưu message hoàn chỉnh thành commit-message.txt ở thư mục cha của repository. Xác nhận vị trí đó phù hợp trên máy bạn. File nằm ngoài working tree được theo dõi, tránh vô tình stage cùng patch.

Từ thư mục gốc repository, sau khi xem diff đã stage:

git commit --file ../commit-message.txt

Tài liệu Git commit mô tả --file là đọc message từ file. Lệnh tạo commit local từ thay đổi đã stage; không stage mọi file đã sửa, không tạo PR trên GitHub và không push branch. Hook và yêu cầu ký commit của dự án vẫn áp dụng.

Dùng file cũng tránh ghép lời đọc thành lệnh shell có nhiều lớp dấu nháy. Đọc lại file trước khi chạy. Nếu dùng editor hoặc Git client, đưa cùng văn bản đã kiểm tra vào ô message của công cụ đó.

Các lệnh chỉ đọc và commit qua file đã được kiểm tra trong Git repository tạm, tách khỏi dự án. Phép thử xác minh quy trình Git, chưa xác minh nhận dạng giọng nói hoặc tính đúng của patch retry minh họa.

Cung cấp đúng ngữ cảnh cho người review PR

PR có thể gồm nhiều commit; phần mô tả cần giải thích hành vi sau toàn bộ thay đổi. Mở đầu bằng tình huống cụ thể và kết quả, rồi nêu kiểm tra đã thực hiện và giới hạn còn ảnh hưởng đến review.

Dùng mẫu mô tả PR làm điểm bắt đầu nếu phù hợp. Mẫu tách vấn đề, hành vi mới, xác minh và câu hỏi còn lại. Thay mọi chỗ trống; không đánh dấu test đã xong chỉ vì bạn định chạy.

Tài liệu PR template của GitHub hỗ trợ .github/pull_request_template.md cùng một số vị trí khác. Template dùng chung có hiệu lực khi đã merge vào nhánh mặc định. Tải file mẫu này không tự cài vào dự án; nếu đã có template, dùng cấu trúc hiện tại.

Đọc vào editor nháp hoặc ô nội dung PR rồi xem lại toàn bộ trước khi đăng. Nếu Flow có transcript nhưng không chèn, dùng hướng dẫn lấy lại văn bản thay vì đọc lại và có thể bỏ mất điều kiện quan trọng.

Kiểm chứng nhận định trước khi gửi

Đối chiếu từng nhận định về hành vi với diff. Phân biệt “đã thử”, “chưa thử” và “dự kiến”; ghi lệnh kiểm tra và kết quả quan sát khi có ích. Nếu test thất bại, nêu lỗi liên quan, không để bước sửa câu biến thành lời khẳng định thành công.

Kiểm tra tham chiếu, phiên bản và phủ định bằng mắt. Bỏ từ đệm và lịch sử triển khai không giúp review. Nếu phạm vi đổi trong lúc làm, viết lại subject và mở đầu PR theo thay đổi cuối.

Muốn biết giọng nói có ích không, so tổng thời gian soạn và sửa với những thay đổi có độ lớn tương đương. Mô tả nói dài hơn không mặc định giúp review tốt hơn. Đầu ra cần là bản trình bày ngắn, chính xác để developer khác đối chiếu được với code.

Nếu ghi chú giọng nói còn có việc cần làm tiếp, workflow transcript trong n8n giúp tách các task chờ duyệt khỏi nội dung commit.