Hướng dẫn cho Dev

TL;DR cho Dev: Dùng Claude Code làm primary tool — slash commands có sẵn cho mọi thao tác. CLI npm run chỉ là fallback khi không có Claude Code.

Workflow chính qua Claude Code

Tạo feature mới

Nói tự nhiên với Claude (skill feature-create tự trigger):

Tạo feature mới: đăng nhập bằng OTP qua SMS

Hoặc dùng slash command rõ ràng:

/new-spec auth-otp-login

Claude sẽ:

Scaffold folder docs/features/auth-otp-login/ từ template (đủ 9 heading).
Hỏi anh: title, owner, priority, platforms.
Điền frontmatter + meta.json chuẩn schema.
Validate xong báo lại đường dẫn + bước tiếp theo.

Load feature trước khi impl code

Trước khi mở repo BE/FE để viết code, dùng:

/load-feature auth-otp-login

Claude đọc spec.md + meta.json + các feature trong depends_on, rồi tóm tắt:

Mục tiêu + acceptance criteria
Quy tắc nghiệp vụ chính
Feature phụ thuộc (sẵn sàng chưa)
Câu hỏi mở (chưa rõ → cần clarify trước)

Sau đó anh đóng repo này, mở repo source code và Claude tiếp tục context để impl.

Kiểm tra impact trước khi sửa

/check-impact auth-otp-login

Liệt kê:

depends_on — feature này cần feature nào có trước
impacts — sửa feature này ảnh hưởng feature nào
reverse_impacts — feature nào khác đang phụ thuộc vào nó
Cảnh báo nếu có feature shipped hoặc in-development bị ảnh hưởng

Sửa spec hiện có

Nói tự nhiên (skill feature-edit tự trigger):

Sửa feature auth-otp-login, thêm AC về voice OTP

Hoặc:

Cập nhật spec checkout-cart: bỏ phần OOS handling

Claude sẽ bảo toàn 9 heading (không cho thêm/xoá/đổi tên), gợi ý chạy impact-check trước.

Cập nhật status / metadata

Đổi status feature auth-otp-login thành in-development

Thêm depends_on auth-signup vào feature auth-otp-login

Claude validate status transition hợp lệ và sync frontmatter ↔ meta.json.

Status workflow (Dev tự cập nhật)

Status là báo cáo của Dev, không phải cổng kiểm duyệt của Boss. Dev tự đánh giá và update — Boss xem để biết tiến độ.

draft → ready → in-development → shipped
                                    ↓
                                 on-hold ↔ ready (rollback)
                                    ↓
                                deprecated

Sự kiện	Status mới	Ai làm
Mới tạo spec, đang viết	`draft`	Dev/PO viết
Spec đã đầy đủ 9 section, sẵn sàng impl	`ready`	Dev tự đánh giá
Bắt đầu code ở repo source	`in-development`	Dev báo
PR code merged vào production	`shipped`	Dev báo sau khi release
Tạm dừng (đổi ưu tiên / blocker)	`on-hold`	Dev hoặc PO
Không còn áp dụng	`deprecated`	Dev hoặc PO

Không có khái niệm “Boss approves” qua status. Nếu Boss muốn block scope, comment qua PR / GitHub Discussion — không gate qua status field.

CLI fallback (khi không có Claude Code)

Tạo feature mới

npm run new:feature -- <feature-id>

Lệnh trên scaffold folder với template chuẩn. Sau đó:

Mở docs/features/<feature-id>/spec.md, điền 9 section.
Mở meta.json, sửa title, owner, priority, platforms, note.
Chạy validate trước commit:

npm run validate
npm run generate:all

Validate trước commit

npm run validate

Check:

JSON Schema cho meta.json
9 heading bắt buộc + đúng thứ tự
Sync frontmatter spec.md ↔ meta.json
Internal link tới feature tồn tại

Generate artifacts cho CI

npm run generate:all

Sinh lại INDEX.md, impact-map.json, llms.txt. CI sẽ fail nếu các file này stale so với meta.json.

Khi sửa spec vs sửa code

Thay đổi gì	Sửa ở đâu
Business rule đổi	`spec.md` ở repo này
Acceptance criteria đổi	`spec.md` ở repo này
Scope đổi (thêm / bớt chức năng)	`spec.md` ở repo này
User flow đổi	`spec.md` (section Luồng chức năng)
Implementation detail (refactor, optimize)	Code ở repo source
Tech stack chọn lựa, DB schema, API design	ADR ở repo source — KHÔNG viết ở đây

Nếu sửa code mà behavior đổi → buộc phải sửa spec trước, sau đó mới sửa code.

Phát hiện spec sai / chưa rõ?

Tạo PR sửa docs/features/<id>/spec.md.
Trong PR description: nêu rõ điểm chưa rõ + đề xuất.
Tag Boss / PO trên PR.
Đừng impl trước khi spec được clarify.

Điều TỐI KỴ trong repo này

Không viết implementation plan, task code vào spec.md. Cái đó thuộc về repo source.
Không viết DB schema cụ thể, API endpoint signature. Đó thuộc về repo BE.
Không viết tech stack chọn lựa. Đó thuộc về ADR ở repo source.
Không thêm / đổi / xoá heading ## trong spec.md. 9 heading là cố định.
Không sửa file trong site/ thủ công. Đó là build output.

Khi Claude phát hiện anh đang yêu cầu viết thứ ngoài phạm vi → skill scope-guard tự kích hoạt và từ chối, chỉ đường về repo source.

Tóm tắt 6 skills tự động trigger

Tình huống	Skill	Ai cần gọi
”Tạo feature mới …”	`feature-create`	Auto
”Sửa feature X …”	`feature-edit`	Auto
”Đổi status / thêm depends_on …”	`meta-update`	Auto
”Feature X ảnh hưởng những gì …”	`impact-check`	Auto
User yêu cầu viết code plan / tech detail	`scope-guard`	Auto (refuse)
“Validate / check trước commit”	`validate-docs`	Auto

Skills tự trigger dựa trên ngôn ngữ tự nhiên — anh không cần nhớ tên skill, chỉ cần mô tả việc muốn làm.