The full journeyHành trình đầy đủ
This page follows acme-shop — the sample e-commerce spec — through every stage of the harness loop: from a blank canvas to a validated, critiqued, packaged, and observed spec. Each stage shows what fires under the hood, what artifact it produces, and what the honest limits of the check are.Trang này theo acme-shop — spec thương mại điện tử mẫu — qua từng giai đoạn của vòng lặp harness: từ canvas trống đến spec đã kiểm tra, phản biện, đóng gói, và quan sát. Mỗi giai đoạn cho thấy cái gì kích hoạt bên trong, nó tạo ra artifact gì, và giới hạn trung thực của kiểm tra là gì.
One pipeline, one feedback loopMột quy trình, một vòng phản hồi
Raw ideas enter the pipeline as a Vision statement. They exit as a structured, traceable, validated, critiqued, and packaged spec. The loop does not end at Ship — telemetry reads the rig's health back, and critique findings flow back into recorded decisions via --apply-critique. --learn closes the outermost ring: spec → build → measure → learn.Ý tưởng thô đi vào quy trình dưới dạng tuyên bố Vision. Chúng ra ngoài dưới dạng spec có cấu trúc, có truy vết, đã kiểm tra, bị phản biện, và đã đóng gói. Vòng lặp không kết thúc ở Ship — telemetry đọc sức khỏe của bộ máy ngược về, và phát hiện phản biện chảy ngược vào các quyết định được ghi qua --apply-critique. --learn khép vòng ngoài cùng: spec → build → đo → học.
docs/product/phỏng vấn product-spec → docs/product/Define — Vision → BRD → PRD → Epic → StoryĐịnh nghĩa — Vision → BRD → PRD → Epic → Story
The product-spec skill runs a phased interview. For acme-shop, the PO answers questions about the north-star goal, the business objective, and the checkout feature area — and the skill builds the full five-layer hierarchy, each node traceable to its parent. Output lands entirely in docs/product/; the skill never writes outside that folder.Skill product-spec chạy một cuộc phỏng vấn theo giai đoạn. Với acme-shop, PO trả lời câu hỏi về mục tiêu north-star, mục tiêu kinh doanh, và vùng tính năng checkout — và skill xây dựng cây năm tầng đầy đủ, mỗi node có thể truy ngược đến cha. Đầu ra hoàn toàn ở docs/product/; skill không bao giờ ghi ra ngoài thư mục đó.
/cleanmatic:product-specThe tree below is the acme-shop spec after the Define stage — built from the real example in examples/acme-shop via --viz tree --format ascii:Cây bên dưới là spec acme-shop sau giai đoạn Định nghĩa — được xây từ ví dụ thật trong examples/acme-shop qua --viz tree --format ascii:
PRODUCT: Acme Shop
[goal:BRD-G1] Onboard 100 boutique brands in 12 months · approved
[prd:PRD-CATALOG] Catalog & Storefront · approved
[epic:PRD-CATALOG-E1] Catalog Management Epic · approved
[story:PRD-CATALOG-E1-S1] Add and publish a product · approved
[story:PRD-CATALOG-E1-S2] Track inventory per variant · approved
[epic:PRD-CATALOG-E2] Brand Storefront Epic · approved
[story:PRD-CATALOG-E2-S1] Browse the catalog · approved
[story:PRD-CATALOG-E2-S2] Product detail page · approved
[prd:PRD-CHECKOUT] Checkout · approved
[epic:PRD-CHECKOUT-E1] Sign-In + Address Epic · approved
[story:PRD-CHECKOUT-E1-S1] Magic-link sign-in at checkout · approved
[story:PRD-CHECKOUT-E1-S2] Saved addresses for returning shoppers · approved
[epic:PRD-CHECKOUT-E2] Stripe Payment Epic · approved
[story:PRD-CHECKOUT-E2-S1] Pay with Stripe at checkout · approved
[story:PRD-CHECKOUT-E2-S2] Order confirmation email · approved
[epic:PRD-CHECKOUT-E3] Order Tracking Epic · approved
[story:PRD-CHECKOUT-E3-S1] Track order status · approved
[goal:BRD-G2] Achieve 80% 90-day repeat-purchase rate · approved
[prd:PRD-CHECKOUT] Checkout · approved
[epic:PRD-CHECKOUT-E1] Sign-In + Address Epic · approved
[story:PRD-CHECKOUT-E1-S1] Magic-link sign-in at checkout · approved
[story:PRD-CHECKOUT-E1-S2] Saved addresses for returning shoppers · approved
[epic:PRD-CHECKOUT-E2] Stripe Payment Epic · approved
[story:PRD-CHECKOUT-E2-S1] Pay with Stripe at checkout · approved
[story:PRD-CHECKOUT-E2-S2] Order confirmation email · approved
[epic:PRD-CHECKOUT-E3] Order Tracking Epic · approved
[story:PRD-CHECKOUT-E3-S1] Track order status · approved
[prd:PRD-FANCRM] Fan-CRM · review
[epic:PRD-FANCRM-E1] Fan Messaging Epic · review
[story:PRD-FANCRM-E1-S1] Send a fan broadcast · draft
[story:PRD-FANCRM-E1-S2] Reply inbox · draft
[epic:PRD-FANCRM-E2] Audience Segments Epic · draft
[story:PRD-FANCRM-E2-S1] Segment by purchase history · draft
[goal:BRD-G3] Reach $2M GMV in the first year · approved
[prd:PRD-ANALYTICS] Brand Analytics · draft
[epic:PRD-ANALYTICS-E1] Revenue Dashboard Epic · draft
[story:PRD-ANALYTICS-E1-S1] View revenue over time · draft
[story:PRD-ANALYTICS-E1-S2] Export report CSV · draft
[prd:PRD-CATALOG] Catalog & Storefront · approved
[epic:PRD-CATALOG-E1] Catalog Management Epic · approved
[story:PRD-CATALOG-E1-S1] Add and publish a product · approved
[story:PRD-CATALOG-E1-S2] Track inventory per variant · approved
[epic:PRD-CATALOG-E2] Brand Storefront Epic · approved
[story:PRD-CATALOG-E2-S1] Browse the catalog · approved
[story:PRD-CATALOG-E2-S2] Product detail page · approved
[prd:PRD-CHECKOUT] Checkout · approved
[epic:PRD-CHECKOUT-E1] Sign-In + Address Epic · approved
[story:PRD-CHECKOUT-E1-S1] Magic-link sign-in at checkout · approved
[story:PRD-CHECKOUT-E1-S2] Saved addresses for returning shoppers · approved
[epic:PRD-CHECKOUT-E2] Stripe Payment Epic · approved
[story:PRD-CHECKOUT-E2-S1] Pay with Stripe at checkout · approved
[story:PRD-CHECKOUT-E2-S2] Order confirmation email · approved
[epic:PRD-CHECKOUT-E3] Order Tracking Epic · approved
[story:PRD-CHECKOUT-E3-S1] Track order status · approved
[goal:BRD-G4] Keep average brand payout latency under 3 days · approved
[prd:PRD-ANALYTICS] Brand Analytics · draft
[epic:PRD-ANALYTICS-E1] Revenue Dashboard Epic · draft
[story:PRD-ANALYTICS-E1-S1] View revenue over time · draft
[story:PRD-ANALYTICS-E1-S2] Export report CSV · draft
[prd:PRD-PAYOUTS] Brand Payouts · approved
[epic:PRD-PAYOUTS-E1] Automated Payouts Epic · approved
[story:PRD-PAYOUTS-E1-S1] Scheduled payout run · approved
[story:PRD-PAYOUTS-E1-S2] Payout statement export · approved
[goal:BRD-G5] Launch native mobile shopping by year 2 · review
[prd:PRD-MOBILE] Native Mobile Shopping · draft
[epic:PRD-MOBILE-E1] Mobile App Shell Epic · draft
[story:PRD-MOBILE-E1-S1] Mobile browse and buy · draft
[goal:BRD-G6] Scale to 500 brands with cross-brand discovery (year 3) · draft
[prd:PRD-DISCOVERY *] Cross-Brand Discovery · draft
[epic:PRD-DISCOVERY-E1 *] Cross-Brand Discovery Epic · draft
[story:PRD-DISCOVERY-E1-S1 *] Personalized discovery feed · draft
— 42 nodes · 6 goals · 7 prds · 11 epics · 18 stories · 0 findings
- The skill never sets
status: approvedon its own — that requires explicit PO sign-off with owner + date.Skill không bao giờ tự đặtstatus: approved— điều đó đòi hỏi PO ký duyệt rõ ràng với chủ + ngày. - It never overwrites PO prose on
--update— it flags affected nodes and asks first.Nó không bao giờ ghi đè văn PO khi--update— nó gắn cờ node bị ảnh hưởng và hỏi trước.
Validate — scripts first, LLM judgesKiểm tra — script trước, LLM nhận định
Validation runs in two passes. Deterministic scripts catch the structural failures that do not require judgment: orphaned nodes, missing acceptance criteria, broken ID traces, persona drift. The LLM layer then adds the judgment a script cannot: INVEST compliance, vague requirements, core-value drift, hidden duplicates. See the validation page for the full rule list.Kiểm tra chạy theo hai lượt. Script tất định bắt lỗi cấu trúc không cần nhận định: node mồ côi, thiếu tiêu chí chấp nhận, truy vết ID gãy, lệch persona. Lớp LLM sau đó thêm nhận định mà script không làm được: tuân thủ INVEST, yêu cầu mơ hồ, lệch giá trị cốt lõi, trùng lặp ẩn. Xem trang validation để biết danh sách quy tắc đầy đủ.
/cleanmatic:product-spec --validateStructural (scripts — deterministic)Cấu trúc (script — tất định)
Judgment (LLM — advisory)Nhận định (LLM — advisory)
approved artifact is surfaced verbatim — the harness never auto-fixes it. The PO chooses:
Một khẳng định mới mâu thuẫn với tài liệu approved được nêu nguyên văn — harness không bao giờ tự sửa. PO chọn:
Critique — four lenses, one reportPhản biện — bốn lăng kính, một báo cáo
--validate tells you the spec is structurally sound. product-spec-critique tells you whether it is any good. Four specialist sub-agents work in parallel, each reading the same spec through a different lens, then a consolidator merges their findings into one report — deduplicated, severity-ranked, with a concrete fix per finding. Every finding cites a real ID:line.--validate nói spec vững về cấu trúc. product-spec-critique nói nó có tốt không. Bốn sub-agent chuyên biệt làm việc song song, mỗi cái đọc cùng spec qua lăng kính khác nhau, rồi một consolidator gộp phát hiện của chúng thành một báo cáo — đã loại trùng, xếp hạng theo mức độ nghiêm trọng, kèm cách sửa cụ thể cho mỗi phát hiện. Mọi phát hiện trích dẫn ID:dòng thật.
/cleanmatic:product-spec-critiqueProductSản phẩm
JTBD, Value Prop Canvas, Kano, RICE-integrity, riskiest assumption, opportunity-solution tree. Catches features nobody needs, fake personas, gold-plating.JTBD, Value Prop Canvas, Kano, RICE-integrity, giả định rủi ro nhất, cây cơ hội-giải pháp. Bắt tính năng không ai cần, persona giả, gold-plating.
TechKỹ thuật
INVEST, Given-When-Then testability, hidden dependencies, complexity-vs-value, NFR gaps. Catches untestable AC and assume-success specs.INVEST, testability Given-When-Then, phụ thuộc ẩn, complexity-vs-value, thiếu NFR. Bắt AC không kiểm thử được và spec giả định thành công.
MarketThị trường
Lean Canvas, Porter-light, Blue Ocean, unit-economics, JTBD-competition. Catches me-too features, no revenue path, no moat.Lean Canvas, Porter-light, Blue Ocean, unit-economics, JTBD-competition. Bắt tính năng me-too, không có đường doanh thu, không có hào.
CraftVăn phong
CSI-4Cs (clear/concise/consistent/correct), terminology drift, unmeasurable adjectives, show-don't-tell, typos. Catches wall-of-text and vague wording.CSI-4Cs (rõ/súc tích/nhất quán/chính xác), drift thuật ngữ, tính từ không đo được, show-don't-tell, lỗi đánh máy. Bắt tường văn và từ ngữ mơ hồ.
--level bump alone only re-renders the voice without re-running sub-agents. Use --fresh to force a full rebuild. See critique and voice levels for the full contract.Chạy lại rẻ. Phản biện cùng phạm vi hai lần thì nó tái dùng kết quả cũ — không đổi spec là không phân tích lại; chỉ tăng --level thì chỉ render lại giọng mà không chạy lại sub-agent. Dùng --fresh để buộc rebuild hoàn toàn. Xem critique và mức giọng để biết hợp đồng đầy đủ.- Critique never edits the spec — it writes one report, the spec stays untouched.Phản biện không bao giờ sửa spec — nó chỉ ghi một báo cáo, spec không bị đụng đến.
- It is never a CI gate — it is opinionated and non-deterministic by design.
--validatestays the reproducible gate.Nó không bao giờ là cổng CI — về thiết kế nó có quan điểm và không tất định.--validatevẫn là cổng tái lập được. - A finding only becomes a recorded decision (
DEC-<n>) if the PO confirms it — critique never writes to memory on its own.Một phát hiện chỉ trở thành quyết định được ghi (DEC-<n>) nếu PO xác nhận — phản biện không bao giờ tự ghi vào bộ nhớ.
Ship — deterministic, hashed, manifest-firstĐóng gói — tất định, có hash, manifest trước
The release skill bundles a curated subset of .claude/ — skills, agents, hooks, rules, the shared eval-gate — into a versioned, deterministic tar.gz. The safety filter drops secrets, .env files, .git/, runtime caches, and session state unconditionally: no flag re-admits them. Each bundle ships with a MANIFEST.json (per-file SHA-256), an INSTALL.md, and multiplatform installers so the recipient runs once and is done.Skill release bundle một tập con chọn lọc của .claude/ — skill, agent, hook, rule, eval-gate dùng chung — thành tar.gz versioned, tất định. Bộ lọc an toàn loại secret, file .env, .git/, cache runtime, và session state vô điều kiện: không cờ nào đưa chúng lại. Mỗi bundle kèm MANIFEST.json (SHA-256 per file), INSTALL.md, và installer đa nền tảng để người nhận chạy một lần là xong.
Preview the bundle — no tarball writtenXem trước bundle — không ghi tarball
/cleanmatic:release -m pack --manifest .claude/pack.manifest.yaml --dry-runbundle_root: product-spec-2.4.0 file_count: 318 total_bytes: 4626012 output_path: /home/hieubt15/Documents/vsf/product-spec/.claude/skills/release/scripts/dist/product-spec-2.4.0.tar.gz max_size: 104857600 would_be_sha256: 414c2cbac29472cdba8f8e4a95f4cb784be6ad092b730844ba7ba806dbc8ba8f over_max_size: False
Build the real bundleBuild bundle thật
/cleanmatic:release -m pack --manifest .claude/pack.manifest.yamlOutput lands in dist/product-spec-{version}.tar.gz + a .sha256 sidecar. The dist/ directory is gitignored — tarballs are reproducible artifacts, not source. Same inputs always produce byte-identical output.Đầu ra ở dist/product-spec-{version}.tar.gz + sidecar .sha256. Thư mục dist/ bị gitignore — tarball là artifact tái lập, không phải source. Cùng đầu vào luôn tạo ra đầu ra giống nhau từng byte.
- No remote upload — use
gh release uploador your CI pipeline after the tarball is built.Không upload từ xa — dùnggh release uploadhoặc CI pipeline sau khi tarball được build. - No GPG signing in v1 — SHA-256 sidecar only.Không ký GPG ở v1 — chỉ sidecar SHA-256.
- Determinism is a contract:
SOURCE_DATE_EPOCHpins the timestamp; without it, mtime varies. CI builds should always set it.Tính tất định là hợp đồng:SOURCE_DATE_EPOCHghim timestamp; không có nó, mtime thay đổi. Build CI luôn nên đặt giá trị này.
Observe — usage & health, never market effectivenessQuan sát — mức dùng & sức khỏe, không phải hiệu quả thị trường
After running the harness for a while, telemetry tells you — in plain Vietnamese — how the tooling is actually performing. Eight lenses cover skill invocation counts, script error rates, sub-agent success/fail, last validate result, and memory tidiness. A script gathers deterministic counts; the skill narrates them and always ends with a "what this does not measure" section. On a thin or new repo, most lenses say "chưa đủ dữ liệu" and suppress recommendations rather than inventing trends.Sau khi dùng harness một thời gian, telemetry cho bạn biết — bằng tiếng Việt thuần — bộ đồ nghề đang hoạt động thế nào. Tám lăng kính bao gồm số lần gọi skill, tỷ lệ lỗi script, sub-agent thành/thất bại, kết quả validate cuối, và độ gọn của bộ nhớ. Script thu thập số liệu tất định; skill diễn giải chúng và luôn kết thúc bằng mục "Cái này KHÔNG đo được". Trên repo mỏng hoặc mới, hầu hết lăng kính nói "chưa đủ dữ liệu" và tắt gợi ý thay vì bịa xu hướng.
/cleanmatic:telemetry== TELEMETRY: MỨC DÙNG & SỨC KHỎE == [OK] MỨC DÙNG — 35 lượt gọi, 4 đã dùng, 0 sở hữu chưa dùng
Eight lensesTám lăng kính
Four output formatsBốn định dạng đầu ra
- Telemetry measures whether the machinery runs, not whether the product wins in the market. The
validateproxy means "spec is well-formed" — not "users adopted it".Telemetry đo máy móc có chạy không, không phải sản phẩm có thắng thị trường không. Proxyvalidatenghĩa là "spec đúng cấu trúc" — không phải "người dùng đã chấp nhận". - Token weight and duration figures are directional approximations, labelled "ước lượng" — not billing-exact.Trọng số token và số liệu thời gian là ước tính định hướng, được ghi nhãn "ước lượng" — không chính xác theo hóa đơn.
- Telemetry is read-only — it never edits specs, code, the catalog, or memory, and has no
--apply.Telemetry chỉ-đọc — không bao giờ sửa spec, code, catalog, hay bộ nhớ, và không có--apply.
The return edge — critique back into decisions, --learn closes the loopCạnh quay về — phản biện ngược vào quyết định, --learn khép vòng
The pipeline is not linear — it has two explicit return paths that close the loop and make the harness self-improving over time.Quy trình không tuyến tính — nó có hai đường quay về rõ ràng giúp khép vòng và làm harness tự cải thiện theo thời gian.
Critique → recorded decisions via --apply-critiquePhản biện → quyết định được ghi qua --apply-critique
After a critique report is generated, the PO reviews the findings. Accepted findings become DEC-<n> entries in the Decision Register — so they are not re-litigated in future critique runs and guide the next iteration of the spec. Run --apply-critique <report> to feed a report back into the spec workflow.Sau khi báo cáo phản biện được tạo, PO xem xét các phát hiện. Phát hiện được chấp nhận trở thành mục DEC-<n> trong Sổ Quyết định — để chúng không bị tranh luận lại trong các lần phản biện tương lai và định hướng vòng lặp tiếp theo của spec. Chạy --apply-critique <report> để đưa báo cáo ngược vào workflow spec.
/cleanmatic:product-spec --apply-critique <path-to-critique-report>--learn — spec → build → measure → learn--learn — spec → build → đo → học
--learn closes the outermost ring. After a feature is built and measured, --learn takes outcome notes (what was observed post-build) and propagates them back into the spec's learning views — so the spec captures not just what was intended but what was learned. This feeds the --viz learning and --viz outcome-trend views.--learn khép vòng ngoài cùng. Sau khi một tính năng được build và đo, --learn nhận ghi chú kết quả (những gì quan sát được sau build) và lan truyền chúng ngược vào khung nhìn học của spec — để spec ghi lại không chỉ những gì đã dự định mà còn những gì đã học được. Điều này cung cấp cho các khung nhìn --viz learning và --viz outcome-trend.
/cleanmatic:product-spec --learnproduct-spec defines and validates → product-spec-critique challenges → --apply-critique records decisions → the build team builds → --learn feeds outcomes back → telemetry reads health — and the next spec iteration starts better than the last.Vòng lặp đầy đủ trong một dòng: product-spec định nghĩa và kiểm tra → product-spec-critique thách thức → --apply-critique ghi quyết định → đội build xây dựng → --learn đưa kết quả ngược về → telemetry đọc sức khỏe — và vòng lặp spec tiếp theo bắt đầu tốt hơn lần trước.