Làm rõ điểm mơ hồ

Trước khi bắt đầu

• Cần biết: cấu trúc tệp spec.md và các phần chính của nó
• Cần có: spec.md đã được tạo ở bước tạo đặc tả (specification)
• Cần đang ở: thư mục gốc của dự án, TRƯỚC khi chạy /speckit-plan

1. Vì sao phải làm rõ trước khi lập kế hoạch

Đặc tả viết bằng ngôn ngữ tự nhiên luôn để lại chỗ trống. Nếu bạn lập kế hoạch (plan) trên nền một đặc tả còn mơ hồ, bạn đang thiết kế trên cát: mọi quyết định kỹ thuật phía sau đều có thể phải làm lại.

/speckit-clarify chặn đúng lỗi đó. Nó tìm những chỗ chưa rõ trong spec.md, hỏi bạn, rồi ghi câu trả lời ngược vào chính tệp đặc tả.

2. Lệnh chạy trước bước lập kế hoạch

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

/speckit-clarify

Kết quả mong đợi: công cụ đọc spec.md, nêu tối đa 5 câu hỏi có mục tiêu về những chỗ chưa rõ, và chờ bạn trả lời.

Bạn trả lời từng câu ngay trong khung chat. Sau khi trả lời xong, công cụ cập nhật spec.md với các quyết định đó.

3. Truyền vùng tập trung khi cần

Nếu bạn biết trước đặc tả còn yếu ở phần nào, hãy chỉ thẳng vùng đó để câu hỏi tập trung hơn:

/speckit-clarify Tập trung vào hành vi của thẻ công việc: đổi trạng thái, giới hạn bình luận, và ai được gán việc.

Kết quả mong đợi: các câu hỏi xoay quanh đúng vùng bạn chỉ định thay vì rải đều toàn bộ đặc tả.

4. Chạy nhiều lần, mỗi lần một vùng

Giới hạn tối đa 5 câu hỏi cho mỗi lần chạy là có chủ đích: nó giữ cho phiên làm việc ngắn và câu trả lời của bạn có chất lượng. Nếu đặc tả còn nhiều vùng mơ hồ, chạy lại lệnh với vùng khác.

Bạn có thể chạy lệnh này bao nhiêu lần cũng được, miễn là trước /speckit-plan.

5. Kiểm tra câu trả lời đã vào đặc tả

Mở lại spec.md và tìm các quyết định bạn vừa chốt. Chúng phải nằm trong tệp, không chỉ nằm trong lịch sử chat.

Cách tự xác nhận nhanh: đọc phần yêu cầu chức năng (functional requirements) và tìm câu trả lời của bạn ở đó.

6. Quay lại bước này khi phân tích phát hiện lỗ hổng

Nếu /speckit-analyze sau này báo còn lỗ hổng về yêu cầu, đừng sửa plan.md cho khớp. Hãy quay lại đây chạy /speckit-clarify, hoặc chạy lại /speckit-specify, rồi mới chạy lại /speckit-analyze.

Kết quả

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

• Trả lời được các câu hỏi làm rõ cho đặc tả của mình
• Có spec.md đã ghi lại các quyết định thay vì để mở

Cách tự xác nhận: mở spec.md và thấy nội dung câu trả lời của bạn đã nằm trong tệp.

Lỗi thường gặp

Lỗi	Nguyên nhân	Cách khắc phục
Lệnh không nêu câu hỏi nào	Đặc tả chưa đủ nội dung để phân tích	Kiểm tra spec.md có tồn tại và có mục yêu cầu chức năng
Câu trả lời không xuất hiện trong spec.md	Trả lời ngoài phiên làm việc của lệnh	Chạy lại /speckit-clarify và trả lời ngay trong khung chat
Câu hỏi lệch khỏi phần bạn quan tâm	Không truyền vùng tập trung	Gọi lại lệnh kèm mô tả vùng cần làm rõ
Chạy lệnh sau khi đã có plan.md	Sai thứ tự	Sửa đặc tả trước, rồi chạy lại /speckit-plan để kế hoạch khớp đặc tả mới

---

Nguồn tham chiếu: Agentic SDDPhiên bản kiểm chứng: Spec Kit 1.1.3