PHẦN 8 — THUẬT NGỮ
File thuật ngữ này là vận hành nội bộ — giữ nguyên qua mọi dự án. Khác với 01-analysis/glossary.md vốn dành cho thuật ngữ nghiệp vụ của khách hàng (RO, PNKN, DDMS, THILOGI…) và thay đổi theo từng dự án.
Tra nhanh theo viết tắt
| Viết tắt | Đầy đủ | Nhóm |
|---|---|---|
| AC | Acceptance Criteria | Tài liệu |
| ADR | Architecture Decision Record | Tài liệu |
| BA | Business Analyst | Vai trò |
| BR | Business Rule | Tài liệu |
| CR | Change Request | Tài liệu |
| DoD | Definition of Done | Chốt kiểm soát |
| DoR | Definition of Ready | Chốt kiểm soát |
| MR | Merge Request | GitLab |
| OQ | Open Question | Tài liệu |
| PM | Project Manager | Vai trò |
| PRD | Product Requirement Document | Tài liệu |
| QC | Quality Control | Kiểm thử |
| SRS | Software Requirement Specification | Tài liệu |
| UAT | User Acceptance Testing | Kiểm thử |
| WIP | Work In Progress | Đo lường |
Tài liệu và yêu cầu
| Thuật ngữ | Giải thích |
|---|---|
| PRD | Tài liệu mô tả một tính năng, đủ chi tiết để DEV code và QC viết test case mà không phải hỏi lại |
| SRS | Tài liệu tổng quan phạm vi toàn hệ thống, đứng trên các PRD |
| Baseline | Bản tài liệu đã được khách hàng phê duyệt chính thức và khóa lại làm mốc đối chiếu |
| Tag git | Nhãn đánh dấu một thời điểm cụ thể trong lịch sử repo, ví dụ FE-001-v1.0 |
| BR | Quy tắc nghiệp vụ. Ví dụ: "xe nhập khẩu tính ngày giao từ mốc thông quan" |
| AC | Điều kiện để coi tính năng là làm xong, viết đủ rõ để chuyển thành test case |
| Tech note | Ghi chú kỹ thuật DEV viết trước khi code: các phương án, phương án chọn và lý do, thay đổi DB, API, rủi ro, cách rollback |
| Traceability ID | Mã định danh chạy xuyên suốt từ tài liệu → issue → branch → commit → test case → báo cáo |
| Scope creep | Phạm vi công việc phình dần qua các yêu cầu nhỏ lẻ mà không ai ghi nhận chính thức |
Hai chốt kiểm soát
DoR — Definition of Ready. Danh sách điều kiện để một issue được phép giao cho DEV. Trả lời: *yêu cầu này đã đủ rõ để bắt đầu chưa?*
DoD — Definition of Done. Danh sách điều kiện để coi issue là xong. Trả lời: *đã đủ điều kiện đóng chưa?*
Không có DoR thì DEV code trên yêu cầu mơ hồ rồi làm lại. Không có DoD thì issue được đóng lúc code chạy được, nhưng tài liệu chưa cập nhật và khách hàng chưa ký.
GitLab
| Thuật ngữ | Giải thích |
|---|---|
| Scoped label | Label có dấu :: như status::in-dev. GitLab tự động gỡ label cũ khi gắn label mới cùng scope |
| Milestone | Nhóm issue theo mốc thời gian — ở đây dùng làm sprint |
| Weight | Trường số nguyên trên issue, dùng làm story point |
| Estimate / Spend | Thời gian ước lượng (/estimate 3d) và thời gian thực tế (/spend 4h, cập nhật hằng ngày) |
| `Closes #42` | Từ khóa trong mô tả MR; khi MR merge, GitLab tự đóng issue 42 |
| CODEOWNERS | File khai báo ai sở hữu thư mục nào, dùng để thực thi ranh giới ghi |
| `resource_label_events` | API trả về lịch sử gắn/gỡ label — nguồn dữ liệu để tính cycle time |
Kiểm thử
| Thuật ngữ | Giải thích |
|---|---|
| QC | Kiểm thử nội bộ do team tự làm trước khi đưa khách hàng |
| UAT | Khách hàng tự kiểm thử và ký xác nhận |
| Staging / Production | Môi trường gần giống thật để test / môi trường thật người dùng cuối đang dùng |
| Severity (Sev) | Mức nghiêm trọng của lỗi (Sev1–Sev4) |
| Edge case | Trường hợp biên, ít xảy ra nhưng vẫn phải xử lý |
| Regression | Lỗi mới phát sinh ở phần đang chạy tốt, do thay đổi ở chỗ khác |
Kỹ thuật (nguồn edge case hay bị bỏ sót)
| Thuật ngữ | Giải thích |
|---|---|
| Concurrent | Hai người cùng thao tác trên một bản ghi tại cùng thời điểm |
| Timeout | Hết thời gian chờ phản hồi từ hệ thống khác |
| Migrate | Chuyển dữ liệu cũ sang cấu trúc mới |
| Rollback | Quay ngược về trạng thái trước khi triển khai, khi deploy lỗi |
| API contract | Thỏa thuận về endpoint, method, cấu trúc request/response giữa hai bên |
| Polling / Webhook | Chủ động hỏi theo chu kỳ / hệ thống khác chủ động đẩy dữ liệu sang khi có thay đổi |
Bốn từ đầu (concurrent, timeout, migrate, rollback) là bốn nguồn edge case bị bỏ sót nhiều nhất. PRD thường mô tả rất kỹ luồng thuận, nhưng im lặng về chuyện hai nhân viên cùng sửa một phiếu, hoặc dữ liệu cũ đã migrate không thỏa mãn ràng buộc mới.
AI và Claude Code
| Thuật ngữ | Giải thích |
|---|---|
| CLAUDE.md | File chứa chỉ dẫn cho AI, tự động nạp khi mở workspace |
| Bộ nhớ dự án / cá nhân | ./CLAUDE.md ở gốc repo (commit) / ~/.claude/CLAUDE.md trên máy từng người (không commit) |
| Context | Toàn bộ thông tin AI đang có trong phiên làm việc |
| Slash command | Lệnh tắt gọi bằng /tên-lệnh, định nghĩa trong .claude/commands/ |
| Hallucination | AI tạo ra thông tin nghe hợp lý nhưng không có thật |
Rủi ro lớn nhất khi dùng AI trong quy trình này không phải là AI viết sai, mà là AI tự lấp khoảng trống trong tài liệu bằng suy diễn hợp lý. Suy diễn của AI thường rất thuyết phục và trôi chảy, nên rất khó phát hiện khi đọc lướt. Đây là lý do có luật P5: mọi giả định phải ghi vào open-questions.md.
Những cặp thuật ngữ hay bị nhầm
- Baseline ≠ version mới nhất. Version thay đổi liên tục; baseline là bản đã đóng dấu và chỉ được đổi qua CR. Đây là lý do issue phải link tới PRD tại tag baseline chứ không link nhánh đang chạy.
- Cycle time ≠ lead time. Lead time là thứ khách hàng cảm nhận (yêu cầu hôm nay, bao giờ có). Cycle time là thứ đo năng lực đội (bắt tay vào thì bao lâu xong). Lead time dài mà cycle time ngắn nghĩa là việc nằm chờ quá lâu ở khâu làm rõ, không phải DEV chậm.
- QC ≠ UAT. QC hỏi "có đúng như tài liệu không". UAT hỏi "có dùng được không". Một tính năng có thể pass QC hoàn toàn mà rớt UAT.
- Estimate ≠ spend. Estimate là dự đoán trước khi làm, spend là thực tế sau khi làm. Tỷ số giữa hai cái đo chất lượng ước lượng, không đo năng suất cá nhân.
- Story point ≠ giờ công. Story point đo độ phức tạp tương đối, không quy đổi trực tiếp ra giờ.
- Defect ≠ Change Request. Defect là code không làm đúng như tài liệu mô tả — sửa miễn phí. CR là tài liệu cần mô tả khác đi — tính chi phí. Baseline chính là căn cứ để phân xử ranh giới này.