Quy trình Prompt-to-PR với Claude Code: Các sửa đổi nhỏ

Tại sao Prompt-to-PR thắng các prompt lớn một lần duy nhất

Các prompt lớn một lần thường dẫn đến thay đổi lớn, lộn xộn: chạm hàng chục tệp, refactor không liên quan, và mã bạn chưa kịp hiểu. Ngay cả khi đầu ra về mặt kỹ thuật đúng, việc review vẫn cảm thấy rủi ro vì khó biết gì đã thay đổi và vì sao.

Sửa đổi nhỏ khắc phục điều đó. Khi mỗi thay đổi có giới hạn và tập trung, bạn có thể đọc nó trong vài phút, bắt lỗi sớm, và tránh phá vỡ những chỗ bạn không định chạm đến. Reviewer tin tưởng các PR nhỏ hơn, nên việc merge diễn ra nhanh hơn và ít comment qua lại.

Prompt-to-PR là một vòng lặp đơn giản:

• Yêu cầu một thay đổi nhỏ với ranh giới rõ ràng.
• Kiểm tra diff và xác nhận nó đúng ý định.
• Chạy các kiểm tra thông thường (test, lint, build).
• Nếu có lỗi, re-prompt kèm lỗi và ngữ cảnh chính xác.
• Lặp lại cho đến khi sẵn sàng merge.

Nhịp này biến lỗi thành phản hồi nhanh thay vì bất ngờ ở cuối. Nếu bạn yêu cầu Claude Code chỉnh một quy tắc xác thực, giữ nó chỉ cho quy tắc đó. Nếu một test fail, dán kết quả lỗi và yêu cầu bản vá nhỏ nhất làm cho test pass, đừng yêu cầu viết lại toàn bộ module.

Một điều không thay đổi: bạn vẫn chịu trách nhiệm cho mã cuối cùng. Đối xử với mô hình như một đồng lập trình viên cục bộ gõ nhanh, chứ không phải autopilot. Bạn quyết định thứ gì vào, thứ gì giữ lại, và khi nào an toàn để mở PR.

Chuẩn bị repo và thiết lập pairing cục bộ

Bắt đầu từ một baseline sạch. Nếu nhánh của bạn lạc hậu hoặc test đang fail, mọi đề xuất sẽ trở thành suy đoán. Pull các thay đổi mới nhất, rebase hoặc merge theo phong cách nhóm bạn, và đảm bảo trạng thái hiện tại là khỏe mạnh trước khi yêu cầu gì.

Một thiết lập "đồng lập trình viên cục bộ" có nghĩa Claude Code chỉnh sửa tệp trong repo của bạn trong khi bạn kiểm soát mục tiêu, các hàng rào, và mọi diff. Mô hình không biết codebase của bạn trừ khi bạn cho xem, nên hãy rõ ràng về tệp, ràng buộc và hành vi mong đợi.

Trước prompt đầu tiên, quyết định nơi chạy các kiểm tra. Nếu bạn có thể chạy test cục bộ, bạn sẽ nhận phản hồi trong vài phút, giúp các vòng nhỏ. Nếu một số kiểm tra chỉ chạy ở CI (một số quy tắc lint, suite dài, bước build), hãy quyết định khi nào bạn sẽ dựa vào CI để không phải chờ sau mỗi thay đổi nhỏ.

Một pre-flight đơn giản:

• Cập nhật nhánh và xác nhận app build hoặc khởi động được.
• Chạy các kiểm tra nhanh cục bộ (lint, unit test, type check).
• Ghi chú các kiểm tra chỉ chạy trên CI và thời gian chúng thường mất.
• Xác nhận bạn có thể tái hiện lỗi hoặc thấy rõ chức năng thiếu.
• Đảm bảo bạn có thể undo thay đổi dễ dàng (trạng thái sạch, commit nhỏ).

Giữ một scratchpad nhỏ mở trong khi làm việc. Ghi các ràng buộc như "không thay đổi API," "giữ tương thích ngược," "chỉ chạm module X," cùng mọi quyết định bạn thực hiện. Khi test fail, dán thông báo lỗi chính xác vào đó. Scratchpad đó trở thành đầu vào tốt nhất cho prompt tiếp theo và ngăn phiên làm việc bị trôi.

Viết prompt dẫn đến các diff nhỏ một cách tự nhiên

Các diff nhỏ bắt nguồn từ prompt được thu hẹp có chủ ý. Con đường nhanh nhất tới mã có thể merge là một thay đổi bạn có thể review trong một phút, không phải một refactor bạn phải hiểu trong một giờ.

Một prompt tốt nêu rõ một mục tiêu, một khu vực code, và một kết quả mong đợi. Nếu bạn không chỉ ra nơi thay đổi nên nằm (một tệp, thư mục, hoặc module), mô hình sẽ đoán và diff sẽ lan rộng.

Một khuôn dạng prompt giữ thay đổi chặt:

• Mục tiêu: hành vi duy nhất bạn muốn thay đổi.
• Vị trí: tệp(s) hoặc component cần chạm tới.
• Ràng buộc: những gì không được thay đổi.
• Chấp nhận: khi nào thì coi là "xong".
• Kích thước diff: yêu cầu rõ ràng thay đổi nhỏ nhất có thể.

Ranh giới là vũ khí bí mật. Thay vì "fix lỗi login," hãy nêu những gì phải giữ nguyên: "Đừng thay đổi hình dạng API," "Đừng đổi tên hàm public," "Không chỉnh chỉ format," "Tránh phụ thuộc mới." Điều đó nói với đồng lập trình viên nơi không được sáng tạo.

Khi thay đổi vẫn không rõ, yêu cầu một kế hoạch trước khi code. Một kế hoạch ngắn ép công việc thành các bước và cho bạn cơ hội duyệt một bước nhỏ đầu tiên.

Goal: Fix the null crash when rendering the profile header.
Location: src/components/ProfileHeader.tsx only.
Constraints: Do not change styling, props, or any exported types.
Expected outcome: If user.name is missing, show "Anonymous" and no crash.
Diff constraint: Minimal diff. No refactors. No unrelated formatting.
If unclear: First reply with a 3-step plan, then wait for approval.

Nếu bạn làm việc trong nhóm, thêm ràng buộc review: "Giữ dưới ~30 dòng thay đổi" hoặc "Chỉ một file trừ khi thực sự cần." Nó làm cho diff dễ quét hơn và khiến prompt tiếp theo sắc nét hơn khi có lỗi.

Chọn đơn vị công việc phù hợp cho mỗi vòng lặp

Giữ mỗi vòng tập trung vào một thay đổi nhỏ, có thể kiểm thử. Nếu bạn có thể mô tả mục tiêu trong một câu và dự đoán tệp nào sẽ thay đổi, đó là kích thước phù hợp.

Các đơn vị công việc tốt bao gồm: sửa một bug trong một đường đi (với repro và guard), điều chỉnh một test đơn cho một hành vi, làm refactor bảo toàn hành vi (đổi tên, tách hàm, loại trùng lặp), hoặc cải thiện một thông báo lỗi hay quy tắc xác thực.

Đặt giới hạn thời gian cho mỗi vòng. 10–20 phút thường đủ để viết prompt rõ, áp dụng diff và chạy kiểm tra nhanh. Nếu bạn vẫn đang khám phá sau 20 phút, thu nhỏ đơn vị hoặc chuyển sang chỉ điều tra (ghi chú, logging, test failing) và dừng ở đó.

Định nghĩa "xong" trước khi bắt đầu:

• Thay đổi ở trong tệp và hành vi dự định.
• Một kiểm tra chứng minh nó hoạt động (test, lint, hoặc bước chạy đơn giản).
• Không có cảnh báo mới hoặc chỉnh format ồn ào.
• Diff dễ giải thích trong hai câu.

Khi scope bắt đầu mở rộng, dừng sớm. Nếu bạn thấy mình nói "nhân tiện," bạn vừa tìm thấy vòng lặp tiếp theo. Ghi nó làm follow-up, commit diff nhỏ hiện tại, và tiếp tục.

Review diff trước khi chạy kiểm tra

Trước khi chạy test hoặc build, đọc diff như một reviewer. Đây là nơi workflow hoặc giữ sạch hoặc lặng lẽ trôi vào "tại sao nó chạm tệp đó?" territory.

Bắt đầu bằng việc yêu cầu Claude Code tóm tắt những gì nó đã thay đổi bằng ngôn ngữ thường: tệp chạm, thay đổi hành vi, và những gì nó không thay đổi. Nếu nó không thể giải thích rõ ràng, diff có khả năng làm quá nhiều.

Rồi tự review. Lướt để kiểm tra scope, sau đó đọc để hiểu ý định. Bạn đang tìm drift: chỉnh format không liên quan, refactor thêm, đổi tên symbol, hoặc thay đổi ngoài yêu cầu.

Một pre-check nhanh:

• Các tệp thay đổi có đúng như bạn yêu cầu không?
• Có chỉnh sửa vội vàng (whitespace, refactor không liên quan) không?
• Nó có giới thiệu hành vi mới bạn không yêu cầu không?
• Có phụ thuộc mới hoặc thay đổi config cần lý do thật không?
• Reviewer có thể hiểu điều này mà không phải đọc năm tệp khác không?

Nếu diff lớn hơn mong đợi, đừng cố test để thoát. Quay lại và re-prompt cho bước nhỏ hơn. Ví dụ: "Chỉ thêm một test failing tái hiện bug. Không refactor." Diff nhỏ giúp lỗi dễ diễn giải và prompt tiếp theo cụ thể hơn.

Chạy kiểm tra sau mỗi thay đổi nhỏ

Diff nhỏ chỉ có ích nếu bạn xác minh ngay lập tức. Mục tiêu là vòng chặt: thay đổi ít, kiểm tra ít, bắt lỗi khi ngữ cảnh còn mới.

Bắt đầu với kiểm tra nhanh nhất có thể cho biết "điều này bị hỏng." Nếu bạn thay đổi format hoặc imports, chạy lint/format trước. Nếu bạn chạm logic nghiệp vụ, chạy unit test nhỏ nhất bao phủ tệp hoặc package đó. Nếu bạn sửa types hoặc config build, chạy compile nhanh.

Một thứ tự thực tế:

• Lint hoặc format.
• Unit test nhắm mục tiêu cho khu vực bạn thay đổi.
• Build hoặc typecheck để xác nhận mọi thứ vẫn khớp.
• Suite chậm hơn (integration, end-to-end) sau khi các bước cơ bản pass.

Khi có lỗi, lưu hai thứ trước khi sửa gì: lệnh bạn chạy và toàn bộ output lỗi (copy nguyên xi). Ghi lại đó để prompt tiếp theo cụ thể và tránh vòng "vẫn lỗi" lặp đi lặp lại.

Giữ scope chặt. Nếu lint fail và test fail, sửa lint trước, chạy lại, rồi xử lý test. Đừng trộn "dọn dẹp nhanh" với sửa crash trong cùng một pass.

Re-prompt với lỗi cho đến khi kiểm tra xanh

Khi kiểm tra fail, coi output lỗi là prompt tiếp theo. Vòng nhanh nhất là: dán lỗi, nhận chẩn đoán, áp dụng bản vá nhỏ nhất, chạy lại.

Dán lỗi nguyên xi, bao gồm lệnh và toàn bộ stack trace. Yêu cầu nguyên nhân khả dĩ nhất trước, không phải một menu các lựa chọn. Claude Code làm tốt hơn khi nó có thể bám vào số dòng và thông báo lỗi cụ thể thay vì đoán mò.

Thêm một câu về những gì bạn đã thử để nó không gửi bạn quay vòng. Nhắc lại các ràng buộc quan trọng ("Đừng thay đổi API public," "Giữ hành vi hiện tại, chỉ sửa crash"). Rồi yêu cầu bản vá nhỏ nhất làm cho kiểm tra pass.

Một prompt lỗi tốt bao gồm:

• Output lỗi chính xác (nguyên xi).
• Tệp(s) và dòng liên quan.
• Những gì bạn thay đổi trong diff gần nhất.
• Những gì bạn đã thử.
• Yêu cầu bản vá nhỏ nhất để kiểm tra pass.

Nếu bản vá đề xuất thay đổi hành vi, yêu cầu một test chứng minh hành vi mới là đúng. Nếu một handler giờ trả 400 thay vì 500, yêu cầu một test tập trung thất bại trên code cũ và pass trên bản vá. Điều đó giữ công việc trung thực và làm PR dễ tin cậy.

Dừng khi kiểm tra xanh và diff vẫn là một ý tưởng duy nhất. Nếu mô hình bắt đầu tối ưu mã không liên quan, re-prompt: "Chỉ xử lý test failing. Không dọn dẹp."

Làm PR dễ review và merge

Một PR được merge nhanh khi rõ ràng những gì thay đổi, tại sao thay đổi, và làm sao để chứng minh nó hoạt động. Với workflow này, PR nên đọc như một câu chuyện ngắn: bước nhỏ, lí do rõ ràng.

Giữ commit phù hợp với các vòng lặp của bạn. Nếu bạn yêu cầu một thay đổi hành vi, làm commit đó. Nếu bạn rồi sửa test failing, làm commit tiếp theo. Reviewer có thể theo dõi hành trình và tin rằng bạn không lẳng lặng thêm thay đổi.

Viết message commit theo ý định, không phải tên tệp. "Fix login redirect when session expires" tốt hơn "Update auth middleware." Khi message nêu kết quả người dùng, reviewer ít tốn thời gian đoán.

Tránh trộn refactor với thay đổi hành vi trong cùng một commit. Nếu muốn đổi tên biến hoặc chuyển helper, làm riêng (hoặc bỏ qua bây giờ). Tiếng ồn làm chậm review.

Trong mô tả PR, giữ ngắn và cụ thể:

• Thay đổi gì (1–2 câu).
• Tại sao thay đổi (lỗi hoặc yêu cầu).
• Cách test (các bước chính xác, bao gồm cờ hoặc dữ liệu cần thiết).
• Bạn không thay đổi gì (để đặt kỳ vọng).
• Rủi ro hoặc ghi chú rollback (cái gì sẽ hỏng nếu sai).

Ví dụ: một crash trang billing do record customer null. Commit 1 thêm guard và trạng thái lỗi rõ ràng. Commit 2 thêm test cho trường hợp null. Mô tả PR nói: "Mở Billing, load customer không có profile, xác nhận trang hiển thị trạng thái rỗng mới." Đó là loại PR reviewer có thể approve nhanh.

Bẫy thường gặp làm chậm bạn

Nhịp này vỡ khi scope lặng lẽ mở rộng. Một prompt bắt đầu là "sửa test failing" biến thành "cải thiện error handling toàn module," và bỗng bạn review một diff lớn với ý định mơ hồ. Giữ chặt: một mục tiêu, một tập thay đổi, một tập kiểm tra.

Chậm nữa là chấp nhận refactor trông đẹp chỉ vì trông đẹp. Đổi tên, di chuyển file và thay đổi style tạo nhiễu trong review và khó phát hiện thay đổi hành vi thực sự.

Các bẫy thường gặp:

• Để mô hình chạm tệp không liên quan "nhân tiện nó ở đây."
• Sửa triệu chứng (thêm null check) thay vì nguyên nhân gốc mà test chỉ ra.
• Chỉ dán một vài dòng cuối log và che dấu lỗi ban đầu.
• Bỏ qua quét diff nhanh trước khi chạy kiểm tra.
• Re-prompt với "nó vẫn lỗi" thay vì lệnh và output chính xác.

Một ví dụ cụ thể: test fail với "expected 400, got 500." Nếu bạn chỉ dán phần cuối stack trace, thường nhận đề xuất try/catch chung chung. Nếu dán toàn bộ output test, bạn có thể thấy vấn đề thật sự: thiếu nhánh validate. Điều đó dẫn tới một diff nhỏ, tập trung.

Trước khi commit, đọc diff như reviewer. Hỏi: mỗi dòng có phục vụ yêu cầu không, và tôi có thể giải thích nó trong một câu không? Nếu không, revert các thay đổi thừa và re-prompt với yêu cầu hẹp hơn.

Ví dụ: sửa lỗi thành PR có thể merge trong vài vòng

Người dùng báo: "Trang cài đặt đôi khi reset về mặc định sau khi lưu." Bạn pull main, chạy test, và thấy một failure. Hoặc không có test, chỉ có repro rõ.

Xử lý như một vòng lặp: một yêu cầu nhỏ, một diff nhỏ, rồi kiểm tra.

Đầu tiên, cho Claude Code ngữ cảnh nhỏ nhất hữu ích: output test failing (hoặc các bước tái hiện), đường dẫn tệp bạn nghi ngờ, và mục tiêu ("giữ hành vi, chỉ sửa reset"). Yêu cầu chẩn đoán và bản vá tối thiểu, không refactor.

Rồi làm việc bằng vòng lặp ngắn:

1. Loop 1 (bản vá tối thiểu): Áp dụng thay đổi nhỏ nhất có thể sửa bug. Giữ chặt: một guard, một null check thiếu, một giá trị default sai, hoặc danh sách dependency sai.

Chạy kiểm tra sau khi bạn review diff.

2. Loop 2 (feed lại lỗi chính xác): Nếu test fail, copy output failing chính xác vào Claude Code. Bao gồm tên tệp, số dòng, và thông báo assertion. Hỏi: "Bản thay đổi nhỏ nhất để sửa lỗi này mà không mở rộng scope?"

Nếu kiểm tra pass nhưng bạn lo ngại về regression, thêm coverage.

3. Loop 3 (điều chỉnh test hoặc thêm test mới): Thêm test fail nếu không có và pass với bản vá. Giữ tập trung vào bug.

Kết thúc với mô tả PR nhỏ: bug là gì, vì sao xảy ra, và thay đổi ra sao. Thêm ghi chú reviewer như "chỉ chạm X file" hoặc "thêm 1 test cho trường hợp reset" để review an toàn.

Checklist nhanh trước khi mở PR

Ngay trước khi mở pull request, làm lần cuối để đảm bảo công việc dễ review và an toàn merge.

• Diff khớp mục tiêu ban đầu và đủ nhỏ để hiểu trong vài phút.
• Bạn đã chạy các kiểm tra liên quan (test, lint, typecheck, build) và chúng pass. Nếu nhóm dùng CI, xác nhận bộ tương tự sẽ chạy trên đó.
• Thay đổi có mạng lưới an toàn phù hợp: một test cho bug/feature khi hợp lý, hoặc lý do rõ vì không cần test.
• Mô tả PR cụ thể: thay đổi gì, vì sao, và các bước để kiểm tra chính xác.
• Không có chỉnh sửa vội vàng: format không liên quan, đổi tên chỉ style, hoặc refactor không cần thiết.

Một ví dụ nhanh: nếu bạn sửa bug login nhưng cũng reformat 20 tệp, undo commit format. Reviewer nên tập trung vào sửa login, không tự hỏi thứ gì khác thay đổi.

Nếu có mục nào fail, làm thêm một vòng nhỏ nữa: tạo diff nhỏ, chạy lại kiểm tra, và cập nhật ghi chú PR. Vòng lặp cuối đó thường tiết kiệm hàng giờ tra hỏi qua lại.

Bước tiếp theo: biến nhịp này thành thói quen

Tính nhất quán biến một phiên tốt thành workflow đáng tin cậy. Chọn một vòng lặp mặc định và chạy theo cùng cách mỗi lần. Sau một tuần, bạn sẽ thấy prompts ngắn hơn và diff dễ review hơn.

Một thói quen đơn giản:

• Chọn một kết quả rất nhỏ (một bug, một edge case, một hàm).
• Yêu cầu một diff nhỏ và lời giải thích ngắn về những gì thay đổi.
• Đọc diff như reviewer, rồi chạy kiểm tra cục bộ.
• Re-prompt với output lỗi chính xác và tên tệp.
• Dừng ngay khi kiểm tra xanh và thay đổi rõ ràng.

Một template prompt cá nhân giúp bạn kỷ luật: "Chỉ thay đổi những gì cần. Chạm tối đa 2 tệp. Giữ hành vi public trừ khi tôi nói khác. Nói lệnh cần chạy và thành công trông như thế nào."

Nếu bạn xây dựng trong Koder.ai, bạn có thể dùng cùng vòng lặp trong giao diện chat của nó. Planning mode phù hợp để xác định lát cắt mergeable nhỏ nhất (inputs, outputs và acceptance checks), và snapshots cùng rollback giúp bạn phục hồi nhanh khi thí nghiệm lệch hướng.

Khi thay đổi ổn định, xuất source để chạy tooling cục bộ, CI và review đồng đội như bình thường. Triển khai khi cần kiểm tra end-to-end thực tế, như kiểm tra flow.

Hãy biến vòng lặp thành mặc định. Prompt nhỏ, diff nhỏ, kiểm tra thường xuyên và sửa nhanh sẽ tạo nên những PR nhàm chán theo nghĩa tốt nhất.