175 lines
9.3 KiB
Markdown
175 lines
9.3 KiB
Markdown
# Hướng dẫn sử dụng — `sa-4-evolution` (Giai đoạn 4)
|
||
|
||
## Giai đoạn này giải quyết gì
|
||
|
||
Hệ thống đã chạy thật. Câu hỏi bây giờ không còn là "thiết kế thế nào" mà là **"kiến trúc ta
|
||
thiết kế và kiến trúc đang chạy có phải một không"**.
|
||
|
||
Đầu vào là số liệu vận hành thật. Đầu ra là **bảng đối chiếu cam kết × thực tế**, và một
|
||
roadmap kỹ thuật PO duyệt được.
|
||
|
||
**Không làm ở giai đoạn này:** thiết kế lại hệ thống (đó là vòng mới, quay về `sa-1-context`),
|
||
post-mortem vận hành (thuộc SRE — ở đây chỉ làm phần kiến trúc).
|
||
|
||
## Khi nào gọi
|
||
|
||
| Tình huống | Có nên gọi |
|
||
|---|---|
|
||
| Một tháng sau go-live | ✅ `--focus conf` — lần đối chiếu đầu tiên |
|
||
| Định kỳ hàng tháng | ✅ `--focus conf` |
|
||
| Hoá đơn cloud tăng bất thường | ✅ `--focus conf`, đọc §b trước |
|
||
| Vừa có sự cố nghiêm trọng | ✅ `--focus review` sau khi SRE xong post-mortem vận hành |
|
||
| Lập kế hoạch quý | ✅ `--focus roadmap` |
|
||
| Đánh giá kiến trúc định kỳ | ✅ `--focus review` mỗi quý |
|
||
| Cần thiết kế một hệ thống mới | ❌ `/sa-1-context` |
|
||
| Chưa có telemetry gì | ⚠️ Chạy được, nhưng `CONF` sẽ toàn "chưa đo được" — đó cũng là một phát hiện |
|
||
|
||
## Cú pháp
|
||
|
||
```
|
||
/sa-4-evolution <PROJECT> [--focus conf|roadmap|review] [--period 2026-09] [--out <path>] [go]
|
||
```
|
||
|
||
| Tham số | Ý nghĩa |
|
||
|---|---|
|
||
| `--focus conf` | Đối chiếu `QAS`/`TCO`/sự cố/drift với thực tế |
|
||
| `--focus roadmap` | Lập `TRM` từ phát hiện của `CONF` |
|
||
| `--focus review` | Đánh giá kiến trúc định kỳ hoặc post-mortem sau sự cố |
|
||
| `--period <YYYY-MM>` | Kỳ đối chiếu, mặc định tháng gần nhất |
|
||
| `go` | Bỏ bước dừng xác nhận input |
|
||
|
||
```
|
||
/sa-4-evolution Settlement --focus conf --period 2026-09
|
||
/sa-4-evolution Settlement --focus review "sự cố INC-2026-0912: batch đối soát chạy 3 giờ, chặn báo cáo sáng"
|
||
```
|
||
|
||
## Chuẩn bị gì trước khi gọi
|
||
|
||
🔴 **Đây là giai đoạn phụ thuộc dữ liệu nhiều nhất.** Không có số thì skill chỉ in ra bảng
|
||
trống — và đó là kết luận, không phải lỗi.
|
||
|
||
| Cần | Lấy ở đâu | Dùng cho |
|
||
|---|---|---|
|
||
| Số đo p50/p95/p99 các thao tác chính | APM / dashboard | `QAS` × thực tế |
|
||
| Uptime thật + tổng downtime trong kỳ | uptime monitor | `QAS` sẵn sàng |
|
||
| Thông lượng thật, đỉnh trong kỳ | metric | `QAS` thông lượng |
|
||
| **Hoá đơn cloud chi tiết theo dịch vụ** | cổng thanh toán cloud | `TCO` × thực tế |
|
||
| Danh sách sự cố trong kỳ + nguyên nhân | log sự cố / ticket | Sự cố × `ADR` |
|
||
| Lịch sử `FIT` trên CI | CI | Drift |
|
||
| Trace/log để biết interface thật đang gọi nhau thế nào | tracing | Drift |
|
||
|
||
## Bạn sẽ nhận được gì
|
||
|
||
```
|
||
sa-output/<PROJECT>/04-evolution/
|
||
├── CONF_<PROJECT>_<YYYY-MM>.md ← mỗi kỳ một file, không ghi đè
|
||
├── TRM_<PROJECT>_v1.0.md ← roadmap, lên version
|
||
└── PMR_<PROJECT>_<YYYY-Qn>.md ← đánh giá định kỳ
|
||
PMR_<PROJECT>_<INC-id>.md ← post-mortem sau sự cố
|
||
```
|
||
|
||
## Đọc bảng đối chiếu thế nào
|
||
|
||
```
|
||
QAS × thực tế · kỳ 2026-09
|
||
┌──────────┬──────────────────┬──────────────┬──────────┬─────────────────────────┐
|
||
│ QAS-001 │ p95 ≤ 300ms │ p95 = 240ms │ ✅ đạt │ │
|
||
│ QAS-004 │ batch ≤ 45 phút │ 52 phút │ ❌ │ TD-05 · TRM mục 1 │
|
||
│ QAS-007 │ SLA 99.9% │ 99.94% │ ✅ đạt │ downtime 26/43 phút │
|
||
│ QAS-011 │ cảnh báo ≤ 3 phút│ chưa đo được │ ⚠️ │ thiếu bài đo — bài học │
|
||
└──────────┴──────────────────┴──────────────┴──────────┴─────────────────────────┘
|
||
```
|
||
|
||
- ✅ đạt · ❌ không đạt ⇒ vào `TRM` · ⚠️ **chưa đo được** ⇒ AG2 định nghĩa cách đo không khả
|
||
thi, hoặc observability thiếu
|
||
|
||
⚠️ **không xấu hơn ❌.** Nó xấu hơn: ❌ ta biết mình đang ở đâu, ⚠️ ta không biết gì cả.
|
||
|
||
## Ví dụ hội thoại
|
||
|
||
```
|
||
Bạn: /sa-4-evolution Settlement --focus conf --period 2026-09
|
||
Đính kèm: hoá đơn AWS tháng 9, export dashboard Grafana, log sự cố
|
||
|
||
Claude: [Bước 0]
|
||
Input: QAS v1.1 ✅, TCO v1.0 ✅, hoá đơn AWS 09/2026, Grafana export, 3 sự cố.
|
||
Đủ để đối chiếu QAS (8/11 mục) và TCO (đầy đủ).
|
||
Thiếu: bài đo cho QAS-009 và QAS-011 (observability) → sẽ ghi "chưa đo được".
|
||
Xác nhận ghi vào CONF_Settlement_2026-09.md?
|
||
|
||
Bạn: ok
|
||
|
||
Claude: ② QAS × thực tế: 6 đạt · 2 không đạt · 3 chưa đo được
|
||
|
||
③ TCO × hoá đơn:
|
||
| Compute | ước 4,2tr | thật 4,0tr | −5% ✅ |
|
||
| CSDL | ước 3,5tr | thật 3,3tr | −6% ✅ |
|
||
| Observability | ước 1,0tr | thật 3,8tr | +280% 🔴 |
|
||
| Egress | ước 0,5tr | thật 2,1tr | +320% 🔴 |
|
||
| Tổng | ước 11tr | thật 15,4tr| +40% |
|
||
|
||
Truy nguyên hai khoản vượt:
|
||
- Observability: đang giữ log 90 ngày, INF §8 thiết kế 30 ngày.
|
||
→ drift cấu hình. Giảm về 30 ngày tiết kiệm ~2,5tr/tháng.
|
||
- Egress: báo cáo tải file PDF trực tiếp từ service, không qua CDN.
|
||
→ không có trong thiết kế. Không thuộc 4 loại lý do hợp lệ ⇒ có thứ
|
||
chạy mà thiết kế không biết. Cần xác nhận với dev.
|
||
|
||
④ Sự cố:
|
||
- INC-0912 (batch 3 giờ) → truy về QAS-004 không đạt, đã biết trước
|
||
- INC-0918 (5xx 12 phút) → truy về ASM-04 "API POS luôn trả trong 2s" SAI
|
||
thực tế có lúc 30s ⇒ FM-02 timeout đặt quá cao
|
||
- INC-0925 (sai số báo cáo) → 🔴 ĐIỂM MÙ MỚI: cache không invalidate khi
|
||
sửa đơn hàng cũ. DAT §7 không nói tới trường hợp này.
|
||
|
||
Điểm mù mới là phát hiện giá trị nhất kỳ này → đề xuất QAS mới + FIT mới.
|
||
|
||
▶ Ba mục đầu cho TRM (PO xếp thứ tự):
|
||
1. Giảm retention log về 30 ngày · 0,5 ngày công · −2,5tr/tháng
|
||
2. Đưa tải file qua CDN · 3 ngày công · −1,8tr/tháng
|
||
3. Sửa chiến lược cache · 5 ngày công · ngăn tái diễn INC-0925
|
||
```
|
||
|
||
## Lỗi thường gặp
|
||
|
||
**"Không có dashboard, không đo được gì."**
|
||
Vậy kết luận của kỳ này là *"hệ thống đang chạy mà không ai biết nó chạy thế nào"* — một phát
|
||
hiện nghiêm trọng và đáng trình. Mục đầu tiên của `TRM` là dựng observability.
|
||
|
||
**"Chi phí vẫn trong ngân sách nên không cần xem."**
|
||
Trong ngân sách nhưng gấp 3 lần ước lượng nghĩa là mô hình chi phí sai — và nó sẽ sai tiếp,
|
||
lớn hơn, khi tải tăng. Truy nguyên chênh lệch kể cả khi chưa vượt.
|
||
|
||
**"Sự cố do dev quên đặt timeout, không phải lỗi kiến trúc."**
|
||
Câu hỏi kiến trúc không phải "ai quên" mà "vì sao hệ thống cho phép một lời gọi không timeout
|
||
tồn tại". Câu trả lời thường là một `FIT` mới — và nó ngăn cả lớp lỗi đó, không chỉ một lần.
|
||
|
||
**"PO không duyệt mục nào trong roadmap kỹ thuật."**
|
||
Roadmap đang viết bằng ngôn ngữ kỹ thuật. Đổi "tái cấu trúc module Order" thành "giảm 2 ngày
|
||
cho mỗi tính năng chạm Order; quý tới có 6 tính năng như vậy ⇒ tiết kiệm 12 ngày". PO duyệt
|
||
con số, không duyệt danh từ kỹ thuật.
|
||
|
||
**"ADR-005 hoá ra sai, tôi sửa lại nội dung cho đúng."**
|
||
Đừng. Viết `ADR` mới có `Supersedes: ADR-005`, đổi trạng thái bản cũ thành `Superseded by`.
|
||
Giá trị lớn nhất của ADR là ghi lại điều ta *đã tin* lúc đó — sửa đi là xoá mất bài học.
|
||
|
||
## Ra khỏi giai đoạn này khi nào
|
||
|
||
Đủ cả bốn:
|
||
|
||
1. Bảng tự chấm AG4 toàn ✅
|
||
2. **PO + SRE + EA** đã ký
|
||
3. Mọi sự cố trong kỳ đã truy về `ADR`, `ASM`, hoặc được ghi nhận là điểm mù mới
|
||
4. `TRM` đã được PO xếp thứ tự và các mục đầu đã vào backlog
|
||
|
||
Sau đó: quay lại `--focus conf` ở kỳ tiếp theo, hoặc mở vòng kiến trúc mới bằng
|
||
`/sa-1-context` nếu driver kinh doanh đã đổi.
|
||
|
||
## Liên quan
|
||
|
||
- Tiêu chí gate AG4: `../sa-lifecycle/references/workflow.md` §2
|
||
- Nhịp chạy đề xuất: `../sa-lifecycle/references/workflow.md` §7
|
||
- Vòng đời ADR: `../sa-lifecycle/references/artifact-map.md` §4
|
||
- Template: `templates/conformance-report.md` · `templates/technical-roadmap.md` ·
|
||
`templates/architecture-review.md`
|