agent-kb

Scaffold một AI knowledge base tiết kiệm token (.ai/) + cấu hình agent đa-tool (AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md) vào bất kỳ dự án nào, chỉ bằng một lệnh.

Dùng nhanh

# Trong thư mục gốc repo:
npx @dtd-dev/agent-kb            # tương tác: hỏi tên dự án + stack
npx @dtd-dev/agent-kb init -y    # dùng mặc định, không hỏi

Không cài global, không cần clone. Zero-dependency nên npx chạy tức thì.

Lệnh & cờ

| Lệnh | Tác dụng | |---|---| | agent-kb / @dtd-dev/agent-kb init | Khởi tạo (tương tác nếu chạy trong terminal); tự nhận diện stack | | @dtd-dev/agent-kb feature <tên> | Tạo nhanh .ai/specs/<tên>/ từ khung trống | | @dtd-dev/agent-kb adr <tiêu đề> | Tạo ADR mới trong .ai/decisions/ (tự đánh số) | | @dtd-dev/agent-kb skill <area>/<tên> | Tạo skill mới trong .ai/skills/<area>/ | | @dtd-dev/agent-kb agent <tên> | Tạo sub-agent (.ai/agents/ → emit .claude/agents/) | | @dtd-dev/agent-kb doctor | Kiểm tra & audit KB (thoát mã ≠0 nếu có lỗi → dùng cho CI/hook) | | @dtd-dev/agent-kb guard [task] | Trước khi sửa: in file cần đọc theo task + nhắc write-back + quét risk diff (bug,feature,review,…) | | @dtd-dev/agent-kb update [--check] | Cập nhật project đã cài: đè nhóm 🟦 Core + đồng bộ block/agents, chừa 🟩/🟥. --check để xem trước | | @dtd-dev/agent-kb import | Gom rule cũ (.cursorrules, CLAUDE.md…) vào AGENTS.md | | @dtd-dev/agent-kb mcp add <name> -c <cmd> [-a a,b] | Thêm MCP server vào .mcp.json | | @dtd-dev/agent-kb hook install | Cài git pre-commit hook chạy doctor | | @dtd-dev/agent-kb hook guard | Cài Claude Code PreToolUse hook chạy guard trước mỗi Edit/Write | | @dtd-dev/agent-kb hook writeback | Cài Claude Code Stop hook nhắc write-back khi task vừa xong (đóng vòng — bù cho PreToolUse chỉ nhắc lúc bắt đầu) | | -y, --yes | Bỏ qua câu hỏi, dùng mặc định + stack tự nhận diện | | -f, --force | Ghi đè file đã tồn tại (mặc định KHÔNG ghi đè) | | --name/--backend/--frontend/--database/--cicd/--deploy | Điền sẵn từng phần, bỏ qua câu hỏi | | --tools <list\|all> | Bật tool phụ: cursor,windsurf,cline,zed,aider (file trỏ về AGENTS.md) | | --stack <list> | Kéo gói chuẩn: go,node,python,react,java,rust,php | | --hook | Cài luôn git pre-commit hook khi init | | help | Trợ giúp |

Chạy tương tác sẽ hỏi: tên dự án, backend, database, frontend, CI/CD, lệnh deploy, tool phụ (Enter để giữ gợi ý). agent-kb tự đọc package.json/go.mod/… để gợi ý stack & database sẵn — quét cả thư mục con tới 3 cấp nên hỗ trợ monorepo (vd apps/web, services/api). Nếu không thấy manifest nào, nó báo rõ và để bạn nhập tay (hoặc dùng cờ --backend/--frontend/--database). Các phần còn lại (cache, state, UI lib, container, URL môi trường, rollback…) là placeholder <!-- vd: ... --> trong file để bạn điền tay sau.

Mặc định emit AGENTS.md + CLAUDE.md + GEMINI.md + .github/copilot-instructions.md. Thêm --tools để phủ Cursor/Windsurf/Cline/Zed/Aider — tất cả chỉ là file nhỏ trỏ về AGENTS.md.

Sub-agents của dự án

Định nghĩa sub-agent (dùng chung cho team) ở .ai/agents/*.md — nguồn chân lý, được emit sang .claude/agents/ cho Claude Code đọc. init ship sẵn 4 agent gắn workflow: reviewer, tester, bug-fixer, feature-builder (mỗi agent tự trỏ về .ai/workflows/skills tương ứng → mang đúng quy ước nghiệp vụ dự án).

@dtd-dev/agent-kb agent security-reviewer \
  --desc "Soát lỗ hổng bảo mật theo chuẩn dự án" \
  --tools "Read,Grep,Bash" --model sonnet

Sửa ở .ai/agents/ rồi chạy lại @dtd-dev/agent-kb init để đồng bộ. Tool khác (Cursor/Codex/Gemini/Copilot) chưa có sub-agent dạng file nên hiện chỉ emit cho Claude Code.

Ví dụ scriptable (CI, không treo vì tự nhận diện không phải terminal):

npx @dtd-dev/agent-kb init --name CarePay \
  --backend "Go 1.22 + Chi" \
  --frontend "React 18 + Vite + Firebase" \
  --database "Firestore" \
  --cicd "GitHub Actions" \
  --deploy "firebase deploy --only functions,hosting"

Tạo spec cho feature mới

npx @dtd-dev/agent-kb feature checkout      # tạo .ai/specs/checkout/ (4 file khung trống)

Sinh sẵn requirements.md / design.md / api.md / test-cases.md với khung trống, tiêu đề đã điền tên feature — khỏi copy thư mục feature-a/ (ví dụ mẫu) bằng tay.

Guard: ép agent đọc đúng file + nhớ write-back (kiểu gitnexus)

Vấn đề kinh điển: agent không tự tìm đúng file theo task và quên ghi lại sau khi xong. Vì mọi quy tắc chỉ là chữ trong AGENTS.md, model dễ bỏ qua. guard biến nó thành một lệnh thật chạy TRƯỚC khi sửa:

@dtd-dev/agent-kb guard bug      # in: Tier-1 + file phải ĐỌC TRƯỚC + file phải GHI LẠI sau khi xong + risk từ diff

guard quét git diff và cảnh báo path nhạy cảm (💰 tiền/thanh toán, 🔐 auth, 🔑 secret, 🗄️ migration, 🚀 CI/CD). Đây là read-only — chỉ nhắc, không chặn.

Tự động trên Claude Code — cài hook để guard chạy trước mỗi Edit/Write (không cần agent tự nhớ):

@dtd-dev/agent-kb hook guard     # thêm PreToolUse hook vào .claude/settings.json

Hook đẩy nhắc thẳng vào ngữ cảnh model qua additionalContext mỗi lần nó định sửa file. Tool khác (Cursor/Copilot/Gemini) chưa có hook pre-edit → vẫn dựa vào BƯỚC 0 bắt buộc trong AGENTS.md (chạy @dtd-dev/agent-kb guard <task> trước khi sửa).

Đóng vòng write-back — guard (PreToolUse) chỉ nhắc lúc bắt đầu sửa; đến khi xong lời nhắc đã trôi khỏi ngữ cảnh nên agent hay quên ghi lại. Cài thêm Stop hook để nhắc đúng lúc task vừa xong:

@dtd-dev/agent-kb hook writeback     # thêm Stop hook vào .claude/settings.json

Khi agent kết thúc lượt mà git diff có thay đổi, hook chặn 1 lần (dùng stop_hook_active để không lặp vô hạn), suy ra cột write-back từ đường dẫn file đang đổi, và ép agent append đúc kết vào file đích (memory/spec/business-rules…) trước khi dừng. Không sửa code → không nhắc.

Cập nhật project đã cài (@dtd-dev/agent-kb update)

Khi bạn nâng cấp package, các project đã cài trước đó không tự đổi. Chạy trong thư mục project:

npx @dtd-dev/agent-kb@latest update          # áp bản mới
npx @dtd-dev/agent-kb@latest update --check   # chỉ xem file Core nào lệch, không sửa

update chỉ đụng nhóm 🟦 Core (phương pháp luận, dùng lại mọi dự án):

• Ghi đè .ai/workflows/* + .ai/README.md từ template (lan cải tiến quy trình/guard/write-back).
• Đồng bộ block <!-- BEGIN/END agent-kb --> trong AGENTS.md/CLAUDE.md/GEMINI.md/Copilot (giữ tên dự án + phần ngoài block của bạn).
• Re-emit sub-agent .ai/agents/ → .claude/agents/.
• Thêm file template mới mà project còn thiếu.

KHÔNG đụng 🟩 (core/*, architecture.md, examples/*) và 🟥 (product/*, specs/, decisions/, skills/backend/carepay-*, memory/*) — nội dung nghiệp vụ & bài học bạn tích luỹ giữ nguyên.

Nếu bạn ĐÃ sửa tay một file Core (vd workflows/fix-bug.md), update sẽ ghi đè nó. Muốn giữ tuỳ biến quy trình riêng → đặt ở file khác (vd skills/), đừng sửa file Core.

An toàn khi chạy lại

• File .ai/*: mặc định không ghi đè — chạy lại chỉ bổ sung file còn thiếu, không đụng nội dung bạn đã điền.
• File agent-config (AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md): nếu đã tồn tại, nội dung agent-kb được chèn/cập nhật trong block <!-- BEGIN agent-kb --> … <!-- END agent-kb --> — phần ngoài block của bạn giữ nguyên, chạy lại không nhân đôi.
• Muốn reset về template thì thêm --force.

Triết lý

• AGENTS.md là nguồn chân lý duy nhất; CLAUDE.md/GEMINI.md/Copilot chỉ trỏ về nó.
• .ai/core/* là Tier 1 (luôn load, giữ nhỏ). Mọi thứ khác load theo task qua router trong AGENTS.md.
• Không nhân bản rule sang nhiều file → tránh lệch và tốn token.

Bản đồ file: cái nào core, cái nào cá nhân hoá, cái nào nhờ AI điền

Sau khi init, mỗi file rơi vào một trong 3 nhóm. Cột "Ai điền" cho biết bạn phải tự làm hay nhờ AI/CLI:

| File / Thư mục | Nhóm | Ai điền | Ghi chú | |---|---|---|---| | AGENTS.md (router + quy tắc), CLAUDE.md/GEMINI.md/copilot-instructions.md | 🟦 Core | CLI | Khung dùng lại mọi dự án. Phần trong block BEGIN/END agent-kb do CLI quản — đừng sửa tay (chạy lại init sẽ ghi đè block). | | .ai/README.md (index Tier 0) | 🟦 Core | — | Bản đồ "task → file". Giữ nguyên. | | .ai/workflows/* (create-feature, fix-bug, code-review, release, learn, incident-response) | 🟦 Core | — | Phương pháp luận, dùng lại như nhau giữa các dự án. | | .ai/agents/* (reviewer, tester, bug-fixer, feature-builder) | 🟦 Core | — | Nguồn chân lý của sub-agent; CLI tự emit sang .claude/agents/. | | .ai/core/tech-stack.md | 🟩 AI điền | CLI + AI | CLI điền {{...}} từ nhận diện stack; AI bổ sung các chỗ <!-- vd: ... --> (cache, state, UI lib…) sau khi đọc code. | | .ai/core/coding-standards.md, .ai/core/glossary.md | 🟩 AI điền | AI | Nhờ AI đọc codebase rồi viết. | | .ai/architecture.md | 🟩 AI điền | AI | AI suy ra từ cấu trúc dự án. | | .ai/examples/* | 🟩 AI điền | AI | Sinh từ code thật của bạn (thay ví dụ mẫu). | | .ai/skills/devops/* (deployment, docker, github-actions), .ai/skills/frontend/react.md, ui-guideline.md | 🟩 AI điền | AI | Skill generic — AI viết theo stack thực tế. deployment.md có {{DEPLOY_CMD}} do CLI điền. | | .ai/memory/* (common-bugs, lessons-learned, troubleshooting) | 🟩 AI điền | AI (dần dần) | Tích luỹ qua workflow learn.md mỗi khi rút kinh nghiệm. | | .ai/product/* (vision, business-rules, domain-model) | 🟥 Cá nhân hoá | Người (+AI hỗ trợ) | Nội dung shipped là MẪU CarePay — bắt buộc thay bằng nghiệp vụ công ty bạn. Giữ cách đánh số (BR-001…). | | .ai/skills/backend/carepay-*, .ai/skills/frontend/carepay-firebase.md | 🟥 Cá nhân hoá | Người | Skill nghiệp vụ mẫu — xoá hoặc thay bằng skill dự án bạn. | | .ai/decisions/ADR-00x-* | 🟥 Cá nhân hoá | Người | Mẫu — thay bằng quyết định thật; tạo mới: @dtd-dev/agent-kb adr <tiêu đề>. | | .ai/specs/feature-a/* | 🟥 Cá nhân hoá | Người | Spec mẫu — tạo spec thật: @dtd-dev/agent-kb feature <tên>. |

🟦 Core = giữ nguyên, dùng lại mọi dự án. 🟩 AI điền = nhờ AI đọc code rồi viết. 🟥 Cá nhân hoá = nội dung nghiệp vụ riêng, bạn (hoặc AI có ngữ cảnh công ty) phải thay.

AI đọc file nào mỗi lần chạy?

• Luôn (mọi session): CLAUDE.md → import AGENTS.md (router + Tier 1). Tier 1 = .ai/core/tech-stack.md + coding-standards.md + glossary.md. Giữ 3 file này thật ngắn (< ~500 token/file) vì đây là phần tốn token cố định.
• Theo task (Tier 2, on-demand): AI tra bảng router trong AGENTS.md / .ai/README.md rồi chỉ mở file khớp task — vd fix bug → workflows/fix-bug.md + memory/common-bugs.md; hiểu nghiệp vụ → product/business-rules.md + product/domain-model.md. Không nuốt cả .ai/.

Gợi ý onboard dự án mới: điền 🟩 (nhờ AI) trước → thay 🟥 (nghiệp vụ) → chạy @dtd-dev/agent-kb doctor để chốt.

Prompt 1-câu để Agent tự điền các file 🟩 (dán vào Claude Code/Cursor… ở thư mục gốc dự án):

Đọc codebase của dự án này rồi điền chính xác CHỈ các file nhóm 🟩 trong .ai/ (core/tech-stack.md ở các chỗ <!-- vd: ... -->, core/coding-standards.md, core/glossary.md, architecture.md, examples/*, skills/devops/* và skills/frontend/react.md + ui-guideline.md) bằng dữ kiện có thật trong code — giữ mỗi file core/* dưới ~500 token, KHÔNG đụng file 🟥 nghiệp vụ (product/*, skills/backend/carepay-*, carepay-firebase, decisions/, specs/), KHÔNG sửa trong block BEGIN/END agent-kb — xong chạy `@dtd-dev/agent-kb doctor` và sửa tới khi sạch cảnh báo.

MIT