Product Spec Harness
GuidesHướng dẫn
HomeTrang chủ › GuidesHướng dẫn › Quick startBắt đầu
Zero to a validated spec in under ten minutesTừ tay không đến spec đã kiểm tra trong dưới mười phút

Quick startBắt đầu nhanh

Five steps: install the harness once, define your first spec through a guided interview, validate and critique it, visualize the hierarchy, and preview a release — all in plain language, no code required from you.Năm bước: cài harness một lần, định nghĩa spec đầu tiên qua phỏng vấn có hướng dẫn, kiểm tra và phản biện nó, trực quan hóa cây cấu trúc, và xem trước bản phát hành — tất cả bằng ngôn ngữ bình thường, không cần code từ phía bạn.

STEP 1BƯỚC 1

Install onceCài một lần

One command drops the coordinated .claude/ rig — four skills, seven critique sub-agents, hooks, rules, and the shared eval-gate — into your project. Requires Python 3.11+. Full details and options on the Install page.Một lệnh thả cả bộ .claude/ phối hợp — bốn skill, bảy sub-agent phản biện, hooks, rules, và eval-gate dùng chung — vào dự án của bạn. Yêu cầu Python 3.11+. Chi tiết đầy đủ và tùy chọn ở trang Cài đặt.

POSIX (macOS / Linux / WSL)POSIX (macOS / Linux / WSL)

bash .claude/skills/product-spec/install.sh

Windows (PowerShell)Windows (PowerShell)

powershell -ExecutionPolicy Bypass -File .\.claude\skills\product-spec\install.ps1

The installer creates the shared venv at .claude/skills/.venv/, installs pyyaml, and vendors Mermaid, marked, and DOMPurify for offline HTML output — verifying each against a pinned SHA-256. Re-running is safe (idempotent). After install, open Claude Code in your project folder so it picks up the new skills, then proceed below.Trình cài tạo venv dùng chung tại .claude/skills/.venv/, cài pyyaml, và vendor Mermaid, marked, DOMPurify cho đầu ra HTML offline — kiểm từng cái bằng SHA-256 đã ghim. Chạy lại an toàn (idempotent). Sau khi cài, mở Claude Code trong thư mục dự án để nó nhận skill mới, rồi tiến hành bên dưới.

STEP 2BƯỚC 2

Define your first specĐịnh nghĩa spec đầu tiên

Run product-spec from the Claude Code command palette. With no flags it shows a menu; the interview walks you through Vision → BRD → PRD → Epic → Story with acceptance criteria, one question at a time. Output lands in docs/product/ — markdown files with YAML frontmatter, never written elsewhere. See the product-spec skill page and spec hierarchy for the full contract.Chạy product-spec từ command palette của Claude Code. Không có cờ nào thì hiện menu; cuộc phỏng vấn dẫn bạn qua Vision → BRD → PRD → Epic → Story kèm tiêu chí chấp nhận, từng câu một. Đầu ra ở docs/product/ — file markdown có YAML frontmatter, không bao giờ ghi ra ngoài. Xem trang skill product-spec và cây spec để biết hợp đồng đầy đủ.

/cleanmatic:product-spec

The five-layer hierarchyCây năm tầng

Every node traces up to the Vision and down to testable acceptance criteria. IDs like PRD-CATALOG-E1-S2 encode the full path.Mọi node truy ngược lên Vision và truy xuôi xuống tiêu chí chấp nhận có thể kiểm thử. Mã như PRD-CATALOG-E1-S2 mã hóa toàn bộ đường dẫn.

Vision BRD PRD Epic Story + AC

Useful flags to know earlyCờ hữu ích biết sớm

You don't have to start from scratch. Drop a brain-dump and let the skill structure it, or target a single feature area.Bạn không cần bắt đầu từ đầu. Đổ "bãi ý tưởng" và để skill cấu trúc lại, hoặc chỉ nhắm vào một vùng tính năng.

--auto --prd <feature> --discover <path> --lang en|vi
STEP 3BƯỚC 3

Validate & critiqueKiểm tra & phản biện

--validate runs deterministic scripts first (orphans, missing AC, ID integrity, broken trace) then an LLM judgment layer (INVEST, vagueness, core-value drift). It is the reproducible gate. product-spec-critique goes further — four lens sub-agents tear the same spec apart and say what --validate cannot: why it would die in the market. See validation and critique for the full depth.--validate chạy script tất định trước (mồ côi, thiếu AC, tính toàn vẹn ID, truy vết gãy) rồi lớp LLM nhận định (INVEST, mơ hồ, lệch giá trị cốt lõi). Đây là cổng tái lập được. product-spec-critique đi xa hơn — bốn sub-agent lăng kính xé cùng spec đó và nói điều --validate không nói được: vì sao nó chết trên thị trường. Xem validation và critique để biết chiều sâu đầy đủ.

Structural + LLM validationKiểm tra cấu trúc + LLM

/cleanmatic:product-spec --validate

Four-lens critique (product / tech / market / craft)Phản biện bốn lăng kính (product / tech / market / craft)

/cleanmatic:product-spec-critique

Default voice is level 5 — brutal but grounded, all about the work. Dial it with --level 1..9. Critique never edits your spec and is never a CI gate.Giọng mặc định là mức 5 — gắt nhưng có căn cứ, xoay quanh công việc. Điều chỉnh bằng --level 1..9. Critique không bao giờ sửa spec và không bao giờ là cổng CI.

No-silent-reversal gate.Cổng không-đảo-ngầm. If a new claim contradicts an approved artifact, the harness surfaces it verbatim and asks the PO to choose: Nếu một khẳng định mới mâu thuẫn với tài liệu approved, harness nêu nguyên văn và yêu cầu PO chọn:
KeepChange + re-approveHybrid
STEP 4BƯỚC 4

Visualize & shipTrực quan hóa & đóng gói

Once the spec is validated and approved, two more commands close the loop: --viz renders the hierarchy in 20 views across three formats; release --dry-run previews the deterministic bundle without writing a tarball; and telemetry reads the harness's own health back to you in plain Vietnamese. Full docs: release and telemetry.Khi spec đã được kiểm tra và duyệt, hai lệnh nữa khép vòng: --viz dựng cây cấu trúc trong 20 khung nhìn qua ba định dạng; release --dry-run xem trước bundle tất định mà không ghi tarball; và telemetry đọc sức khỏe của chính harness bằng tiếng Việt thuần. Tài liệu đầy đủ: release và telemetry.

Visualize the spec tree (20 views — ascii, mermaid, html)Trực quan hóa cây spec (20 khung nhìn — ascii, mermaid, html)

/cleanmatic:product-spec --viz tree

Preview a release bundle without writing a tarballXem trước bundle phát hành mà không ghi tarball

/cleanmatic:release -m pack --manifest .claude/pack.manifest.yaml --dry-run

Read harness usage & health in one glanceĐọc mức dùng & sức khỏe harness trong một cái liếc

/cleanmatic:telemetry
🔒
No network calls at runtime. The installer vendors Mermaid, marked, and DOMPurify locally, each verified against a pinned SHA-256. After install, all four skills run entirely on your machine. Telemetry sinks write only to gitignored .claude/telemetry/*.jsonl — nothing is transmitted.Không gọi mạng khi chạy. Trình cài vendor Mermaid, marked, DOMPurify cục bộ, mỗi cái được kiểm bằng SHA-256 đã ghim. Sau khi cài, cả bốn skill chạy hoàn toàn trên máy bạn. Sink telemetry chỉ ghi vào .claude/telemetry/*.jsonl đã gitignore — không có gì được truyền đi.
FAQHỎI ĐÁP

Common questionsCâu hỏi thường gặp

Do I need to write any code?Tôi có cần viết code không?
No. The four skills are invoked entirely through the Claude Code command palette in plain language. The product-spec and product-spec-critique skills are designed specifically for non-technical product owners.Không. Bốn skill được gọi hoàn toàn qua command palette của Claude Code bằng ngôn ngữ bình thường. Skill product-spec và product-spec-critique được thiết kế đặc biệt cho Product Owner không chuyên kỹ thuật.
Where does the spec output land?Đầu ra spec nằm ở đâu?
product-spec writes only to docs/product/ inside your project — markdown files with YAML frontmatter. It never writes prose anywhere else in the repo.product-spec chỉ ghi vào docs/product/ bên trong dự án của bạn — file markdown có YAML frontmatter. Không bao giờ ghi văn ra nơi khác trong repo.
Can I re-run the installer safely?Có chạy lại trình cài an toàn không?
Yes — the installer is idempotent. Each step checks whether it is already done and skips if so. The vendored JS files are verified against pinned SHA-256 hashes on every run.Có — trình cài là idempotent. Mỗi bước kiểm xem đã làm chưa và bỏ qua nếu rồi. Các file JS đã vendor được kiểm bằng SHA-256 đã ghim ở mỗi lần chạy.
Can I use the harness in Vietnamese?Tôi có dùng harness bằng tiếng Việt không?
Yes. Pass --lang vi and the interview, story descriptions, and AC are written in Vietnamese. IDs and frontmatter keys stay English for structural stability. Visualization labels also localize. The telemetry skill narrates entirely in plain Vietnamese by default.Có. Truyền --lang vi và phỏng vấn, mô tả story, AC được viết bằng tiếng Việt. Mã và khóa frontmatter vẫn là tiếng Anh để cấu trúc ổn định. Nhãn trực quan cũng được bản địa hóa. Skill telemetry mặc định trần thuật hoàn toàn bằng tiếng Việt thuần.
What if the HTML visualization shows a blank diagram?Nếu trực quan hóa HTML hiện sơ đồ trống thì sao?
Re-run the installer — it will re-vendor the Mermaid engine. ASCII and body views never require the CDN; only Mermaid graph views fall back to a CDN script if the local vendor copy is missing.Chạy lại trình cài — nó sẽ vendor lại Mermaid engine. Khung nhìn ASCII và body không bao giờ cần CDN; chỉ khung nhìn Mermaid graph mới fall back về CDN script nếu bản vendor cục bộ bị thiếu.
What happens if a new claim contradicts an approved artifact?Điều gì xảy ra nếu khẳng định mới mâu thuẫn với tài liệu đã duyệt?
The harness surfaces the contradiction verbatim and gives the PO three choices: Keep (reject the new claim), Change (re-approve with owner + date), or Hybrid (record both, schedule a follow-up). It never silently picks a side or edits approved content.Harness nêu mâu thuẫn nguyên văn và cho PO ba lựa chọn: Giữ (bác khẳng định mới), Đổi (duyệt lại với chủ + ngày), hoặc Kết hợp (ghi cả hai, lên lịch theo dõi). Không bao giờ tự chọn bên hay sửa nội dung đã duyệt.
Full install guideHướng dẫn cài đặt đầy đủ See the full journeyXem hành trình đầy đủ
← PrevTrướcAll guidesMục lụcNextSau →InstallCài đặt