InstallCài đặt
Installing is one command. It creates the shared Python venv, installs runtime dependencies, vendors Mermaid, marked, and DOMPurify for offline HTML output — verifying each against a pinned SHA-256 — then smoke-tests the result. Re-running is safe (idempotent). After install, everything runs on your machine; no network is needed at runtime.Cài đặt là một lệnh. Nó tạo venv Python dùng chung, cài phụ thuộc runtime, vendor Mermaid, marked, DOMPurify cho đầu ra HTML offline — kiểm từng cái bằng SHA-256 đã ghim — rồi smoke-test kết quả. Chạy lại an toàn (idempotent). Sau khi cài, mọi thứ chạy trên máy bạn; không cần mạng khi chạy.
RequirementsYêu cầu
The harness needs two things on the machine before you install: a recent Python and (on first install if the vendored JS is absent) a download tool. Claude Code is assumed to be already running.Harness cần hai thứ trên máy trước khi cài: một Python gần đây và (lần đầu cài nếu JS chưa vendor) một công cụ tải xuống. Claude Code được coi là đã chạy sẵn.
| RequirementYêu cầu | DetailsChi tiết |
|---|---|
| Python 3.11+ | Required at both install time and runtime. The shared venv is created at .claude/skills/.venv/; all four skills use it. Check: python3 --version. If missing, install from python.org.Cần cả lúc cài và lúc chạy. Venv dùng chung được tạo tại .claude/skills/.venv/; cả bốn skill dùng chung. Kiểm tra: python3 --version. Nếu thiếu, cài từ python.org. |
curl orhoặc wget |
Needed on POSIX for the one-time vendor download of Mermaid, marked, and DOMPurify. After the first install (or on a repo where the vendored files are already committed) this step is skipped.Cần trên POSIX cho lần tải vendor một lần của Mermaid, marked, DOMPurify. Sau lần đầu cài (hoặc trên repo đã commit sẵn file vendor) bước này bị bỏ qua. |
| Claude CodeClaude Code | Open in your project folder (the one containing .claude/) so the skills are visible in the command palette. Restart after install if Claude Code was already open.Mở trong thư mục dự án (thư mục chứa .claude/) để skill hiện trong command palette. Khởi động lại Claude Code nếu nó đã mở sẵn trước khi cài. |
python3, so the venv must remain present and intact on the machine where Claude Code operates. The four skills share one venv at .claude/skills/.venv/ — created or updated by any of the skill installers.Python là yêu cầu runtime, không chỉ lúc cài. Mọi script harness gọi lúc chạy đều là python3, nên venv phải còn nguyên trên máy chạy Claude Code. Bốn skill dùng chung một venv tại .claude/skills/.venv/ — được tạo hoặc cập nhật bởi bất kỳ installer nào của skill.One commandMột lệnh
Run the appropriate installer from your project root (the directory containing .claude/). The installer is idempotent — it checks what is already done and skips completed steps safely.Chạy trình cài phù hợp từ thư mục gốc dự án (thư mục chứa .claude/). Trình cài là idempotent — nó kiểm những gì đã xong và bỏ qua bước hoàn thành một cách an toàn.
POSIX — macOS, Linux, WSLPOSIX — macOS, Linux, WSL
bash .claude/skills/product-spec/install.shAdd --dev to also install pytest + pytest-cov and run the test suite against the freshly installed skill. Idempotent — re-run any time.Thêm --dev để cài thêm pytest + pytest-cov và chạy bộ test với skill vừa cài. Idempotent — chạy lại bất cứ lúc nào.
Windows — PowerShellWindows — PowerShell
powershell -ExecutionPolicy Bypass -File .\.claude\skills\product-spec\install.ps1Add -Dev for the dev dependencies. Requires Python 3.11+ on PATH or the py launcher.Thêm -Dev cho phụ thuộc dev. Yêu cầu Python 3.11+ trên PATH hoặc launcher py.
After the installer completes, invoke the skill from Claude Code:Sau khi trình cài hoàn tất, gọi skill từ Claude Code:
/cleanmatic:product-specWhat it installsNó cài gì
Installing drops a coordinated .claude/ tree into your project — not just the skill files. See the full rig page for a component-by-component breakdown. The key pieces placed on disk:Cài đặt thả một cây .claude/ phối hợp vào dự án — không chỉ file skill. Xem trang cả bộ máy để biết chi tiết từng thành phần. Các phần chính được đặt trên đĩa:
Shared Python venvVenv Python dùng chung
.claude/skills/.venv/ — created by the installer and shared by all four skills. Contains pyyaml (runtime). Add --dev / -Dev to also install pytest + pytest-cov..claude/skills/.venv/ — được tạo bởi trình cài và dùng chung bởi cả bốn skill. Chứa pyyaml (runtime). Thêm --dev / -Dev để cài thêm pytest + pytest-cov.
Vendored JS runtimesJS runtime đã vendor
mermaid.min.js, marked.min.js, purify.min.js — downloaded once from the public CDN (cdn.jsdelivr.net), verified against pinned SHA-256 hashes, and stored locally. All HTML visualization views render offline after this step.mermaid.min.js, marked.min.js, purify.min.js — tải một lần từ CDN công khai (cdn.jsdelivr.net), kiểm bằng SHA-256 đã ghim, rồi lưu cục bộ. Mọi khung nhìn trực quan HTML render offline sau bước này.
Skills, sub-agents, hooks, and rulesSkill, sub-agent, hook và rule
Four skills under .claude/skills/, seven critique sub-agents under .claude/agents/, hooks under .claude/hooks/ (5 telemetry sinks auto-registered; memory-gap hook opt-in), and orchestration rules under .claude/rules/.Bốn skill ở .claude/skills/, bảy sub-agent phản biện ở .claude/agents/, hook ở .claude/hooks/ (5 sink telemetry tự đăng ký; memory-gap hook opt-in), và rule điều phối ở .claude/rules/.
docs/product/, telemetry sinks under .claude/telemetry/*.jsonl (gitignored), and release tarballs under dist/ (gitignored). The installer does not touch these.Sinh ra lúc chạy, không phải lúc cài: file spec của bạn ở docs/product/, sink telemetry ở .claude/telemetry/*.jsonl (gitignore), và tarball release ở dist/ (gitignore). Trình cài không đụng đến những thứ này.Offline & privateOffline & riêng tư
All four skills make no network calls at runtime. The one-time installer vendors Mermaid, marked, and DOMPurify from the public CDN and verifies each against a pinned SHA-256 before storing them. Once installed, those files never change unless you re-run the installer.Cả bốn skill không gọi mạng khi chạy. Trình cài một lần vendor Mermaid, marked, DOMPurify từ CDN công khai và kiểm từng cái bằng SHA-256 đã ghim trước khi lưu. Sau khi cài, các file đó không bao giờ thay đổi trừ khi bạn chạy lại trình cài.
Telemetry sinks — stdlib onlySink telemetry — chỉ stdlib
The 5 telemetry sink hooks are fail-open and use only Python stdlib — no pip package, no network. They write to gitignored .claude/telemetry/*.jsonl files on your local disk only. Nothing is transmitted anywhere.5 sink hook telemetry là fail-open và chỉ dùng Python stdlib — không gói pip, không mạng. Chúng chỉ ghi vào file .claude/telemetry/*.jsonl đã gitignore trên đĩa cục bộ. Không có gì được truyền đi đâu.
Release safety filter — always onBộ lọc an toàn release — luôn bật
The release skill's safety filter always drops .env files, secrets, keys, .git/, runtime caches, and session state from any bundle — no flag can disable this rule.Bộ lọc an toàn của skill release luôn loại file .env, secret, key, .git/, cache runtime, và session state khỏi mọi bundle — không cờ nào tắt được luật này.
mermaid.min.js failed to vendor (network was unavailable at install time), Mermaid graph views fall back to a cdn.jsdelivr.net script at browser-render time. ASCII views and body views never reach a CDN. Fix: re-run the installer with network access to complete the vendor step.Lưu ý cài bị thiếu: nếu mermaid.min.js không vendor được (mạng không có lúc cài), khung nhìn Mermaid graph fall back về script cdn.jsdelivr.net lúc browser render. Khung nhìn ASCII và body không bao giờ dùng CDN. Cách sửa: chạy lại trình cài khi có mạng để hoàn tất bước vendor.Verify & troubleshootXác nhận & xử lý sự cố
If the installer completed without error, the venv is intact and the vendored files are present and verified. The most common issues are a missing Python or a vendoring failure due to network access.Nếu trình cài hoàn tất không lỗi, venv nguyên vẹn và các file vendor đã có và được kiểm. Sự cố phổ biến nhất là thiếu Python hoặc vendor thất bại do không có mạng.
python3: command not foundpython3: command not found
apt install python3 (Debian/Ubuntu), brew install python (macOS), or download from python.org. Then re-run the installer.Cài Python 3.11+ trước: apt install python3 (Debian/Ubuntu), brew install python (macOS), hoặc tải từ python.org. Rồi chạy lại trình cài.bash: install.sh: Permission deniedbash: install.sh: Permission denied
chmod +x .claude/skills/product-spec/install.sh, then re-run. On Windows, always use the PowerShell form with -ExecutionPolicy Bypass.Đánh dấu script có quyền thực thi trước: chmod +x .claude/skills/product-spec/install.sh, rồi chạy lại. Trên Windows, luôn dùng dạng PowerShell với -ExecutionPolicy Bypass.pip install hangs or failspip install bị treo hoặc lỗi
pyyaml. Check your network connection. If you are behind a proxy, set https_proxy before running. After the first successful install, the venv is local and the skill runs offline.Trình cài cần truy cập PyPI một lần để cài pyyaml. Kiểm tra kết nối mạng. Nếu sau proxy, đặt https_proxy trước khi chạy. Sau lần cài thành công đầu tiên, venv là cục bộ và skill chạy offline.Claude Code doesn't see the skill after installClaude Code không thấy skill sau khi cài
.claude/. If it was already open before you installed, restart it so it picks up the new skill directories.Đảm bảo bạn mở Claude Code trong thư mục dự án — thư mục chứa .claude/. Nếu nó đã mở trước khi bạn cài, khởi động lại để nó nhận thư mục skill mới.How do I debug the installer step by step?Làm sao debug trình cài từng bước?
bash -x .claude/skills/product-spec/install.sh to print each step as it runs. The output will show exactly which step failed and why.Chạy trình cài POSIX với bash -x .claude/skills/product-spec/install.sh để in từng bước khi chạy. Đầu ra sẽ cho thấy chính xác bước nào thất bại và tại sao.Can I opt in to the memory-gap enforcement hook?Có thể opt-in vào memory-gap enforcement hook không?
bash .claude/skills/product-spec/install.sh --memory-hook to flip the flag. The hook is already wired into the bundle's Stop chain; enabling it just turns on the gate. To disable later, set "memory_gap_hook": false in .claude/hooks/product-spec-hooks.json.Có — mặc định tắt và có cổng cấu hình. Chạy bash .claude/skills/product-spec/install.sh --memory-hook để bật cờ. Hook đã được nối vào chuỗi Stop của bundle; bật nó chỉ là mở cổng. Để tắt sau, đặt "memory_gap_hook": false trong .claude/hooks/product-spec-hooks.json.