Vì sao tôi chuyển sang Spec-Driven Development khi làm việc với AI agent

Tôi đang dùng AI agent để xây và vận hành hai website: blog bạn đang đọc và một website showroom B2B. Agent viết code, sửa lỗi, đo số liệu, soạn bài. Sau hơn mười năm làm phát triển phần mềm, tôi thấy cách làm việc này thay đổi rất nhiều thứ, nhưng không thay đổi một điều: phần mềm hỏng nhiều nhất ở chỗ các bên không cùng hiểu cần làm gì.

Đây là bài đầu tiên trong chuỗi về cách tôi hiểu và áp dụng AI vào vòng đời phát triển phần mềm (SDLC). Bài này trả lời câu hỏi mà nhiều người hỏi tôi nhất: vì sao tôi không “cứ để AI code”, mà chuyển sang Spec-Driven Development (SDD), phát triển dẫn dắt bởi đặc tả.

Vấn đề không nằm ở AI, mà ở chỗ không có spec

Khi làm việc với AI agent mà không có đặc tả (spec), code tự trở thành spec. Agent phải đoán phần còn thiếu, và nó đoán rất tự tin. Vấn đề hiện ra theo năm cách:

Mỗi bên giả định một kiểu. Trong bài giới thiệu Spec Kit của Microsoft, PM, backend, frontend và designer mỗi người hiểu một tính năng theo cách hợp lý của riêng mình, và chỉ phát hiện ra sau vài sprint. Thêm một AI agent vào nhóm là thêm một bên giả định nữa.
Agent mất ngữ cảnh. Quyết định đã chốt ở vài lượt chat trước bị quên, lý do đằng sau thiết kế biến mất theo, và lỗi đã sửa có thể quay lại (Jama Software).
Giả định không ghi lại thành lỗ hổng bảo mật. Báo cáo của Veracode (07/2025) thử hơn 100 mô hình trên 80 tác vụ: khoảng 45% tác vụ sinh ra lỗi thuộc OWASP Top 10, riêng lỗi XSS thì mô hình thất bại 86% số lần. Mô hình lớn hơn hay mới hơn cũng không an toàn hơn.
Phải giải thích lại mỗi phiên, và “cảm giác nhanh” không phải nhanh thật. Trong nghiên cứu của METR (2025), lập trình viên nhiều kinh nghiệm dùng công cụ AI lại mất thời gian hơn 19%, dù trước đó tin rằng sẽ nhanh hơn khoảng 24%. Nghiên cứu này không nói về spec, nhưng nhắc một điều quan trọng: phải đo, đừng tin cảm giác.
Không có chỗ để review trước khi code. Không có spec thì chỉ review được trên code, lúc đó mọi thay đổi đều đắt.

Tóm lại, SDD làm một việc đơn giản: đưa ý định ra khỏi lịch sử chat, vào một bản hợp đồng có version nằm cạnh code, được review trước khi agent viết dòng nào.

Spec-Driven Development là gì?

SDD đảo thứ tự quen thuộc. Thay vì “code trước, viết tài liệu sau (nếu còn thời gian)”, ta viết đặc tả hành vi trước: hệ thống phải làm gì, trong tình huống nào, kết quả ra sao. Các bên review và đồng ý trên đặc tả. Sau đó agent code theo đặc tả, và người kiểm tra code có khớp đặc tả không.

Spec ở đây không phải tài liệu Word dày trăm trang. Nó là file Markdown nằm ngay trong kho code, đi qua git như code, mỗi yêu cầu kèm vài tình huống dạng “KHI… THÌ…”. Người đọc được, agent cũng đọc được.

Vì sao tôi chọn OpenSpec

Có nhiều công cụ cho SDD. Hai cái tôi cân nhắc nhiều nhất là OpenSpec và Spec Kit của GitHub. Tôi chọn OpenSpec vì ba lý do:

Hợp cả dự án mới lẫn dự án đang chạy. OpenSpec tự mô tả là “built for brownfield not just greenfield”. Cả hai website của tôi đều là site WordPress đã chạy nhiều năm, không phải dự án làm lại từ đầu.
Ít tài liệu hơn. Spec Kit đi qua nhiều pha cho mỗi tính năng: nguyên tắc dự án (constitution), đặc tả, kế hoạch kỹ thuật kèm nghiên cứu và hợp đồng dữ liệu, rồi danh sách việc. Kỹ, nhưng nhiều giấy. OpenSpec gọn hơn: mỗi thay đổi là một thư mục gồm đề xuất, phần đặc tả thay đổi, thiết kế và danh sách việc.
Spec luôn là sự thật hiện tại. Mỗi thay đổi (change) chỉ ghi phần khác đi: thêm, sửa hay bỏ yêu cầu nào. Khi xong và lưu trữ (archive), phần đó được gộp vào bộ spec chung. Nhờ vậy, sau mỗi lần thay đổi, dự án lại có một bộ spec chuẩn mô tả đúng hệ thống đang chạy, và đó là nguồn sự thật duy nhất (single source of truth) của dự án.

Một backlog, một changelog, một cổng

Công cụ chỉ là một nửa. Nửa còn lại là quy trình bao quanh nó. Ở cả hai dự án, tôi dùng một mô hình ba phần:

1. Một cửa vào: backlog. Mọi việc, dù là yêu cầu mới, phát hiện từ số liệu hay sự cố, đều thành một dòng trong backlog, có cỡ công việc ước lượng và tiêu chí chấp nhận đo được. Không có việc nào làm “ngoài sổ”.

2. Một cổng rẽ: có cần OpenSpec change không? Không phải việc nào cũng cần hồ sơ đặc tả. Tôi chỉ mở một change khi việc đó:

tạo ra hành vi chưa từng có;
đổi hành vi đã có spec theo hướng phá vỡ cái cũ;
đủ lớn và người dùng nhìn thấy được;
cần duyệt thiết kế trước khi code;
đụng nhiều file và đổi hành vi.

Sửa lỗi cho khớp spec đã có, refactor, chỉnh nhỏ hay viết nội dung thì đi luồng thường. Lý do rất thực tế: hồ sơ đặc tả cũng tốn công và tốn token, làm cho mọi việc nhỏ thì hồ sơ đắt hơn chính việc sửa. Ngược lại, không có cổng thì việc lớn dễ bị làm tuỳ hứng.

3. Một cửa ra: changelog. Mọi thứ lên môi trường thật đều ghi đúng một dòng: đổi gì, người dùng thấy gì, hồ sơ nằm ở đâu, và chi phí thực tế so với ước lượng. Nếu có change thì cập nhật spec và lưu trữ. Nếu là sửa lỗi thì kèm báo cáo sự cố. Bài học đáng nhớ được ghi vào file hướng dẫn mà agent đọc trước mỗi phiên.

Vì sao phải là “một”? Vì mỗi câu hỏi chỉ nên có một nơi trả lời. Đang làm gì thì xem backlog. Hệ thống phải làm gì thì xem spec. Ngày đó đổi gì thì xem changelog. Không có hai sự thật song song, nên người mới hay agent mới vào dự án chỉ cần đọc vài file là nắm được.

Sau khi áp dụng: điều gì thay đổi, điều gì chưa

Tôi kỳ vọng SDD giúp giao hàng nhanh hơn, và nói thật luôn: token vẫn đốt khá nhiều. Viết spec, review spec, giữ spec cập nhật đều tốn. Nhưng thứ tôi nhận được lớn hơn tốc độ:

Ít phải giải thích lại. Khi spec đã được các bên đồng ý, đó là nguồn sự thật chung. Ai cần thông tin thì lấy từ spec, kể cả agent ở phiên làm việc tiếp theo.
Spec là thứ giúp các bên align. Tranh luận diễn ra trên vài dòng đặc tả, không phải trên một đống code đã viết xong.

Về sự cố: có lúc engineer chưa đánh giá hết rủi ro khi code với AI, nên vẫn có những sự cố chưa lường trước. Theo tôi, đó là do người làm ban đầu chưa quen làm việc với AI. Tôi tin rằng khi engineer đã làm chủ quy trình, sự cố sẽ ít đi, và việc giao hàng sẽ nhanh và gọn, như cách tôi đang làm với hai dự án của mình.

Về token: cần có phương pháp. Engineer quen quy trình sẽ giảm sai sót ngay từ đầu, và đó là cách tiết kiệm token nhiều nhất. Hiểu cách AI làm việc cũng giúp rất nhiều; Anthropic gần đây có một loạt khoá học về chủ đề này.

Điều vẫn còn khó

Phần khó nhìn thấy nhất là bảo mật. Số liệu của Veracode ở trên cho thấy đây không phải chuyện riêng của ai: code AI viết ra chạy được không có nghĩa là an toàn.

Phần còn lại, theo tôi, khó là vì chúng ta chưa hiểu hết AI: làm sao tiết kiệm token nhất, làm sao xây một quy trình và một đội agent hiệu quả, với vai trò phù hợp và mô hình phù hợp cho từng vai. Những thứ này cần thời gian thử và sai.

Nếu một founder hỏi tôi

“Đội của tôi có nên code với AI không?” Câu trả lời của tôi: bắt buộc phải code với AI agent, và đi theo quy trình OpenSpec. AI code, con người review.

Ở các bài tiếp theo trong chuỗi, tôi sẽ đi sâu từng phần: cổng phân loại hoạt động thế nào, chia vai cho một đội agent ra sao, và dùng ngân sách token như một công cụ ước lượng dự án.

What’s your Reaction?