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ệ.

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) + 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 ghi entry vào docs/dev-journal/<YYYY-MM>.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 | | 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"] },
  "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 đủ → .codex/hooks.json (event/envelope Codex tương thích Claude Code) | ⚠️ một phần → group devkit trong .agents/hooks.json / ~/.gemini/config/hooks.json | ❌ skip + note (OpenCode mở rộng bằng JS/TS plugin, không có shell-command hooks) |

• 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; 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). 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.

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.