Hiểu harness để dùng đúng, tinh chỉnh để phù hợp pilot Hub Khánh Xuân
Hiểu nguồn gốc giúp biết cái gì cố định (từ upstream), cái gì custom (của Hubflow ERP).
Harness-vibe-code là template trống (Harness v0, chưa có product code). Zui fork về, lắp Hubflow ERP vào, rồi áp dụng cho pilot thực tế. Tức là repo Hubflow ERP không phải "framework cần install" — nó là dự án luôn, có harness đi kèm như công cụ quản lý workflow.
Harness = bộ khung quy trình + template + công cụ để người và AI agent cùng làm dự án. Không phải thư viện, không phải framework code — là "luật chơi".
Quyết định kiến trúc bất biến. Mỗi ADR có lý do + phạm vi. Khi muốn đổi → viết ADR mới supersede, không sửa cũ.
Công thức nấu ăn sẵn cho việc lặp lại: discovery interview, gap analysis, build execution, code review, UAT... Mỗi lần gặp vấn đề quen → check playbook trước.
Mẫu spec-intake, story packet, decision, validation. Không phải viết doc từ đầu — điền vào template.
Pre-commit hook cơ khí — block commit nếu TEST_MATRIX có Result: fail. Không bypass bằng --no-verify.
Khi vào repo, đọc theo thứ tự này để hiểu nhanh:
STAGE.md — đang ở stage nào (một dòng)README.md — overview repoAGENTS.md — quy tắc cho agent + humandocs/HARNESS.md — mô hình hợp tácdocs/WORKFLOW.md — 13 stage delivery mapdocs/product/ — hợp đồng sản phẩm (ERD, event catalog, state machine...)docs/stories/ — story packet (~70+)docs/decisions/ — tại sao quyết định thếdocs/TEST_MATRIX.md — chứng cứ đã pass chưaMỗi stage có gate riêng, playbook riêng, artifact riêng. Stage nào chưa pass → không nhảy sang stage sau.
Hook .githooks/harness-verify-gate.sh chạy tự động khi commit. Nó sẽ block commit nếu docs/TEST_MATRIX.md có Result: fail hoặc never-run trên stage-close.
CẤM: git commit --no-verify, git commit -n, git push --no-verify, git config --unset core.hooksPath
ĐÚNG: Fix lỗi thật, hoặc chạy lại verify command rồi ghi Result: pass.
--no-verify chỉ dành cho con người với lý do rõ ràng. Agent không tự ý dùng.
Token là REQ-xxx (requirement), SC-xxx (scenario), TC-xxx (test case). Commit message phải có token để traceability.
Ví dụ: feat(menu): add menu item list [REQ-M2-001, TC-014]
Đóng stage 7 = sửa STAGE.md History + Snapshot. Sửa này phải land cùng commit với artifact (story packet, ERD addenda, prototype...)
Lý do: tránh drift giữa "nói đã xong" và "thực tế có file".
Mỗi lần bắt đầu làm việc: STAGE.md → README → AGENTS.md → FEATURE_INTAKE.md → spec → docs/product/ → ARCHITECTURE.md → stories → TEST_MATRIX → decisions → playbooks → WORKFLOW.md.
Đọc sai thứ tự = hiểu sai context = làm sai.
Upstream harness-experimental là template trống. Hubflow ERP là dự án thật đã lắp Hubflow vào. Đây là những thứ Hubflow ERP có mà upstream không có:
| Layer | Upstream (harness-experimental) | Hubflow ERP (fork) |
|---|---|---|
| Product spec | Không có (chờ user input) | 48 entity ERD, event catalog, state machine, NFR, identity & access |
| Module | Không | 6 module (Platform/Menu/Order/Pancake/Migration/Dashboard) |
| Stories | Không | ~70-81 story packet, 23 standalone, 6 wave A-D |
| ADR | Một số generic | 21 ADR (0015 stack, 0017 system boundary, 0020 design, 0022 AI pattern...) |
| UI design | Không | shadcn/ui + Tailwind, agri green hsl(142 64% 38%), light+dark, Inter |
| Stack | Không | NestJS + Next.js + PostgreSQL, end-to-end TS, modular monolith |
| Integration | Không | Pancake POS (read stock + push orders), Abaha (reference read) |
| Test data | Không | Seed data playbook, e2e canonical flow, scenario taxonomy |
3 blockers hiện tại mà team research nên đề xuất fix:
7 file .sh trong repo có line ending Windows. Khi chạy trên Linux/macOS → fail ngay.
# Fix: find . -name "*.sh" -exec dos2unix {} \;
git config core.hooksPath chưa set. Tức là Verify Gate vẫn bypass được trên máy chưa config.
git config core.hooksPath .githooks chmod +x .githooks/*
STAGE.md stage 6 nói "concept clickable prototype 8 screens" nhưng thư mục docs/visuals/ không tồn tại. Audit cần:
Hiện đang chờ detailed prototype qua claude.ai/design. Cần Zui quyết: làm prototype trước, hay nhảy thẳng Build? Khuyến nghị: làm prototype (giảm rủi ro screen rework).
ADR 0022 đã ghi: "AI suggests, human decides, system records". Phase 1 chỉ ship schema ai_suggestion_log + 5 cột trên shortage. Service AiShortageSuggester để Phase 2.
ADR 0016: mọi table phải có hub_id, mọi query scope theo hub. Pilot = 1 hub (Khánh Xuân) nhưng schema phải multi-tenant từ đầu.
"Toàn team dev research. e (Mavis) hãy nắm rõ và giải thích cho mọi người hiểu. Tạo 1 HTML page present cho mọi người dễ hiểu."
STAGE.md + README.md + AGENTS.md (~30 phút)docs/STAGE_GOALS.md + playbook stage 7 (~20 phút)docs/HARNESS_BACKLOG.md hoặc tạo PR mới| Người | Focus | Deliverable |
|---|---|---|
| Neo (Tech Lead) | Modular monolith boundary (0018) + stack (0015) + system boundary (0017) | Doc kiến trúc tổng + module split đề xuất |
| Lợi | Stage 7 story packet + TEST_MATRIX + verify command | Template code/test cho 1 story mẫu |
| Thắng | UI design system (0020) + design-guidelines + shadcn tokens | Design system contract cho Hubflow ERP |
| Mavis (AI partner) | Pattern tinh chỉnh + HARNESS_BACKLOG + research synthesis | PR synthesis tổng (nếu cần) |
1. Mỗi dev đọc xong 3 file gốc + checklist research ở trên
2. Họp align 30 phút: chia module + confirm stack + confirm tinh chỉnh
3. Zui quyết: làm detailed prototype trước hay nhảy thẳng Build
4. Đóng stage 7 → mở stage 8 Build
5. Wave A (6 P0 packet) bắt đầu code
6. Mỗi commit cite token, chạy verify command, update TEST_MATRIX
1. Fix 3 blockers (CRLF, hooksPath, visuals) — không fix thì team khác cũng vấp
2. Confirm runtime stack + module boundary với cả team
3. Đọc và ký cam kết 4 quy tắc sống còn (đặc biệt: KHÔNG bypass Verify Gate)
STAGE.md — đang ở stage nàoAGENTS.md — 4 quy tắc + Task Loop 10 bướcdocs/WORKFLOW.md — 13 stage mapdocs/HARNESS.md — mô hình hợp tác human × agentdocs/FEATURE_INTAKE.md — phân loại tiny/normal/high-riskdocs/STAGE_GOALS.md — goal từng stagedocs/TEST_MATRIX.md — proof paneldocs/HARNESS_BACKLOG.md — đề xuất tinh chỉnh