QC Skills Guideline

Bộ 12 atomic skills + 5 workflows hỗ trợ toàn bộ vòng đời kiểm thử theo pipeline SPEC → PLAN → TASKS → REVIEW → IMPLEMENT — từ review tài liệu, khởi tạo test plan, sinh & review test case (Workflow 1: QC Manual) đến convert Gherkin, gen Playwright BDD script và chạy E2E automation (Workflow 2: BDD Automation). Output: docs-QA/features/ · tests-e2e/.

QC-SPEC-KIT · V2.0.0 · June 2026
✍️ QC Manual 🤖 BDD Automation 🔄 Full QC-SPEC-KIT
Tổng quan — Workflow 1: QC Manual → Workflow 2: BDD Automation
✍️ Workflow 1 — QC Manual
/qc-spec-review
Static+Q&A
/qc-testplan-init
Test Plan
/qc-testcase-gen
Gen TC
/qc-tc-review-update
Review+Fix

🤖 Workflow 2 — BDD Automation
/qc-testcase-convert-md-to-gherkin
Gen feature files
/qc-testcase-gherkin-review
Review+Fix
/qc-bdd-automation-genscripts
Gen Scripts
/qc-bdd-execute-report
Execute+Report
💡
QC-SPEC-KIT là bộ framework AI hỗ trợ toàn bộ pipeline QA theo chuẩn SPEC → PLAN → TASKS → REVIEW → IMPLEMENT, tích hợp trong Claude Code. Mỗi skill kích hoạt bằng slash command. Output: docs-QA/ (QC Manual) và features/ + tests-e2e/ (BDD Automation).
AI review tài liệu → phát hiện defect + Q&A → khởi tạo Test Plan → sinh TC 5 nhóm → review 8 tiêu chí → convert Gherkin → gen Playwright BDD script → chạy E2E → báo cáo Mermaid với delta so sánh.

Workflow 1 — QC Manual

🔄
Workflows WF1: /qc-spec-review = qc-doc-static-testing + qc-spec-qna-update  |  /qc-tc-review-update = qc-testcase-review → checkpoint → qc-testcase-update  |  /qc-spec-kit = orchestrate toàn bộ WF1
Slash CommandSkillLoạiMục đíchOutput
/qc-doc-static-testingStatic TestingSkill conReview tài liệu (SRS, BRS, User Story, HLD, Figma) — phát hiện lỗi, mâu thuẫn, thiếu sót trước khi viết TCstatic-review_*.md
/qc-spec-qna-updateQ&A UpdateSkill conCập nhật Q&A tracking sau khi BA/Dev trả lời. Chạy nhiều lần cho cùng tài liệuqa-tracking_*.md
/qc-testplan-initTest Plan InitSkill độc lậpKhởi tạo Test Plan: scope, TC estimate, risk & mitigation, schedule — chạy khi Q&A ổn địnhtestplan_*.md
/qc-testcase-genTC GeneratorSkill độc lậpSinh TC 5 nhóm: UI / Function / Validation / Integration / Other (+ Mobile). Paging tự nhận diện +12 TCTC_*.md
/qc-testcase-reviewTC ReviewSkill conReview TC theo 8 tiêu chí (A→H) — sinh issues ISS-xxx có severity + TC còn thiếu TCM-xxxreview_*.md
/qc-testcase-updateTC UpdateSkill conApply fix: sửa issues, thêm TC thiếu, tự tăng version, lưu changelog. Hỗ trợ "fix all" / "fix ISS-001" / "skip"TC_*_v2_*.md

Workflow 2 — BDD Automation

🔄
Workflows WF2: /qc-bdd-automation-genscripts = convert → gherkin-review (opt.) → gen-script  |  /qc-bdd-execute-report = execute-testscript → report (tự động)
#Slash CommandSkillLoạiMục đíchOutput
1/qc-testcase-convert-md-to-gherkinMD→GherkinSkill conConvert TC Markdown 7 cột sang Gherkin .feature (Given/When/Then, Background, tag @TC/@fixme)features/tc_*/
/qc-testcase-gherkin-reviewGherkin ReviewQA Gate opt.Review .feature theo 10 tiêu chí Gherkin chuẩn — Critical/Major/Minor. Chỉ báo cáo, không tự sửaissues report
2/qc-e2e-bdd-gen-scriptGen ScriptSkill conGen Playwright BDD — Phase A: skeleton. Phase B: điền locator thật qua browser MCPtests-e2e/
3/qc-e2e-bdd-execute-testscriptExecuteSkill conChạy Playwright BDD → phân loại lỗi (CODE/DATA/SYSTEM/BUG-APP/STEP-MISSING). Không tự fixkết quả test
4/qc-e2e-bdd-reportReportSkill conBáo cáo Markdown + biểu đồ Mermaid + delta lần trước + verdict PASSED/NEEDS ATTENTION/FAILEDTestReport_LATEST.md
/ai-test-scanTest ScanPre-scan opt.Quét source code lập bản đồ kỹ thuật module/feature — giúp gen-script chuẩn xác hơntests-e2e/discovery/

5 Workflows

WorkflowPhaseSkills điều phốiMục đích
/qc-spec-reviewSPECqc-doc-static-testing + qc-spec-qna-updateReview tài liệu mới + quản lý Q&A
/qc-tc-review-updateREVIEWqc-testcase-review → [checkpoint] → qc-testcase-updateReview TC + checkpoint + apply fix
/qc-bdd-automation-genscriptsIMPL-1convert-md-to-gherkin + gherkin-review (opt.) + gen-scriptChuyển TC sang automation — chạy 1 lần
/qc-bdd-execute-reportIMPL-2execute-testscript → report (tự động)Chạy test + báo cáo — lặp đến 0 FAIL
/qc-spec-kitORCHToàn bộ SPEC → PLAN → TASKS → REVIEWEntry point — điều phối WF1 với resume support

Workflow 1 — QC Manual

ℹ️
Chỉ cần Claude Code — không cần Node.js hay app đang chạy. Hỗ trợ Web, Mobile App, API. Output tại docs-QA/. Mỗi skill chạy độc lập hoặc qua workflow điều phối.
🔍
/qc-doc-static-testingStatic Testing · v1.4

Review tài liệu (SRS, BRS, User Story, HLD, LDD, Figma) để phát hiện lỗi, mâu thuẫn, thiếu sót trước khi viết TC. Hỗ trợ đọc ảnh UI multimodal, quét cross-reference. Sinh static-review + qa-tracking. AI hỏi có muốn gửi email báo cáo defect cho BA.

📋
/qc-spec-qna-updateQ&A Update · v1.0

Đánh dấu GAP Resolved / Pending, thêm ghi chú từ BA/Dev/Designer. Chạy sau khi nhận trả lời. Có thể chạy nhiều lần (/qc-spec-review update) mà không cần review lại từ đầu. Khi Pending = 0 → sẵn sàng /qc-testplan-init.

📅
/qc-testplan-initTest Plan Init · v1.0

Khởi tạo Test Plan đầy đủ: scope (in/out), TC estimate theo viewpoint, risk & mitigation, schedule. AI hỏi: tên dự án, sprint, deadline, QA Lead, BA/Dev Lead. Kế thừa kết quả SPEC phase. Output là DRAFT — nên điều chỉnh theo thực tế team.

/qc-testcase-genTC Generator · v1.2 ⭐

Sinh TC theo 5 nhóm (UI / Function / Validation / Integration / Other + Mobile). Tự nhận diện paging (+12 TC chuẩn), integration points. AI không tự bịa business rule — spec mơ hồ đánh dấu [Cần BA xác nhận]. Auto push Google Sheets.

🔎
/qc-testcase-reviewTC Review · v1.2

Review TC theo 8 tiêu chí (A→H): Completeness · Correctness · Clarity · Test Data · BVA/EP · Priority · Integration · Duplicate. Sinh ISS-001... có severity 🔴/🟠/🟡 + TC còn thiếu TCM-001.... Input trực tiếp cho qc-testcase-update.

✏️
/qc-testcase-updateTC Update · v1.3

Apply fix sau checkpoint: sửa issues, thêm TC thiếu, tự động tăng version, lưu changelog. Hỗ trợ: fix all / fix ISS-001,ISS-003 / skip ISS-007 / SKIP (chỉ lấy review, không update file).

Workflow 2 - BDD Automation

⚠️
Điều kiện tiên quyết: Đã có TC Markdown approved từ Workflow 1. Cần Node.js, npm installnpx playwright install. App đang chạy trên Staging/Local.
🔄
/qc-testcase-convert-md-to-gherkinMD→Gherkin · v1.1

Convert TC Markdown (7 cột chuẩn) sang Gherkin .feature — parse Given/When/Then, tách precondition chung thành Background, thêm tag @TC-xxx/@high/@fixme. Sinh warning report: DB assertion, step mơ hồ, test data không cụ thể.

🔍
/qc-testcase-gherkin-reviewGherkin Review · v1.0 ⬡ Tuỳ chọn

QA Gate — review .feature theo 10 tiêu chí Gherkin chuẩn (Cucumber official). Phát hiện vi phạm cú pháp, cấu trúc, chất lượng step — Critical/Major/Minor. Chỉ báo cáo, không tự sửa. Chạy giữa convert và gen-script để bắt lỗi sớm.

🧩
/qc-e2e-bdd-gen-scriptGen Script · v1.9

Sinh Playwright BDD script từ .feature — Phase A: skeleton (steps/pages/config/helpers/_NOTES) với TODO selectors. Phase B: Required Field Audit + mở browser thật, điền selector thực qua playwright-MCP. Discrepancy → _NOTES/, không sửa script theo app.

▶️
/qc-e2e-bdd-execute-testscriptExecute · v1.7

Thực thi Playwright BDD — phân loại lỗi: 🔴 CODE / 🟡 DATA / ⚪ SYSTEM / 🟠 BUG-APP / 🔵 STEP-MISSING. Không tự sửa bất kỳ file nào — chỉ run + report, chờ QA quyết định. Hỗ trợ chạy feature đơn lẻ hoặc filter theo @tag.

📊
/qc-e2e-bdd-reportReport · v1.0

Tổng hợp biểu đồ Mermaid (PASS/FAIL/SKIPPED), bảng BUG-APP, bảng TC manual-only (@fixme), delta so lần trước, lưu history. Verdict: PASSED ✅ / NEEDS ATTENTION ⚠️ / FAILED 🔴. Chạy tự động sau execute trong workflow.

🕵️
/ai-test-scanTest Scan ⬡ Pre-scan

Quét source code lập bản đồ kỹ thuật theo module/feature — routes, API, selectors, flows, data models. Đọc trực tiếp qua Filesystem MCP. Output làm blueprint cho gen-script chuẩn xác hơn. Không bắt buộc — chỉ cần khi gen-script cần context sâu.

5 Workflows — 2 Pipelines + 1 Orchestrator

ℹ️
Workflow 1 — QC Manual: /qc-spec-review → /qc-testplan-init → /qc-testcase-gen → /qc-tc-review-update
Workflow 2 — BDD Automation: /qc-bdd-automation-genscripts (1 lần) → /qc-bdd-execute-report (lặp đến 0 FAIL)
Orchestrator: /qc-spec-kit điều phối WF1 — hỗ trợ resume nếu bị gián đoạn
🎯
Entry Point — /qc-spec-kit · Orchestrator Workflow 1
State lưu tại docs-QA/.spec-kit-state.json — hỗ trợ resume khi bị gián đoạn giữa chừng
CommandHành động
/qc-spec-kit spec <file>→ /qc-spec-review <file>
/qc-spec-kit plan→ /qc-testplan-init
/qc-spec-kit tasks <file>→ /qc-testcase-gen <file>
/qc-spec-kit review [file]→ /qc-tc-review-update [file]
/qc-spec-kit run <file>Chạy tuần tự SPEC → PLAN → TASKS → REVIEW. Hỏi user tại mỗi checkpoint BLOCKED. Kết thúc với gợi ý Workflow 2
/qc-spec-kit statusDashboard: DONE / PENDING / bước tiếp theo. Dùng khi pipeline bị gián đoạn
✍️
Workflow 1 — QC Manual
/qc-spec-review → /qc-testplan-init → /qc-testcase-gen → /qc-tc-review-update
Pipeline
SPEC/qc-spec-review
PLAN → TASKS → REVIEWmỗi sprint
Tài liệuSRS/BRS
/qc-spec-reviewStatic+Q&A
qna-updateQ&A resolved
/qc-testplan-initTest Plan
/qc-testcase-genTC Generator
/qc-tc-review-updateReview+Fix v2
defect+GAPresolved testplan_*.mdTC_*.mdv2+changelog
Chi tiết từng bước
1

/qc-spec-review <file>— [SPEC]

Điều phối: qc-doc-static-testing (defect Critical/Major/Minor, status PASSED✅/NEEDS REVIEW⚠️/BLOCKED🔴) → qc-spec-qna-update (Q&A tracking). Dùng /qc-spec-review update khi BA reply — không cần review lại từ đầu.

2

/qc-testplan-init— [PLAN]

Chạy khi Q&A ổn định (Pending = 0). AI hỏi: tên dự án, sprint, deadline, QA Lead, BA/Dev Lead. Kế thừa TC estimate từ SPEC. Output DRAFT — điều chỉnh lịch và estimate theo thực tế.

3

/qc-testcase-gen <file>— [TASKS]

Sinh TC 5 nhóm. Spec mơ hồ → đánh [Cần BA xác nhận]. Paging → +12 TC tự động. Cảnh báo Automation Warning nếu TC có DB assertion. Hỏi output mode (1 file / tách file/section).

4

/qc-tc-review-update <tc-file>— [REVIEW]

Điều phối: qc-testcase-review → issues ISS-xxx + TCM-xxx → checkpoint (user chọn: "fix all" / "fix ISS-001" / "SKIP") → qc-testcase-update (v2 + changelog). Luôn có checkpoint — AI không tự apply fix.

🤖
Workflow 2 — BDD Automation
/qc-bdd-automation-genscripts (1 lần duy nhất) → /qc-bdd-execute-report (lặp đến 0 FAIL)
Pipeline tổng thể
TC Markdownapproved
đầu vào
convert-md-to-gherkinMD→.feature
features/tc_*/
gherkin-review⬡ opt.
issues report
bdd-gen-scriptPhase A+B
tests-e2e/
execute-testscriptrun+classify
PASS/FAIL
bdd-reportMermaid+delta
TestReport
Phase 1 — /qc-bdd-automation-genscripts (1 lần)
1

/qc-testcase-convert-md-to-gherkin— convert TC sang Gherkin

Parse bảng 7 cột → Given/When/Then, tách Background, gắn tag. Sinh warning report: DB assertion, test data không cụ thể. Có 2 checkpoint trong workflow: sau convert (xác nhận warning) và cuối (tổng kết).

/qc-testcase-gherkin-review— [tuỳ chọn] QA Gate

Chạy tự động trong workflow sau convert. Muốn kiểm soát thủ công: (1) /qc-testcase-convert-md-to-gherkin → (2) /qc-testcase-gherkin-review features/tc_*/ → (3) /qc-e2e-bdd-gen-script.

2

/qc-e2e-bdd-gen-script— gen Playwright BDD

Phase A: skeleton (steps/pages/config/helpers/_NOTES). Phase B: Required Field Audit + điền selector thực qua browser MCP. Nếu app khác spec → ghi discrepancy vào _NOTES/, không sửa script theo app.

Phase 2 — /qc-bdd-execute-report (lặp đến 0 FAIL)
3

/qc-e2e-bdd-execute-testscript— chạy test + phân loại lỗi

Phân loại từng FAIL: 🔴 CODE (script sai) / 🟡 DATA (test data sai) / ⚪ SYSTEM (môi trường) / 🟠 BUG-APP (app sai spec) / 🔵 STEP-MISSING (chưa impl). Không tự sửa — báo cáo xong chờ QA quyết định.

4

/qc-e2e-bdd-report— báo cáo (tự động)

Tổng hợp: biểu đồ Mermaid, bảng BUG-APP, bảng TC manual (@fixme), delta so lần trước. Lưu TestReport_LATEST.md + history/TestReport_[date].md.

Vòng lặp thực tế
Lần 1: /qc-bdd-execute-report → 7 FAIL (3 BUG-APP, 4 CODE) — xem report
Lần 2: Sau fix lỗi CODE → delta: FAIL 7→3 (chỉ còn BUG-APP)
Lần 3: Dev fix xong BUG-APP → 0 FAIL ✅ Pipeline hoàn thành!
Phân loại lỗi
LoạiNghĩaCần làm
🔴 CODELỗi trong test script — locator sai, step thiếu logicQA fix script
🟡 DATATest data không phù hợp với app hiện tạiUpdate config/
⚪ SYSTEMMôi trường staging lỗi, timeout, networkDevOps check
🟠 BUG-APPApp sai so với TC spec — bug thật, đã phát hiện từ gen-scriptTạo ticket, chờ Dev fix
🔵 STEP-MISSINGStep trong .feature chưa có implementationViết thêm step definition
Cấu trúc thư mục output
📁Output QC-SPEC-KITdocs-QA/ · features/ · tests-e2e/
docs-QA/ # Workflow 1 ├── Inputs/ ├── QC-static-testing/ │ ├── static-review_*.md │ └── qa-tracking_*.md ├── Test-Plans/ │ └── testplan_*.md ├── Test-Cases/ │ ├── TC_[feature]_[date]/ │ │ ├── TC_*_Function_*.md │ │ └── TC_*_v2_*.md │ ├── Reviews/ │ └── history/changelog_*.md └── Test-Reports/ ├── TestReport_LATEST.md └── history/ features/ # convert output └── tc_[tenmanhinh]/ └── TC_*_gherkin_*.feature tests-e2e/ # Workflow 2 ├── steps/tc_[tenmanhinh]/ ├── pages/tc_[tenmanhinh]/ ├── config/tc_[tenmanhinh]/ ├── helpers/tc_[tenmanhinh]/ ├── _NOTES/tc_[tenmanhinh]/ # discrepancy └── discovery/ # ai-test-scan
📥
docs-QA/Inputs/

Tài liệu đầu vào: SRS, BRD, User Story.

🔍
QC-static-testing/

Static review + Q&A tracking từ qc-spec-review.

📅
Test-Plans/

Test Plan mỗi sprint — qc-testplan-init.

🧪
Test-Cases/

TC theo version, Reviews, history changelog.

📊
Test-Reports/

LATEST + history mỗi lần chạy.

📄
features/tc_*/

Gherkin .feature — convert-md-to-gherkin.

⚙️
tests-e2e/ steps+pages+config

Playwright BDD scripts — gen-script Phase A+B.

📝
_NOTES/

Discrepancy TC vs app — phát hiện khi Phase B.

Best Practices

Tips & Mẹo sử dụng

🚀

Dùng Entry Point

/qc-spec-kit run <file> tự động chạy toàn Workflow 1, hỏi tại checkpoint BLOCKED. Nếu gián đoạn: /qc-spec-kit status để resume.

📎

Cung cấp context đầy đủ

  • Đặt tài liệu vào docs-QA/Inputs/
  • Nêu rõ platform: Web / Mobile / API
  • Paste link Google Sheet khi được hỏi

TC Generator

  • Mode 2 (tách file/section) cho automation
  • Paging → +12 TC tự động
  • Output TC_*.md dùng thẳng cho Workflow 2
🎯

Gherkin Review

  • Chạy giữa convert và gen-script để bắt lỗi sớm
  • Skill chỉ báo cáo — QA tự sửa .feature trước khi gen
  • Không bắt buộc nhưng khuyến nghị lần đầu
🔄

BDD Execute Loop

  • Dùng @high priority trước để tiết kiệm thời gian
  • Lặp đến 0 FAIL — delta tự sinh mỗi lần
  • BUG-APP = bug thật, không sửa assertion để pass
📊

TC Review

  • Cung cấp spec gốc để so sánh coverage
  • "fix all" cho sprint đầu tiên
  • Có thể chạy lại nhiều lần (v2, v3...)
Prompt mẫu

Sample Prompts

1

Chạy toàn Workflow 1 từ tài liệu mới

/qc-spec-kit run docs-QA/Inputs/SRS_DangNhap.md
Tuần tự SPEC → PLAN → TASKS → REVIEW. Hỏi tại checkpoint. Kết thúc với gợi ý Workflow 2.
2

Review tài liệu mới — lần đầu

/qc-spec-review docs-QA/Inputs/SRS_QuanLyNguoiDung.md
Static testing → Q&A tracking. Sau khi BA reply: /qc-spec-review update. Khi Q&A ổn định: /qc-testplan-init.
3

Gen TC rồi review + fix trong 1 luồng

/qc-testcase-gen docs-QA/Inputs/SRS.md
Sau khi gen: /qc-tc-review-update docs-QA/Test-Cases/TC_Login.md → checkpoint "fix all" → v2 + changelog.
4

Chuyển TC approved sang BDD automation

/qc-bdd-automation-genscripts docs-QA/Test-Cases/TC_Login.md
1 lần duy nhất: convert .feature → gherkin-review (opt.) → gen-script Phase A+B. Output: tests-e2e/ đầy đủ.
5

Chạy E2E & báo cáo — lặp đến pass

/qc-bdd-execute-report @high
Priority high trước → phân loại lỗi → report + delta. Sau fix: lặp lại. Xem lịch sử: /qc-bdd-execute-report status.
6

Chạy 1 feature cụ thể

/qc-bdd-execute-report features/tc_dangnhap/
Mọi skill đều gọi độc lập được. Lịch sử báo cáo tại: docs-QA/Test-Reports/history/.
Lưu ý

Nên và không nên

✓ Nên làm
  • Chạy /qc-spec-review trước khi gen TC để phát hiện lỗi sớm
  • Dùng /qc-testcase-gherkin-review giữa convert và gen-script
  • Lặp /qc-bdd-execute-report đến 0 FAIL — delta tự sinh
  • Chạy @high priority trước để tiết kiệm thời gian
  • Mode 2 (tách file) khi gen TC dùng cho automation
✗ Không nên
  • Bỏ qua static testing khi tài liệu còn nhiều lỗi chưa giải quyết
  • Sửa assertion để test pass — FAIL = bug thật, không che giấu
  • Chạy /qc-bdd-automation-genscripts nhiều lần cho cùng TC file
  • Bỏ qua checkpoint trong /qc-tc-review-update — xem issues trước "fix all"
  • Paste nội dung dài không format — AI có thể đọc sai context
Tra cứu nhanh

Bảng lệnh theo phase

LệnhPhaseDùng khiChạy mấy lần
/qc-spec-review <file>SPECNhận tài liệu mới1 lần / tài liệu
/qc-spec-review updateSPECBA vừa reply câu hỏiNhiều lần
/qc-testplan-initPLANQ&A ổn định, cần kế hoạch1 lần / sprint
/qc-testcase-gen <file>TASKSSinh TC từ tài liệu1 lần / feature
/qc-tc-review-update <file>REVIEWReview + fix TC1–2 lần / TC file
/qc-spec-kit run <file>ORCHChạy toàn bộ Workflow 11 lần
/qc-bdd-automation-genscripts <file>IMPL-1TC approved, cần automation1 lần duy nhất
/qc-testcase-gherkin-review <path>QA GateReview .feature trước gen-scriptTuỳ chọn
/qc-bdd-execute-reportIMPL-2Chạy test + báo cáoLặp đến 0 FAIL
/ai-test-scan <source>Pre-scanBlueprint trước gen-scriptTuỳ chọn