dev-kit

Bộ kit chuẩn hoá Claude Code cho công ty và cá nhân: workflow skills, agents, rules, hooks harness + CLI đồng bộ.

npx @hao159/dev-kit sync          # cài kit vào repo hiện tại (scope project — mặc định)
npx @hao159/dev-kit sync --scope user   # hoặc cài toàn máy (~/.claude)

Vì sao dùng kit thay vì prompt thuần?

Prompt/rules là gợi ý — Claude có thể quên hoặc tự biện hộ bỏ qua, nhất là cuối phiên dài. Kit chuyển những thứ cần đảm bảo 100% sang hook script (cưỡng chế, chạy ngoài context window), và chuẩn hoá phần cần phán đoán thành skill dùng chung cả team.

| | Prompt / rules thuần | Kit (skill + hook script) | |---|---|---| | Tính chất | Gợi ý — model có thể bỏ qua dưới áp lực | Hook cưỡng chế thật (deny/ask/block), không "thuyết phục" được | | Chi phí context | Chiếm token, bị đọc lại nhiều lần mỗi phiên | Logic hook ~0 token; skill chỉ load khi cần, chi tiết đẩy sang references/ | | Ổn định | Có variance — phiên này nghe, phiên kia không | Cùng input → cùng output; test được bằng node --test | | Thời điểm | Nhồi trước rồi hy vọng model nhớ đến lúc cần | Bắn đúng event (PreToolUse, Stop, SessionStart…) | | Chia sẻ team | Mỗi người tự chép prompt, drift dần | 1 nguồn sự thật, devkit sync đồng bộ + version hoá | | Kiểm chứng | Phải chạy thử mới biết wording có ăn không | Unit test + devkit validate trong CI |

Nguyên tắc phân chia: việc cần phán đoán → skill/rule (prompt); việc cần đảm bảo 100% → hook script. Ví dụ: rule "ghi dev-journal khi sửa file then chốt" nếu chỉ nằm trong prompt sẽ bị bỏ qua khi phiên dài — cặp hook journal-track + journal-gate biến nó thành gate không né được.

Nhược điểm (đánh đổi có chủ đích):

• Có chi phí xây và bảo trì: hook phải viết + test, đổi kit phải publish và mọi máy chạy lại sync (prompt thì sửa phát ăn ngay).
• Hook là luật cứng — pattern chặn sai (false positive) sẽ cản việc thật; cần escape hatch qua devkit.config.json (allowlist, tắt từng hook) thay vì sửa nóng.
• Script chỉ làm được việc deterministic; nhồi phán đoán vào script là sai chỗ — phần đó vẫn phải là prompt.
• Thêm một tầng gián tiếp khi debug: hành vi phiên = prompt + rules + hooks, người mới cần đọc ~/.claude/devkit/logs/hooks.jsonl để hiểu vì sao bị chặn.

Cấu trúc

dev-kit/
├── bin/devkit.js          # entry CLI
├── src/                   # code CLI (zero-dependency, Node >= 18.17)
│   ├── cli.js             # parse args + dispatch
│   ├── kit.js             # load kit.json, resolve profile
│   ├── targets/           # adapter per CLI (chọn bằng --cli, mặc định claude-code)
│   │   ├── shared.js      # engine chung: manifest+sha256, stale, keep-local, managed block
│   │   ├── claude-code.js # ~/.claude hoặc .claude/ + merge hooks vào settings.json
│   │   ├── codex.js       # .agents/skills + .codex/ + AGENTS.md (managed block)
│   │   ├── antigravity.js # .agents/skills + .agent/rules|workflows + GEMINI.md
│   │   └── opencode.js    # .agents/skills + .opencode/ + AGENTS.md (managed block)
│   └── commands/          # sync, uninstall, new, validate, list, doctor
├── test/                  # node --test: hooks + sync
└── kit/                   # ⭐ SOURCE OF TRUTH — nội dung kit
    ├── kit.json           # manifest: tên, version, profiles, deletions
    ├── rules/<name>.md    # quy tắc LUÔN được load mỗi phiên (giữ ngắn)
    ├── skills/<name>/SKILL.md (+ references/ load-khi-cần)
    ├── commands/<name>.md # slash commands (/ten-lenh)
    ├── agents/<name>.md   # subagents
    └── hooks/
        ├── hooks.json     # khai báo hook (placeholder ${DEVKIT_SCRIPTS})
        └── scripts/*.mjs  # hook scripts Node đa OS (+ lib/common.mjs)

Workflow skills (gõ /dk-... trong Claude Code)

| Skill | Vai trò | |-------|---------| | /dk-plan | Lập kế hoạch theo phase → plans/<slug>/plan.md + phase files, ghi con trỏ active-plan | | /dk-cook | Triển khai end-to-end với HARD-GATE: scout-first, chốt yêu cầu, kiểm chứng, chốt sổ | | /dk-fix | Sửa bug — bắt buộc root-cause có bằng chứng, quy tắc 3 lần, regression test | | /dk-scout | Khảo sát codebase bằng subagent song song — phiên chính chỉ nhận kết luận | | /dk-review | Review 2 tầng (đúng spec → chất lượng) + lăng kính soi code AI viết | | /dk-docs | Khởi tạo/cập nhật docs cho codebase — overview, module/API, onboarding; đọc code thật qua subagent | | /dk-test | Viết test diff-aware, không mock thừa, không sửa code sản phẩm cho test pass | | /dk-ship | Commit/push/PR có gate: chạy test, quét secret, không force-push | | /dk-status | Báo cáo trạng thái (chỉ đọc): plan dở, tiến độ, việc nên làm tiếp |

Chuỗi điển hình: /dk-plan → /dk-cook <plan> → /dk-ship. Bug: /dk-fix. Định tuyến chi tiết: kit/skills/dk-cook/references/workflow-routing.md.

Stack skills công ty (load trước khi đụng code stack đó): dk-php (PHP thuần), dk-laravel, dk-codeigniter, dk-javascript (JS thuần), dk-jquery-kendo, dk-react, dk-nextjs, dk-mongodb. Nguyên tắc chung: detect, don't assume — đọc version/config từ repo; API nhạy version phải tra docs hiện hành qua Context7 MCP.

Triết lý nội dung: mỗi file .md trong kit ≤ 300 dòng (validate chặn cứng) để AI không ngộp context; plan/journal/docs luôn theo template (dk-plan/references/plan-template.md, dk-journal/references/journal-template.md, dk-docs/references/*-template.md) — thiếu section = output không hợp lệ.

Docs sống trong repo đích (docs/)

Kit chuẩn hoá một bộ tài liệu sống mà AI + hook cùng giữ cho khỏi lỗi thời (/dk-docs bootstrap, /dk-journal ghi, /dk-scout đối chiếu):

| File | Vai trò | Ai giữ cho sống | |------|---------|-----------------| | docs/dev-journal/<YYYY-MM-DD> <summary>.md | 1 file / 1 thay đổi — What/Why/Impact/Files | journal-track/journal-gate ép ghi khi sửa file then chốt | | docs/summary-codebase.md | Bản đồ codebase: cây thư mục (auto) + module & trách nhiệm (prose) | codebase-map-track tự ghi phần cây giữa marker <!-- devkit:auto-tree -->; codebase-map-gate nhắc làm mới prose khi có dir mới; /dk-scout báo drift | | docs/system-architecture.md | Kiến trúc hệ thống: thành phần, luồng dữ liệu, phụ thuộc ngoài | AI (/dk-docs) — reconcile khi kiến trúc đổi | | docs/<topic>-logic.md | Quyết định/cơ chế lớn tự chứa (vd failover-logic.md): vấn đề, cơ chế, trade-off, edge case | AI (/dk-docs) khi có quyết định đáng tách riêng | | docs/project-change-logs.md | Ledger cấp cao được curate (chỉ thay đổi kiến trúc/contract/quyết định), mỗi dòng trỏ tới file journal | AI đề xuất mỗi phiên, user xác nhận |

Nguyên tắc: hook giữ phần cơ học (cây thư mục, ép ghi), AI viết phần cần phán đoán (prose, quyết định), user chốt cái gì lên ledger. summary-codebase.md là living contract giống docs/api/exposes.md — chỉ bật khi repo tự tạo file (opt-in), không nag repo chưa dùng.

Hooks harness (quy trình an toàn + quản lý context)

Tất cả hook fail-open (hook lỗi không bao giờ phá phiên làm việc), tắt/bật được từng cái qua devkit.config.json, log JSONL tự xoay vòng tại ~/.claude/devkit/logs/hooks.jsonl.

| Hook | Event | Vai trò | |------|-------|---------| | block-dangerous | PreToolUse[Bash] | 2 mức: deny lệnh phá huỷ (rm -rf /, force-push main, curl|sh, mkfs…), ask lệnh cần xác nhận (git clean/reset --hard, DROP TABLE, --no-verify, npm publish…) | | pre-read | PreToolUse[Read|Glob|Grep] | Dispatcher 1-process gộp scout-block (chặn đọc node_modules/dist/.git — bảo vệ context) + privacy-guard (chặn đọc/grep/glob .env/key/credentials, hướng dẫn hỏi user + allowlist) | | session-init | SessionStart | Bơm context: loại dự án, plan đang hoạt động, trạng thái phiên trước; nhắc khôi phục sau compact | | rules-reminder | UserPromptSubmit | Nhắc định tuyến workflow — throttle 5 phút/dự án, không spam | | subagent-context | SubagentStart | Bơm quy ước cho MỌI subagent: đường dẫn báo cáo, status protocol, kỷ luật context | | session-state | Stop + PreCompact | Lưu trạng thái (nhánh, file đổi, plan) ra ~/.claude/devkit/state/ — phiên sau tự khôi phục | | post-edit | PostToolUse[Write|Edit] | Dispatcher 1-process gộp journal-track (ghi nhận file then chốt vừa sửa: migrations/schema, routes, config, package/composer.json, CI/docker, auth/middleware) + plan-track (ghi nhận file code sửa khi có active-plan) + codebase-map-track (khi có dir mới: tự ghi lại cây thư mục trong block auto-tree của docs/summary-codebase.md; opt-in — no-op nếu repo chưa có file) + format-after-edit (Prettier/Pint best-effort nếu project có config) | | journal-gate | Stop | Có file then chốt đổi mà chưa ghi journal → chặn kết thúc 1 lần, bắt Claude tạo file per-change docs/dev-journal/<YYYY-MM-DD> <summary>.md theo template dk-journal (What/Why/Impact/Files); sửa toàn việc vặt thì được phép giải thích thay vì bịa entry | | codebase-map-gate | Stop | Có dir mới xuất hiện trong phiên (auto-tree đã được đồng bộ) mà prose docs/summary-codebase.md chưa cập nhật → chặn kết thúc 1 lần, bắt Claude mô tả vùng mới (Modules & responsibilities); opt-in như trên | | plan-gate | Stop | Có active-plan + đã sửa code mà chưa động vào phase file nào → chặn kết thúc 1 lần, bắt Claude tick checkbox/flip status phase tương ứng; không phase nào thực sự xong thì giải thích thay vì bịa tiến độ |

Cấu hình: ~/.claude/devkit.config.json (toàn cục) + <repo>/.claude/devkit.config.json (theo dự án, đè lên toàn cục):

{
  "hooks": { "rules-reminder": false },
  "privacy": { "allow": [".env.development"] },
  "scout": { "allow": ["node_modules/lodash"], "extraBlocked": ["generated"] },
  "journal": { "dir": "docs/dev-journal", "extraPatterns": ["(^|/)app/Services/Payment"] },
  "codebaseMap": { "path": "docs/summary-codebase.md", "depth": 3, "ignoreDirs": ["fixtures"] },
  "relatedRepos": ["F:/Code/service-b", "F:/Code/service-c"]
}

relatedRepos (đường dẫn tuyệt đối tới các repo anh em gọi chéo internal API): dùng bởi các skill — /dk-scout scout cross-repo tìm consumer, /dk-fix quét blast radius, /dk-review check backward-compat, /dk-docs điền "known consumers" vào docs/api/exposes.md, /dk-tech-graph vẽ call graph từ các file docs/api/*.md. Hooks không đọc key này.

Lệnh CLI

| Lệnh | Mô tả | |------|-------| | devkit sync [--cli claude-code\|codex\|antigravity\|opencode] [--scope user\|project] [--profile <tên>] [--dry-run] [--keep-local] | Cài/cập nhật kit vào CLI đích (mặc định claude-code, scope project); --keep-local giữ file bạn đã sửa tay thay vì ghi đè | | devkit uninstall [--cli ...] [--scope user\|project] | Gỡ sạch những gì devkit đã cài cho CLI đó (mặc định claude-code, scope project) | | devkit new skill\|command\|agent\|hook\|rule <tên> | Scaffold thành phần mới (chạy trong repo kit) | | devkit validate | Kiểm tra frontmatter (theo kit/schemas/skill-schema.json), luật ≤300 dòng/.md, agent phải có model+tools, references tồn tại, syntax hook scripts, hooks.json, profiles | | devkit list | Liệt kê thành phần + profile | | devkit doctor | Kiểm tra môi trường (node, claude CLI, settings.json) + báo version mới trên npm | | devkit update | So version đã cài với npm registry, in lệnh nâng cấp |

Cách sync hoạt động

• Skills/commands/agents/rules được copy vào <repo>/.claude/ (scope project — mặc định) hoặc ~/.claude/ (scope user).
• Hooks được merge vào settings.json — chỉ thêm/xoá entry do devkit quản lý (deep-equal với manifest), không đụng hook user tự thêm; re-sync không bao giờ nhân đôi entry kể cả khi manifest bị mất.
• Pre-flight: settings.json hỏng JSON → sync fail NGAY, trước khi copy bất kỳ file nào (chạy devkit doctor để tìm lỗi).
• Manifest devkit-manifest.json ghi mọi file đã cài kèm sha256 → re-sync tự xoá file cũ, phát hiện + cảnh báo file bị sửa tay (kit là nguồn sự thật; muốn giữ thì --keep-local), uninstall gỡ sạch 100%.
• Sync fail giữa chừng (file readonly, hết đĩa…) → manifest vẫn được ghi đúng hiện trạng đĩa; chạy lại devkit sync là hồi phục.
• kit.json > deletions[] dọn file do version cũ (trước khi có manifest) để lại.
• Scope project dùng $CLAUDE_PROJECT_DIR trong hook command → settings.json commit được vào git, chạy trên mọi máy.

Sync sang Codex / Antigravity / OpenCode (--cli)

Một nguồn kit, nhiều harness — devkit sync --cli codex|antigravity|opencode map thành phần sang layout của từng CLI:

| Kit | Claude Code (mặc định) | Codex | Antigravity | OpenCode | |-----|------------------------|-------|-------------|----------| | skills | .claude/skills/ | .agents/skills/ (project) · ~/.agents/skills/ (user) | .agents/skills/ (project) · ~/.gemini/config/skills/ (user) | .agents/skills/ (project) · ~/.agents/skills/ (user) — OpenCode đọc native dir chuẩn chung này | | commands | .claude/commands/ | ~/.codex/prompts/ (chỉ scope user — Codex không có prompts per-project) | .agent/workflows/ (project) · ~/.gemini/antigravity/global_workflows/ (user) | .opencode/commands/ (project) · ~/.config/opencode/commands/ (user) — format description + $ARGUMENTS tương thích sẵn | | agents | .claude/agents/*.md | .codex/agents/*.toml (tự convert md→TOML; bỏ model/tools vì là khái niệm Claude) | ❌ skip + note (Antigravity chưa có agent file user-defined) | .opencode/agents/*.md (project) · ~/.config/opencode/agents/*.md (user) — convert frontmatter sang mode: subagent; bỏ name (tên = filename), model (OpenCode cần full provider/model id), tools | | rules | .claude/rules/ | managed block trong AGENTS.md (project) / ~/.codex/AGENTS.md (user) | .agent/rules/*.md + trigger: always_on (project) / block trong ~/.gemini/GEMINI.md (user) | managed block trong AGENTS.md (project) / ~/.config/opencode/AGENTS.md (user) | | hooks | merge settings.json | ✅ đầy đủ trên macOS/Linux → .codex/hooks.json · ❌ Windows: không cài (hook engine của Codex chưa hỗ trợ Windows) | ⚠️ một phần → group devkit trong .agents/hooks.json / ~/.gemini/config/hooks.json | ❌ không port shell-command hooks (OpenCode mở rộng bằng JS/TS plugin) | | guardrails | permissions trong settings.json + hook block-dangerous | managed block trong .codex/config.toml (sandbox) | qua hook block-dangerous | plugin .opencode/plugins/devkit-guard.js (deny) + permission.bash trong opencode.json (ask) |

• Hooks đa harness: cùng một bộ script (lib/common.mjs tự nhận diện qua flag --harness do sync gắn vào command). Codex nhận đủ 7 event (hooks.json của Codex cùng format Claude Code) — khác biệt duy nhất: Codex chưa honor ask nên devkit hạ xuống deny kèm hướng dẫn xin xác nhận; trên macOS/Linux, sau khi sync phải chạy /hooks trong Codex để trust (Codex bỏ qua hook chưa trust; đổi nội dung script là phải trust lại). Trên Windows hook của Codex không chạy — devkit không cài chúng và không giả vờ là có; guard của Codex trên Windows là sandbox trong config.toml (xem mục Guardrails). Antigravity chỉ có PreToolUse/PostToolUse/Stop và không có kênh inject context hay chặn Stop → chỉ port guards (block-dangerous, scout-block, privacy-guard qua normalize toolCall.args), tracker post-edit và session-state; 5 hook còn lại skip kèm note. Command trong hooks.json dùng đường dẫn tuyệt đối (Codex/Antigravity không có $CLAUDE_PROJECT_DIR) — máy khác phải tự chạy devkit sync, đừng commit hooks.json vào git.
• Managed block: với file dùng chung mà user cũng tự viết (AGENTS.md, GEMINI.md), devkit chỉ ghi/xoá phần giữa marker <!-- devkit:start --> … <!-- devkit:end --> — nội dung ngoài marker không bao giờ bị đụng. Tương tự với hooks: Codex merge entry theo deep-equal (như settings.json của Claude), Antigravity own trọn key devkit trong hooks.json — đồ user tự thêm không bao giờ bị đụng.
• Mỗi CLI có manifest riêng (.codex/devkit-manifest.json, .agent/devkit-manifest.json, ~/.gemini/devkit-manifest.json, .opencode/devkit-manifest.json / ~/.config/opencode/devkit-manifest.json) → sync/uninstall độc lập, vẫn đủ checksum drift + --keep-local + dọn stale như Claude Code.
• Lưu ý: .agents/skills/ là thư mục chuẩn chung (open SKILL.md standard) — Codex, Antigravity (project scope) và OpenCode cùng đọc một chỗ; uninstall CLI này rồi thì sync lại CLI kia để khôi phục skills nếu cần. Tương tự, AGENTS.md ở repo root là file rules chung của Codex và OpenCode — hai target ghi cùng một managed block (nội dung giống hệt nhau), uninstall một bên sẽ gỡ block, sync lại bên kia để khôi phục.
• Alias: --cli claude = claude-code, --cli agy = antigravity.

Guardrails (chống mất dữ liệu)

Nguồn sự thật duy nhất: kit/hooks/scripts/policy.json. Mỗi rule có id, level (deny | ask), pattern (regex) và glob native cho từng harness.

| Lớp | Chạy ở đâu | Bắt được gì | |---|---|---| | Sandbox (không sinh từ policy.json) | Codex .codex/config.toml — sandbox_mode, network_access | Kể cả lệnh chưa ai liệt kê — sandbox không cần đoán trước pattern | | Permission khai báo (sinh từ policy.json) | OpenCode permission.bash trong opencode.json | Rule ask: harness tự hỏi người dùng | | Hook / plugin script (đọc policy.json) | block-dangerous.mjs (Claude Code, Codex, Antigravity) · devkit-guard.js (OpenCode, chỉ deny) | Biến thể regex mà glob bỏ sót | | Rule trong prompt | kit/rules/devkit.md | Việc cần phán đoán — ví dụ script thao tác dữ liệu phải dry-run trước |

Số lớp khác nhau theo harness: Codex có sandbox + hook (macOS/Linux) hoặc chỉ sandbox (Windows); OpenCode có permission + plugin; Claude Code và Antigravity hiện chỉ có hook block-dangerous.

Giới hạn — đọc kỹ: đây là guard chống tai nạn của agent, không chống dev cố ý. Ai sửa file config của mình thì gỡ được, và đó là chủ đích: bạn phải nới được khi guard cản việc thật.

Cách nới:

// .claude/devkit.config.json — chỉ hạ cấp được, không siết thêm
{ "permissions": { "downgrade": { "laravel-migrate-fresh": "ask" }, "off": ["db-raw-client"] } }

Hoặc sửa thẳng rule trong file permission của project — devkit sync giữ nguyên chỗ bạn sửa và báo drift, không lặng lẽ ghi đè. Muốn siết thêm thì sửa policy.json rồi sync lại.

Codex sandbox_mode = "workspace-write" + network_access = "restricted" có thể cản script cần ghi ra ngoài repo hoặc gọi mạng. Nới bằng cách thêm dòng sau ngoài block devkit trong .codex/config.toml — phải dùng dạng dotted key, viết [sandbox_workspace_write] sẽ trùng khai báo với block devkit và làm hỏng cả file:

sandbox_workspace_write.writable_roots = ["/tmp/build"]

Sync cảnh báo nếu bạn khai trùng key/table mà devkit đang quản. Với --scope project, config Codex chỉ có hiệu lực sau khi bạn trust project đó — muốn guard luôn áp dụng thì dùng --scope user.

Quy trình thêm thành phần mới

devkit new skill deploy-checklist   # tạo kit/skills/deploy-checklist/SKILL.md
# ... viết nội dung (SKILL.md < 300 dòng, chi tiết đẩy sang references/) ...
devkit validate                     # kiểm tra format + syntax
npm test                            # hooks + sync tests
devkit sync                         # thử trên máy mình
# commit + publish

Quy ước viết skill: description nêu rõ làm gì + khi nào dùng (Claude đọc dòng này để tự kích hoạt); gate cứng viết dạng HARD-GATE; cuối skill có mục "Vị trí trong workflow" (đứng sau/trước skill nào). Đổi tên/xoá thành phần → thêm đường dẫn cũ vào kit.json > deletions[].

Phân phối (npm public registry)

Package publish công khai tại npmjs.org: @hao159/dev-kit (scoped package cần publishConfig.access=public; publish qua Classic Automation token để né OTP).

# Publish (maintainer) — bump version ở CẢ package.json và kit/kit.json
npm version minor && npm publish

# Cài đặt / cập nhật (dev trong team) — onboarding 1 lệnh:
npx @hao159/dev-kit@latest sync --profile company

Khi kit có version mới, dev chạy lại lệnh trên — sync tự dọn file cũ. Kiểm tra version mới: devkit update (hoặc devkit doctor).

Profiles: company — bộ curated theo stack công ty (14 workflow + 9 stack + 5 support skills, đủ agents/rules/hooks); personal (mặc định) — toàn bộ kit; minimal — chỉ review/fix, không hooks.

Lộ trình đa tool (Codex, IDE...)

Nội dung kit viết theo format Claude Code (canonical). Mỗi tool mới = một adapter trong src/targets/ (ví dụ codex.js chuyển skills → AGENTS.md/rules format). CLI thêm flag --target codex. Không cần đổi cấu trúc nội dung.

Ghi chú kỹ thuật

• Hook script viết bằng Node .mjs (không phải bash, không phải .js — tránh phụ thuộc package.json gần nhất khi copy sang ~/.claude).
• Khung hook chuẩn nằm ở kit/hooks/scripts/lib/common.mjs: runHook(name, handler) — fail-open, config gate, logger; handler trả ctx.deny()/ctx.ask()/ctx.context()/ctx.block()/null (block chỉ dành cho Stop — ép Claude tiếp tục kèm chỉ dẫn).
• Sau khi sync, restart Claude Code (hoặc kiểm tra /hooks) để nhận hook mới.