Tiếng Việt: Hands-on: Build a reusable context toolkit

Đây là bài thực hành tổng kết module context engineering. Không có lý thuyết mới — chỉ có một mục tiêu: đến cuối bài này, bạn có trong tay một Context Toolkit (bộ công cụ context) thật, gồm các template đã được validate, sẵn sàng dùng ngay trong sprint tiếp theo và chia sẻ được cho team. Chuẩn bị sẵn một file text để ghi chép trong lúc làm theo — bài này là một workshop, không phải bài đọc.

Làm sao audit các task QA của bạn và xác định nhu cầu context?

Trước khi xây bất kỳ template nào, bạn cần biết chính xác mình đang lặp lại việc gì và cần loại context nào cho mỗi việc đó. Bỏ qua bước audit này là lý do phổ biến nhất khiến các "bộ prompt" tự chế biến thành một đống file không ai dùng sau vài tuần.

Bước 1: Liệt kê các task QA lặp lại

Mở một file mới, dành 15 phút liệt kê mọi task QA bạn làm lặp đi lặp lại trong một sprint bình thường. Đừng lọc lúc này, chỉ liệt kê. Danh sách gợi ý để bạn đối chiếu (thường sẽ trùng ít nhất 70%): viết test case từ ticket, lên test plan cho sprint, triage bug report mới về, làm root cause analysis (RCA) cho bug phức tạp, khoanh vùng regression trước release, viết automation script, review coverage của PR trước khi ký duyệt QA, sinh test data, viết báo cáo test summary cuối sprint.

Cách làm thực tế hơn lý thuyết: đừng chỉ ngồi nhớ lại — trong sprint hiện tại, mỗi lần bạn thực hiện một task QA, ghi ngay một dòng vào file audit.md. Sau một sprint đầy đủ, bạn sẽ có dữ liệu thật về tần suất, thay vì đoán theo cảm giác.

Bước 2: Đánh giá AI Potential (tiềm năng áp dụng AI) của từng task

Với mỗi task trong danh sách, chấm điểm 1-5 theo 3 tiêu chí:

Task điểm cao ở cả 3 tiêu chí (lặp lại nhiều, context dễ lấy, risk chấp nhận được) chính là ứng viên ưu tiên số 1 để xây template. Ví dụ thực tế: "viết test case API từ OpenAPI spec" thường chấm cao cả 3 — rất lặp lại, context (schema) luôn sẵn có, và sai sót dễ bị catch khi review trước khi merge automation.

Bước 3: Với mỗi task ưu tiên, xác định nhu cầu context

Quay lại mô hình Dual-Context đã học ở bài trước — với mỗi task ưu tiên, xác định rõ nó cần Spec Context nào, Code-Change Context nào, hay cả hai. Ví dụ với task "bug triage": cần bug report gốc (steps, expected/actual), diff hoặc file code nghi ngờ, error log/stack trace, và lịch sử bug liên quan đã từng xảy ra ở khu vực đó. Viết rõ danh sách này ra — nó chính là phần "CONTEXT CẦN CUNG CẤP" bạn sẽ đưa vào template ở phần sau.

Bước 4: Xác định pattern có thể tái sử dụng

Sau khi làm xong bước 3 cho vài task, bạn sẽ nhận ra một số "khối context" xuất hiện lặp lại ở nhiều task khác nhau — ví dụ acceptance criteria của sprint hiện tại, hay schema OpenAPI của service đang test, xuất hiện trong cả task "test planning", "API test generation", và "regression scoping". Đây là các context snippet đáng được chuẩn hoá riêng (một đoạn bạn copy-paste sẵn, không phải soạn lại mỗi lần), giúp bạn lắp ráp template nhanh hơn nhiều về sau.

Mẹo: Đừng audit trên lý thuyết trong đầu — audit ngay trong sprint hiện tại bạn đang chạy. Kết quả từ dữ liệu thật luôn khác — và thường chính xác hơn — so với danh sách bạn tưởng tượng ra khi ngồi brainstorm một mình.

Làm sao xây dựng context template cho test planning, test generation, và bug analysis?

Đây là phần tạo ra deliverable chính của bài này: 4 template hoàn chỉnh, sẵn sàng dùng ngay. Bạn có thể copy trực tiếp và điền vào context thật của dự án mình.

Nguyên tắc thiết kế template

Trước khi vào từng template cụ thể, ghi nhớ 4 nguyên tắc giúp template của bạn không trở thành "một đoạn văn dài khó dùng":

• Tách rõ 3 khối: ROLE (vai trò AI đóng), CONTEXT CẦN CUNG CẤP (placeholder rõ ràng, không mơ hồ), và NHIỆM VỤ (liệt kê từng bước, đánh số).
• Luôn định nghĩa OUTPUT FORMAT — đừng để AI tự chọn format, nếu không mỗi lần chạy bạn sẽ nhận được cấu trúc khác nhau, khó so sánh/tái sử dụng.
• Placeholder cụ thể, không placeholder chung: dùng {{OpenAPI schema của endpoint}} tốt hơn nhiều so với {{context}} — placeholder mơ hồ khiến người dùng template (kể cả bạn 3 tháng sau) không biết chính xác cần điền gì.
• Test template trên task thật trước khi coi là "xong" — nguyên tắc này sẽ được nói kỹ ở phần validate ngay sau.

Template 1: Sprint Test Planning

ROLE: Bạn là senior QA engineer đang lên test plan cho sprint.

CONTEXT CẦN CUNG CẤP:
- Sprint goal: {{mục tiêu/theme của sprint}}
- Danh sách ticket trong sprint: {{paste tên ticket + acceptance criteria}}
- Bug/tech debt tồn đọng ảnh hưởng đến testing: {{danh sách}}
- Năng lực team: {{số QA, số ngày làm việc có sẵn}}
- Môi trường test sẵn có: {{staging/UAT/...}}
- Khu vực rủi ro đã được dev/PM cảnh báo trước: {{danh sách}}

NHIỆM VỤ:
1. Nhóm các ticket theo mức rủi ro (High/Medium/Low) dựa trên: mức ảnh hưởng
   người dùng, độ phức tạp, khu vực bị chạm tới (payment, auth, data integrity
   mặc định là High).
2. Với mỗi ticket High và Medium, đề xuất: loại test cần làm (functional,
   regression, exploratory, performance, security), effort ước tính (giờ).
3. Đánh dấu ticket nào thiếu acceptance criteria rõ ràng — liệt kê câu hỏi
   cần hỏi lại PM.
4. Đề xuất lịch test theo từng ngày trong sprint, dựa trên năng lực team.
5. Chỉ ra dependency giữa các ticket ảnh hưởng đến thứ tự test.

OUTPUT FORMAT: Markdown, gồm bảng tổng hợp (Ticket | Risk | Loại Test |
Effort | Owner), theo sau là lịch test và danh sách câu hỏi mở.

Context cần thu thập trước khi dùng template này: backlog sprint kèm acceptance criteria đã link đầy đủ; khu vực rủi ro rút ra từ retro/incident gần nhất; năng lực team QA thực tế cho sprint; lịch trống của môi trường test.

Template 2: API Test Case Generation

ROLE: Bạn là senior QA engineer chuyên thiết kế test cho API.

CONTEXT CẦN CUNG CẤP:
- Endpoint: {{METHOD}} {{PATH}}
- OpenAPI/Swagger schema: {{paste schema}}
- Cơ chế auth: {{API key / OAuth2 / JWT}}
- Business rule không có trong schema: {{free text}}
- Bug/lịch sử liên quan: {{link ticket}}

NHIỆM VỤ:
1. Generate full test matrix gồm: happy path, thiếu field required, sai
   type/format, boundary value (min/max length, giới hạn numeric), auth
   failure (401/403), rate-limit/429, idempotency (nếu POST/PUT/PATCH),
   và pagination edge case (nếu có).
2. Mỗi test case gồm: precondition, request payload mẫu, expected status
   code, expected response body.
3. Đánh dấu case nào nên automate, case nào chỉ nên exploratory.
4. Chỉ ra điểm mập mờ trong schema cần xác nhận lại với owner của API.

OUTPUT FORMAT: Bảng markdown — ID | Title | Precondition | Request |
Expected Result | Automate? (Y/N)

Context cần thu thập trước khi dùng template này: bản OpenAPI spec mới nhất khớp với branch đang test; hướng dẫn setup auth token; business rule chưa nằm trong schema; bug lịch sử của chính endpoint này.

Template 3: Bug Root Cause Analysis

ROLE: Bạn là senior QA engineer thực hiện root cause analysis (RCA)
cho một bug đã được báo.

CONTEXT CẦN CUNG CẤP:
- Bug report: {{steps to reproduce, expected vs actual, môi trường, log/screenshot}}
- Diff hoặc file code bị nghi ngờ: {{paste diff hoặc đường dẫn file}}
- Spec/acceptance criteria liên quan: {{paste}}
- Error log/stack trace: {{paste}}
- Commit gần đây chạm vào khu vực này: {{git log output}}

NHIỆM VỤ:
1. Tóm tắt defect trong 1 câu (mô tả triệu chứng, không phải nguyên nhân).
2. Đề xuất 3 nguyên nhân khả năng cao nhất, xếp theo độ khả thi, có lý giải
   dựa trên code/log đã cung cấp.
3. Với giả thuyết khả năng cao nhất, gợi ý cách xác nhận cụ thể (log cần
   kiểm tra, breakpoint, test cần chạy).
4. Xác định đây là bug đơn lẻ hay pattern có thể ảnh hưởng module khác dùng
   logic tương tự.
5. Gợi ý 1 regression test case lẽ ra đã bắt được bug này sớm hơn.

OUTPUT FORMAT: Markdown gồm các mục: Symptom Summary, Ranked Hypotheses,
Confirmation Steps, Blast Radius, Suggested Regression Test.

Context cần thu thập trước khi dùng template này: bước reproduce đầy đủ kèm chi tiết môi trường; error log/stack trace liên quan; diff hoặc khu vực code nghi ngờ; lịch sử commit gần đây chạm vào khu vực đó.

Template 4: Regression Scope Analysis

ROLE: Bạn là senior QA engineer khoanh vùng regression cho một release
sắp tới.

CONTEXT CẦN CUNG CẤP:
- Change summary của release: {{git diff --stat + commit log}}
- Danh sách module/feature bị chạm tới: {{suy ra từ diff}}
- Danh mục regression suite hiện có: {{tên/tag các test suite}}
- Bản đồ phụ thuộc hoặc điểm tích hợp đã biết: {{nếu có}}
- Mức chấp nhận rủi ro của release: {{ví dụ "không được để lỗi ở payment"}}

NHIỆM VỤ:
1. Map từng file/module đã đổi với regression suite đang cover nó.
2. Đánh dấu module nào thay đổi nhưng KHÔNG có regression coverage nào —
   đây là chỗ cần viết test mới trước khi release.
3. Xác định ảnh hưởng gián tiếp: shared utility/library bị đổi mà feature
   khác (không nằm trong diff) đang phụ thuộc vào.
4. Đề xuất kế hoạch regression theo tier: Must-Run (rủi ro cao, full coverage),
   Should-Run (rủi ro trung bình, smoke test), Skip (rủi ro thấp, không có
   dependency chung).
5. Ước tính tổng thời gian chạy regression theo cách phân tier trên.

OUTPUT FORMAT: Bảng markdown — Module | Có Đổi? | Coverage Hiện Có |
Có Gap? | Tier | Hành Động Đề Xuất

Context cần thu thập trước khi dùng template này: toàn bộ diff/danh sách commit của release; danh mục regression suite kèm mapping với module; sơ đồ kiến trúc/dependency nếu có; mức chấp nhận rủi ro từ PM/eng lead.

Mẹo: Viết cả 4 template vào một file duy nhất trong lần đầu (đừng tách file ngay) — dễ so sánh cấu trúc giữa các template và đảm bảo tính nhất quán (cùng 3 khối ROLE/CONTEXT/NHIỆM VỤ). Tách thành file riêng sau, khi bạn đã chắc mỗi template ổn định qua bước validate ở phần tiếp theo.

Làm sao test và validate các context template với công việc thực tế?

Một template chưa được test trên task thật không khác gì một đoạn code chưa qua unit test — trông có vẻ đúng, nhưng bạn không có bằng chứng. Phần này là bước không thể bỏ qua trước khi bạn tự tin gọi bất kỳ template nào là "sẵn sàng dùng".

Quy trình validation

Làm theo 5 bước cho mỗi template mới:

1. Chạy trên task lịch sử đã biết kết quả đúng. Chọn một ticket/bug/API đã xử lý xong trước đó, chạy template với context thật của nó — vì bạn đã biết đáp án đúng, bạn có thể chấm được output AI có sát thực tế không.
2. Review output bằng checklist đánh giá đã học ở bài "Iterating and Refining" (specificity, traceability, testability, coverage, consistency, actionability).
3. Chấm pass/fail trên từng tiêu chí, không chấm cảm tính "thấy ổn".
4. Nếu fail, xác định nguyên nhân: do thiếu context (cần thêm placeholder), do nhiệm vụ mô tả mơ hồ, hay do format chưa rõ — sửa đúng chỗ đó trong template, không sửa tay output.
5. Test lại bản đã sửa trên một task thật KHÁC, chưa dùng để test lần đầu — một lần đúng có thể là trùng hợp, không phải bằng chứng template đã ổn.

Tần suất lặp lại cho template

Không phải mọi template cần review với tần suất giống nhau. Template dùng hàng tuần (như API test case generation) nên review nhanh sau mỗi 2 sprint. Template dùng ít hơn có thể review theo quý. Ngoài lịch định kỳ, có 2 sự kiện luôn buộc phải review lại ngay: hệ thống/spec nền tảng có thay đổi lớn (ví dụ đổi từ REST sang GraphQL), hoặc bạn đổi model/version model đang dùng — hành vi model có thể thay đổi đủ nhiều để một template từng ổn định bỗng cho output khác đi.

Ghi lại Template Quality Log

Duy trì một log đơn giản, không cần tool phức tạp — một bảng trong file markdown là đủ:

Log này có giá trị lớn hơn bạn nghĩ: nó là bằng chứng cho việc template đã được validate thật, không phải "tôi thấy nó ổn". Khi bạn chia sẻ toolkit cho team (phần tiếp theo), log này chính là thứ giúp đồng nghiệp tin tưởng dùng ngay mà không phải tự validate lại từ đầu.

Mẹo: Chấm điểm một template trên ít nhất 3 task thực tế khác nhau trước khi gọi nó "stable". Một lần đúng có thể chỉ là may rủi trùng hợp giữa context và cách AI diễn giải câu prompt lần đó — không phải bằng chứng đáng tin.

Làm sao tổ chức và chia sẻ Context Toolkit với team QA?

Một toolkit chỉ nằm trên máy bạn thì giá trị chỉ dừng ở cá nhân. Giá trị thật của context engineering nhân lên khi cả team cùng dùng chung một bộ template đã được validate — đây là bước biến kỹ năng cá nhân thành tài sản của team.

Chọn nơi lưu trữ phù hợp cho toolkit

Có 2 lựa chọn phổ biến, mỗi lựa chọn có trade-off riêng:

• Trong repo dự án (ví dụ docs/qa-prompts/ hoặc .ai/prompts/): version cùng code, review được qua PR, luôn đồng bộ với branch đang làm việc. Nhược điểm: người ngoài team dev (một số PM/BA) khó truy cập.
• Notion/Confluence: dễ discover, dễ truy cập cho người không quen git. Nhược điểm: dễ bị lãng quên, không version control chặt, dễ có nhiều bản trùng lặp không đồng bộ.

Lựa chọn tôi khuyến nghị cho hầu hết team: source of truth nằm trong repo, sau đó link/sync ra Confluence/Notion cho khả năng discover rộng hơn — không làm ngược lại (giữ source of truth ở wiki), vì rất dễ để wiki "trôi" khỏi thực tế code.

Viết README Cho Toolkit

Đây là khung README bạn có thể dùng ngay, đặt tại docs/qa-prompts/README.md:

## What Is This?
Đây là bộ template prompt đã được team QA validate và dùng trong công việc
hàng ngày: test planning, test case generation, bug RCA, regression scoping.
Mỗi template đã được test trên ít nhất 3 task thực tế trước khi đưa vào đây
(xem Quality Standards).

## How to Use a Template
1. Mở file template tương ứng trong thư mục `templates/`.
2. Điền đầy đủ các placeholder trong phần CONTEXT CẦN CUNG CẤP — đừng bỏ
   trống, output sẽ kém chính xác nếu thiếu context.
3. Paste nguyên prompt vào AI tool bạn đang dùng.
4. Luôn review output theo checklist ở `docs/qa-prompts/output-checklist.md`
   trước khi dùng cho công việc thật.

## Template Index
| Template | Dùng cho | Cập nhật lần cuối |
|---|---|---|
| sprint-test-planning.md | Lên test plan đầu sprint | {{ngày}} |
| api-test-case-generation.md | Sinh test case cho API | {{ngày}} |
| bug-root-cause-analysis.md | RCA cho bug phức tạp | {{ngày}} |
| regression-scope-analysis.md | Khoanh vùng regression trước release | {{ngày}} |

## Contributing a New Template
1. Validate template trên ít nhất 3 task thực tế (theo Quy trình validation
   trong bài học context engineering).
2. Ghi lại kết quả validate vào Template Quality Log.
3. Mở PR thêm file template mới vào `templates/`, cập nhật Template Index.
4. Cần ít nhất 1 approval từ QA Lead hoặc người sở hữu toolkit trước khi merge.

## Quality Standards
- Mọi template phải có đủ 3 khối: ROLE, CONTEXT CẦN CUNG CẤP, NHIỆM VỤ.
- Mọi template phải định nghĩa rõ OUTPUT FORMAT.
- Mọi template phải có ví dụ đã điền sẵn (filled example) đi kèm.
- Template không được review/dùng trong 2 quý liên tiếp sẽ được đánh dấu
  "cần review lại" hoặc gỡ khỏi Template Index.

Onboard đồng nghiệp vào toolkit

Đừng chỉ gửi link repo và kỳ vọng team tự đọc. Cách hiệu quả hơn: dành 30 phút làm một buổi walkthrough trực tiếp, chọn 1-2 template dùng minh hoạ ngay trên một task thật của team đang làm. Sau đó, pair với một đồng nghiệp trong lần đầu họ dùng thật một template — quan sát xem họ vướng ở đâu (thường là chỗ điền placeholder hoặc không biết lấy context ở đâu), và sửa ngay chỗ đó trong template nếu cần.

Giữ toolkit luôn "sống"

Toolkit bị bỏ quên là kết cục phổ biến nhất nếu không ai chịu trách nhiệm duy trì nó. Giải pháp thực tế: chỉ định một người (có thể xoay vòng theo quý) làm "chủ sở hữu" toolkit — người này chịu trách nhiệm review PR thêm template mới, dọn template lỗi thời (dựa trên "last validated" date trong metadata), và định kỳ nhắc team review lại template dùng nhiều nhất. Một mẹo giữ động lực: mỗi khi một template giúp ai đó tiết kiệm rõ ràng thời gian, khuyến khích họ chia sẻ ngay trong kênh chat chung của team — sự công nhận nhỏ này giữ toolkit "sống" tốt hơn bất kỳ chính sách bắt buộc nào.

Đo lường impact của toolkit

Không cần đo lường phức tạp — vài chỉ số đơn giản đủ để chứng minh giá trị và xin thêm thời gian đầu tư duy trì toolkit: thời gian tiết kiệm ước tính mỗi lần dùng (tự ước lượng, không cần chính xác tuyệt đối), tỉ lệ thành viên team thực sự dùng toolkit (adoption rate), tỉ lệ defect escape trước/sau khi áp dụng test generation có AI hỗ trợ, và số lần một template được tái sử dụng. Không cần dashboard riêng — một reaction emoji trong kênh Slack mỗi lần dùng thành công, hoặc một khảo sát ngắn cuối quý, là đủ dữ liệu để có căn cứ.

Giá trị compound của một toolkit được chia sẻ

Đây là điểm khác biệt cốt lõi giữa việc bạn tự giỏi prompt và việc cả team cùng có một toolkit chung: mỗi lần một người cải tiến một template, TẤT CẢ mọi người dùng template đó từ lần sau đều được hưởng lợi ngay — không ai phải tự mắc lại lỗi mà đồng nghiệp đã từng gặp và đã sửa. Đây chính là giá trị compound (tích luỹ dồn) mà kỹ năng cá nhân đơn lẻ không bao giờ tạo ra được. Kỹ năng context engineering, nếu chỉ nằm trong đầu một người, sẽ mất đi khi người đó chuyển team hoặc nghỉ việc. Nhưng nếu nó được đóng gói thành một toolkit sống, được validate, và được chia sẻ — nó trở thành tài sản lâu dài của cả team, đúng như tinh thần xuyên suốt module này: context engineering không phải là một kỹ năng cá nhân bí truyền, mà là một năng lực có thể xây dựng, đo lường, và nhân rộng.

Mẹo: Tạo một kênh chat riêng (ví dụ #qa-prompt-wins) chỉ để mọi người post trước/sau khi dùng một template thành công trong công việc thật. Kênh này vừa là "marketing nội bộ" giúp toolkit không bị quên lãng, vừa là nguồn feedback nhanh nhất để bạn biết template nào cần cải tiến tiếp — nhanh hơn nhiều so với chờ review định kỳ theo quý.