SDD Board
VS Code extension for the Spec-Driven Development workflow.
Two panels in one extension:
- 📋 Review Board — visual UI to review AI-generated findings from
/refine-prd, /review-context, /review-tech-docs
- 📊 Living Documentation — project-wide traceability dashboard driven by
.trace/ hoặc .trace-mirror/
Installation
code --install-extension EducaCorp.sdd-board
Hoặc VS Code → Ctrl+Shift+P → "Extensions: Install from Marketplace" → search SDD Board.
VS Code tự động cập nhật khi có version mới.
Panel 1 — Review Board
Cách dùng
Bước 1 — Chạy một review command trong Claude Code
/refine-prd specs/prd/payment/create-invoice.md
/review-context specs/prd/payment/create-invoice.md
/review-context specs/bdd/payment/PAY-UC01.feature
/review-tech-docs tech-docs/payment/PAY-UC01-tech-design.md
Claude phân tích và ghi file vào .agent/review/:
| Command |
Findings file |
/refine-prd |
{prd-slug}-findings.yaml |
/review-context (PRD) |
{prd-slug}-review-context-findings.yaml |
/review-context (BDD) |
{uc-id}-review-bdd-findings.yaml |
/review-tech-docs |
{uc-id}-tech-review-findings.yaml |
Bước 2 — Mở Review Panel
- Sidebar (khuyến nghị): Click icon trên Activity Bar → danh sách findings files → click file
- Right-click: Right-click vào file
*-findings.yaml trong Explorer → "Open Review Board"
- Command Palette:
Ctrl+Shift+P → "SDD Board: Open Review Board"
VS Code tự hiện thông báo "Mở ngay?" khi file findings vừa được tạo.
Bước 3 — Review từng finding
Mỗi finding hiển thị:
- Severity: 🔴 Critical / 🟡 Major / 🔵 Minor
- Badge:
⚡ auto-fix (AI có thể tự sửa) / 👤 human (cần quyết định của người)
- ID: check_id (
P1, B2, T3) hoặc lens (QA, DEV, SA, PO)
- Section / Issue / Suggestion
Bấm để xử lý:
| Nút |
Kết quả |
| ✓ Accept |
Chấp nhận finding |
| ✎ Modify |
Chấp nhận có chỉnh sửa — nhập note vào modal |
| ⏸ Defer |
Để sau |
| ✗ Reject |
Từ chối — nhập lý do vào modal |
| ↩ Change |
Hoàn tác về pending |
| 💬 Giải thích |
Nhờ Claude giải thích finding bằng ngôn ngữ no-tech + đề xuất phương án (cover edge case), chờ bạn confirm trước khi apply. Luôn hiện ở mọi finding. |
Bước 4 — Apply
Sau khi review xong, bấm "Apply" ở cuối panel. Extension tự chọn lệnh đúng theo loại findings:
| Workflow |
Terminal command |
refine-prd |
/refine-prd {prd-file} --resume |
review-context |
/review-context --resume {source-file} |
tech-design |
/review-tech-docs --resume {tech-doc} |
Quick-fix path (không qua Review Board)
Dành cho dev muốn apply nhanh tất cả auto_fixable findings:
/review-context --fix specs/bdd/payment/PAY-UC01.feature
AI apply ngay, bỏ qua Review Board, chỉ để lại các finding cần quyết định của người.
Settings (sửa không cần build lại)
Hai setting đọc lúc runtime — đổi xong là lần bấm nút tiếp theo dùng giá trị mới ngay, không phải cài lại / build lại extension:
| Setting |
Mặc định |
Ý nghĩa |
sddBoard.reviewer |
reviewer |
Tên người review, ghi vào prd-refinement-report.yaml |
sddBoard.clarifyPrompt |
(prompt no-tech, cover edge, confirm trước khi apply) |
Prompt gửi cho Claude khi bấm 💬 Giải thích |
Thứ tự ưu tiên: Workspace (.vscode/settings.json trong repo project) > User > default. Đặt ở Workspace để cả team dùng chung 1 prompt. File mẫu copy được: sample/.vscode/settings.json.
Tính năng
| Tính năng |
Mô tả |
| Multi-command |
Hỗ trợ findings từ /refine-prd, /review-context, /review-tech-docs |
| Lens tabs |
All / QA / DEV / SA / PO (refine-prd) hoặc PRD / BDD / TECH (review-context) |
| auto_fixable badge |
⚡ auto-fix / 👤 human trên mỗi finding |
| check_id label |
P1, B2, T3 hiển thị khi dùng review-context / review-tech-docs |
| Progress bar |
Thanh tiến độ % đã review |
| Search |
Tìm kiếm toàn văn qua issue / suggestion / section |
| Smart Apply |
Tự chọn --resume command đúng theo loại findings file |
| Auto-detect |
Tự tìm findings files khi mở từ Command Palette |
| File watcher |
Tự refresh sidebar khi findings file mới được tạo |
Panel 2 — Living Documentation
Dashboard traceability health của toàn project, đọc từ .trace-mirror/ hoặc .trace/.
Cách mở
Ctrl+Shift+P → "SDD Board: Open Living Documentation"
Dashboard
┌──────────────────────────────────────────────────────────────────┐
│ PRDs Use Cases Scenarios Code Cov. Test Cov. Drift Gap Orphaned │
│ 19 86 1077 93% 89% 12 5 2 │
└──────────────────────────────────────────────────────────────────┘
Drill down: PRD → Use Case → per-scenario table
| SC ID |
Title |
Spec ver |
Gen ver |
Code |
Tests |
Status |
| PAY-UC01-SC1 |
Happy path |
1.2 |
1.2 |
✅ |
✅ |
OK |
| PAY-UC01-SC2 |
Refund |
1.3 |
1.2 |
⚠️ |
✅ |
DRIFT |
| PAY-UC02-SC1 |
Void |
1.0 |
— |
— |
— |
UNTRACKED |
Status badges:
- ✅ OK — spec ver = gen ver, code + tests tồn tại
- ⚠️ DRIFT — spec ver ≠ gen ver (scenario đã sửa, code chưa update)
- 🔴 GAP — code tồn tại nhưng chưa có tests
- UNTRACKED — chưa có code implement
- 🔴 ORPHANED — code còn nhưng scenario đã bị xoá khỏi
.feature. Cờ chặn PR; không tính vào mẫu số Scenarios (nó không còn là scope), nên có ô thống kê riêng
Tính năng:
- Filter theo PRD status (Approved / Draft / Other)
- Search theo UC/SC ID hoặc title
- Filter theo status (OK / DRIFT / GAP / UNTRACKED)
- Live reload khi
.trace/ hoặc .trace-mirror/ thay đổi
Data source — thứ tự ưu tiên
| # |
Nguồn |
Khi nào |
| 1 |
.trace-mirror/trace-report.json |
Framework ≥ 0.4.3. Mirror sinh từ report đã gộp nên phủ mọi service → dùng một mình nó |
| 2 |
.trace/trace-report.json |
Sổ gốc mount trong workspace này, hoặc mirror của bản < 0.4.3 |
| 3 |
.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv |
Chưa có report — parse TSV thô (bỏ qua _seams.tsv) |
Được ghi bởi /generate-bdd, /generate-code, /dev-gen-test; cập nhật bởi /validate-traces.
Vì sao đọc CẢ HAI tên. SDD Framework ≥ 0.4.3 tách sổ gốc khỏi bản sao:
| Path |
Vai trò |
Git |
.trace/ |
authoritative — .tsv + trace-history.jsonl, không regenerate được |
phải commit |
.trace-mirror/ |
bản sao để panel chạy được ở workspace không chứa sổ gốc |
gitignore |
Trước 0.4.3 cả hai cùng tên .trace — chính va chạm đó là lý do framework đổi tên (một luật gitignore viết theo tên có thể xoá sạch sổ gốc). Panel đọc cả hai nên chạy đúng với mọi phiên bản framework, không cần phát hành đồng bộ.
Mirror thắng tuyệt đối khi có mặt — nếu đọc thêm cả sổ mà nó mirror thì mọi scenario bị đếm hai lần, làm phồng tổng số, mẫu số coverage, và mọi con số drift/gap. Với workspace < 0.4.3 (cả hai cùng tên) panel khử trùng bằng cách so nội dung report.
Yêu cầu
Uninstall
code --uninstall-extension EducaCorp.sdd-board
Liên quan
