Tạo đặc tả

Trước khi bắt đầu

• Cần biết: hiến chương dự án là gì và bạn đã tạo nó
• Cần có: dự án đã chạy specify init, công cụ AI đang mở trong thư mục dự án
• Cần đang ở: thư mục gốc của dự án, sau khi đã chạy /speckit-constitution

1. Đặc tả trả lời câu hỏi gì

Đặc tả (specification) mô tả tính năng của bạn trông ra sao với người dùng. Nó trả lời hai câu hỏi: bạn xây cái gì (WHAT) và vì sao nó đáng xây (WHY).

Ở bước này bạn KHÔNG bàn tới công nghệ. Không chọn ngôn ngữ, không chọn cơ sở dữ liệu, không chọn thư viện. Những quyết định đó thuộc bước lập kế hoạch. Đưa công nghệ vào đặc tả chỉ làm bản đặc tả cứng nhắc và khó sửa.

2. Gọi lệnh với mô tả tính năng

Gõ trong khung chat của công cụ AI:

/speckit-specify Xây một ứng dụng giúp tôi sắp xếp ảnh thành các album riêng. Album được nhóm theo ngày và có thể sắp xếp lại bằng cách kéo thả trên trang chính. Album không lồng nhau. Trong mỗi album, ảnh hiện dưới dạng lưới.

Kết quả mong đợi: công cụ tạo thư mục specs/001-<ten-tinh-nang>/ chứa tệp spec.md.

3. Xem tệp đặc tả vừa tạo

ls specs/001-*/

Kết quả mong đợi: bạn thấy đường dẫn tới thư mục tính năng, bên trong có spec.md.

Mở tệp spec.md để đọc. Tên thư mục có tiền tố số thứ tự NNN do Spec Kit tự tăng dần cho mỗi tính năng mới.

4. Bốn phần chính trong spec.md

Một bản đặc tả đạt chuẩn có bốn nhóm nội dung sau:

• Tình huống người dùng (user scenarios): các luồng sử dụng được kể theo góc nhìn người dùng, kèm mức ưu tiên. Đây là phần cho biết tính năng phục vụ ai và theo thứ tự nào.
• Yêu cầu chức năng (functional requirements): danh sách việc hệ thống phải làm, mỗi yêu cầu một mã số để tham chiếu về sau.
• Tiêu chí thành công (success criteria): cách đo tính năng đã đạt mục tiêu hay chưa, viết dưới dạng kiểm chứng được.
• Điểm chưa rõ: những chỗ bản đặc tả còn để mở, là đầu vào cho bước làm rõ.

5. Kiểm tra đặc tả trước khi đi tiếp

Đọc lại spec.md và tự hỏi ba câu: người dùng nào được phục vụ, họ làm được gì, và bạn đo thành công bằng gì. Nếu còn chỗ trả lời không được, hãy giữ nguyên và chuyển sang bước làm rõ.

Đừng tự sửa spec.md bằng tay ở bước này nếu bạn chưa chắc. Bước làm rõ được thiết kế để ghi câu trả lời ngược vào đặc tả một cách có hệ thống.

Kết quả

Sau khi hoàn thành trang này, bạn đã:

• Tạo được spec.md từ một mô tả ngôn ngữ tự nhiên
• Biết bốn phần chính cần có trong một bản đặc tả

Cách tự xác nhận: tệp specs/001-*/spec.md tồn tại, có mục yêu cầu chức năng, và không nhắc tới tên công nghệ nào.

Lỗi thường gặp

Lỗi	Nguyên nhân	Cách khắc phục
Không có thư mục specs/ nào được tạo	Lệnh chạy ngoài thư mục dự án	cd về thư mục gốc dự án rồi gọi lại lệnh
spec.md nhắc tới framework hoặc cơ sở dữ liệu	Mô tả ban đầu đã lẫn công nghệ	Chạy lại /speckit-specify với mô tả chỉ nói về hành vi người dùng
Đặc tả quá chung, không kiểm chứng được	Mô tả đầu vào quá ngắn	Bổ sung ví dụ cụ thể rồi chạy lại lệnh
Tên thư mục tính năng không như mong đợi	Spec Kit tự sinh tên từ mô tả	Giữ nguyên; tên thư mục không ảnh hưởng nội dung đặc tả

---

Nguồn tham chiếu: Spec-Driven Development QuickstartPhiên bản kiểm chứng: Spec Kit 1.1.3