understand-questions

Mục tiêu: tạo file understand-questions.md ở root project — bộ Q&A onboarding cho dev mới, trả lời các câu hỏi thực dụng kiểu "làm sao để chạy", "cần config gì", "nó dùng để làm gì", "luồng hoạt động ra sao". KHÔNG phải audit risk (đó là deep-questions), KHÔNG phải architecture report (đó là project-discovery).

Phân biệt với 2 skill anh em:

• project-discovery → kiến trúc + dependency graph (cho architect)
• deep-questions → GOLIVE risk audit (cho release manager)
• understand-questions → practical onboarding (cho dev mới gia nhập)

Nguyên tắc

• Người mới hỏi gì cần đúng thứ đó: câu hỏi phải bắt nguồn từ "tôi vừa clone repo về, giờ phải làm gì". Tránh câu hỏi học thuật
• Stepped progression: Từ "chạy được" → "hiểu use case" → "hiểu flow" → "hiểu sâu". Người đọc có thể dừng ở STEP nào cũng có giá trị
• Bằng chứng từ code: Mọi câu trả lời phải có path/file:line. Không paraphrase README
• Fan-out 1 message: TẤT CẢ câu hỏi spawn sub-agent trong 1 message duy nhất
• Bảng khi liệt kê: Tham số/use case/endpoint phải dạng table, không phải prose
• Không tạo file phụ: Chỉ ghi understand-questions.md

Phase 1: Project recon (1 message song song)

• Read: README.md, CLAUDE.md, AGENTS.md, discovery.md, how-to-run.md (nếu có)
• Glob manifest: Cargo.toml, package.json, go.mod, pyproject.toml, *.csproj, Dockerfile*, Makefile, justfile
• Glob entry hint: main.rs, main.go, index.ts, app.py, __main__.py, server.ts, cmd/**/main.go
• Glob config: .env*, config/*, settings*.json, *.yaml, *.toml
• Bash: git log --oneline -5

Sau Phase 1 phải xác định được loại project để tuỳ biến STEP — CLI / web service / library / desktop app / batch job đều có question set hơi khác.

Phase 2: Bộ câu hỏi 8 STEP (chuẩn)

Đây là question bank — chọn câu phù hợp loại project, có thể bỏ STEP không liên quan (vd library bỏ STEP 6 deploy).

STEP 0 — Hiểu nhanh (Quick start)

0.1. Làm thế nào để khởi động chương trình từ trong IDE? (lệnh, debug config, entry point) 0.2. Liệt kê tất cả tham số cấu hình bắt buộc và tuỳ chọn dạng bảng: STT | Tên | Mục đích | Miền giá trị | Default | Giá trị tối ưu | Bắt buộc? 0.3. Làm thế nào để biết chương trình khởi động thành công? (log dòng nào, port nào, health endpoint nào, file flag nào) 0.4. Chương trình có cho phép nhiều người/nhiều instance chạy đồng thời không? Có lock file / port conflict không? 0.5. Có thể biết chương trình đang chạy ở phiên/instance nào một cách tường minh không? (PID file, session ID, hostname log) 0.6. Lệnh dừng chương trình an toàn? Có graceful shutdown không?

STEP 1 — Hiểu use cases (What & Why)

1.1. Chương trình này dùng để làm gì? Mô tả 1 đoạn cho người không phải dev hiểu 1.2. Liệt kê 5 kịch bản sử dụng hữu ích nhất mang lại lợi ích cụ thể cho người dùng cuối, mỗi kịch bản kèm ví dụ lệnh/luồng thao tác 1.3. Không nên dùng nó cho việc gì? (anti-use-case, scope giới hạn) 1.4. Đối tượng người dùng là ai? (CLI dev / end user / SRE / data engineer...)

STEP 2 — Hiểu luồng hoạt động (Runtime flow)

2.1. Entry point chính là hàm nào, file nào? (main, init, bootstrap) 2.2. Quá trình khởi động chi tiết gồm những bước nào theo thứ tự? Khi nào và mất bao lâu thì coi là khởi động xong? 2.3. Khi nhận 1 request/lệnh từ user, đường đi qua các module/lớp nào? Vẽ flow ASCII đơn giản 2.4. Khi gặp lỗi runtime, lỗi đi đâu? In ra log nào, mã trả về gì, có tự retry không? 2.5. Quá trình shutdown gồm những bước nào? Có cleanup resource không?

STEP 3 — Hiểu dữ liệu (State & data)

3.1. Chương trình có lưu state ở đâu? (DB, file, in-memory, OS keychain) 3.2. Schema/format dữ liệu chính trông như thế nào? (1 ví dụ JSON/SQL/struct) 3.3. Có cache không? Cache invalidation khi nào? 3.4. Khi xoá toàn bộ state thì điều gì xảy ra? Có migrate / re-init tự động không?

STEP 4 — Hiểu tích hợp (External integrations)

4.1. Chương trình gọi ra ngoài những service/API nào? (DB, third-party API, message queue, file system, network) 4.2. Mỗi integration cần credential/config gì? (env var, secret file) 4.3. Khi external service offline thì hành vi ra sao? (fail-fast / degrade / queue / retry) 4.4. Có expose endpoint/interface gì cho bên ngoài không? (HTTP, gRPC, WebSocket, IPC, MCP, plugin)

STEP 5 — Hiểu cách kiểm tra (How to verify it works)

5.1. Sau khi chạy, làm sao biết nó đang work đúng? (smoke test, ví dụ command, expected output) 5.2. Test suite chạy thế nào? Bao lâu? Cần setup gì? 5.3. Có dataset/fixture mẫu để thử không? 5.4. Cách reproduce 1 luồng end-to-end đơn giản nhất từ A → Z

STEP 6 — Hiểu cách deploy (Build & ship) — bỏ nếu là library

6.1. Build artifact ở đâu, dạng gì? (target/release/, dist/, container image, RPM, MSI) 6.2. Lệnh build cho production khác lệnh build dev thế nào? 6.3. Quy trình deploy chuẩn lên môi trường (dev/staging/prod) gồm những bước gì? 6.4. Rollback thế nào? Có version trong artifact để check không?

STEP 7 — Hiểu observability & debug

7.1. Log đi đâu? Format gì? Có level config được không? 7.2. Khi cần debug, bật verbose/trace bằng flag/env nào? 7.3. Có metrics/health endpoint không? Tên metric quan trọng nhất? 7.4. Khi crash, để lại trace/dump ở đâu?

STEP 8 — Hiểu dev loop (Contribute)

8.1. Setup dev environment cần gì? (toolchain, version, OS) 8.2. Edit-build-test-rerun loop mất bao lâu trên 1 thay đổi nhỏ? 8.3. Linter/formatter nào bắt buộc? Pre-commit hook? 8.4. Quy ước commit/branch/PR? Có CI nào sẽ chạy?

Quy tắc chọn câu theo loại project:

• CLI tool: full STEP 0–8, bỏ 4.4 endpoint
• Web service: full, nhấn mạnh STEP 0.3 (port/health), 4.4 (endpoints), 7
• Library: bỏ STEP 0.3–0.6, STEP 6 (deploy), giữ STEP 1, 2.1, 5, 8
• Desktop app: bỏ STEP 0.4 multi-instance (thường no), bỏ STEP 6 thay bằng "đóng gói installer"
• Batch job: nhấn STEP 2.2 startup time, STEP 3 state, STEP 7 logs

Số câu cuối: thường 15–25. Không cố nhồi đủ.

Phase 3: Fan-out sub-agent (1 message)

Spawn Agent (subagent_type=Explore) cho mỗi câu hỏi. Tất cả trong cùng 1 message.

Brief template:

Câu hỏi onboarding: <câu hỏi đầy đủ> STEP: <STEP X — tên>

Nhiệm vụ: Trả lời câu hỏi trên cho 1 dev vừa clone repo <project_root> về, chưa biết gì. Phải mở code thật, KHÔNG paraphrase README.

Cách làm:

1. Tìm file/section liên quan (Glob/Grep targeted)
2. Đọc và trích đoạn code/config làm bằng chứng
3. Nếu README/doc đã trả lời, vẫn phải verify bằng code và bổ sung chi tiết doc thiếu
4. Nếu không tìm thấy → ghi rõ "không có / chưa implement" — đó là câu trả lời hợp lệ

Format trả lời (Markdown, tiếng Việt có dấu, ≤350 từ):

#### Trả lời
<2-4 câu trực tiếp, không lan man>

#### Bằng chứng
- `path/file.ext:line` — mô tả ngắn
- <code block ngắn nếu cần>

#### Lệnh/ví dụ cụ thể (nếu có)
```bash
<command thực tế chạy được>

Lưu ý cho dev mới

<1-2 bullet warning hoặc tip — vd "phải set env X trước khi chạy")

**Yêu cầu đặc biệt**:
- Câu hỏi liệt kê tham số/use case/endpoint → BẮT BUỘC dùng bảng Markdown
- Câu hỏi flow → vẽ ASCII đơn giản hoặc danh sách số bước
- Câu hỏi "bao lâu" → đo bằng cách đọc code (timeout config, sleep, polling interval) hoặc ghi "(chưa đo được)"

**Giới hạn**: Đọc tối đa 10 file. Không sửa code. Báo cáo ≤350 từ.

Self-check trước khi gửi: số agent gọi trong 1 message phải bằng số câu hỏi đã chọn ở Phase 2. Nếu định chia nhiều message là sai pattern — sửa ngay.

Phase 4: Tổng hợp & ghi understand-questions.md

Template output:

# <PROJECT_NAME> — Understand Questions

> Generated by understand-questions skill on YYYY-MM-DD
> Onboarding Q&A cho dev mới · <N> câu hỏi qua <S> STEP

## Bắt đầu nhanh (TL;DR)

- **Chương trình này là gì**: <1 câu từ STEP 1.1>
- **Chạy thế nào**: <command từ STEP 0.1>
- **Verify đã chạy**: <từ STEP 0.3>
- **Stop**: <từ STEP 0.6>

---

## STEP 0 — Hiểu nhanh

### 0.1. Làm thế nào để khởi động chương trình từ trong IDE?
<paste nguyên report của sub-agent>

### 0.2. Tham số cấu hình
<paste — bảng tham số phải nằm gọn trong section này>

### 0.3. ...

---

## STEP 1 — Hiểu use cases

### 1.1. ...

...

## Câu hỏi không trả lời được

<liệt kê các câu sub-agent ghi "không tìm thấy / chưa implement" — đây là gap document thực sự>

Quy tắc viết:

• TL;DR ở đầu bắt buộc — 4 dòng đủ để dev quyết định có đáng học tiếp không
• Section "Câu hỏi không trả lời được" ở cuối — chính là TODO cho team viết doc
• Giữ nguyên bảng/code block từ sub-agent, không reformat
• Cuối file: link sang discovery.md và deep-questions.md nếu tồn tại

Phase 5: Báo cáo

Sau khi Write understand-questions.md:

1. wc -l understand-questions.md
2. Tóm tắt: số câu hỏi, số STEP cover, số câu "không trả lời được"
3. Highlight 3 phát hiện thú vị nhất cho dev mới (vd: "phải set env X trước khi chạy", "khởi động mất ~3s vì lazy load model")

KHÔNG commit, KHÔNG push, KHÔNG sửa file khác.

Anti-patterns

Test thực tế

Skill phát triển trên claurst (Rust CLI multi-provider, có TUI, MCP, plugin). Chạy skill trên claurst phải sinh understand-questions.md với:

• TL;DR 4 dòng
• ≥15 câu hỏi qua ≥6 STEP
• STEP 0.2 phải có bảng tham số từ ~/.claurst/settings.json schema
• STEP 1.2 phải có 5 kịch bản cụ thể (vd: "code review với multi-provider", "MCP integration với DB", ...)
• STEP 2.1 phải chỉ ra src-rust/crates/cli/src/main.rs là entry và mô tả flow startup
• Mỗi câu trả lời có ≥1 reference src-rust/.../*.rs:line