Spec-Driven Development: Khi Đặc Tả Trở Thành Source Code

Posted on: 5/25/2026 2:18:07 PM

Bạn gõ "build cho tôi tính năng đăng nhập", agent phun ra 600 dòng code chạy được trong 5 phút — và rồi bạn mất 3 ngày để hiểu nó thực sự làm gì, vá những lỗ hổng bạn không hề yêu cầu, và phát hiện nó hiểu sai một nửa ý định của bạn. Đó là cái giá của vibe coding ở quy mô thật. Năm 2026, khi agent đã đủ giỏi để viết hàng nghìn dòng một lượt, nút thắt không còn là tốc độ sinh code mà là tốc độ truyền đạt ý định. Spec-Driven Development (SDD) là câu trả lời: đảo ngược dòng chảy, biến bản đặc tả — chứ không phải code — thành nguồn chân lý.

1. Vì sao "vibe coding" sụp đổ ở quy mô lớn

Vibe coding — gõ một prompt mơ hồ rồi để agent tự suy diễn — tuyệt vời cho prototype cuối tuần. Nhưng khi đưa vào codebase thật, nó để lộ một khuyết tật cấu trúc: ý định nằm trong đầu bạn, còn agent chỉ thấy vài câu chữ rời rạc bạn vừa gõ. Khoảng cách giữa "điều bạn muốn" và "điều bạn nói" chính là nơi bug, scope creep và nợ kỹ thuật sinh sôi.

Vấn đề càng trầm trọng khi agent ngày một mạnh. Một agent có thể vui vẻ sinh ra 600 dòng dựa trên một giả định sai ngay từ câu đầu tiên — và vì code chạy được, bạn không nhận ra cho đến lúc quá muộn. Đây là nghịch lý của năng suất: agent càng nhanh, sai lầm về ý định càng lan rộng trước khi có ai kịp phanh lại.

2. Spec-Driven Development là gì?

SDD đảo ngược quan hệ truyền thống giữa tài liệu và code. Trong lối làm cũ, code là chân lý còn tài liệu là thứ luôn lỗi thời theo sau. Trong SDD, một bản đặc tả có cấu trúc (thường là Markdown nằm trong repo) là nguồn chân lý, còn code là sản phẩm được sinh ra từ nó. Spec không phải bản nháp ném đi sau khi code xong — nó là tạo tác sống, được review, version, và là hợp đồng giữa con người và agent.

Khác biệt mấu chốt so với "viết tài liệu cho kỹ" nằm ở chỗ: spec được viết với độ chính xác đủ để một agent thực thi, và quy trình ép bạn tách bạch ba câu hỏi thường bị trộn lẫn trong vibe coding:

• CÁI GÌ & TẠI SAO — kết quả mong muốn, ranh giới phạm vi, tiêu chí thành công (pha Specify).
• NHƯ THẾ NÀO — quyết định kiến trúc, ngăn xếp công nghệ, ràng buộc (pha Plan).
• THỨ TỰ NÀO — chia nhỏ thành các đơn vị kiểm thử được, có thể giao cho agent (pha Tasks).

3. Quy trình bốn pha: Specify → Plan → Tasks → Implement

Đây là xương sống của SDD, được chuẩn hoá rõ nhất bởi GitHub Spec Kit qua bốn lệnh. Mỗi pha tạo ra một tạo tác mà con người review trước khi bước sang pha sau — đó chính là các checkpoint giám sát.

flowchart LR
    A[/specify/
CAI GI & TAI SAO] --> B[/plan/
NHU THE NAO]
    B --> C[/tasks/
THU TU NAO]
    C --> D[/implement/
Agent thuc thi]
    A -. review .-> A1{Dung y dinh?}
    B -. review .-> B1{Hop rang buoc?}
    C -. review .-> C1{Chia du nho?}
    D --> E[Code + Test]
    E -. doi chieu .-> A
    style A fill:#e94560,stroke:#fff,color:#fff
    style D fill:#16213e,stroke:#fff,color:#fff
    style E fill:#4CAF50,stroke:#fff,color:#fff

1. Specify — Mô tả bài toán theo ngôn ngữ nghiệp vụ: outcome, ai dùng, tiêu chí thành công, các trường hợp biên. Chưa nói gì về công nghệ.
2. Plan — Dịch spec thành quyết định kiến trúc: ngăn xếp, mô hình dữ liệu, điểm tích hợp, ràng buộc phi chức năng (bảo mật, hiệu năng).
3. Tasks — Băm kế hoạch thành các đầu việc nhỏ, độc lập, kiểm thử được. Không phải "làm authentication" mà là "tạo endpoint đăng ký user, validate định dạng email, trả 409 nếu trùng".
4. Implement — Agent code từng task trong khuôn khổ đã chốt. Vì mỗi task nhỏ và có tiêu chí rõ, output dễ kiểm tra và dễ sửa cục bộ.

4. "Hiến pháp" của dự án: ràng buộc bất biến

Spec Kit đưa ra một khái niệm rất đáng giá: constitution (hiến pháp) — tập nguyên tắc nền không đổi của dự án, được nạp vào mọi pha. Đây là nơi bạn ghi những thứ agent không bao giờ được vi phạm: "luôn viết test trước", "không gọi network trong tầng domain", "mọi API phải có phân trang", "tuân thủ GDPR cho dữ liệu cá nhân".

Khác với prompt rời rạc dễ bị quên giữa các lượt, hiến pháp là ràng buộc thường trực. Nó biến những quy ước ngầm trong đầu senior dev thành luật thành văn mà agent buộc phải tuân theo ở từng task.

# Constitution — Dự án Thanh toán

## Nguyên tắc bất biến
1. Mọi thay đổi schema DB phải kèm migration có thể rollback.
2. Tầng domain KHÔNG được phụ thuộc framework hay I/O.
3. Mọi số tiền dùng kiểu decimal, không bao giờ float.
4. Mọi endpoint ghi (write) phải idempotent qua Idempotency-Key.
5. Test trước, code sau. Không merge khi coverage giảm.

5. Một bản spec tốt gồm những gì?

Theo các hướng dẫn 2026 (Addy Osmani, Thoughtworks, Spec Kit), một spec đủ dùng cho agent cần định nghĩa sáu yếu tố. Thiếu yếu tố nào, agent sẽ "tự điền vào chỗ trống" — và đó là lúc nó đi chệch ý bạn.

6. Hệ sinh thái công cụ SDD 2026

SDD đã có một hệ công cụ trưởng thành, chia thành hai nhóm: static-spec (chốt yêu cầu trước rồi sinh code) và living-spec (giữ tài liệu đồng bộ với code khi agent làm việc). Dưới đây là các lựa chọn nổi bật.

7. SDD gặp Multi-Agent: Coordinator → Implementor → Verifier

Mẫu mạnh nhất nhưng ít được dùng trong SDD là không để agent tự chấm bài của chính nó. Khi spec đã chia task rạch ròi, ta có thể phân vai cho nhiều agent: một Coordinator đọc spec và giao việc, các Implementor làm từng task, và một Verifier độc lập đối chiếu kết quả với tiêu chí chấp nhận trước khi đánh dấu hoàn thành.

sequenceDiagram
    participant S as Spec + Tasks
    participant C as Coordinator
    participant I as Implementor Agents
    participant V as Verifier Agent
    participant H as Con nguoi
    S->>C: Danh sach task + tieu chi chap nhan
    C->>I: Giao task doc lap
    I->>V: Code + test cho tung task
    V->>V: Doi chieu voi spec
    alt Dat tieu chi
        V->>C: PASS, danh dau hoan thanh
    else Khong dat
        V->>I: FAIL + ly do cu the
        I->>V: Sua va nop lai
    end
    C->>H: Bao cao tien do theo spec

Vì mọi quyết định đều quy chiếu về spec, bất đồng giữa các agent được giải quyết bằng cách hỏi lại đặc tả chứ không phải đoán. Spec trở thành "trọng tài" chung — điều bất khả thi trong vibe coding khi mỗi prompt là một sự thật riêng.

8. Khi nào KHÔNG nên dùng spec

SDD không miễn phí: viết và review spec tốn thời gian trả trước. Áp nó lên mọi việc sẽ biến thành quan liêu. Dùng heuristic sau để quyết định:

flowchart TD
    A[Cong viec moi] --> B{Mo ho se gay hau qua dat?}
    B -- Co --> C{Nhieu nguoi/he thong
phu thuoc ket qua?}
    B -- Khong --> P[Prompt thang, bo qua spec]
    C -- Co --> S[Viet spec day du]
    C -- Khong --> D{Can lam lai nhieu lan?}
    D -- Co --> S
    D -- Khong --> M[Spec nhe: vai gach dau dong]
    style S fill:#e94560,stroke:#fff,color:#fff
    style P fill:#4CAF50,stroke:#fff,color:#fff
    style M fill:#2c3e50,stroke:#fff,color:#fff

Một bản vá CSS nhỏ, một script dùng một lần, một thử nghiệm bỏ đi — đừng spec. Một module thanh toán, một thay đổi schema dùng chung, một tính năng nhiều đội phụ thuộc — bắt buộc spec. SDD trao cho bạn quyền chọn mức formal hoá, thay vì luôn ở thái cực "vibe" hoặc thái cực "tài liệu 40 trang".

9. Góc nhìn Quản lý dự án: spec là khế ước, không phải thủ tục

SDD không chỉ là kỹ thuật — nó định hình lại cách một đội phối hợp với agent. Với Tech Lead và PM, spec mang lại ba thứ mà vibe coding phá huỷ:

• Truy vết ý định (traceability): mỗi dòng code truy ngược được về một task, mỗi task về một outcome trong spec. Khi ai đó hỏi "tại sao code làm thế này?", câu trả lời nằm trong repo, không phải trong một cửa sổ chat đã đóng.
• Review đúng tầng: thay vì review 600 dòng code đã sinh, bạn review spec — nơi sai một câu rẻ hơn sai một nghìn dòng. Đây là dịch chuyển kiểm soát chất lượng về thượng nguồn.
• Đơn vị giao việc cho agent: task trong SDD chính là "ticket" cho agent — ước lượng được, kiểm thử được, song song được. PM lập kế hoạch sprint cho một đội lai người + agent y như với một đội người.

10. Kết luận

Năm 2026, lợi thế không thuộc về đội "gõ prompt nhanh nhất", mà thuộc về đội truyền đạt ý định rõ ràng nhất cho những agent ngày càng mạnh. Spec-Driven Development trưởng thành nghĩa là:

• Coi spec là nguồn chân lý, code là sản phẩm sinh ra — không phải ngược lại.
• Tách bạch Specify → Plan → Tasks → Implement, review tại mỗi pha thay vì review code cuối cùng.
• Cố định nguyên tắc bằng constitution, băm việc thành task kiểm thử được kiểu TDD.
• Dùng Verifier tách khỏi Implementor để agent không tự chấm bài.
• Biết khi nào KHÔNG spec — spec là khoản đầu tư, không phải nghi thức.

Vibe coding hỏi "agent có viết được code không". Spec-driven hỏi một câu khó hơn và quan trọng hơn: "tôi có diễn đạt đủ rõ điều mình muốn để bất kỳ ai — người hay máy — đều xây đúng nó không". Câu hỏi đó vốn là cốt lõi của kỹ thuật phần mềm; agent chỉ làm nó trở nên cấp thiết hơn bao giờ hết.

Nguồn tham khảo

• GitHub — Spec Kit: Toolkit for Spec-Driven Development
• Kiro — Bring engineering rigor to agentic development
• Thoughtworks — Spec-driven development: unpacking a key new AI-assisted engineering practice
• Addy Osmani — How to write a good spec for AI agents
• MarkTechPost — Meet GitHub Spec Kit
• Towards Data Science — From Vibe Coding to Spec-Driven Development