Quy trình làm dự án với agent: lập kế hoạch, làm, kiểm

Bài này dựa trên trang best practices và các trang liên quan trong tài liệu Claude Code, đọc ngày 11/11/2026. Ví dụ dùng Claude Code vì tài liệu của nó viết cụ thể nhất, nhưng quy trình áp dụng được cho các công cụ agent lập trình khác. Nếu chưa rõ agent là gì, đọc trước AI agent là gì.

Vì sao cần một quy trình?

Agent lập trình rất giỏi đọc code. Theo tài liệu Claude Code, agent bắt đầu mỗi việc bằng việc đọc kho mã và thường tự tìm ra cấu trúc thư mục, quy ước, công cụ test của dự án nhanh hơn bạn giải thích. Nhưng có hai thứ nó không thể tự biết:

• Bạn muốn gì. Tài liệu ghi rằng khi một phiên không như ý, gần như luôn là vì agent làm ra thứ khác với điều bạn nghĩ, do thiếu thông tin không có trong kho mã: một quyết định của nhóm, một quy trình chỉ có trong đầu một người.
• Khi nào thật sự xong. Tài liệu viết: agent dừng khi công việc trông như đã xong. Nếu không có gì để chạy và cho biết việc đã xong thật chưa, "trông như xong" là tất cả những gì nó dựa vào, và bạn trở thành bộ test.

Quy trình bốn bước dưới đây nhằm đúng hai lỗ hổng đó: bước 1 và 2 lo phần "muốn gì", bước 3 và 4 lo phần "xong thật chưa".

Bước 0: chuẩn bị chỗ làm việc

Trước khi giao việc, ba điều nên có sẵn:

1. Một nhánh git sạch. Commit hết thay đổi đang dở, tạo nhánh mới cho việc này. Nếu agent làm hỏng, bạn bỏ nhánh đi. Tài liệu Claude Code nhắc rằng điểm khôi phục (checkpoint) của nó chỉ áp dụng cho tệp agent sửa bằng công cụ sửa tệp, tệp bị thay đổi bởi lệnh shell thì không được khôi phục, và checkpoint làm việc cùng git chứ không thay git.
2. Lệnh chạy test trong tệp hướng dẫn dự án. Tài liệu nói thẳng: nếu kho đã có test, dòng hữu ích nhất trong CLAUDE.md là lệnh chạy test. Xem viết hướng dẫn dự án cho AI.
3. Một việc vừa cỡ. "Sửa lỗi giảm giá sai ở giỏ hàng" vừa cỡ; "làm lại cả trang thanh toán" thì nên chia nhỏ trước.

Bước 1: nói rõ việc và thế nào là xong

Một yêu cầu cụ thể đưa cho agent thông tin nó không tự có. Tài liệu khuyên nêu tên tệp, mô tả triệu chứng và nói "đã sửa" trông thế nào ngay từ đầu, để đỡ một vòng sửa lại sau đó.

Hai lưu ý từ tài liệu đáng biết:

• Đưa thẳng thứ agent cần thay vì mô tả nó: nhắc tệp bằng @đường/dẫn, dán ảnh chụp giao diện hay lỗi, hoặc chuyển đầu ra của một lệnh vào cho agent đọc.
• Nói về phạm vi. Tài liệu cho biết agent thường hiểu yêu cầu theo hướng thận trọng và làm bản nhỏ nhất thỏa yêu cầu, vì nó không biết bạn mong bao nhiêu. Nếu muốn bản đầy đủ (xử lý trạng thái trống, trạng thái lỗi, các trường hợp biên), hãy nói rõ.

Khi chính bạn chưa rõ mình muốn gì, tài liệu gợi ý đảo vai: nhờ agent phỏng vấn bạn cho tới khi đủ để viết bản đặc tả, rồi ghi vào một tệp như SPEC.md. Sau đó mở phiên mới để làm theo tệp đó, để việc xây dựng bắt đầu với ngữ cảnh sạch và một định nghĩa "xong" được viết ra. Ví dụ yêu cầu: "Tôi muốn thêm giới hạn số lần gọi cho API nhưng chưa nghĩ kỹ. Hãy phỏng vấn tôi cho tới khi đủ để viết đặc tả, rồi ghi vào SPEC.md."

Bước 2: để agent lập kế hoạch trước khi sửa

Với việc có nhiều cách làm hoặc đụng nhiều tệp, hãy để agent khảo sát và đề xuất kế hoạch trước khi sửa. Claude Code có chế độ lập kế hoạch (plan mode): theo tài liệu, ở chế độ này agent khảo sát và đề xuất kế hoạch mà không sửa tệp mã nguồn.

Đọc kế hoạch như đọc đề xuất của một đồng nghiệp: nó định sửa những tệp nào, theo thứ tự nào, kiểm bằng cách nào, có đụng vào chỗ bạn không muốn đụng không. Sửa kế hoạch lúc này rẻ hơn rất nhiều so với sửa code sau. Với việc nhỏ và rõ (đổi tên một biến, sửa một lỗi có test tái hiện), bạn có thể bỏ qua bước này.

Anthropic, trong bài "Building effective agents", nêu ba nguyên tắc khi làm việc với agent, trong đó có nguyên tắc làm cho các bước lập kế hoạch của agent hiện ra rõ ràng. Một kế hoạch được viết ra là cách đơn giản nhất để bạn thấy agent định làm gì trước khi nó làm.

Bước 3: làm cùng một phép kiểm đạt hay không đạt

Đây là bước quan trọng nhất. Tài liệu khuyên: hãy cho agent một thứ nó chạy được và trả về đạt hay không đạt. Khi có nó, agent tự khép vòng: sửa, chạy kiểm, nếu hỏng thì đọc đầu ra và sửa trước khi chạy lại. Phép kiểm có thể là tệp test, mã thoát của bước build, công cụ kiểm lỗi định dạng, một script so đầu ra với tệp mẫu, hay ảnh chụp trình duyệt đặt cạnh bản thiết kế.

Mức chặt của phép kiểm do bạn chọn, theo tài liệu có bốn mức:

Một cổng kiểm tra dùng chung

Đoạn Python dưới đây là một "cổng kiểm tra" nhỏ: chạy bộ test của dự án bằng unittest có sẵn trong Python, in "Đạt" và thoát mã 0 nếu mọi test qua, còn không thì in tóm tắt lỗi ra stderr và thoát mã 2. Bạn chạy được bằng tay sau khi agent báo xong, hoặc đăng ký làm hook Stop: theo tài liệu tham chiếu hooks, với sự kiện Stop, mã thoát 2 ngăn Claude dừng và cho cuộc trò chuyện tiếp tục, nên Claude đọc lỗi và sửa tiếp (cách đăng ký hook xem bài hooks cho AI).

"""Cổng kiểm tra: chạy bộ test của dự án và trả về đạt hoặc không đạt.

Dùng được theo hai cách:
- Chạy tay sau khi agent báo xong: python cong_kiem_tra.py <thư mục dự án>
- Làm hook Stop của Claude Code: thoát mã 2 khi test hỏng, nên Claude chưa dừng mà đọc lỗi và sửa tiếp.
Dùng unittest có sẵn trong Python để không phải cài thêm gì.
"""
import subprocess
import sys


def chay_test(thu_muc):
    """Trả về (đạt?, tóm tắt kết quả)."""
    p = subprocess.run([sys.executable, "-m", "unittest", "discover", "-q"], cwd=thu_muc,
                       capture_output=True, text=True, encoding="utf-8", timeout=300)
    dong = [d for d in p.stderr.strip().splitlines() if d.strip()]
    tom_tat = dong[-1] if dong else "không có kết quả"
    if p.returncode == 0:
        return True, tom_tat
    loi = [d for d in dong if d.startswith(("FAIL:", "ERROR:", "AssertionError"))]
    return False, "; ".join(loi[:5] + [tom_tat])


if __name__ == "__main__":
    dat, tom_tat = chay_test(sys.argv[1] if len(sys.argv) > 1 else ".")
    if dat:
        print("Đạt:", tom_tat)
        sys.exit(0)
    print("Chưa đạt, hãy sửa rồi chạy lại test:", tom_tat, file=sys.stderr)
    sys.exit(2)

Thử trên một dự án nhỏ có hàm giam_gia viết sai (quên chia cho 100) và hai bài test:

Chưa đạt, hãy sửa rồi chạy lại test: FAIL: test_giam_10 (test_gia.T.test_giam_10); AssertionError: -1800 != 180; FAILED (failures=1)

Mã thoát là 2. Sau khi sửa thành gia - gia * phan_tram / 100, chạy lại được Đạt: OK với mã thoát 0. Dòng lỗi đủ cụ thể để agent biết test nào hỏng, giá trị mong đợi và giá trị thật, nên nó sửa đúng chỗ thay vì đoán.

Một điểm thiết kế: dự án chưa có test nào thì unittest báo "NO TESTS RAN" và cổng coi là chưa đạt. Không có test thì không có bằng chứng là xong. Nếu dùng làm hook Stop, chỉ bật cho dự án đã có test, vì tài liệu có mục riêng về trường hợp hook Stop chặn quá nhiều lần.

Cẩn thận với một kiểu lách: agent có thể "sửa" bài test cho khớp với code thay vì sửa code. Khi xem thay đổi, hãy để ý xem test có bị sửa không, và nếu có thì sửa có hợp lý không. Bài kiểm chứng việc AI làm nói kỹ về cách xem lại.

Bước 4: xem bằng chứng rồi mới commit

Tài liệu khuyên dù dùng cách kiểm nào, hãy xin bằng chứng: lệnh agent đã chạy và đầu ra của nó, hoặc ảnh chụp. Câu "mọi test đã qua" không kèm đầu ra cho bạn biết rất ít; còn đọc đầu ra thì nhanh hơn tự chạy lại. Với một phiên bạn không ngồi xem, bằng chứng là thứ duy nhất bạn có.

Muốn xem lại theo đặc tả thay vì tìm lỗi chung chung, tài liệu gợi ý tự viết yêu cầu xem lại, ví dụ: dùng một subagent xem lại thay đổi so với SPEC.md, kiểm mọi yêu cầu đã làm và các trường hợp biên có test, chỉ báo lỗi ảnh hưởng tính đúng và bỏ qua chuyện phong cách. Tài liệu giải thích lý do của câu cuối: người xem lại được giao tìm lỗi thì kiểu gì cũng tìm ra "một cái gì đó", và sửa mọi góp ý sẽ sinh thêm lớp trừu tượng và test cho những trường hợp không thể xảy ra.

Sau đó commit, với lời mô tả nói rõ thay đổi gì và vì sao. Nếu làm việc nhóm, mở pull request để đồng đội xem (xem issue và pull request).

Lái phiên làm việc: khi nào dừng, khi nào bắt đầu lại

Tài liệu có một lời khuyên ngắn gọn: xem phút đầu tiên, nhấn Esc ngay khi agent đi lệch, và sau hai lần sửa không được thì /clear rồi viết một yêu cầu tốt hơn thay vì sửa lần thứ ba. Ba công cụ cần nhớ:

• Esc dừng agent giữa chừng mà giữ những gì đã làm, để bạn chỉnh hướng.
• /rewind (hoặc nhấn Esc hai lần khi ô nhập trống) mở menu quay lại: đưa code, cuộc trò chuyện hoặc cả hai về một lời nhắn trước. Nhờ vậy thử cách táo bạo trước rồi quay lại nếu không ổn là việc ít rủi ro.
• /clear bắt đầu lại. Theo tài liệu, sau hai lần sửa vẫn sai, lần sửa thứ ba chủ yếu thêm vào một cuộc trò chuyện đã chứa hai lần thất bại mà agent cứ phải đọc lại; xóa rồi viết một yêu cầu gộp những gì bạn đã học được hầu như luôn tốt hơn.

Tài liệu cũng khuyên /clear giữa các việc khác nhau, vì ngữ cảnh tập trung cho câu trả lời tốt hơn và tốn ít hơn. Xem thêm chi phí khi dùng agent.

Những lời khuyên cũ có thể bỏ

Tài liệu Claude Code có một bảng các lời khuyên từng đúng nhưng nay không còn cần, vì mô hình đã tốt lên. Một vài mục đáng biết:

• Viết HOA hay thêm "QUAN TRỌNG" vào chỉ dẫn: mô hình hiện tại làm theo câu viết bình thường; nhấn mạnh quá mức chỉ làm nó áp dụng quy tắc quá tay. Quy tắc không được phép sai thì chuyển thành hook hay quy tắc chặn.
• "Suy nghĩ thật kỹ", "làm thật cẩn thận" trong yêu cầu: đó chỉ là chữ thường, mức nỗ lực mới là nút điều khiển thật.
• "Cứ làm tiếp tới khi xong, đừng lười": mô hình hiện tại thường tự làm hết việc đã thống nhất; những câu như vậy dễ gây làm thừa. Cho agent một phép kiểm để qua là chuyện khác, và vẫn nên làm.
• Mô tả kiến trúc và cấu trúc thư mục trong CLAUDE.md: agent tự đọc kho mã; chỉ ghi điều không có trong đó.

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

Học tiếp

• Muốn xem lại việc AI làm một cách có hệ thống, đọc kiểm chứng việc AI làm.
• Muốn ghi lệnh test và quy ước cho agent đọc mỗi phiên, đọc viết hướng dẫn dự án cho AI.
• Muốn biến phép kiểm thành luật tự động, đọc hooks cho AI.

Nếu bạn muốn học lập trình và cách làm việc với AI bài bản cùng giảng viên, tham khảo khóa học AI của Big-O Coding.

Nguồn tham khảo

• Tài liệu Claude Code: Best practices
• Tài liệu Claude Code: How Claude Code works
• Tài liệu Claude Code: Hooks reference
• Anthropic: Building effective agents (19/12/2024)