Quy trình phát triển (Tài liệu trước)
Một luồng, bắt buộc. Mọi thay đổi không tầm thường đều đi qua sáu pha như nhau, theo thứ tự, mỗi pha tạo ra một tài liệu tại một vị trí chuẩn. Tài liệu được viết trước code và được sửa trong lúc triển khai nếu thực tế khác đi — không bỏ qua, không tự do tùy tiện.
1. Nguyên tắc
| Nguyên tắc | Ý nghĩa |
|---|---|
| Tài liệu trước | Yêu cầu và ý định được viết trước khi triển khai. Bắt đầu trong docs/wiki, không phải trong code. |
| Một vị trí cho một loại tài liệu | Mỗi loại tài liệu có đúng một vị trí (bảng bên dưới). Không rải spec/plan tự do khắp repo. |
| Truy vết được | Mỗi tài liệu mang ID và liên kết tiến/lùi dọc xương sống, để theo dõi một tính năng roadmap → URD → PRD → ADR → Plan → code → test. |
| Code là sự thật | Khi đã build, tài liệu mô tả hành vi thực tế đã kiểm chứng. Nếu triển khai cho thấy tài liệu sai, sửa tài liệu trong cùng thay đổi đó — tài liệu và code không bao giờ lệch. |
| Có cổng kiểm soát | Mỗi pha có định nghĩa hoàn thành phải thỏa mãn trước khi sang pha kế. |
2. Luồng
| # | Pha | Tài liệu | Vị trí chuẩn | Chịu trách nhiệm | Cổng sang pha kế |
|---|---|---|---|---|---|
| 1 | Yêu cầu | URD | content/{en,vi}/modules/<tier>/<module>/urd.md | PM/PO/BA | Yêu cầu chức năng có ID URD-<AREA>-NNN + MoSCoW + tiêu chí chấp nhận |
| 2 | Phạm vi đợt | PRD | …/<module>/prds/YYYY-MM-DD-<slug>.md | PM/PO | Trích dẫn các URD ID nó giao; mục tiêu/không mục tiêu, UX/luồng, rollout |
| 3 | Kiến trúc (chỉ khi không tầm thường) | ADR | content/{en,vi}/developer/packages/<pkg>/decisions/NNNN-<slug>.md | Eng | Quyết định + phương án + hệ quả; liên kết từ PRD |
| 4 | Kế hoạch triển khai | Plan | .agents/plans/YYYY-MM-DD-<module>-<slug>.md | Eng | Từng bước; mỗi bước trích URD ID / ADR; kiểm chứng theo bước |
| 5 | Code | source | packages/*, apps/*, third-parties/* | Eng | Build xanh (bun run rebuild), lint 0 |
Brainstorm không có vị trí riêng. Khám phá thiết kế kết tinh vào PRD (ý định sản phẩm) và ADR (quyết định kiến trúc). Không có file "spec" độc lập — xem §5.
3. Khi nào áp dụng pha nào?
| Loại thay đổi | URD | PRD | ADR | Plan | Test cases |
|---|---|---|---|---|---|
| Module mới / tính năng lớn | ✅ | ✅ | nếu không tầm thường | ✅ | ✅ |
| Đợt tính năng trong module có sẵn | cập nhật | ✅ | nếu không tầm thường | ✅ | cập nhật |
| Chỉ đổi kiến trúc (không đổi hành vi người dùng) | — | — | ✅ | ✅ | nếu test được |
| Sửa lỗi / thay đổi cơ học nhỏ | — | — | — | tùy chọn | cập nhật nếu hành vi đổi |
"Không tầm thường" = bất cứ thứ gì đưa vào một pattern, một hợp đồng liên-package, một migration dữ liệu, hoặc một quyết định mà kỹ sư tương lai sẽ hỏi "tại sao?". Khi nghi ngờ, hãy viết ADR.
4. Xương sống truy vết
Chuỗi được neo bởi khối truy vết ở đầu mỗi index.md của module (xem Quy ước Module §6.1). Khối đó nay mang thêm link Plan để bước kỹ thuật cũng nằm trên xương sống:
> | Chuỗi | Link |
> |-------|------|
> | Roadmap | [Phase 1](/vi/delivery/roadmap#phase-1) |
> | URD | [URD](./urd) |
> | PRD | [PRD-XXX-001](./prds/2026-06-04-...) |
> | Decisions (ADR) | [ADR-0001](/vi/developer/packages/<pkg>/decisions/0001-...) |
> | Plan | [.agents/plans/2026-06-04-<module>-...](…) |
> | Dev docs | [@nx/<pkg>](/vi/developer/packages/<pkg>/) |
> | Runbook | [<module> ops](/vi/runbook/operations/) |
> | Delivery log | [Traceability matrix](/vi/delivery/traceability-matrix) |ID khớp nhau giữa các tài liệu qua mã <AREA>: URD-STK-001 ↔ TC-STK-001 ↔ PRD-STK-001. Xem Quy ước Module §6.
5. Một vị trí cho một loại tài liệu (không tự do)
| Tài liệu | Vị trí DUY NHẤT | Đã bỏ / không dùng |
|---|---|---|
| Yêu cầu | module urd.md | ghi chú yêu cầu tùy tiện |
| Ý định sản phẩm / đợt | module prds/ | docs/superpowers/specs/, "design.md" nháp |
| Quyết định kiến trúc | developer/packages/<pkg>/decisions/ (ADR) | ghi chú thiết kế trong code/PR |
| Kế hoạch triển khai | .agents/plans/ | docs/superpowers/plans/, docs/plans/ |
docs/superpowers/đã bị bỏ. Brainstorm tạo ra PRD (+ ADR); viết plan tạo ra file.agents/plans/. Cả hai liên kết vào xương sống module.
6. Làm việc theo luồng với agent
- Bắt đầu mọi tính năng trong
docs/wiki— viết/mở rộng URD, rồi PRD. Chỉ sau khi PRD được thống nhất mới viết plan; chỉ sau khi có plan mới viết code. - Brainstorming (đối thoại thiết kế) kết thúc bằng việc viết PRD (và ADR nếu có kiến trúc), không phải spec độc lập.
- Viết plan kết thúc bằng file
.agents/plans/, được PRD liên kết tới. - Trong lúc triển khai, nếu code cho thấy tài liệu sai, sửa tài liệu trong cùng thay đổi trước khi tiếp tục. Tài liệu được sửa, không bị bỏ.
7. Liên quan
- Cấu trúc tài liệu Developer — phần dành cho kỹ sư
- Delivery — Roadmap · Traceability Matrix
_template/— bộ khung sao chép cho module mới