🗺️ MOC - Spec-Driven Development

36 dot notes tách từ ebook của Nguyễn Thế Huy. Sách kể những câu chuyện rất thật khi áp dụng Spec-Driven Development (SDD) - phương pháp làm việc với AI đang phổ biến. Có thể đọc tuần tự, nhưng không bắt buộc; sau đó dùng từng note như tài liệu tra cứu độc lập.

Tư tưởng xuyên suốt của cả cuốn sách: Khi AI viết code rất nhanh, câu hỏi lớn nhất không còn là “viết code thế nào” mà là “viết đúng cái gì?“. Spec là nơi con người thống nhất ý định TRƯỚC khi tốc độ của AI khuếch đại mọi thứ. Spec rõ → AI giúp đi nhanh hơn; spec mơ hồ → AI vẫn đi nhanh, chỉ là nhanh về sai hướng.

🧭 Lộ trình học đề xuất (7 chương → 6 level)

Level 0 - Vì sao cần SDD (Chương 1) ⭐ đọc trước tiên

Hiểu vấn đề trước khi hiểu giải pháp. Không nắm level này thì SDD chỉ là “quy trình vì quy trình”.

Vibe Coding - “chat thử rồi merge”: nhanh tuần 1, nguy hiểm tháng 3. Bắt đầu từ đây!
Code không có ngữ cảnh - nợ kỹ thuật mới: code sạch, test xanh, nhưng “vì sao đoạn này tồn tại?” → không ai biết
Spec-Driven Development - định nghĩa cốt lõi: sửa spec trước, sửa code sau ⭐⭐
SDD không phải Waterfall - gỡ hiểu nhầm đầu tiên và lớn nhất

Level 1 - Spec thật ra là gì (Chương 2) 🔥 phần nền tảng

Spec không phải một đống tài liệu. Nó có 4 tầng, mỗi tầng trả lời một câu hỏi.

Bốn tầng của yêu cầu - bản đồ 4 tầng, đọc đầu tiên trong level này ⭐⭐
Business Requirement (BR) - tầng 1: vì sao làm? (Goal, Metric, Out of Scope)
Use Case (UC) - tầng 2: ai làm gì? (đơn vị làm việc chính của SDD)
Entity Model - tầng 3: nói về những danh từ nào?
Acceptance Criteria - tầng 4: biết đúng bằng cách nào? (nối spec sang test) ⭐⭐

DDD & Hexagonal - kiến trúc cũ bỗng hợp thời AI: 10. Ubiquitous Language - business + dev + AI dùng chung một ngôn ngữ 11. Bounded Context - một từ, một nghĩa, trong một context (tránh god object) 12. Hexagonal Architecture - tách lõi nghiệp vụ khỏi DB/HTTP/provider ⭐ 13. Port và Adapter - vùng lý tưởng để giao cho AI 14. Spec hiện tại và Spec thay đổi - tách baseline (specs/) khỏi đề xuất (changes/)

Level 2 - Sáu nguyên tắc Spec-Driven (Chương 3) ⭐ phần cốt lõi

Đọc Sáu nguyên tắc Spec-Driven trước để có bức tranh tổng, rồi đào từng nguyên tắc. Mỗi note có một tình huống thật + bài học + cách áp dụng.

Sáu nguyên tắc Spec-Driven - bản đồ 6 nguyên tắc + 6 câu hỏi mang về team
Requirements-Driven - 1: spec dẫn dắt code, không phải ngược lại
AI-Assisted - 2: AI làm phần lặp lại, con người giữ phần quyết định
Iterative Improvement - 3: spec không cần hoàn hảo ngày đầu
Test-Protected - 4: test là hàng rào để AI viết lại mà không lệch hành vi
Stakeholder-Centric - 5: spec chỉ có giá trị khi người chịu hậu quả đã đọc
Traceable - 6: từ code → spec → test → requirement

Level 3 - SDD chạy ngoài đời (Chương 4 & 5)

Đọc cái nào trước cũng được, tùy bạn đang đứng ở đâu.

🌱 Greenfield - dự án mới từ con số không: 22. Greenfield với SDD - nhật ký 5 ngày, 3 người, một HR tool (+ checklist + 4 lỗi hay gặp)

🏚️ Brownfield - legacy 5 năm không doc: 23. Brownfield với SDD - chiến lược 5 bước cho billing-engine 320k dòng ⭐ 24. Reverse Engineering từ code - đào spec ngược từ code/DB/log (bước 1-2) 25. Characterization Test - ảnh chụp hành vi hiện tại làm lưới an toàn (bước 4) 26. Big Bang Rewrite - cái bẫy: rewrite khi chưa có baseline 27. Module nóng ấm lạnh - đầu tư spec theo nhiệt độ, đừng ép 100%

Level 4 - Vận hành team hằng ngày (Chương 6)

Những quy ước nhỏ được giữ đều để SDD không thành phong trào ngắn hạn.

Vai trò trong SDD - PO/BA, Tech Lead, Dev, EM, QA - ai làm gì
Cấu trúc Repo SDD - spec / code / test soi chiếu được nhau
Code Review trong SDD - 5 quy tắc: code có khớp spec không?
Chỉ số đo SDD - Spec Coverage, AC Coverage, Regen Success Rate, Trace Ratio
Lộ trình 30-60-90 ngày - thử nhỏ → mở rộng → quyết định dựa trên dữ liệu

Level 5 - Ranh giới, hiểu nhầm & công cụ (Phần Kết + Phụ lục)

Khi nào không nên dùng SDD - quan trọng không kém hiểu phương pháp
Những hiểu nhầm về SDD - gỡ 5 hiểu nhầm: waterfall, chậm, chỉ cho enterprise, bắt buộc DDD/Hexagonal, AI giỏi khỏi cần spec
Vai trò Engineer thời AI - dev/PO/BA/Tech Lead/QA sẽ đổi ra sao khi AI gõ code nhanh hơn người
Công cụ SDD - Spec Kit, OpenSpec, AIUP + git convention + sách nên đọc

🚀 Lối vào nhanh theo vấn đề (tra cứu khi gặp chuyện)

Bạn đang gặp gì?	Đọc note
AI viết code nhanh nhưng vài tháng sau sửa gì cũng chậm	Vibe Coding → Code không có ngữ cảnh
Không ai nhớ vì sao một field/rule tồn tại	Requirements-Driven → Traceable
PO và dev ngầm hiểu khác nhau (“QR 5 phút hay 15 phút?“)	Bốn tầng của yêu cầu → Acceptance Criteria
AI đoán sai rule nghiệp vụ, team mất tiền	AI-Assisted → Stakeholder-Centric
Code AI sinh dính chặt vào Stripe/Postgres, khó đổi	Hexagonal Architecture → Port và Adapter
Cùng một từ “Order” có nhiều nghĩa, class phình to	Bounded Context → Ubiquitous Language
Refactor mà sợ phá vỡ hành vi	Test-Protected → Characterization Test
3h sáng production lỗi, không biết bắt đầu từ đâu	Traceable → Cấu trúc Repo SDD
Thừa kế legacy 5 năm không doc	Brownfield với SDD → Reverse Engineering từ code
Muốn dùng AI viết lại toàn bộ file cũ	Big Bang Rewrite (đừng!) → Module nóng ấm lạnh
Bắt đầu dự án mới, muốn làm đúng từ đầu	Greenfield với SDD
Muốn thử SDD cho team nhưng không biết bắt đầu	Lộ trình 30-60-90 ngày
Sếp hỏi “team dùng AI hiệu quả chưa?”	Chỉ số đo SDD
Không chắc dự án này có đáng làm SDD không	Khi nào không nên dùng SDD
Bị phản đối “AI giỏi rồi cần gì spec” / “SDD là waterfall”	Những hiểu nhầm về SDD
Lo vai trò dev/QA của mình thay đổi thế nào khi có AI	Vai trò Engineer thời AI

🧠 6 câu thần chú rút gọn cả cuốn sách

“Sửa spec trước, rồi mới sửa code” - Spec-Driven Development
“AI càng giỏi viết code, câu hỏi ‘viết đúng cái gì?’ càng quan trọng” - AI-Assisted
“Không có Acceptance Criteria thì không bắt đầu code” - Acceptance Criteria
“Test là hàng rào để AI được viết lại mà không lệch hành vi” - Test-Protected
“SDD trên legacy không phải để trả hết nợ, mà để dừng vay thêm” - Brownfield với SDD
“Spec mơ hồ → AI vẫn đi nhanh, chỉ là nhanh về sai hướng” - Vibe Coding

👥 Đọc theo vai trò

Dev / Tech Lead: Level 0 → 1 → 2 → chọn Greenfield với SDD hoặc Brownfield với SDD theo tình huống của bạn.
Engineering Manager: Spec-Driven Development → Chỉ số đo SDD → Lộ trình 30-60-90 ngày → Vai trò trong SDD.
PO / BA / non-tech: Vibe Coding → Bốn tầng của yêu cầu → Business Requirement (BR) → Acceptance Criteria → Stakeholder-Centric. Không cần biết code; việc quan trọng nhất là đọc spec và hỏi “Nếu A thì sao? B có được tính không?”

🗺️ Spec-Driven Development - Reading Map

Sơ đồ cấu trúc & thứ tự đọc ebook của Nguyễn Thế Huy. Có thể đọc tuần tự, nhưng không bắt buộc; sau đó dùng từng phần như tài liệu tra cứu.

Tổng quan: thứ tự đọc 6 level (7 chương)

flowchart TD
    Start(["📖 Bắt đầu"]) --> P0

    subgraph P0["0️⃣ VÌ SAO CẦN SDD (Chương 1)"]
        direction TB
        A0["Vibe Coding<br/>(nhanh tuần 1, nguy hiểm tháng 3)"]
        A1["Code không có ngữ cảnh<br/>(nợ kỹ thuật mới)"]
        A2["Spec-Driven Development<br/>(sửa spec trước, sửa code sau)"]
        A3["SDD không phải Waterfall"]
        A0 --> A1 --> A2 --> A3
    end

    P0 --> P1

    subgraph P1["1️⃣ SPEC LÀ GÌ + DDD/HEXAGON (Chương 2) 🔥"]
        direction TB
        B0["Bốn tầng của yêu cầu<br/>BR - UC - Entity - AC"]
        B1["Ubiquitous Language + Bounded Context"]
        B2["Hexagonal Architecture + Port/Adapter"]
        B3["Spec hiện tại và Spec thay đổi<br/>(specs/ vs changes/)"]
        B0 --> B1 --> B2 --> B3
    end

    P1 --> P2

    subgraph P2["2️⃣ SÁU NGUYÊN TẮC (Chương 3) ⭐"]
        direction TB
        C0["Requirements-Driven · AI-Assisted"]
        C1["Iterative Improvement · Test-Protected"]
        C2["Stakeholder-Centric · Traceable"]
        C0 --> C1 --> C2
    end

    P2 --> P3

    subgraph P3["3️⃣ SDD CHẠY NGOÀI ĐỜI (Chương 4 & 5)"]
        direction TB
        D1["🌱 Greenfield<br/>(nhật ký 5 ngày)"]
        D2["🏚️ Brownfield<br/>(legacy 5 năm, chiến lược 5 bước)"]
        D3["Reverse Engineering · Characterization Test<br/>Big Bang Rewrite · Module nóng ấm lạnh"]
        D1 --> D2 --> D3
    end

    P3 --> P4

    subgraph P4["4️⃣ VẬN HÀNH TEAM (Chương 6)"]
        direction TB
        E1["Vai trò trong SDD · Cấu trúc Repo"]
        E2["Code Review · Chỉ số đo SDD"]
        E3["Lộ trình 30-60-90 ngày"]
        E1 --> E2 --> E3
    end

    P4 --> P5

    subgraph P5["5️⃣ RANH GIỚI, HIỂU NHẦM & CÔNG CỤ (Phần Kết)"]
        direction TB
        F1["Khi nào không nên dùng SDD"]
        F2["Những hiểu nhầm về SDD"]
        F3["Vai trò Engineer thời AI"]
        F4["Công cụ SDD (Spec Kit, OpenSpec, AIUP)"]
        F1 --> F2 --> F3 --> F4
    end

    P5 --> Done(["✅ Chọn 1 use case, thử trọn 1 vòng SDD"])

    style P1 fill:#f8d7da,stroke:#c82333,stroke-width:2px
    style P2 fill:#fff3cd,stroke:#e0a800,stroke-width:3px
    style Start fill:#d4edda,stroke:#28a745
    style Done fill:#d4edda,stroke:#28a745

Tư tưởng chi phối tất cả

flowchart LR
    T1["🤖 AI viết code rất nhanh"] --> X["❓ Câu hỏi lớn nhất:<br/>VIẾT ĐÚNG CÁI GÌ?"]
    X --> S["📝 Spec đứng ở giữa<br/>(con người thống nhất ý định)"]
    S --> R1["Spec rõ → AI đi nhanh ĐÚNG hướng"]
    S --> R2["Spec mơ hồ → AI vẫn nhanh,<br/>chỉ là nhanh về SAI hướng"]
    K["🔑 Sửa spec trước, rồi mới sửa code"] --> S

Đọc theo vai trò

flowchart TD
    Q(["👤 Bạn là ai?"]) --> G{"Vai trò?"}

    G -- "Dev / Tech Lead" --> R1["Level 0 → 1 → 2<br/>rồi Greenfield HOẶC Brownfield<br/>theo tình huống"]
    G -- "Engineering Manager" --> R2["Spec-Driven Development →<br/>Chỉ số đo SDD →<br/>Lộ trình 30-60-90 → Vai trò trong SDD"]
    G -- "PO / BA / non-tech" --> R3["Vibe Coding → Bốn tầng của yêu cầu →<br/>Business Requirement → Acceptance Criteria →<br/>Stakeholder-Centric"]

    style Q fill:#f8d7da,stroke:#c82333
    style R1 fill:#d4edda,stroke:#28a745
    style R2 fill:#d4edda,stroke:#28a745
    style R3 fill:#d4edda,stroke:#28a745

Chọn note nào? (tra nhanh theo vấn đề)

flowchart TD
    Q(["🤔 Vấn đề của bạn?"]) --> G{"Thuộc nhóm nào?"}

    G -- "AI chạy nhanh nhưng mất kiểm soát" --> C1{"Tình huống?"}
    C1 -- "Vài tháng sau sửa gì cũng chậm" --> F1["Vibe Coding → Code không có ngữ cảnh"]
    C1 -- "Không ai nhớ vì sao rule tồn tại" --> F2["Requirements-Driven → Traceable"]

    G -- "Spec chưa rõ ràng" --> C2{"Tình huống?"}
    C2 -- "PO và dev hiểu khác nhau" --> F3["Bốn tầng của yêu cầu → Acceptance Criteria"]
    C2 -- "AI đoán sai rule, mất tiền" --> F4["AI-Assisted → Stakeholder-Centric"]

    G -- "Code dính chặt công nghệ" --> C3{"Tình huống?"}
    C3 -- "Dính Stripe/Postgres khó đổi" --> F5["Hexagonal Architecture → Port và Adapter"]
    C3 -- "Refactor mà sợ phá hành vi" --> F6["Test-Protected → Characterization Test"]

    G -- "Áp dụng thực tế" --> C4{"Tình huống?"}
    C4 -- "Dự án mới từ đầu" --> F7["Greenfield với SDD"]
    C4 -- "Legacy 5 năm không doc" --> F8["Brownfield với SDD → Reverse Engineering"]
    C4 -- "Thử SDD cho team" --> F9["Lộ trình 30-60-90 ngày"]
    C4 -- "Không chắc có đáng làm không" --> F10["Khi nào không nên dùng SDD"]

    style Q fill:#f8d7da,stroke:#c82333
    style F1 fill:#d4edda,stroke:#28a745
    style F2 fill:#d4edda,stroke:#28a745
    style F3 fill:#d4edda,stroke:#28a745
    style F4 fill:#d4edda,stroke:#28a745
    style F5 fill:#d4edda,stroke:#28a745
    style F6 fill:#d4edda,stroke:#28a745
    style F7 fill:#d4edda,stroke:#28a745
    style F8 fill:#d4edda,stroke:#28a745
    style F9 fill:#d4edda,stroke:#28a745
    style F10 fill:#d4edda,stroke:#28a745

🪴ttuan's garden