Wavi Books · Kỹ nghệ phần mềm & Clean Code

Spec-Driven Development là gì? Đừng giao việc mơ hồ cho AI coding agent

Nguyễn Minh Trí · Biên tập chuyên môn Wavi Books

Spec-Driven Development là gì? Cách viết spec, plan, tasks và tiêu chí nghiệm thu để AI coding agent tạo phần mềm đúng yêu cầu, an toàn, dễ kiểm chứng.

## ‘Thêm đăng nhập Google, nhớ bảo mật’ — một câu có thể tạo ra cả tuần sửa lỗi

Tôi từng thấy nhiều yêu cầu phần mềm được giao đúng kiểu này: ‘Thêm đăng nhập Google, nhớ bảo mật, làm giống các app lớn’. Với một developer có kinh nghiệm, câu nói ấy mở ra hàng loạt câu hỏi. Tài khoản cũ ghép với tài khoản Google theo email hay bắt người dùng xác nhận? Nếu email Google đã tồn tại thì xử lý thế nào? Quyền truy cập nào được xin? Phiên đăng nhập sống bao lâu? Khi người dùng thu hồi quyền ở Google, hệ thống có vô hiệu hóa phiên hiện tại không?

AI coding agent không tự biết câu trả lời đúng của doanh nghiệp. Nó sẽ điền vào chỗ trống bằng phương án nghe có vẻ hợp lý. Code có thể chạy, giao diện có thể đẹp, unit test có thể xanh — nhưng sản phẩm vẫn sai. Vấn đề không hẳn nằm ở model. Vấn đề là chúng ta đã giao một ý định mơ hồ rồi mong nhận lại một quyết định kiến trúc chính xác.

Spec-Driven Development, thường viết tắt là SDD, xuất hiện để xử lý đúng khoảng trống này. Nói đơn giản: trước khi để AI viết code, team biến điều mình muốn thành những tài liệu đủ rõ để có thể lập kế hoạch, chia việc và nghiệm thu. Spec không phải bài văn dài để cất vào Google Drive. Nó là hợp đồng làm việc sống giữa Product, kỹ sư, tester và AI agent.

## Spec-Driven Development là gì?

Trong cách làm truyền thống, đặc tả thường đứng sau code: viết một bản PRD, bắt đầu triển khai, rồi tài liệu nhanh chóng lỗi thời. SDD đảo chiều quan hệ đó. Đặc tả nêu rõ sản phẩm phải làm gì và vì sao; kế hoạch kỹ thuật quyết định làm bằng cách nào; danh sách task biến kế hoạch thành các thay đổi có thể thực hiện; code và bài kiểm thử phải chứng minh rằng chúng đáp ứng đặc tả.

GitHub Spec Kit mô tả chuỗi làm việc cốt lõi là `Spec → Plan → Tasks → Implement`. Google Conductor cũng đưa nhận thức về dự án ra khỏi đoạn chat tạm thời và lưu vào các tệp Markdown có phiên bản trong repository. Điểm đáng chú ý không phải tên công cụ. Điểm đáng chú ý là ngữ cảnh quan trọng không còn biến mất khi đóng cửa sổ chat hoặc đổi từ agent này sang agent khác.

Một prompt trả lời câu hỏi ‘hãy làm gì ngay bây giờ’. Một spec tốt trả lời bốn câu hỏi lâu dài hơn: người dùng cần đạt kết quả gì, hệ thống phải hành xử ra sao, giới hạn nào không được vượt qua, và bằng chứng nào cho thấy công việc đã hoàn thành. Khi yêu cầu thay đổi, ta sửa spec, nhìn thấy lịch sử thay đổi và buộc kế hoạch đi theo sự thật mới.

## Vì sao prompt dài vẫn chưa chắc là spec tốt?

Nhiều người đối phó với AI viết sai bằng cách viết prompt ngày càng dài. Nhưng độ dài không tạo ra sự rõ ràng. Một prompt 2.000 chữ vẫn có thể thiếu đối tượng người dùng, ngoại lệ, tiêu chí hiệu năng hoặc cách xử lý dữ liệu nhạy cảm. Ngược lại, một spec ngắn nhưng có ví dụ, ranh giới và tiêu chí nghiệm thu thường hữu ích hơn.

Hãy lấy tính năng đăng nhập Google. ‘Dùng OAuth 2.0, lưu token an toàn’ chỉ là chỉ dẫn kỹ thuật chung. Spec cần nói rõ luồng người dùng mới, người dùng đã có tài khoản, trường hợp email không được Google xác minh, cách liên kết hoặc từ chối liên kết tài khoản, yêu cầu đăng xuất trên mọi thiết bị, dữ liệu nào được lưu và dữ liệu nào tuyệt đối không ghi vào log.

Đến đây nhiều bạn sẽ hỏi: có phải viết hết mọi chi tiết trước khi code? Không. Spec không nên đoán trước từng tên hàm hoặc khóa chặt một thư viện khi chưa cần thiết. Nó cần làm rõ hành vi quan sát được và các ràng buộc quan trọng. Những quyết định triển khai thuộc về plan; những thay đổi nhỏ, ít rủi ro có thể dùng spec rất gọn.

## Một spec đủ dùng cần có những gì?

### 1. Bối cảnh và kết quả người dùng

Đừng mở đầu bằng tên framework. Hãy nói ai đang gặp vấn đề gì và kết quả nào đáng giá. Ví dụ: ‘Người dùng đã có tài khoản bằng email cần đăng nhập nhanh bằng Google mà không tạo tài khoản trùng’. Một câu như vậy giúp Product, developer và AI cùng nhìn vào một đích.

### 2. Phạm vi và phần không làm

Câu ‘không làm trong phiên bản này’ cứu team khỏi rất nhiều code thừa. Nếu bản đầu chỉ hỗ trợ Google trên web, hãy ghi rõ chưa hỗ trợ Apple, mobile native và đăng nhập doanh nghiệp. AI agent đặc biệt dễ mở rộng quá tay khi một yêu cầu có nhiều cách diễn giải.

### 3. Luồng chính, ngoại lệ và trạng thái lỗi

Mô tả luồng bình thường thôi chưa đủ. Cần có tài khoản bị khóa, email trùng, người dùng hủy cấp quyền, nhà cung cấp OAuth timeout, callback bị dùng lại và phiên hết hạn. Ngoại lệ là nơi phần mềm production khác với một demo đẹp.

### 4. Tiêu chí nghiệm thu

Tiêu chí nghiệm thu, hay acceptance criteria, phải kiểm tra được. Thay vì viết ‘đăng nhập phải nhanh’, hãy dùng ‘95% lượt callback hoàn tất trong dưới 800 ms ở điều kiện tải đã nêu’. Thay vì ‘không tạo tài khoản trùng’, hãy chỉ rõ với cùng email đã xác minh, hệ thống yêu cầu xác nhận liên kết và không tự động ghi đè thông tin hồ sơ.

### 5. Ràng buộc phi chức năng

Đây là phần hay bị bỏ quên: bảo mật, quyền riêng tư, khả năng truy cập, hiệu năng, quan sát hệ thống, tương thích ngược và quy định lưu dữ liệu. Coding agent có thể tạo chức năng đúng nhưng vẫn làm lộ token trong log hoặc thêm một dependency không được phép.

### 6. Câu hỏi chưa chốt

Một spec trung thực nên có mục ‘chưa quyết định’. Che giấu sự mơ hồ không làm nó biến mất. Hãy giao các câu hỏi này cho đúng người: Product quyết định trải nghiệm, Security quyết định mức kiểm soát, kỹ sư quyết định giải pháp trong giới hạn đã thống nhất.

## Từ spec đến code: quy trình 5 bước cho team nhỏ

### Bước 1: Viết spec từ góc nhìn hành vi

Bắt đầu bằng user story, tình huống và kết quả. Dùng ví dụ cụ thể thay vì tính từ. ‘Dễ dùng’, ‘an toàn’, ‘scalable’ đều vô nghĩa nếu không có ngữ cảnh và ngưỡng kiểm chứng.

### Bước 2: Làm rõ trước khi lập kế hoạch

Yêu cầu AI liệt kê giả định, mâu thuẫn và câu hỏi còn thiếu. Người chịu trách nhiệm phải trả lời hoặc chấp nhận rủi ro. Đây là điểm con người tạo ra nhiều giá trị nhất: quyết định điều gì đúng với sản phẩm, không phải chọn hộ AI một tên biến.

### Bước 3: Tạo plan kỹ thuật

Plan nối hành vi với hệ thống hiện có: module nào thay đổi, dữ liệu nào được thêm, API nào bị ảnh hưởng, chiến lược migration và rollback ra sao, test ở tầng nào. Plan tốt cũng nêu những phương án đã loại và lý do loại. Nếu không, agent sau có thể lặp lại đúng ngõ cụt cũ.

### Bước 4: Chia thành task có thể kiểm tra

Mỗi task nên tạo ra một kết quả nhỏ và có điểm dừng rõ: migration, domain logic, API, giao diện, telemetry, kiểm thử, tài liệu vận hành. Task ‘làm toàn bộ login Google’ quá lớn; agent dễ sửa nhiều vùng cùng lúc và khiến review mất kiểm soát.

### Bước 5: Triển khai trong ranh giới và đối chiếu lại spec

Coding agent cần quyền vừa đủ, môi trường tách biệt, log hoạt động và điểm duyệt cho thao tác rủi ro. OpenAI mô tả cách sandbox, approval, cấu hình quản trị và telemetry được dùng để giữ coding agent trong biên kỹ thuật rõ ràng. Sau mỗi task, đừng chỉ hỏi ‘test có pass không’; hãy hỏi ‘thay đổi này chứng minh tiêu chí nào trong spec?’

## Ví dụ rút gọn: spec cho tính năng thử lại thanh toán

**Mục tiêu:** Người mua không bị trừ tiền hai lần khi mạng chập chờn và ứng dụng gửi lại yêu cầu thanh toán.

**Luồng chính:** Client tạo một idempotency key cho mỗi ý định thanh toán. Server lưu kết quả theo key. Yêu cầu lặp lại cùng key và cùng payload nhận lại kết quả cũ; cùng key nhưng payload khác bị từ chối và ghi cảnh báo.

**Ngoại lệ:** Gateway timeout sau khi đã trừ tiền; callback đến trước response; người dùng bấm thanh toán nhiều lần; worker xử lý lại message; dữ liệu idempotency hết hạn.

**Tiêu chí nghiệm thu:** Cùng key không tạo quá một giao dịch; mọi trạng thái không chắc chắn được đối soát trước khi cho phép thử lại; log không chứa dữ liệu thẻ; dashboard theo dõi tỷ lệ retry, conflict và giao dịch pending.

Một đoạn như vậy chưa đủ để triển khai toàn bộ hệ thống thanh toán, nhưng nó đã buộc team nói về những điểm dễ gây thiệt hại thật. AI agent có thể từ đó đề xuất schema, state machine và bài kiểm thử. Con người vẫn phải kiểm tra phương án với gateway, dữ liệu production và quy định của doanh nghiệp.

## Khi SDD biến thành thủ tục, hãy dừng lại

Không phải thay một màu nút cũng cần bảy tệp tài liệu. Chi phí viết và giữ spec phải tương xứng với độ mơ hồ, phạm vi ảnh hưởng và rủi ro. Một chỉnh sửa copy có thể dùng vài acceptance criteria ngay trong issue. Một thay đổi liên quan thanh toán, phân quyền hoặc dữ liệu cá nhân cần đặc tả và kế hoạch nghiêm túc hơn.

Dấu hiệu SDD đang đi sai là tài liệu dài nhưng không ai dùng để review; spec chép lại code sau khi code đã xong; mọi câu hỏi đều bị đẩy sang AI; hoặc team coi template là mục tiêu. Mục tiêu thật là tạo một chuỗi quyết định có thể truy vết. Nếu tài liệu không giúp phát hiện sai sớm hơn, hãy rút gọn hoặc đổi cách viết.

Spec cũng không tự động trở thành sự thật. GitHub Spec Kit để team tự chọn vòng đời của `spec.md`, `plan.md` và `tasks.md` khi yêu cầu thay đổi. Vì thế cần quy ước rõ: tài liệu nào tồn tại lâu dài, tài liệu nào chỉ dùng trong một feature, ai chịu trách nhiệm cập nhật và khi nào code được xem là lệch spec.

## Checklist trước khi giao feature cho AI coding agent

- Người dùng và kết quả mong muốn đã rõ chưa? - Phạm vi không làm đã được ghi chưa? - Có ít nhất một luồng chính và các ngoại lệ nguy hiểm chưa? - Tiêu chí nghiệm thu có thể đo hoặc kiểm tra không? - Ràng buộc bảo mật, dữ liệu, hiệu năng và tương thích đã đủ chưa? - Giả định nào vẫn chưa được xác nhận? - Plan có migration, rollback và chiến lược test không? - Task có đủ nhỏ để con người review không? - Agent được cấp quyền vừa đủ và có log hoạt động không? - Sau triển khai, mỗi tiêu chí trong spec có bằng chứng tương ứng không?

## AI viết code nhanh hơn; trách nhiệm kỹ sư không vì thế mà nhẹ đi

Spec-Driven Development không đảm bảo AI sẽ không mắc lỗi. Nó làm một việc thực tế hơn: kéo các quyết định quan trọng ra khỏi phần đoán mò, biến chúng thành vật thể có thể đọc, tranh luận, lưu phiên bản và kiểm chứng. Khi code được tạo nhanh hơn, chất lượng câu hỏi, ranh giới và tiêu chí nghiệm thu càng trở nên đắt giá.

Nếu muốn đi sâu vào kỷ luật viết phần mềm, [Clean Code bản tiếng Việt](/sach/clean-code-robert-c-martin-2026) giúp bạn nhìn rõ cấu trúc của code có thể đọc và bảo trì; [The Clean Coder bản tiếng Việt](/sach/the-clean-coder-robert-c-martin-2026) bàn về trách nhiệm nghề nghiệp khi nhận cam kết; còn [AI Agents in Action bản tiếng Việt](/sach/ai-agents-in-action-michael-lanham-2026) mở rộng sang cách xây agent, công cụ, bộ nhớ và workflow.

Wavi Books phụ trách biên phiên dịch, dữ liệu sản phẩm và nội dung chuyên môn cho sách lập trình tiếng Việt. 89ebook là đối tác thương mại độc quyền phân phối sách tiếng Việt của Wavi Books tại Việt Nam trong thời điểm hiện tại. Với developer Việt Nam, giá trị của SDD không nằm ở việc dùng thêm một công cụ mới. Nó nằm ở thói quen rất cũ nhưng thường bị bỏ qua: hiểu đúng điều cần xây trước khi viết dòng code đầu tiên.