Worktree và khung rà soát: làm song song nhưng vẫn kiểm soát

English title: Worktrees and Review Pane

Cập nhật: 29/06/2026. Đây là bài 5 trong chuỗi Codex Power 10 - 10 bài hướng dẫn dùng các năng lực mạnh của Codex theo cách có kiểm soát.

Bạn sẽ biết cách chia việc thành nhánh nhỏ, đọc diff theo ý định, và phản hồi cho Codex mà không mất dòng suy nghĩ chính.

Bảng Nhớ Nhanh

Dùng bài này khi: bạn muốn Codex làm song song mà không làm bẩn checkout chính.

Không dùng bài này khi: task quá nhỏ, bạn đang đứng sẵn trong local checkout và có thể đọc diff ngay.

Xong bài khi: mỗi worktree có một mục tiêu, một diff đọc được và một quyết định handoff/branch rõ.

Ghi nhớ: Bài thực hành này không cố làm bạn nhớ hết tính năng. Nó giúp bạn dựng một vòng làm việc có mục tiêu, có biên và có bằng chứng.

Trước Khi Bắt Đầu

• Repo phải là Git repository.
• Task nên tách được thành một đơn vị review nhỏ.
• Biết bạn sẽ kiểm chứng ngay trong worktree hay handoff về Local.

Cẩn trọng: Nếu môi trường hoặc quyền đang mơ hồ, hãy dừng một nhịp để kiểm tra. Agent chạy nhanh trong bối cảnh sai sẽ tạo ra diff rất thuyết phục nhưng khó dùng.

Ý Tưởng Trong 3 Phút

Khi một người tự sửa code, họ thường giữ toàn bộ ngữ cảnh trong đầu. Khi làm với Codex, bạn cần chuyển ngữ cảnh đó thành các đơn vị có thể rà soát: một worktree, một diff, một cổng kiểm tra.

Worktree là bàn phụ cho thí nghiệm. Khung rà soát là kính lúp. Nếu bàn phụ bừa bộn, kính lúp cũng không cứu được; vì vậy việc quan trọng là chia task nhỏ trước.

• Một worktree nên gắn với một mục tiêu. Đừng trộn refactor, sửa bug và đổi nội dung trong cùng một nhánh nếu không cần.
• Diff tốt kể câu chuyện: file nào đổi, vì sao đổi, test nào chứng minh. Codex nên tóm tắt theo câu chuyện đó.
• Khung rà soát hữu ích nhất khi bạn phản hồi vào điểm cụ thể: dòng này thiếu trường hợp biên, component này lệch mẫu, test này chưa bao phủ.
• Nếu diff quá lớn, yêu cầu Codex tự chia lại thành các phần có thể đọc được trước khi tiếp tục.

Công Thức 1: Chạy Quy Trình Chính

Khi dùng: bạn muốn Codex làm song song mà không làm bẩn checkout chính.

1. Tạo hoặc để Codex tạo một nhánh/worktree theo tên mục tiêu.
2. Yêu cầu thay đổi tối thiểu trước, chưa tối ưu hóa sâu.
3. Đọc diff theo ba câu hỏi: đúng mục tiêu không, có lan phạm vi không, có test không.
4. Phản hồi bằng điểm cụ thể rồi cho Codex sửa vòng tiếp theo.

Công Thức 2: Đóng Cổng Kiểm Chứng

Một phiên tốt không cần lúc nào cũng dài. Điều cần giữ là nhịp: giao việc rõ, để Codex đọc đúng, cho nó thực hiện trong phạm vi nhỏ, rồi bắt nó tự chứng minh kết quả.

Prompt Mẫu

Goal: Làm thử cải tiến UI trong worktree riêng.
Context: Component đích, screenshot hiện trạng và tiêu chí nghiệm thu.
Constraints: Một mục tiêu, không refactor toàn trang, không đổi route.
Done-when: Diff đọc được, test/build pass hoặc có blocker rõ, đề xuất handoff hay giữ branch.

Ví Dụ Tối Thiểu: Review contract cho một worktree

Mode: Worktree
Goal: sửa một lỗi UI nhỏ
Review: tóm tắt ý định diff trước khi merge
Gate: build pass, screenshot mobile không tràn chữ

Khi Có Lỗi

Nếu gặp một trong các lỗi trên, cách sửa thường không phải là viết prompt dài hơn. Cách sửa là thêm đúng mảnh còn thiếu: một đường dẫn ngữ cảnh, một ràng buộc phạm vi, hoặc một tiêu chí nghiệm thu.

Quy Trình Trong Đội

Trong nhóm, có thể dùng Codex cho vòng chuẩn bị: tạo nhánh, viết test, sửa hẹp. Con người giữ quyền merge sau khi đọc diff và xác nhận rủi ro.

Với đội mới bắt đầu, đừng đưa Codex vào khâu rủi ro nhất ngay. Hãy bắt đầu ở nơi có phản hồi nhanh: viết test, tạo bản nháp, rà link, chuẩn hóa tài liệu, tạo ảnh minh họa, hoặc chuẩn bị diff nhỏ để con người rà soát.

Bài Tập 30 Phút

1. Chọn một repo, bài viết hoặc màn hình thật để thực hành.
2. Viết một câu mục tiêu cho bài 5, tránh yêu cầu chung chung.
3. Liệt kê đúng ba nguồn context mà Codex nên đọc trước.
4. Ghi hai ràng buộc không được vượt.
5. Viết Done-when bằng bằng chứng có thể kiểm tra.
6. Chạy prompt trong Codex CLI hoặc Codex App.
7. Dừng sau plan đầu tiên và xem Codex có hiểu đúng không.
8. Cho Codex làm phần nhỏ nhất có thể.
9. Đóng gate: Mục tiêu, Diff, Test, Handoff.
10. Ghi lại một điều nên đưa vào prompt hoặc AGENTS.md cho lần sau.

10 Điều Cần Nhớ

1. Worktree là bàn phụ cho thí nghiệm.
2. Mỗi worktree nên có một mục tiêu.
3. Handoff đưa việc về Local khi bạn cần inspect trực tiếp.
4. Create branch here giữ kết quả trong nhánh riêng.
5. Git không cho cùng một branch checkout ở hai worktree.
6. .worktreeinclude xử lý file ignored cần copy.
7. Diff tốt kể câu chuyện thay đổi.
8. Comment vào chunk cụ thể giúp Codex sửa nhanh hơn.
9. Diff quá lớn là tín hiệu cần chia lại.
10. Merge chỉ nên đến sau gate.

Nguồn tham khảo chính: OpenAI Codex documentation. Bài tiếp: Skills và plugins: đóng gói quy trình lặp lại.