- Cách sử dụng công cụ lập trình AI được tái cấu trúc một cách căn bản, đề xuất quy trình làm việc bắt buộc phải qua bước rà soát kế hoạch rõ ràng trước khi viết mã
- Nguyên tắc cốt lõi là “không để Claude viết mã trước khi kế hoạch được phê duyệt”, qua đó đạt được khả năng kiểm soát có cấu trúc và sử dụng token hiệu quả
- Toàn bộ quy trình vận hành theo cấu trúc lặp Research → Plan → Annotation → Todo List → Implementation → Feedback
- Ở mỗi giai đoạn, việc cộng tác xoay quanh các tài liệu markdown (
research.md, plan.md), lặp lại quá trình chú thích và chỉnh sửa để nâng cao độ hoàn thiện
- Phương pháp này tập trung vào việc tách ra rồi kết hợp năng lực thực thi của AI với khả năng phán đoán của con người, nhằm tạo ra kết quả ổn định và nhất quán ngay cả trong các hệ thống phức tạp
Tổng quan toàn bộ quy trình làm việc
- Trong khoảng 9 tháng dùng Claude Code làm công cụ phát triển chính, tác giả đã xây dựng một quy trình có hệ thống tách riêng lập kế hoạch và thực thi, thay cho cách làm phổ biến kiểu “nhập prompt → sinh mã → lặp lại chỉnh sửa”
- Trước khi Claude viết mã, nó chỉ được phép thực thi dựa trên tài liệu kế hoạch (
plan.md) đã được người viết xem xét và phê duyệt
- Cách tiếp cận này giảm bớt thử-sai không cần thiết, giữ quyền quyết định kiến trúc, và tối đa hóa chất lượng trên lượng token sử dụng
Giai đoạn 1: Research
- Mọi công việc đều bắt đầu bằng phân tích sâu codebase
- Yêu cầu Claude phân tích một thư mục hoặc tính năng cụ thể theo hướng “đọc thật sâu” (
detailed, intricacies)
- Kết quả bắt buộc phải được ghi vào tệp
research.md
- Tài liệu này đóng vai trò là bề mặt rà soát (review surface) để kiểm chứng mức độ hiểu của Claude; nếu có hiểu sai thì sửa ngay ở bước này
- Vì nghiên cứu sai sẽ dẫn đến kế hoạch sai và triển khai sai, đây là bước ngăn chặn trước yếu tố thất bại có chi phí lớn nhất
- Ví dụ, có thể phòng tránh các vấn đề như bỏ qua tầng cache, không phản ánh đúng quy tắc ORM, hoặc tạo logic trùng lặp
Giai đoạn 2: Planning
- Sau khi rà soát phần nghiên cứu, yêu cầu Claude viết kế hoạch triển khai chi tiết (
plan.md)
- Bao gồm snippet mã thực tế, đường dẫn tệp cần sửa và các đánh đổi
- Thay vì dùng plan mode tích hợp sẵn, tác giả dùng tệp markdown có thể tự quản lý trực tiếp
- Nếu cung cấp thêm reference implementation từ mã nguồn mở, chất lượng kế hoạch của Claude sẽ được cải thiện rõ rệt
- Điều quan trọng hơn chính bản thân tài liệu kế hoạch là chu kỳ chú thích (Annotation) diễn ra sau đó
Chu kỳ Annotation
- Người viết mở
plan.md và tự thêm chú thích inline trực tiếp
- Sửa giả định sai, bác bỏ cách tiếp cận, bổ sung tri thức miền, v.v.
- Ví dụ: “chỗ này phải là PATCH”, “không cần cache”, “trường visibility chuyển lên cấp danh sách”
- Sau đó yêu cầu Claude “cập nhật tài liệu để phản ánh các chú thích, nhưng chưa được triển khai”
- Chu kỳ chú thích - cập nhật này được lặp từ 1 đến 6 lần, dùng lệnh “don’t implement yet” để ngăn thực thi quá sớm
- Tài liệu markdown hoạt động như một trạng thái dùng chung (shared state), rõ ràng và có cấu trúc hơn so với chỉ dẫn hội thoại
- Qua lặp lại, một kế hoạch tổng quát sẽ tiến hóa thành đặc tả khớp hoàn toàn với hệ thống thực tế
Tạo Todo List
- Trước khi triển khai, yêu cầu Claude thêm danh sách công việc chi tiết (todo list)
- Bao gồm các tác vụ con theo từng bước để theo dõi tiến độ
- Claude sẽ đánh dấu các mục đã hoàn thành, nên ngay cả trong các phiên dài vẫn dễ nắm trạng thái
Giai đoạn 3: Implementation
- Khi mọi quyết định đã được chốt, dùng prompt tiêu chuẩn hóa để ra lệnh thực thi
- Chẳng hạn: “không được dừng cho tới khi hoàn tất mọi tác vụ”, “cấm chú thích không cần thiết”, “cấm kiểu
any/unknown”, “liên tục chạy type-check”, v.v.
- Lệnh này biến giai đoạn thực thi thành một bước cơ học làm đúng theo kế hoạch, vì phần phán đoán sáng tạo đã hoàn tất từ trước
- Nếu triển khai ngay mà không có kế hoạch, rất dễ xây mã trên những giả định sai; vì vậy quy tắc “don’t implement yet” là chốt an toàn cốt lõi
Phản hồi trong lúc Implementation
- Trong khi thực thi, người viết chuyển sang vai trò giám sát
- Phản hồi được đưa ra ngắn gọn và rõ ràng: “thiếu hàm này”, “chuyển sang app admin”, v.v.
- Khi sửa frontend, có thể dùng các chỉ dẫn ngắn như “wider”, “2px gap” hoặc dùng ảnh chụp màn hình
- Việc tham chiếu mã sẵn có được dùng thường xuyên để duy trì UI/UX nhất quán
- Nếu đi sai hướng,
git revert rồi thử lại với phạm vi nhỏ hơn sẽ hiệu quả hơn là sửa dần từng chút
Giữ quyền điều khiển
- Không trao cho Claude quyền tự chủ hoàn toàn; quyết định cuối cùng luôn do con người đưa ra
- Có thể chỉ chọn một phần trong các đề xuất của Claude, hoặc sửa, xóa, tái định nghĩa lựa chọn kỹ thuật
- Ví dụ: “cái đầu tiên dùng
Promise.all”, “bỏ qua cái thứ tư và thứ năm”
- “gỡ chức năng tải xuống”, “không được đổi function signature”, “dùng method của thư viện cụ thể”
- Claude đảm nhận thực thi cơ học, còn con người phụ trách phán đoán và xác định ưu tiên
Một phiên dài duy nhất
- Toàn bộ quá trình từ nghiên cứu đến triển khai được thực hiện liên tục trong một phiên dài duy nhất
- Trong phiên đó, Claude liên tục tích lũy ngữ cảnh và nhờ auto-compaction vẫn giữ đủ bối cảnh
plan.md được giữ nguyên ở dạng đầy đủ trong suốt phiên, có thể tham chiếu bất cứ lúc nào
Tóm tắt cốt lõi
- “Đọc thật sâu, viết kế hoạch, tinh chỉnh bằng chú thích rồi thực thi một lần.”
- Ngay cả không cần prompt phức tạp hay chỉ dẫn hệ thống, vẫn có thể đạt chất lượng cao bằng một pipeline có kỷ luật, trong đó tách riêng Thinking và Typing
- Research ngăn các thay đổi thiếu hiểu biết, Plan ngăn các thay đổi sai hướng, còn Annotation đưa phán đoán của con người vào quy trình
- Bước thực thi cuối cùng được tự động hóa sau khi mọi quyết định đã được chốt, hoàn thiện một cấu trúc cộng tác hiệu quả
4 bình luận
Tôi cũng liên tục gặp phải vấn đề tương tự. Nếu chỉ cộng tác với AI theo kiểu dựa trên trò chuyện, thì việc phân rã đơn vị công việc (WBS), tiến độ và ghi chép các quyết định sẽ dễ bị mờ nhạt.
Nếu cứ đặt luôn file kế hoạch vào trong repository rồi thực thi kế hoạch đó để lưu lại các nội dung được áp dụng, thì ngữ cảnh được giữ lại khá tốt.
Nội dung này không chỉ giới hạn ở Claude mà có vẻ cũng có thể áp dụng một cách tổng quát cho các dịch vụ AI dựa trên CLI khác.
Ý kiến trên Hacker News
Điều thực sự cốt lõi không phải là “có lập kế hoạch hay không”, mà là buộc mô hình bộc lộ các giả định trước khi chúng bị đóng cứng thành mã
LLM thất bại không phải ở cú pháp mà ở những tiền đề vô hình như kiến trúc hay ràng buộc. Vì vậy, một bản kế hoạch được tài liệu hóa sẽ trở thành bề mặt để gỡ lỗi các tiền đề đó
Có ý nói rằng phải dùng những từ như “sâu”, “chi tiết” thì Claude mới không đọc hời hợt, nhưng thành thật mà nói tôi không trực quan hiểu nổi vì sao lại thế
Tôi dùng một cấu trúc gồm ba loại tài liệu và hai loại skill
Specs là tài liệu thiết kế tĩnh của dự án, Plans là kế hoạch thực thi do LLM tạo ra, còn file Working memory dùng để theo dõi trạng thái tiến độ.
Tôi dùng planner skill của Gemini Pro để tạo kế hoạch mới, rồi dùng implementer skill của Codex để thực hiện.
Làm vậy thì context nhẹ và tập trung hơn nên hiệu quả cao. Ngay cả với gói $20 của Codex/Gemini cũng đủ để làm việc khá nhanh
Ý tưởng để lại chú thích trực tiếp trong tài liệu kế hoạch khiến tôi thấy khá mới mẻ. Không biết có cách nào lưu riêng các chú thích đó hoặc quản lý để có thể xem lại sau này không
Có vài điểm trong cách tiếp cận này tôi không thích
Thứ nhất, kiểu big bang tạo toàn bộ mã trong một lần sẽ tạo ra một khối mã khổng lồ rất khó hiểu. Tôi nghĩ tốt hơn là lập kế hoạch và thực hiện theo từng bước.
Thứ hai, dù có đưa phản hồi nhưng lại không cập nhật knowledge base, điều này khá đáng tiếc. Cần ghi lại nguyên nhân lỗi để lần sau không lặp lại.
Cuối cùng là không thấy nhắc đến kiểm thử. Nên đưa vào ít nhất một phần của phát triển hướng kiểm thử (TDD). Tôi thấy rất thú vị khi AI-assisted development sẽ hòa nhập với những phương pháp luận này như thế nào
Workflow này thực ra là cách dùng Claude Code tiêu chuẩn mà Anthropic khuyến nghị. Nhưng nhược điểm là nếu kế hoạch không hoàn hảo thì phải làm lại từ đầu.
Vì thế tôi chia thiết kế → lập kế hoạch → thực thi thành nhiều đợt. Nếu chia thành các đơn vị kế hoạch dưới 1.500 dòng thì sẽ dễ kiểm soát độ phức tạp hơn.
Ứng dụng 30 nghìn LOC của tôi có tới 100 nghìn dòng kế hoạch. Không thể làm một lần được
Thay vì plan.md, tôi làm việc xoay quanh scaffold có thể chạy được và vòng lặp xác minh
Tôi đã xây dựng một hệ thống thanh toán thật tên là Kolibri Tickets cùng với AI. Cốt lõi không phải là để mô hình gõ code thật nhanh, mà là thiết kế vòng lặp xác minh
Làm như vậy thì không phải là “ảo giác về tốc độ” mà thực sự có thể triển khai nhanh hơn. Tài liệu Plan là một cách để duy trì trạng thái chia sẻ, còn harness có thể kiểm chứng cũng là một cách khác
Tôi dùng Claude Code để chuẩn bị bài giảng
Tôi viết ghi chú bài giảng bằng Quarto, rồi để Claude chuyển chúng thành slide Slidev. Sau đó tôi thêm chú thích vào slide như “cái này tách thành hai trang”, “thêm hình ở đây” để đưa phản hồi.
Kiểu phản hồi dựa trên chú thích này rất mạnh. Nó giúp ích nhiều cho khoảng cách token và việc giữ ngữ cảnh
# đổi phần này thành Xkiểu vậy?Đã có những công cụ như Kiro của Amazon, Antigravity của Google, Spec Kit của GitHub, OpenSpec cung cấp các chức năng kiểu này
Thất bại đắt giá nhất của AI-assisted coding không phải là lỗi cú pháp, mà là một phần thì chạy được nhưng lại phá hỏng toàn bộ hệ thống
Vì vậy tôi thêm brief.md ngay từ đầu để ghi rõ định nghĩa vấn đề, chỉ số mục tiêu, tiêu chí dừng tính năng, v.v. Làm vậy giúp giảm chi phí khi mục tiêu kinh doanh và triển khai kỹ thuật bị lệch nhau