Phát triển dựa trên bản đặc tả với Claude Code: Hướng dẫn có chỉ dẫn

Phát triển dựa trên bản đặc tả là gì?

Phát triển dựa trên bản đặc tả là quy trình làm việc dựa trên ba tài liệu theo thứ tự: tài liệu nêu thay đổi cần làm gì, một kế hoạch chỉ rõ các bước, và mã được viết theo kế hoạch, với bước người kiểm duyệt giữa mỗi cặp.

Ba điểm kiểm duyệt mà một tính năng đi qua trong phát triển dựa trên bản đặc tả.

Bản đặc tả là một tài liệu ngắn, viết bằng ngôn ngữ thường trước khi có bất kỳ mã nào, nêu rõ thay đổi cần làm gì. Lấy ví dụ tính năng "cho phép người dùng xuất dữ liệu của họ." Một bản đặc tả cho tính năng đó sẽ chốt chặn các câu trả lời mà agent nếu không sẽ phải đoán. Nó liệt kê 

• Định dạng tệp được hỗ trợ
• Phương thức phân phối
• Hành vi trong lúc xuất dở
• Những phần của tính năng được cố ý bỏ qua

Đây là phần mở đầu thực tế của một bản đặc tả mà Claude Code đã viết cho thay đổi workout-shape-verification trong một ứng dụng trách nhiệm qua Telegram của tôi. Thay đổi này thay thế ngưỡng nhịp tim dễ hỏng bằng một phép kiểm tra hình dạng đường cong nhịp tim theo thời gian:

# Workout Shape-Based Verification — Design Spec
 
**Created:** 2026-05-05
**Status:** Draft
**Supersedes (partially):** [2026-03-17-calisthenics-verification-design.md]
  — replaces the absolute-HR thresholds for the Workout activity type.
  Run / Ride / Walk verification is unchanged.
 
## Problem
 
The current Workout verifier accepts an activity only if absolute heart-rate
levels clear fixed cutoffs: avg ≥ 120, max ≥ 140, range ≥ 30, suffer_score ≥ 3.
Two failures in production:
 
1. **False-negative risk.** As cardiovascular fitness improved
   (resting HR ~80), real calisthenics sessions with disciplined rest now
   average 115–125 bpm. Recent sessions have come within 4 bpm of the 120 floor.
 
<!-- ... continues for hundreds of lines through Solution, Risks,
 	Out of scope, and What is removed / added / changed / unchanged -->

Kế hoạch là tài liệu tiếp theo. Nó phân rã bản đặc tả ở trên thành các tác vụ được đánh số để agent thực hiện lần lượt, mỗi tác vụ nêu tệp, thay đổi, thứ tự và kiểm thử. Nếu bản đặc tả trả lời "cần làm gì," thì kế hoạch trả lời "làm theo những bước nào." 

Mã đến sau cùng, được viết theo kế hoạch từng tác vụ một.

Ba tài liệu. Có bước người kiểm duyệt giữa mỗi cặp. Bạn duyệt bản đặc tả trước khi thành kế hoạch. Bạn duyệt kế hoạch trước khi thành mã. Bạn duyệt mã trước khi hợp nhất.

Khác gì so với chế độ lập kế hoạch (plan mode)

Bạn có thể đã dùng chế độ lập kế hoạch tích hợp của Claude Code (nhấn Shift+Tab hai lần để vào) và tự hỏi tại sao cách này khác. Plan mode tạo một kế hoạch trong một lượt chat duy nhất. Kế hoạch sống trong bộ nhớ, không có bản đặc tả lưu trữ và không có bước duyệt giữa các giai đoạn.

Phát triển dựa trên bản đặc tả lưu trữ cả bản đặc tả và kế hoạch dưới dạng tệp trên đĩa. Mỗi tệp đều qua bước người kiểm duyệt trước khi bước tiếp theo bắt đầu, và các tạo phẩm tồn tại qua nhiều phiên. Plan mode nén hai giai đoạn phát triển phần mềm vào một lượt chat. Cách đó phù hợp cho việc nhỏ và thất bại ngay khi codebase lớn lên và phục vụ người dùng thực.

Vì sao vibe-coding chạm trần

Vibe-coding hiệu quả cho nguyên mẫu, tệp đơn và script dùng rồi bỏ. Nó tệ đi trong ứng dụng thực có người dùng và trong codebase lớn sẵn có. Ranh giới đáng vẽ là khoảng 4 tệp. Bất kỳ thay đổi nào chạm đến chừng đó tệp đều cần bản đặc tả, cũng như mọi refactor có trạng thái đích rõ ràng, hoặc mọi tác vụ mà phần khó là "chính xác phải làm gì?"

Nguyên nhân thất bại rất rõ. Một prompt mơ hồ như "thêm chia sẻ ảnh vào ứng dụng của tôi" khiến mô hình phải đoán hàng nghìn yêu cầu không được nêu.

Chỉ một yêu cầu trong số đó: tùy chọn thông báo. PM mặc định có công tắc theo kênh. Backend xây một công tắc bật/tắt. Frontend giả định tích hợp ở cấp hệ điều hành. Bốn cách hiểu hợp lý của ba từ, ra bốn sản phẩm khác nhau.

Mỗi bước duyệt trong phát triển dựa trên bản đặc tả bắt lỗi một lớp sai khác nhau trước khi nó trở nên tốn kém. Duyệt bản đặc tả bắt trôi phạm vi và chẩn đoán sai gốc rễ. Duyệt kế hoạch bắt triển khai dang dở và mẫu mực xung đột. Duyệt mã bắt các kế hoạch đọc thì ổn nhưng vỡ ngay ở bài test đầu tiên thất bại.

Lợi ích là thật, và tích lũy dần. Giai đoạn bản đặc tả tốn vài giờ viết trước khi có dòng mã nào chạy, và vài tính năng đầu sẽ thấy chậm hơn vibe-coding. Điểm hòa vốn của tôi đến khoảng tính năng thứ tư hoặc thứ năm. Lúc đó, bản đặc tả bắt được các lỗi thiết kế mà nếu không tôi đã phát hành rồi viết lại một tuần sau.

Ba phần tiếp theo sẽ đi qua ba cách tiếp cận mã nguồn mở vận hành luồng này trong Claude Code. Chúng được sắp từ nhẹ đến nặng về mức độ cấu trúc áp đặt.

Superpowers

Superpowers là nhẹ nhất trong ba. Đây là công cụ tôi dùng hằng ngày, và cũng là công cụ chúng ta sẽ đi sâu nhất.

Superpowers là gì?

Superpowers là plugin Claude Code của Jesse Vincent (obra/superpowers, giấy phép MIT), với khoảng 194k sao trên GitHub. 

Nó đi kèm một bộ kỹ năng. Một kỹ năng Claude trong Claude Code là một tệp hướng dẫn có tên mà agent tải theo nhu cầu để theo một quy trình cụ thể. Superpowers cung cấp các kỹ năng buộc Claude Code đi theo vòng lặp dựa trên bản đặc tả thay vì nhảy thẳng vào viết mã.

Trang dự án Superpowers trên GitHub.

Cách cài đặt Superpowers

Cài đặt qua chợ plugin chính thức của Claude Code:

/plugin install superpowers@claude-plugins-official

Hook SessionStart tự động tải kỹ năng using-superpowers, nên quy trình hoạt động ngay khi bạn bắt đầu gõ. (Claude code hooks là các script agent chạy tại một sự kiện vòng đời cụ thể.) Không cần cấu hình theo từng dự án.

Quy trình Superpowers

Sau đó, bốn kỹ năng quản lý công việc hằng ngày của bạn:

Subagent là một phiên bản Claude Code riêng mà tác nhân cha điều phối để làm việc tập trung trong cửa sổ ngữ cảnh của riêng nó. Các subagent reviewer trong bảng trên chạy như subagent, nên họ đọc mã hoàn toàn mới, không bị khung tham chiếu của tác nhân cha chi phối.

Cách sử dụng Superpowers

Bạn gọi bốn kỹ năng bằng cách mô tả điều bạn muốn bằng ngôn ngữ thường. Kỹ năng brainstorming nghe thấy "hãy bàn về tính năng mới này" và tự khởi động cuộc trao đổi bản đặc tả. Các kỹ năng khác cũng kích hoạt theo cách tương tự.

Bốn kỹ năng Superpowers theo thứ tự, với hai điểm người duyệt nằm giữa brainstorming và writing-plans.

Phần hướng dẫn dưới đây dùng cùng tính năng workout-shape-verification từ trích đoạn bản đặc tả ở trên.

Giai đoạn 1: từ động não đến bản đặc tả

Tôi mở Claude Code và gõ:

Let's discuss a new feature. The Workout verifier in make-me-work uses absolute heart-rate cutoffs and is now misfiring as my resting HR drops. I want to replace the absolute cutoffs with a check on the shape of the HR curve over the session.

Kỹ năng brainstorming tiếp quản và hỏi lại khoảng mười câu, trong đó có:

• Thế nào là "hình dạng" đúng
• Kết hợp các luồng dữ liệu nào
• Xử lý các phiên có hình dạng đúng nhưng trượt một ngưỡng cũ ra sao
• Liệu thay đổi có áp dụng cho Run và Ride không

Hai điểm người duyệt nằm ở đây. Điểm đầu là duyệt thiết kế, nơi tôi xác nhận các câu trả lời tôi đưa ra khớp với điều tôi muốn. Điểm thứ hai là duyệt bản đặc tả. Tôi đọc tệp Claude đã viết và phê duyệt trước khi bất kỳ công việc lập kế hoạch nào bắt đầu.

Giai đoạn 2: từ bản đặc tả đến kế hoạch

Tôi chạy kỹ năng writing-plans. Nó đọc bản đặc tả đã duyệt và viết một tệp kế hoạch với bốn phần:

• Định nghĩa "Hoàn thành" nghĩa là gì
• Bản đồ tệp các tệp bị ảnh hưởng
• Hành trình người dùng qua đường đi demo
• Danh sách tác vụ được đánh số gồm các bước con dạng checkbox. 

Tôi duyệt kế hoạch, phản hồi với các tác vụ có vẻ sai thứ tự hoặc quá thô, rồi phê duyệt.

Giai đoạn 3: từ kế hoạch đến mã

Tôi chạy subagent-driven-development. Từ đây vòng lặp chạy không cần tôi. Với mỗi tác vụ trong kế hoạch, kỹ năng sẽ:

1. Viết một bài kiểm thử thất bại
2. Viết mã để vượt qua kiểm thử
3. Refactor
4. Gửi một subagent code-review đọc diff từ đầu

Nếu reviewer gắn cờ vấn đề, vòng lặp sẽ sửa trước khi chuyển sang tác vụ tiếp theo. Không có điểm người duyệt trong giai đoạn này. Các bước duyệt quan trọng cho giai đoạn này là hai bước trước đó.

Giai đoạn 4: duyệt toàn bộ diff

Khi xong kế hoạch, tôi chạy requesting-code-review. Một subagent mới đọc toàn bộ diff so với bản đặc tả và kế hoạch, rồi đăng bài duyệt. Tôi áp dụng các đề xuất trước khi hợp nhất.

Khi một tác vụ trong kế hoạch lộ mâu thuẫn với bản đặc tả, vòng lặp sẽ dừng và hỏi. Tôi có thể chỉnh bản đặc tả (hoặc để Claude làm) và sinh lại các tác vụ bị ảnh hưởng. Lựa chọn khác là sửa một lần ngay trong tác vụ. Superpowers không âm thầm lách qua lỗi của bản đặc tả.

Bản đặc tả và kế hoạch thật trên đĩa

Đây là bản đặc tả cho tính năng workout-shape-verification, mở trong trình soạn thảo:

Tệp bản đặc tả như nó được ghi xuống đĩa sau khi kỹ năng brainstorming viết xong.

Phần đầu mang các trường Created, Status và Supersedes mà kỹ năng brainstorming viết mặc định. Tiếp theo là phần Problem. Không có phần nào là mã. Tệp tiếp tục vượt quá ảnh chụp màn hình qua các phần giải pháp đề xuất và các ràng buộc về những gì thay đổi nên và không nên chạm tới.

Kế hoạch tương ứng mở đầu bằng User Journey:

Tệp kế hoạch do kỹ năng writing-plans tạo ra từ bản đặc tả đã phê duyệt.

Hành trình đi qua đường demo từng năm bước, nêu rõ lệnh, tệp và tham số ở mỗi bước. Các tác vụ được đánh số theo sau chuyển mỗi bước thành các bước con dạng checkbox mà kỹ năng subagent-driven-development có thể xử lý.

Hai tài liệu ghép cặp như sau:

Bản đặc tả và kế hoạch đặt cạnh nhau. Bản đặc tả trả lời thay đổi gì và vì sao. Kế hoạch trả lời theo những bước nào.

Với các bản đặc tả và kế hoạch lớn hơn, tôi thêm một bước không có trong vòng lặp chính thức: một lượt red-team. Trước khi ký duyệt, tôi để một hoặc vài subagent Opus đọc bản đặc tả từ đầu, tìm lỗ hổng từ các góc nhìn khác nhau. Đó là thói quen cá nhân, không phải tính năng của Superpowers. Nó đã bắt đủ giả định sai để tôi duy trì thói quen này.

Khi nào Superpowers không phù hợp

Superpowers hợp với công việc solo trên một repo. Nó tốt nhất khi toàn bộ codebase vừa trong một phiên Claude Code và bạn thực sự sẽ đọc một bản đặc tả 2 trang. So sánh chi tiết nằm ở Cách chọn giữa các công cụ phía dưới. Tóm tắt: Superpowers gặp khó với tính năng đa repo và công việc đòi hỏi phân tách vai trò rõ ràng.

Một nhà phát triển đã chỉ ra lỗi thứ tư trong một phàn nàn công khai về plugin: “Ngay cả tác vụ nhỏ nhất cũng mất cả đời, Claude quay subagent và viết kế hoạch quá thừa. Sửa chút CSS giờ cũng mất cả đời.”

Cách khắc phục là bỏ qua Superpowers cho các thay đổi rất nhỏ. Các kỹ năng chỉ kích hoạt khi có trigger brainstorming. Một chỉnh sửa CSS một dòng có thể đi qua Claude Code mà không bao giờ gọi vòng lặp bản đặc tả. Kiểu lỗi thật sự ở đây là lạm dụng quy trình cho công việc không cần bản đặc tả.

GitHub Spec Kit

Spec Kit là lựa chọn khi bản đặc tả cần tồn tại lâu hơn bất kỳ phiên Claude Code nào. Nó cũng đúng khi những người không bao giờ mở Claude Code vẫn cần đọc bản đặc tả.

GitHub spec-kit là gì?

Spec Kit là một dự án GitHub (github/spec-kit, giấy phép MIT), do chính GitHub duy trì, với hơn 100k sao. Nó cung cấp một CLI cùng quy trình hoạt động giống nhau trên mọi agent viết mã AI lớn. Claude Code, Cursor, Aider, Cline và Roo Code đều được hỗ trợ. Thiết kế trung lập agent là thứ cho phép bản đặc tả sống bên ngoài Claude Code.

Trang dự án Spec Kit trên GitHub.

Cách cài đặt GitHub spec-kit

Chưa có gói PyPI chính thức, nên cài CLI từ thẻ Git bằng uv:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Thay vX.Y.Z bằng thẻ phát hành hiện tại. Gói là specify-cli, và lệnh nó đăng ký là specify.

Quy trình GitHub spec-kit

Quy trình chạy qua chín lệnh gạch chéo mà CLI cài vào danh sách slash-command của agent. Sáu lệnh là lõi của vòng lặp, ba lệnh tùy chọn cho các trường hợp mà vòng lặp lõi không bao phủ.

Ký tự phân tách giữa nhóm lệnh và động từ là dấu chấm, không phải dấu hai chấm: /speckit.specify, không phải /speckit:specify. 

Chín lệnh gạch chéo của Spec Kit: sáu lệnh cốt lõi trên pipeline, ba lệnh tùy chọn treo bên dưới.

Các tạo phẩm mà các lệnh này sinh ra chính là bản đặc tả và kế hoạch bạn đã thấy ở phần Superpowers, cũng được ghi xuống đĩa và theo dõi bằng Git. Khác biệt là tính di động: tạo phẩm của Spec Kit được thiết kế để làm việc với bất kỳ agent viết mã AI nào, không chỉ Claude Code, và quy trình hướng tới việc người liên quan duyệt qua pull request trên GitHub thay vì là hệ quả phụ của vòng lặp một công cụ duy nhất.

Khi nào dùng GitHub spec-kit

Với dự án solo, có lẽ bạn sẽ không cần Spec Kit. Hãy dùng khi:

• Dự án lớn hơn một người
• Bản đặc tả cần được những người không bao giờ mở Claude Code duyệt
• Bạn chạy một agent không phải Claude Code cho một phần công việc
• Bạn muốn định dạng bản đặc tả sống ngoài bất kỳ công cụ nào và vẫn đọc được sau nhiều tháng

Phương pháp BMAD

Nếu Spec Kit tổ chức tạo phẩm, BMAD tổ chức con người. Nó tách quy trình từ bản đặc tả đến mã thành bốn giai đoạn, mỗi giai đoạn do một agent-vai trò đảm nhiệm.

BMAD là gì?

BMAD-METHOD (bmad-code-org/BMAD-METHOD, giấy phép MIT, khoảng 47k sao) đang ở phiên bản 6. Theo tài liệu của dự án, chữ viết tắt mở rộng là "Breakthrough Method for Agile AI-Driven Development." Nó chạy trên Claude Code và các agent khác, và cài đặt dưới dạng hệ sinh thái mô-đun. Cài đặt mặc định cung cấp mô-đun lõi gồm sáu agent-vai trò, bốn giai đoạn quy trình và từ 34 workflow có tên trở lên.

Trang dự án BMAD-METHOD trên GitHub.

Cách cài đặt BMAD

Cài BMAD bằng Node:

npx bmad-method install

Sáu agent-vai trò là các persona prompt mà người dùng kích hoạt theo tên từ trong công cụ host. Trong Claude Code, nghĩa là gõ lệnh kích hoạt mà BMAD cài đặt. Kiểm tra README để biết cú pháp chính xác, có thay đổi giữa các bản phát hành. 

Giới thiệu các agent đồng nghiệp và tạo phẩm của BMAD

Khi kích hoạt, agent nhận hướng dẫn, giọng điệu và đầu ra của vai trò đó cho đến khi bạn chuyển persona. Sáu vai trò gồm:

• Mary, Nhà phân tích
• Paige, Người viết tài liệu kỹ thuật
• John, Quản lý sản phẩm
• Sally, Nhà thiết kế UX
• Winston, Kiến trúc sư
• Amelia, Lập trình viên

Hai vai trò bạn có thể mong đợi lại thiếu trong v6: không có agent Scrum Master và không có agent QA độc lập. Lập kế hoạch sprint và chuẩn bị story do agent Lập trình viên đảm nhiệm, và sinh test QA là một workflow do Lập trình viên kích hoạt.

Bộ tạo phẩm nặng hơn một bản đặc tả đơn. Bạn có:

• bản tóm tắt sản phẩm
• PRD (Tài liệu yêu cầu sản phẩm)
• bản đặc tả UX
• tài liệu kiến trúc
• epic được chia thành user story (những gì người dùng có thể làm khi phát hành)

PRD và tài liệu kiến trúc cùng nhau đóng vai trò tương tự bản đặc tả trong Superpowers. Sự tách này đặt chúng vào hai agent-vai trò và một định dạng chính quy hơn. Bộ tạo phẩm bao quát toàn bộ vòng đời phát triển phần mềm, với mỗi tính năng thừa hưởng ngữ cảnh từ lớp phía trên.

Quy trình BMAD

Quy trình v6 chạy qua bốn giai đoạn.

Bốn giai đoạn BMAD và agent-vai trò chạy mỗi giai đoạn. Nhánh Quick Flow bỏ qua ba giai đoạn đầu cho việc nhỏ.

Giai đoạn 1, phân tích, là tùy chọn. Mary (Nhà phân tích) và Paige (Người viết tài liệu kỹ thuật) nghiên cứu và tạo bản tóm tắt sản phẩm. Bỏ qua giai đoạn nếu bạn đã biết bạn sẽ xây gì.

Giai đoạn 2, lập kế hoạch, là bắt buộc. John (PM) viết PRD. Sally (Nhà thiết kế UX) bổ sung bản đặc tả UX khi tính năng có giao diện.

Giai đoạn 3, giải pháp, là giai đoạn của Winston. Kiến trúc sư phác thảo kiến trúc trước, rồi John chia yêu cầu thành epic và story. Đặt story sau kiến trúc là lựa chọn của v6 giúp ước lượng theo ranh giới triển khai thực. Winston sau đó chạy kiểm tra sẵn sàng triển khai với kết luận PASS, CONCERNS hoặc FAIL.

Giai đoạn 4, triển khai, là nơi Amelia (Lập trình viên) làm việc theo từng story: tạo story, xây dựng và code-review. Khi hoàn thành cả một epic, cô kích hoạt workflow sinh test QA cho toàn bộ epic. Đây là giai đoạn Claude Code thực sự viết mã, hoạt động như Amelia.

Với việc nhỏ, phạm vi rõ, BMAD có nhánh "Quick Flow" kích hoạt trực tiếp Amelia và bỏ qua ba giai đoạn đầu. Lệnh kích hoạt nằm trong README của BMAD (cú pháp cụ thể thay đổi giữa các bản). Quick Flow không tạo PRD hay tài liệu kiến trúc, chỉ có một story ngắn và mã đáp ứng story đó. Đây là câu trả lời cho phản biện "quá rườm rà cho một thay đổi nút bấm".

Khi bản đặc tả hóa ra sai giữa lúc triển khai, BMAD quay lại kết luận của Giai đoạn 3 của Winston. FAIL gửi bạn về Giai đoạn 2 để viết lại PRD. CONCERNS tiếp tục với các rủi ro Winston ghi chú kèm story. Cách tách này cho phép bạn tiếp tục với bất nhất nhỏ và dừng hẳn với bất nhất lớn.

Khi độ phức tạp xứng đáng

BMAD hiệu quả cho các dự án dài hạn với người dùng thực. Nó cũng phù hợp với đội nhiều lập trình viên, bàn giao công việc giữa người với người. Việc tách giai đoạn và vai trò phải tiết kiệm thời gian nhiều hơn chi phí phát sinh.

Nó không phù hợp cho dự án cá nhân một người. Với việc solo, tách bốn giai đoạn, sáu agent chủ yếu là chi phí. Không có người thứ hai trong nhóm để việc phân vai thành vấn đề đáng kể.

Cách chọn giữa các khung công cụ

Ba quy tắc quyết định lựa chọn.

• Dùng Spec Kit nếu bản đặc tả phải được những người không bao giờ mở Claude Code đọc, hoặc phải sống trong Git như một tạo phẩm dài hạn.
• Nếu nhiều người làm việc theo các vai trò tách biệt, hoặc có stakeholder kiểu PM thực sự trong vòng lặp, dùng BMAD.
• Nếu không, dùng Superpowers.

Ba câu hỏi về dự án của bạn, bốn lựa chọn khung công cụ ở phía kia.

Có lựa chọn thứ tư mà cây quyết định nêu: kết hợp Spec Kit với Superpowers. Dùng Spec Kit cho giai đoạn bản đặc tả để tạo phẩm sống trong Git cho việc duyệt liên phòng ban. Sau đó trỏ kỹ năng subagent-driven-development của Superpowers vào tệp kế hoạch của Spec Kit bằng một dòng cấu hình. Bạn sẽ có bản đặc tả bền vững từ Spec Kit cùng vòng lặp triển khai chặt chẽ từ Superpowers.

Kết luận

Phát triển dựa trên bản đặc tả là ba tài liệu theo thứ tự. Bản đặc tả nêu cần xây gì, kế hoạch nêu theo những bước nào, và mã đi theo kế hoạch. Có bước người duyệt giữa mỗi cặp.

Hãy chạy cây quyết định ở trên để chọn khung công cụ, mà với đa số độc giả sẽ là Superpowers. Cài đặt và chọn một tính năng mà bình thường bạn sẽ vibe-code, thứ chạm vào 3 đến 5 tệp. Chạy trọn vẹn qua động não, bản đặc tả, kế hoạch và thực thi. Một lượt chạy thực tế dạy quy trình tốt hơn mọi mô tả.

Nếu bạn muốn ôn lại kiến thức nền tảng về Claude Code trước, DataCamp có hướng dẫn thực hành về Claude Code, một hướng dẫn thực hành tốt nhất bao gồm plan mode, CLAUDE.md và TDD, và một bài chuyên sâu về chính plan mode.