Nơi lưu cách làm việc của team — để AI làm đúng ngay từ lần đầu
Xem mã nguồn và bản phát hành trên GitHub
Một thư viện hướng dẫn dùng chung cho cả người và AI. Bạn ghi cách team làm việc vào wiki. Trước khi hỗ trợ, AI sẽ đọc các hướng dẫn này để làm đúng chuẩn của team.
Mỗi công ty/dự án = 1 workspace. Kiến thức KHÔNG trộn lẫn giữa các workspace.
Gói kiến thức theo công nghệ: web-api, frontend-react, ai-app, product, ... Bật/tắt tuỳ ý.
Thoả thuận cố định: cấu trúc API, định dạng dữ liệu, mã lỗi. Engineer KHÔNG được thay đổi.
Cách làm chuẩn cho từng vấn đề. Dùng lại thay vì tự nghĩ cách mới mỗi lần.
Tóm tắt sản phẩm, mục tiêu, người dùng, số đo — kiến thức phi kỹ thuật. Cần pack-product.
Quy trình: đưa dữ liệu thô vào → phân tích → kiểm tra → áp vào wiki.
Chọn đúng vai trò để xem các bước bắt đầu đơn giản nhất.
Bạn không cần viết code. Bạn chỉ cần mô tả mục tiêu, người dùng và bối cảnh sản phẩm.
Nếu bạn làm business, bắt đầu ở đâyBạn viết code và muốn AI tuân thủ contracts/patterns của team. Bạn cần wiki-aware code generation.
Nếu bạn là developer, bắt đầu ở đâyBạn setup và duy trì wiki cho team — đưa dữ liệu vào, viết quy tắc, kiểm tra wiki không lệch so với code thật.
Nếu bạn quản lý wiki, bắt đầu ở đâyBạn làm ngành khác (cơ khí, kế toán, y tế...) và dùng Claude Code như "công cụ tự build" để tạo ứng dụng hỗ trợ công việc.
Nếu bạn không phải dev nhưng tự làm tool, bắt đầu ở đâyPM, Product Owner, Business Analyst, Stakeholder. Không cần biết lập trình.
Bạn không cần tự tạo workspace. Chỉ cần biết team đang dùng workspace nào.
Trong Claude Code, gõ /list-workspaces để xem tất cả.
/list-workspacesNếu gặp từ khó (ví dụ thuật ngữ kỹ thuật), dùng lệnh sau để nhận giải thích ngắn gọn:
/contextd-explain chủ-đề. Kết quả là 1 trang giải thích đơn giản, có ví dụ thực tế.
/contextd-explain circuit-breaker --depth tldr
/contextd-explain mqtt-topic-contract --depth shortHệ thống sẽ hỏi theo mẫu: vấn đề gì, ai dùng, đo thành công ra sao, mốc thời gian khi nào. Không cần trả lời kỹ thuật.
/product-brief "Reduce signup friction for mobile users"Hệ thống sẽ tự lưu kết quả. Bạn chỉ cần điền các mục còn trống.
/business-view {service-name} — output là 1 document plain-language tự động sync với engineering doc.
Backend / frontend / fullstack / mobile dev. Bạn viết code, AI đọc wiki rồi sinh code đúng quy tắc team.
Lần đầu mở 1 codebase mới. Lệnh detect project name + tech stack rồi tạo
.claude/wiki.json kết nối với workspace.
/contextd-setupNếu workspace chưa có, gõ /new-workspace tên-dự-án để tạo mới.
Biết mình cần tìm gì thì dùng /find {keywords} để tìm nhanh trong wiki.
/find idempotency retry
/find rest error shapeTrước MỌI task (implement feature, fix bug, design, incident, review), gõ
/use-contextd để chạy quy trình kiểm tra trước khi viết code, giúp giảm sai sót.
/use-contextd implement payment refund flow with idempotencyMục tiêu: code bám đúng quy tắc của team, tránh tạo ra phần không được thống nhất.
/update-contextd để wiki cập nhật theo code mới.
Định kỳ chạy /rebase-contextd để sửa chỗ wiki khác so với code thật.
Bạn setup wiki cho team mới, hoặc tạo workspace từ codebase cũ.
Wizard hỏi metadata (company, role, period, stack, packs) rồi scaffold đủ folder + workspace.md + patterns-index.md trống.
/new-workspace acme-corpNếu team đã có codebase legacy, dùng /code-analyze để snapshot codebase
→ hệ thống đề xuất quy tắc, thoả thuận, và kiến trúc từ code thật.
/code-analyze
/evidence-qa
/evidence-applyMột file HTML self-contained với toàn bộ workspace (Overview / Architecture / Contracts / Patterns / Domains / ADRs / Runbooks).
/contextd-reportMở file HTML trong trình duyệt — không cần server.
/contextd-eval để xem hiệu quả wiki
(hallucination rate, knowledge gaps, plan-block rate). Khi nghi wiki lệch so với code → /rebase-contextd.
Bạn là chuyên gia ngành khác (cơ khí, kế toán, y tế, luật, giáo viên...) tự dùng Claude Code làm trợ lý cá nhân để tạo công cụ. Có ý tưởng nhưng không biết bắt đầu từ đâu.
Cách dễ nhất: gõ /tool-design ngay — hệ thống tự hỏi và bật gói giúp.
Cách thủ công: chạy /contextd-setup → bước chọn packs, tick pack-solo-builder.
Khi muốn áp cho tất cả dự án trong workspace → sửa file workspace.md mục ## Packs:
## Packs
- pack-solo-builderÝ tưởng chưa rõ cũng OK. Hệ thống sẽ hỏi 6-8 câu (mỗi câu có ví dụ + option "tôi không biết"), vẽ sơ đồ hệ thống, kiểm tra công cụ đã có để tránh trùng, rồi gợi ý cách làm phù hợp.
/tool-design "tool tính moment uốn cho dầm thép"
/tool-design "quản lý kho linh kiện trong xưởng"
/tool-design "pull tỷ giá USD/VND mỗi sáng"Kết quả: 1 bản thiết kế chứa sơ đồ hệ thống, công nghệ được chọn + lý do, hướng dẫn cài đặt cho cả Linux lẫn Windows, và tiêu chí kiểm tra.
Khi bản thiết kế đã hoàn chỉnh (đầy đủ, không còn câu hỏi mở), yêu cầu Claude Code viết code theo đúng thiết kế:
implement spec ở workspaces/{ws}/tools/{slug}-spec.mdClaude sẽ viết code đúng theo bản thiết kế — không tự đổi công nghệ hay tự quyết định.
/tool-list xem công cụ đã tạo (tránh tạo trùng). /tool-extend tên-công-cụ thêm tính năng cho công cụ đã có. Trên Windows nếu cần cài đặt phức tạp → Claude tự gợi ý dùng Docker.
Hiểu 5 khái niệm này là đủ để dùng wiki hằng ngày.
.claude/wiki.json.packs. Bật/tắt qua /contextd-setup bước chọn packs (giao diện tick), hoặc sửa file workspace.md. Hiện có 13 packs, xem section bên dưới./use-contextd, /find, ...) = lệnh bạn gọi trực tiếp.
Quy trình nội bộ (planner, context-selector, reviewer, ...) = các bước chạy tự động bên trong,
bạn không cần quan tâm./evidence-ingest (nhập) → /evidence-analyze (phân tích) → /evidence-qa (kiểm tra) → /evidence-apply (áp dụng).
Dùng khi có nguồn ngoài (Confluence, Linear, paste, code) cần đưa vào wiki đã kiểm tra.
Dữ liệu gốc không đổi sau khi nhập. Mỗi workspace tách biệt hoàn toàn.Tag tech = dành cho engineer · nontech = không cần biết code · maint = wiki owner.
| Lệnh | Mục đích | Khi nào |
|---|---|---|
| /contextd-setuptech | Tạo .claude/wiki.json cho codebase, detect project name + components | Lần đầu dùng wiki với 1 codebase |
| /contextd-detecttech | Validate wiki.json, scan dependency, propose update | Kiểm tra sau setup, hoặc khi gặp lỗi |
| /switch-workspace têntech | Đổi workspace đang dùng cho codebase hiện tại | Cùng codebase phục vụ nhiều lĩnh vực |
| /new-workspace tên-dự-ánmaint | Tạo workspace mới từ mẫu | Mới tham gia công ty/dự án |
| /list-workspacesnontechtech | Hiện danh sách mọi workspace, đánh dấu workspace đang dùng | Xem workspace nào đã có |
| Lệnh | Mục đích | Khi nào |
|---|---|---|
| /use-contextdtech | 4-stage pipeline (planner → context → code → reviewer) | Trước MỌI task: implement, fix bug, design, review |
| /find {keywords}tech | Tìm nhanh quy tắc/thoả thuận/dịch vụ, 5 kết quả phù hợp nhất | Tìm nhanh khi đã biết mình cần gì |
| /update-contextdtech | Sync wiki với code đã thay đổi (git diff → curator áp dụng) | Sau khi merge code, để wiki không bị lệch |
| /rebase-contextdmaint | Quét toàn bộ wiki vs code, sửa chỗ wiki khác so với code thật | Định kỳ (tuần/tháng), hoặc khi nghi drift lớn |
| Lệnh | Mục đích | Khi nào |
|---|---|---|
| /product-brief [title]nontech | Hướng dẫn tạo bản tóm tắt sản phẩm: Vấn đề / Người dùng / Số đo thành công / Tiêu chí | PM tạo brief mới trước khi giao cho engineering |
| /business-view {target}nontech | Dịch tài liệu kỹ thuật → ngôn ngữ dễ hiểu cho người phi kỹ thuật | Giải thích tính năng cho sếp/kinh doanh/CS |
| /contextd-explain chủ-đềnontech | Giải thích 1 thuật ngữ/quy tắc bằng ngôn ngữ đơn giản | Đọc wiki gặp thuật ngữ lạ, cần hiểu nhanh |
pack-product — dễ nhất: chạy /contextd-setup Bước 4.5 và tick pack-product (UI checkbox, không cần edit markdown). Hoặc slash /product-brief tự hỏi và bật giúp nếu chưa có.
| Lệnh | Mục đích | Khi nào |
|---|---|---|
| /tool-design "ý tưởng"nontech | Wizard discovery → system map → recipe match → recommend tech stack → ghi spec (KHÔNG sinh code) | Có ý tưởng công cụ mới nhưng chưa biết bắt đầu thế nào |
| /tool-listnontech | Hiện danh sách công cụ đã tạo, nhóm theo trạng thái | Xem "tôi đã tạo cái gì rồi" trước khi tạo mới (tránh trùng) |
| /tool-extend tên-công-cụnontech | Đề xuất nâng cấp cho công cụ đã có — thêm tính năng, thay đổi phạm vi | Công cụ đã có cần thêm tính năng hoặc điều chỉnh |
pack-solo-builder (slash /tool-design tự bật giúp). Recipe library cross-platform: Linux native + Windows recommend Docker khi deps phức tạp (PDF, image, share team).
| Lệnh | Mục đích | Khi nào |
|---|---|---|
| /contextd-reportmaint | 1 file HTML độc lập — Tổng quan / Kiến trúc / Thoả thuận / Quy tắc / Tài liệu vận hành | Onboard thành viên mới, báo cáo định kỳ, kiểm tra khoảng trống |
| Lệnh | Mục đích | Khi nào |
|---|---|---|
| /code-analyzemaint | Phân tích codebase → đề xuất quy tắc/thoả thuận/kiến trúc từ code thật | Nhập codebase cũ, hoặc làm mới sau thay đổi lớn |
| /evidence-ingestmaint | Pull raw từ MCP / API / paste / code vào evidence/sources/{id}/ | Có nguồn ngoài cần đưa vào wiki |
| /obsidian-ingestmaint | Nhập hàng loạt từ Obsidian vault: quét, loại trùng, kiểm tra trước khi nhập | Maintain Second Brain trong Obsidian |
| /evidence-analyzemaint | Phân tích dữ liệu đã nhập | Sau khi nhập dữ liệu |
| /evidence-qamaint | Q&A loop với user, sinh verified-facts.md | Sau khi phân tích, kiểm tra trước khi áp dụng |
| /evidence-applymaint | Áp dụng sự kiện đã kiểm tra vào wiki | Sau khi kiểm tra xong |
| Lệnh | Mục đích | Khi nào |
|---|---|---|
| /contextd-trace {run_id}maint | Render Markdown timeline 1 run pipeline (4 stage) | Khi output /use-contextd sai — debug stage divergence |
| /contextd-evalmaint | Thống kê: tỷ lệ AI bịa, khoảng trống kiến thức, điểm vi phạm | Định kỳ kiểm tra hiệu quả wiki |
| /contextd-vizmaint | HTML viewer + live watch cho trace | Kiểm tra trực quan |
Ba công thức đời thực — cho thấy sức mạnh khi chain các lệnh lại với nhau.
Tình huống: Nhận codebase không có docs, cần wiki + báo cáo chia sẻ cho team.
/new-workspace acme-corp # Tạo workspace mới
↓
/code-analyze # Snapshot code → đề xuất rules & contracts
↓
/evidence-qa # Kiểm tra từng đề xuất (Y/N)
↓
/evidence-apply # Áp dụng fact đã verify vào wiki
↓
/contextd-report # Sinh báo cáo HTML độc lậpKết quả: Wiki có pattern/contract rút từ code thật + 1 file HTML overview để share team. Hết cảnh "không biết bắt đầu từ đâu" cho thành viên mới.
Tình huống: Bug duplicate charge trên prod. Cần fix tuân thủ rule retry/idempotency của team — không phải AI tự đoán.
/find "idempotency retry" # Tìm pattern liên quan trong vài giây
↓
/use-contextd "fix duplicate refund in payment flow"
↓ (planner → context → builder → reviewer — pipeline 4 stage)
Claude viết code tuân thủ contract đã retrieve
↓
/update-contextd # Sync code thay đổi về wikiKết quả: Fix theo rule team, wiki tự sync sau merge — không drift giữa code và docs.
Tình huống: Bạn là chuyên gia ngành khác (cơ khí, kế toán, y tế, ...). Có ý tưởng nhưng không biết tech stack.
/tool-design "tính moment uốn dầm thép"
↓ (6-8 câu hỏi có hướng dẫn, mỗi câu kèm ví dụ + "tôi không biết")
Spec lưu vào → workspaces/{ws}/tools/{slug}-spec.md
↓
implement spec at workspaces/{ws}/tools/{slug}-spec.md
↓ (Claude làm đúng spec — không tự đổi tech stack)
/tool-list # Xem toolbox nhóm theo trạng thái
↓
/tool-extend tên-tool # Thêm tính năng sau mà không phải làm lạiKết quả: Tool chạy được + setup guide cho cả Linux & Windows + record trong toolbox.
Bật pack: chạy /contextd-setup Bước 4.5 (checkbox UI per-codebase, ghi vào wiki.json#packs) — hoặc edit workspaces/{ws}/workspace.md section ## Packs (áp dụng workspace-wide cho mọi codebase).
| Pack | Status | Use cho |
|---|---|---|
| pack-event-driven | stable | Xử lý sự kiện: Kafka, MQTT, RabbitMQ — hàng đợi thử lại, xử lý lỗi |
| pack-web-api | stable | API web: REST/GraphQL/gRPC — kiểm tra đầu vào, mã lỗi, không lộ thông tin |
| pack-frontend-react | stable | React + Next.js — hooks rules, a11y, effect cleanup, list keys, server/client boundary |
| pack-ui-ux | beta v0.1 | UI/UX design — design system, design tokens, WCAG 2.1 AA accessibility, user flows, UX writing. Pairs với pack-frontend-react (design doc ↔ code impl) |
| pack-ai-app | stable | Ứng dụng AI: prompt caching, output có cấu trúc, kiểm thử, không lộ dữ liệu cá nhân |
| pack-agentic | stable | AI Agent: vòng lặp, dùng công cụ, đa agent — giới hạn bước, công cụ lặp lại an toàn |
| pack-claude-plugin-dev | stable | Phát triển plugin cho Claude Code — lệnh, agent con, kỹ năng, hook |
| pack-product | beta | Tài liệu sản phẩm cho PM/business — bản tóm tắt, OKR, lộ trình, người dùng, chỉ số |
| pack-solo-builder | beta | Cho non-tech expert ngành khác (cơ khí, kế toán, ...) dùng Claude Code làm "no-code IDE" — tool design coach + recipe library cross-platform |
| pack-ba | beta | Business analysis — mô hình hóa yêu cầu, acceptance criteria, process mapping, stakeholder alignment |
| pack-qc | beta v0.2 | Quality control + performance optimization (gộp pack-optimize) — test design/execution, defect triage, regression, release gate, baseline metric, profiling, regression guard |
| pack-security | beta v0.2 | Security engineering + authorized pentest (gộp pack-pentest) — threat modeling, secure design review, scope discipline, evidence-based findings, risk rating, remediation |
| pack-dba | beta | DBA workflow — schema change safety, query hygiene, backup/restore readiness, operational guardrails |
Ví dụ kết hợp: Solo fullstack → pack-web-api + pack-frontend-react + pack-ai-app.
AI agent product → pack-ai-app + pack-agentic + pack-web-api + pack-frontend-react.
Team có PM → thêm pack-product.
Có — 2 hướng tuỳ vai trò:
Nếu bạn là PM / người làm business trong team có engineer: bật pack-product, dùng:
/product-brief — tạo brief mới/business-view {service} — đọc service ở góc nhìn business/contextd-explain chủ-đề — giải thích thuật ngữ kỹ thuậtNếu bạn là chuyên gia ngành khác (cơ khí, kế toán, y tế, ...) tự dùng Claude Code build tools: bật pack-solo-builder, dùng:
/tool-design "ý tưởng" — wizard discovery + recommend tech stack/tool-list — xem toolbox đã có/tool-extend tên-công-cụ — thêm tính năng cho tool đã cóKhông cần biết git, terminal, hay code. Chỉ cần biết gõ lệnh trong Claude Code.
Có — mỗi công ty/dự án = 1 workspace riêng dưới workspaces/{name}/. Knowledge KHÔNG được trộn (Hệ thống đảm bảo).
Tạo workspace mới: /new-workspace tên-dự-án. Đổi: /switch-workspace tên.
2 lệnh:
/update-contextd — sau mỗi code merge, áp git diff vào wiki/rebase-contextd — định kỳ quét toàn bộ wiki so với code, sửa chỗ lệchĐể evaluate hiệu quả wiki: /contextd-eval — báo cáo tỷ lệ AI bịa, khoảng trống kiến thức.
Dùng pack khi knowledge đặc thù theo stack (vd Kafka rules, React hooks rules). Bật qua /contextd-setup Bước 4.5 — checkbox UI, không cần edit markdown.
KHÔNG dùng pack cho rule chỉ áp dụng riêng workspace bạn — viết vào
workspaces/{ws}/agents/constraints.md với prefix ws-.
Engine rule (mọi workspace, stack-agnostic) → sửa agents/constraints.md.
Per-codebase override qua .claude/wiki.json#packs field:
workspaces/acme-corp/workspace.md ## Packs = [pack-event-driven, pack-web-api]acme-frontend/.claude/wiki.json ghi "packs": ["pack-frontend-react", "pack-web-api"] → effective = chỉ frontend + web-apiReplace semantics, không additive. null/không có field = follow workspace default. Array = override hoàn toàn.
Cách dễ nhất: chạy /contextd-setup trong codebase → Bước 4.5 hiện checkbox UI cho mọi pack có sẵn, tick/untick → tự ghi wiki.json.
Không. 80% use case chỉ cần 3-4 lệnh:
/use-contextd, /find, /update-contextd/product-brief, /business-view, /contextd-explain/contextd-setup hoặc /new-workspaceCòn lại là cho maintainer hoặc trường hợp đặc biệt — học khi cần.
Mặc định {wiki-template-root}/workspaces/{name}/. Có thể override qua ~/.claude/wiki-global.json field wiki_root.
Để xem path active: /list-workspaces hoặc đọc <cwd>/.claude/wiki.json.
Hệ thống có quy tắc cứng: nếu thiếu kiến thức → AI PHẢI báo "Giả định" hoặc "Xung đột quy tắc", KHÔNG được tự bịa.
Có validator (scripts/validate.py) chạy regex check pattern phổ biến.
Để monitor: /contextd-eval báo hallucination rate per run.
Chạy lệnh tạo pack mới:
python scripts/scaffold-pack.py pack-mobile-flutterSinh 8 file skeleton. Customize pack.yaml components + keywords, viết constraints.md, thêm rule vào scripts/rules.py.
Đăng ký vào catalog: edit packs/README.md.