144 lines
6.6 KiB
Markdown
144 lines
6.6 KiB
Markdown
# Hướng dẫn sử dụng — `sa-lifecycle` (điều phối)
|
||
|
||
## Skill này giải quyết gì
|
||
|
||
Bạn có một đống tài liệu kiến trúc rải rác, hoặc chưa có gì cả, và không biết bắt đầu từ đâu.
|
||
`sa-lifecycle` là **la bàn**: nó đọc hiện trạng, chấm gate, chỉ ra cái đang chặn, và nói đúng
|
||
một việc nên làm tiếp.
|
||
|
||
**Không làm ở skill này:** viết `SAD`, viết `ADR`, thiết kế bất cứ thứ gì. Thấy nó bắt đầu vẽ
|
||
kiến trúc ⇒ nó đã lấn sân `sa-2-architecture`.
|
||
|
||
## Khi nào gọi
|
||
|
||
| Tình huống | Có nên gọi |
|
||
|---|---|
|
||
| Bắt đầu một dự án kiến trúc mới | ✅ Gọi đầu tiên — nó tạo cây thư mục và nói cần chuẩn bị gì |
|
||
| Quay lại dự án sau 2 tuần, quên đang làm gì | ✅ Đúng mục đích |
|
||
| Trước khi trình một gate | ✅ Chấm gate trước, đỡ bị trả về |
|
||
| Nhận bàn giao kiến trúc từ người khác | ✅ Chạy chế độ rà soát toàn bộ |
|
||
| Đã biết rõ cần viết ADR nào | ❌ Gọi thẳng `/sa-2-architecture` |
|
||
| Cần trả lời một câu hỏi kỹ thuật cụ thể | ❌ Hỏi thẳng, không cần skill |
|
||
|
||
## Cú pháp
|
||
|
||
```
|
||
/sa-lifecycle <PROJECT> [--mode status|init|audit] [--out <đường-dẫn>] [go]
|
||
```
|
||
|
||
| Tham số | Ý nghĩa |
|
||
|---|---|
|
||
| `--mode status` | *(mặc định)* Chấm gate, chỉ việc tiếp theo |
|
||
| `--mode init` | Khởi tạo cây thư mục `sa-output/<PROJECT>/` cho dự án mới |
|
||
| `--mode audit` | Rà soát toàn bộ: chấm `D1–D12` cho từng artifact + coverage |
|
||
| `--out <path>` | Đổi nơi ghi, mặc định `sa-output/` trong thư mục làm việc |
|
||
| `go` | Bỏ bước dừng xác nhận input |
|
||
|
||
Ví dụ:
|
||
|
||
```
|
||
/sa-lifecycle Settlement
|
||
/sa-lifecycle Settlement --mode init
|
||
/sa-lifecycle Settlement --mode audit --out .docs/architecture
|
||
```
|
||
|
||
## Chuẩn bị gì trước khi gọi
|
||
|
||
**Tối thiểu:** tên dự án. Không có gì khác cũng chạy được — nó sẽ nói bạn thiếu gì.
|
||
|
||
**Nên có:** thư mục `ba-output/<PROJECT>/` nếu bộ BA đã chạy. Skill đối chiếu chéo hai bộ và
|
||
đây là chỗ nó tạo ra giá trị lớn nhất — phát hiện `NFR` của BA chưa được lượng hoá, `API` đề
|
||
xuất chưa ai xác nhận, `RBAC` chưa map xuống cơ chế kỹ thuật.
|
||
|
||
## Bạn sẽ nhận được gì
|
||
|
||
Ba bảng in ra màn hình:
|
||
|
||
```
|
||
① Bảng trạng thái artifact — loại · file · version · status · confidence · ghi chú
|
||
② Bảng chấm gate hiện tại — ☐/✅ từng tiêu chí, kèm "thiếu gì, ai cung cấp"
|
||
③ Một khuyến nghị — việc tiếp theo + lệnh chạy + cần chuẩn bị gì + ai phải trả lời
|
||
```
|
||
|
||
Cộng với file `00-index/INDEX_<PROJECT>.md` được cập nhật. Ở `--mode init`, thêm cây thư mục
|
||
và 6 file khung trong `00-index/`.
|
||
|
||
## Đọc bảng chấm gate thế nào
|
||
|
||
```
|
||
AG2 — Ready for Build · duyệt bởi Tech Lead + Security + Ops
|
||
✅ ASR 12 mục, mọi mục truy về DRV hoặc QAS
|
||
❌ QAS 9 NFR, 7 còn định tính ("nhanh", "ổn định") → chặn
|
||
✅ SAD C4 Context + Container, 8 CMP có trách nhiệm rõ
|
||
⚠️ ADR 11 ADR, ADR-009 điểm radar 9 nhưng chưa có POC → cần POC
|
||
❌ SEC chưa có threat model → chặn
|
||
```
|
||
|
||
- ✅ đạt · ❌ chặn gate, phải làm · ⚠️ chưa chặn nhưng sẽ chặn nếu không xử lý
|
||
- Mục ❌ luôn kèm **cái thiếu cụ thể**, không phải "chưa đầy đủ"
|
||
|
||
## Ví dụ hội thoại
|
||
|
||
```
|
||
Bạn: /sa-lifecycle Settlement
|
||
|
||
Claude: [Bước 0]
|
||
Quét được:
|
||
| sa-output/Settlement/ | Chưa tồn tại | — |
|
||
| ba-output/Settlement/ | Có: BRIEF v1.0 ✅, BACKLOG v1.1 ✅, SRS_US059 v1.0 🟠 | Cao |
|
||
|
||
Phân loại: dự án kiến trúc MỚI, nhưng BA đã qua G2.
|
||
Đề xuất ghi vào: sa-output/Settlement/
|
||
Xác nhận giúp tôi đường dẫn này.
|
||
|
||
Bạn: ok
|
||
|
||
Claude: [tạo cây thư mục + 6 file index rỗng]
|
||
|
||
① Trạng thái: chưa có artifact kiến trúc nào.
|
||
|
||
② Gate AG1 — 0/7 mục đạt.
|
||
|
||
③ Việc tiếp theo: /sa-1-context Settlement
|
||
Cần chuẩn bị:
|
||
- Ngân sách hạ tầng được duyệt (tháng/năm) — hỏi PO
|
||
- Ràng buộc cloud/stack của Kakao — hỏi Tech Lead
|
||
- Số giao dịch POS/ngày hiện tại — có trong BRIEF §3? cần xác nhận
|
||
- Ai vận hành hệ thống sau go-live — chưa rõ, hỏi PM
|
||
|
||
⚠️ Đối chiếu BA: SRS_US059 đang 🟠 In Review và có API contract đánh dấu
|
||
"BA đề xuất — chờ BE xác nhận". Người xác nhận là bạn, qua ICD ở GĐ2.
|
||
```
|
||
|
||
## Lỗi thường gặp
|
||
|
||
**"Nó bảo tôi chưa qua AG1 nhưng tôi đã thiết kế xong hết rồi."**
|
||
Kiểm tra header các file: `Status` có phải `✅ Baselined` không, `Approved by` có tên người ký
|
||
không. Gate đọc header, không đọc nội dung. Thiết kế xong mà chưa ai ký thì chưa qua gate —
|
||
đó chính là điều gate tồn tại để phát hiện.
|
||
|
||
**"Tôi không có bộ BA, chỉ có yêu cầu trong đầu."**
|
||
Chạy được, nhưng mọi `DRV` sẽ là 🔴 giả định. Cách rẻ nhất để sửa: viết `CTX` với `Confidence`
|
||
🔴, đem đi hỏi PO, rồi nâng lên 🟢. Đừng chờ có BA đầy đủ mới bắt đầu.
|
||
|
||
**"Nó đề xuất một việc, nhưng tôi thấy việc khác gấp hơn."**
|
||
Cứ làm việc bạn thấy gấp hơn. Khuyến nghị dựa trên gate, không dựa trên áp lực thực tế của
|
||
bạn. Nhưng nếu việc bạn làm bỏ qua một mục ❌, nó sẽ quay lại chặn ở gate — biết trước vẫn hơn.
|
||
|
||
**"`--mode audit` in ra quá nhiều lỗi."**
|
||
Bình thường với tài liệu kế thừa. Đọc theo mức: xử 🔴 trước, 🟠 trước release, 🟡 ghi vào
|
||
`TDEBT` để làm dần. Đừng cố xanh hết trong một lần.
|
||
|
||
## Ra khỏi skill này khi nào
|
||
|
||
Skill này không có gate. Bạn rời nó ngay khi có câu trả lời cho "làm gì tiếp", rồi chạy skill
|
||
giai đoạn tương ứng. Quay lại nó sau mỗi lần qua gate để cập nhật `INDEX`.
|
||
|
||
## Liên quan
|
||
|
||
- Định nghĩa 4 gate: `references/workflow.md` §2
|
||
- Artifact nào ở đâu, header bắt buộc: `references/artifact-map.md`
|
||
- 12 quy tắc viết: `references/design-rules.md`
|
||
- Quyết định nào cần ADR: `references/decision-radar.md`
|
||
- Bộ BA tương ứng: `../ba-lifecycle/GUIDE.md`
|