spec-writer

spec-writer — Sinh & quản lý tài liệu spec 2 tầng

Tạo và duy trì bộ tài liệu đặc tả 2 tầng cho một dự án phần mềm:

• Spec tổng (01_requirements.md) — Tài liệu Định nghĩa Yêu cầu cấp cao.
• Spec con (screens/F-NNN_*.md) — Đặc tả chi tiết từng màn hình/chức năng.
• Index truy vết (00_index.md) — nguồn sự thật về quan hệ F-NNN ↔ màn hình ↔ NFR ↔ file.

Mục tiêu: tài liệu dùng làm đầu vào cho hệ thống tạo test spec bên ngoài, đồng thời dùng được để lập plan và code.

Ngôn ngữ mặc định: tiếng Việt là chính; field name/thuật ngữ kỹ thuật và message UI để tiếng Anh (theo mẫu).

---

Kỷ luật xuất (BẮT BUỘC — tránh dump dài, lag)

• Ghi file trực tiếp bằng Write/Edit tool. TUYỆT ĐỐI KHÔNG in/dán toàn bộ nội dung tài liệu ra chat (file dài → chat phình, lag).
• Không hỏi "có tạo file không" kèm preview nội dung. Cứ tạo file, rồi báo ngắn gọn: đường dẫn + tóm tắt 2–4 dòng (số F-NNN, số màn, NFR chính). Người dùng muốn xem thì mở file.
• Khi cần xác nhận, hỏi câu ngắn (vd "đã tạo 01_requirements.md với F-001~F-003, xem & cho ý kiến?") — không lặp lại nội dung file trong chat.
• Áp dụng cho mọi file ở mọi stage/nhánh.

---

Vị trí trong pipeline (orchestrator)

spec-writer chèn bước spec có cấu trúc vào pipeline superpowers, dừng được ở bất kỳ stage:

Stage	Việc	Cơ chế
1. Hỏi/đáp	Khai thác yêu cầu	Gọi superpowers:brainstorming nếu có; khi brainstorming định gọi writing-plans, trả quyền lại đây; KHÔNG sinh design doc riêng của brainstorming. Nếu chưa cài superpowers → tự hỏi-đáp (xem Fallback dưới) rồi sang Stage 2
2. Spec	Sinh docs/spec/ (spec tổng + spec con màn hình)	Lõi skill — deliverable mặc định, dừng được ở đây
3. DB	Thiết kế CSDL từ spec	Gọi skill db-designer (tùy chọn) — sinh docs/spec/database/, cập nhật truy vết
4. API	Thiết kế API từ spec + DB	Gọi skill api-designer (tùy chọn) — sinh docs/spec/api/, cập nhật truy vết
4.5. Test	Sinh chiến lược & test case từ spec/DB/API (tùy chọn)	Xem references/test-strategy.md — map mọi test về F-NNN/API-ID/NFR
5. Plan	Lập kế hoạch code	Gọi superpowers:writing-plans, dùng spec/DB/API làm đầu vào (tùy chọn)
6. Code	Triển khai	Gọi executing-plans/subagent-driven-development (tùy chọn)

Hết Stage 2 LUÔN hỏi người dùng: "Dừng ở spec, hay tiếp tục sang DB (Stage 3, skill db-designer)?" — dừng được ở bất kỳ stage.

Truy vết xuyên pipeline: db-designer và api-designer đọc & cập nhật chung 00_index.md. Trong pipeline này màn hình = F-NNN (không tạo hệ SCR-ID song song). Mapping đầy đủ: F-NNN ↔ màn ↔ bảng DB ↔ API-ID — để hệ tạo test spec / code join lại được.

---

Bốn nhánh — tự nhận diện ý định người dùng

Nhánh 1 — Khởi tạo dự án mới (tích hợp brainstorming)

1. Khai thác yêu cầu: mục tiêu, scope (In/Out/TBD), actor, chức năng chính, ràng buộc.
   • Có superpowers → gọi superpowers:brainstorming. Khi brainstorming tới bước viết design doc / writing-plans → dừng nó lại, quay về đây.
   • Không có superpowers (Fallback) → tự hỏi-đáp: hỏi từng câu một, ưu tiên trắc nghiệm, lần lượt làm rõ mục tiêu → scope → actor → chức năng chính → ràng buộc/NFR. Đủ thông tin thì tóm tắt cho người dùng xác nhận rồi sang bước 2. KHÔNG sinh design doc riêng — đầu ra là docs/spec/.
2. Tạo cấu trúc docs/spec/ (xem bên dưới). Sinh 01_requirements.md theo references/master-spec-template.md, gán ID F-NNN, NFR-X-NNN, ACT-NNN (theo references/id-and-style-rules.md).
3. Sinh conventions.md theo references/conventions-template.md.
4. Sinh 00_index.md theo references/traceability-index-template.md.
5. Hỏi người dùng làm spec con cho màn/chức năng nào trước → với mỗi cái, làm theo Nhánh 2.
6. Self-review (xem checklist cuối). Báo người dùng review. Hỏi có sang Stage 3 (DB, skill db-designer) không.

Nhánh 2 — Thêm spec con (1 màn hình/chức năng)

1. Đọc 00_index.md + 01_requirements.md để lấy ngữ cảnh, ID đã có, NFR liên quan.
2. Sinh screens/F-NNN_<slug>.md theo references/screen-spec-template.md — gồm Gherkin/Expected result (§5A.1), State Transition nếu có trạng thái; thiết kế trực quan dùng Claude design (https://claude.ai/design), KHÔNG Figma; điền mục Responsive & Accessibility (bám NFR-U).
3. Link ngược trong file: Thuộc: F-NNN, NFR liên quan.
4. Cập nhật 00_index.md thêm dòng truy vết.
5. Cập nhật design/design-prompt.md (tạo theo references/design-prompt-template.md nếu chưa có) — thêm/sửa mục F-NNN khớp bảng Items. Đây là file prompt DUY NHẤT để dán vào Claude design.

Nhánh 3 — Cập nhật khi yêu cầu thay đổi (đồng bộ 2 tầng) — QUAN TRỌNG

1. Đọc 00_index.md để xác định MỌI file bị ảnh hưởng (spec tổng + các spec con + NFR + transition).
2. Liệt kê danh sách file tác động cho người dùng xác nhận TRƯỚC KHI sửa.
3. Sửa đồng bộ tất cả file liên quan (gồm mục màn trong design/design-prompt.md nếu màn bị đổi).
4. Trong mỗi file đụng tới: tăng version + ghi dòng Lịch sử thay đổi.
5. Cập nhật 00_index.md (trạng thái, quan hệ mới nếu có).
6. Chạy kiểm tra chéo theo references/cross-doc-checks.md (spec ↔ DB ↔ API); báo các điểm CRITICAL/WARNING trước khi kết thúc.

Nhánh 4 — Sửa quy ước chung / NFR

1. Sửa conventions.md hoặc mục NFR trong 01_requirements.md.
2. Rà các spec con tham chiếu quy ước/NFR đó → cảnh báo người dùng nếu cần đồng bộ.

---

Cấu trúc tài liệu sinh ra (trong repo dự án)

docs/spec/
├── 00_index.md            # Traceability index — nguồn sự thật
├── 01_requirements.md     # Spec tổng (master)
├── conventions.md         # Quy ước chung
├── design/
│   └── design-prompt.md   # 1 file prompt DUY NHẤT cấp cho Claude design (mọi màn)
└── screens/
    └── F-NNN_<slug>.md     # Spec con

Tên file spec con: F-NNN_<slug>.md khớp ID trong index.

---

Quy tắc tầng nào sở hữu gì (tránh test trùng / mâu thuẫn)

• Spec tổng sở hữu: ý định nghiệp vụ, User Story, Acceptance Criteria cấp chức năng, NFR, RBAC matrix, scope.
• Spec con sở hữu: cơ chế field/validation, flow màn hình, edge case, message, transition chi tiết.
• KHÔNG lặp cùng một rule ở hai tầng với từ ngữ khác nhau.

---

Template & quy tắc — đọc khi cần

• references/master-spec-template.md — khuôn spec tổng.
• references/screen-spec-template.md — khuôn spec con (có Gherkin/Expected result, State Transition).
• references/conventions-template.md — quy ước data, status dict, search/filter/pagination, State Transition Matrix, chuẩn Label, chuẩn Message.
• references/traceability-index-template.md — khuôn index.
• references/id-and-style-rules.md — quy tắc ID, song ngữ, Gherkin, RBAC matrix, changelog & version.
• references/design-prompt-template.md — khuôn file prompt DUY NHẤT cho Claude design (design/design-prompt.md).
• references/cross-doc-checks.md — kiểm tra toàn vẹn chéo spec ↔ DB ↔ API (dùng ở Nhánh 3 / review).
• references/test-strategy.md — chiến lược test & nguồn sinh test từ spec (Stage Test, tùy chọn).

---

Checklist self-review (trước khi báo người dùng)

1. Placeholder: không còn TBD/TODO/ô trống vô nghĩa (trừ phần cố ý đánh dấu Cần xác nhận).
2. Truy vết: mọi spec con có F-NNN tương ứng trong 00_index.md; mọi F-NNN có dòng index.
3. Đồng bộ 2 tầng: không mâu thuẫn giữa spec tổng và spec con; không lặp rule.
4. Testability: mỗi business rule/edge case ở spec con có expected result; transition & RBAC có bảng nếu áp dụng.
5. Style: ID đúng định dạng, label/message theo chuẩn conventions.md, có Lịch sử thay đổi + version.