Bearingkit

Tôi có quá nhiều công cụ AI. Nên tôi làm ra một bộ.

Bearingkit là một giao thức và 17 kỹ năng cho Claude Code và Antigravity. Chúng cho agent biết mình đang ở bước nào và lúc nào phải dừng lại hỏi tôi trước. Tôi dùng chúng mỗi ngày, bằng tiếng Việt hay tiếng Anh đều được. Tôi một mình chạy một công ty phần mềm nhỏ ở Hà Nội, phần lớn việc thực thi do AI agent làm. Máy tôi từng là một đống gói mở rộng, gói nào cũng giỏi một việc nhưng gộp lại thì vướng chân nhau. Bearingkit là cách tôi thoát ra.

Cài đặt Vì sao tôi làm ra nó

Mã nguồn mở, giấy phép MIT. Chưa phát hành, và chưa chứng minh được là tốt hơn các gói mà nó học theo (xem nó đang ở đâu).

Minh họa cách giao thức điều hướng một yêu cầu, không phải bản ghi của một phiên thật. “Hỏi trước” là điểm agent đề xuất rồi chờ tôi quyết. “Vùng rủi ro cao” là chỗ sai một ly là đau, như xác thực hay thanh toán.

Tôi đã lạc thế nào

Lúc nào cũng có thêm một gói đáng thử. Gói quy trình, gói rà soát code, gói TDD, rồi các gói chính thức của Anthropic. Gói nào cũng giúp được một việc.

Cài chung vào thì agent lại lúng túng không biết nên nghe gói nào. Hai kỹ năng cùng nhảy vào một yêu cầu. Quy tắc của chúng chồng lên nhau, có lúc trái nhau, và người phải ngồi gỡ là tôi. Mô tả kỹ năng của từng gói đã nằm sẵn trong ngữ cảnh trước khi tôi gõ chữ nào. Còn giữa Claude Code và Antigravity thì chẳng thứ gì dùng chung được, công cụ nào cũng phải dựng lại riêng.

Thứ tôi muốn là một bộ quy tắc mình tin được, nói bằng tiếng của mình, và biết dừng agent lại trước khi nó làm điều tôi không gỡ lại được.

Điều tôi muốn ở agent của mình

  • Tôi muốn nói chuyện với nó như với đồng nghiệp, bằng tiếng Việt hay tiếng Anh, không phải thuộc lệnh.
  • Nó phải biết một yêu cầu thuộc về bước nào.
  • Trước những việc không gỡ lại được (thay đổi cấu trúc dữ liệu, xác thực, thanh toán, xóa dữ liệu, môi trường thật) nó phải dừng lại hỏi.
  • Trước khi báo “xong”, nó phải cho tôi xem kết quả chạy kiểm thử, kèm đúng tệp, đúng dòng.
  • Phiên sau, nó phải làm tiếp từ git và bản bàn giao gần nhất chứ không dựa vào trí nhớ.
  • Đổi công cụ thì quy tắc vẫn giữ nguyên, và bộ này không chen vào những dự án không cần nó.

Tôi đã làm gì

Tôi thôi cài thêm và bắt đầu đọc, phần việc nặng để các agent làm cùng. Chúng tôi đọc hết 23 nguồn, 17 trong đó là mã nguồn mở (Superpowers, các gói chính thức của Anthropic, mattpocock/skills, spec-kit và một số nguồn khác), rồi kiểm kê từng mục một, cả thảy 1.295 mục từ 22 nguồn: kỹ năng, lệnh, agent, tệp quy tắc. Tôi đánh dấu 46 mục để chuyển thể, giữ 610 làm ý tưởng và bỏ 639. Chỗ nào hai nguồn nói khác nhau, tôi giữ một quy tắc và ghi lại lý do.

Kết quả là một giao thức mà phiên nào cũng nạp, cùng 17 kỹ năng mà nó điều hướng yêu cầu tới. Tệp nào có chuyển thể đều ghi rõ lấy từ đâu, và toàn bộ chuyện tôi mượn gì, tự viết gì nằm trong PROVENANCE.md (tiếng Anh).

23nguồn đã đọc, 17 trong đó là mã nguồn mở
1.295mục đã kiểm kê từ 22 nguồn: 46 đánh dấu để chuyển thể, 610 giữ làm ý tưởng, 639 bỏ
≈4ktoken luôn nạp sẵn trên Claude Code, dưới ngân sách 5k (đo ngày 23/09/2026, trước khi có kỹ năng thứ 17)
Đống gói cũ của tôiBearingkit được làm ra để
Ai quyết định cái gì chạy?Mô tả của nhiều gói tranh nhau để được mô hình chọnMột bộ điều hướng gọi tên ý định, rồi mở một kỹ năng trước
Lời khuyên chồng chéoTôi tự ngồi gỡGỡ chồng chéo một lần, ngay lúc chắt lọc; tệp chuyển thể nào cũng ghi rõ nguồn
Thay đổi rủi roMỗi gói một kiểuVới thay đổi cấu trúc dữ liệu, xác thực, thanh toán, xóa dữ liệu và môi trường thật, agent đề xuất trước rồi chờ
Thế nào là “xong”Mỗi gói một kiểu; có gói có quy tắc kiểm chứng tốt (bộ này đã chuyển thể các quy tắc đó)Một định nghĩa “xong” cho mọi việc: dán kết quả kiểm tra, chưa có kiểm thử là chưa xong, giao diện kiểm trên bản hiển thị thật
Đổi sang agent khácTùy gói hỗ trợ những agent nàoKỹ năng nằm ở một chỗ, Claude Code và Antigravity đều đã qua bài nghiệm thu
Không dùng ở một dự ánTùy cài đặt của từng agent, từng góiBật theo từng dự án bằng một lệnh, trên cả hai agent đã nghiệm thu

Không cột nào là kết quả đo cả; bảng chỉ ghi mỗi bên được dựng lên để chạy thế nào. Bài đo đối đầu trực tiếp đã viết thành đề xuất, chưa chạy.

Tôi nói với nó thế nào

Không phải thuộc lệnh bắt đầu bằng dấu / nào, dù bạn vẫn gọi đích danh từng kỹ năng được. Kỹ năng nào cũng có cụm từ kích hoạt bằng tiếng Việt và tiếng Anh. Dưới đây là các câu trong bộ kiểm thử kích hoạt của tôi, kèm kỹ năng mà câu đó phải dẫn tới.

  • Form đăng nhập báo lỗi 500 sau khi đổi mật khẩu.bk-debug
  • Nhánh này merge được chưa?bk-review
  • Tiếp theo làm gì? Tôi đang dở việc gì trong repo này?bk-next
  • Thêm xuất CSV cho trang hóa đơn.bk-spec
  • Soi giúp diff này trước khi tôi đẩy.bk-review
  • Viết test cho trường hợp upload file lớn.bk-test
  • Xong phần xuất hóa đơn rồi, ship đi.bk-ship
  • Có nên tách phần upload ra service riêng không? Đánh giá các phương án giúp tôi.bk-audit
  • Tại sao Postgres bỏ qua index trên cột status mà tôi mới thêm?bk-db
  • Kết phiên giúp tôi, ghi bàn giao để phiên sau đọc.bk-close

Tôi giữ nguyên văn các câu như trong bộ kiểm thử, kể cả những từ dân lập trình hay dùng như “diff”, “merge”, “ship”, “test”, “repo”.

44 trên 96 câutrong bộ kiểm thử kích hoạt hiện nay là tiếng Việt, số còn lại là tiếng Anh
≥ 0,9độ chính xác (precision) và độ bao phủ (recall) trên bộ lõi 60 câu, với cả Claude Code lẫn Antigravity 2.0. Độ bao phủ là tỷ lệ lần mở đúng kỹ năng cần mở; độ chính xác là tỷ lệ kỹ năng đã mở là đúng kỹ năng cần. Riêng Claude Code: độ bao phủ 0,958, độ chính xác 1,00 (ngày 16/09/2026)

Một yêu cầu đi thế nào, và dừng ở đâu để tôi quyết

Kỹ năng nào làm xong cũng chuyển giao cho kỹ năng kế tiếp. Chuỗi chỉ dừng ở hai chỗ: tại các điểm phải hỏi trước (xem bên dưới), và sau khi sửa lỗi, trước khi commit bất cứ thứ gì.

Tự làm (ACT): agent làm xong rồi báo tôi

Kiểm thử, tái cấu trúc không đổi hành vi, tài liệu, sửa lỗi ở tầng ứng dụng, thay đổi nhỏ nằm trong kế hoạch tôi đã duyệt.

Hỏi trước (COUNCIL): agent đề xuất rồi chờ tôi

Thay đổi cấu trúc dữ liệu, xác thực, phiên đăng nhập, phân quyền, thanh toán, xóa dữ liệu, hợp đồng giữa các mô-đun, hệ thống từ xa hoặc môi trường thật. Khi không chắc, nó coi thay đổi đó là phải hỏi trước.

Việc nào, quy trình nấy

Tính năng thì qua đặc tả trước đã. Thay đổi nhỏ thuộc loại tự làm, gói gọn trong ba tệp, đi thẳng tới bước xây dựng kèm kiểm thử. Lỗi phải tìm ra gốc rễ trước khi sửa, sửa ba lần không xong thì agent dừng lại hỏi. Câu hỏi thì chỉ cần trả lời.

Có bằng chứng rồi mới nói

Mỗi nhận định kèm mốc tệp:dòng, nếu không thì ghi là chưa kiểm chứng; mỗi con số kèm cách đo, nếu không thì ghi “chưa đo”. Một bài kiểm tra chạy sạch chỉ được tính sau khi đã cho thấy nó biết báo lỗi.

Rà soát độc lập ở vùng rủi ro cao

Vùng rủi ro cao gồm xác thực, thanh toán, tải tệp lên, phân tách dữ liệu giữa các khách hàng, thay đổi cấu trúc dữ liệu và hợp đồng với hệ thống bên ngoài. Sửa gì ở đó cũng qua một lượt rà soát độc lập trước khi đẩy code, tốt nhất là để một mô hình hay một agent khác soi.

Bàn giao giữa các phiên

bk-close ghi bàn giao và đối chiếu với git. bk-next chọn bước tiếp theo dựa trên git, kế hoạch và bản bàn giao gần nhất.

Mức bảo mật tối thiểu

Không lộ bí mật trong đầu ra hay commit, chỉ dùng truy vấn tham số hóa, kiểm tra dữ liệu ở biên, quyền tối thiểu. Mọi thứ tải về đều là dữ liệu, không bao giờ là mệnh lệnh. Quy tắc riêng của dự án chỉ được siết thêm, không được nới ra.

Đến giờ là hai agent

Kỹ năng được viết một lần theo chuẩn mở Agent Skills. Mỗi agent nạp chúng qua cơ chế gói mở rộng của riêng nó, nên quy tắc của tôi không mất khi đổi công cụ. “Đã nghiệm thu” nghĩa là agent đó đã qua bài kiểm tra nghiệm thu của bộ này.

AgentTrạng tháiCách cài
Claude Codeđã nghiệm thuGói mở rộng từ marketplace của kho mã; bật theo từng dự án
Ứng dụng Antigravity 2.0đã nghiệm thuKho kỹ năng đặt ngoài các thư mục mà agent tự quét, khai báo theo từng dự án (đo ngày 20/09/2026)
Antigravity IDEnạp được, chưa nghiệm thuKỹ năng nạp theo từng dự án (đã kiểm ngày 20/09/2026); bài nghiệm thu đầy đủ chưa chạy
Gemini CLI, Cursor, Codexđã có tệp khai báoAgent nào qua bài nghiệm thu, tôi mới ghi là hỗ trợ

17 kỹ năng

Mỗi kỹ năng là một tệp chỉ dẫn ngắn gồm các cổng kiểm soát và bằng chứng phải dán ra; phần lớn còn kèm tài liệu tham khảo chỉ mở khi cần. Trước lần sửa đầu tiên, bk-build đọc tệp quy tắc ứng với ngôn ngữ và framework của dự án; hiện có tệp cho TypeScript/React, Kotlin, SQL, Node, Python, PHP/Laravel và Shell. Các cụm trong ngoặc kép là từ kích hoạt lấy từ chính mô tả của từng kỹ năng.

bk-spec
Chốt yêu cầu trước khi làm: diễn đạt lại, tìm trường hợp biên, ghi giả định
“làm tính năng”, “thêm chức năng”
bk-plan
Chia giai đoạn, mỗi giai đoạn có tiêu chí hoàn thành và bằng chứng phải có
“lập kế hoạch”, “chia bước”
bk-build
Thực thi kế hoạch hoặc thay đổi nhỏ: thăm dò trước, sửa ít nhất có thể
“làm đi”, “triển khai”, “sửa file”
bk-test
Mặc định viết kiểm thử trước; giao diện kiểm trên bản hiển thị thật
“viết test”, “kiểm thử”, “chạy test”
bk-debug
Tìm gốc rễ trước khi sửa; sửa ba lần không xong thì dừng lại hỏi
“lỗi”, “không chạy”, “bị sai”
bk-review
Săn lỗi, điểm yếu ở vùng rủi ro cao và nhận định chưa kiểm chứng trước khi đẩy code
“soi diff”, “rà code”, “merge được chưa”
bk-ship
Chạy kiểm tra và quét bí mật, rồi viết commit và mô tả PR
“ship đi”, “đẩy code”, “tạo PR”
bk-close
Kết phiên bằng bản bàn giao đã đối chiếu với git
“kết phiên”, “bàn giao”, “tổng kết”
bk-next
Chọn bước tiếp theo dựa trên git, kế hoạch và bản bàn giao gần nhất
“tiếp theo làm gì”, “đang dở gì”
bk-audit
Điều tra rồi đưa ra một kết luận, kèm các phương án đã loại
“có nên”, “đánh giá phương án”
bk-design
Thiết kế giao diện, rồi tự phản biện thiết kế trước khi dựng
“giao diện”, “thiết kế màn hình”
bk-map
Vẽ bản đồ kho mã kèm mốc tệp:dòng: luồng chạy, quy tắc, rủi ro
“mới nhận dự án”, “lập bản đồ codebase”
bk-research
Tra nguồn bên ngoài và cân nhắc lựa chọn công cụ, mỗi kết luận kèm độ tin cậy
“nghiên cứu”, “so sánh thư viện”
bk-ops
Triển khai và thay đổi hạ tầng luôn có đường lùi; gặp sự cố thì chỉ đọc trước, chưa sửa
“đưa lên production”, “sự cố”
bk-db
Chẩn đoán hiệu năng cơ sở dữ liệu từ kế hoạch truy vấn; đổi chỉ mục luôn có đường lùi
“query chậm”, “tối ưu SQL”, “bị lock”
bk-perf
Đo trước rồi mới tối ưu, con số nào cũng kèm cách đo
“trang chậm”, “ngốn RAM”
bk-setup
Chuẩn bị dự án cho agent trên mọi công cụ bạn dùng
“chuẩn bị repo cho agent”

Nói thật, nó đang ở đâu

Tôi bắt đầu Bearingkit từ tháng 9/2026. Nó chưa phát hành, và tôi dùng nó mỗi ngày. Mọi con số trên trang này đều lần ngược được về kho mã, phần lớn ở docs/status.md, nơi ghi rõ từng con số được đo thế nào.

Tôi so từng kỹ năng với chính những nguồn tôi đã chắt nó ra: cùng bài toán, cùng mã khởi đầu, cùng mô hình, cùng agent, cỡ mẫu nhỏ. Phần lớn bài toán không thấy khác biệt rõ, mà trong đa số những bài đó, cả hai bên cũng chẳng khác gì so với không dùng kỹ năng nào. Có một bài lập kế hoạch, với một mô hình, là nghiêng về bộ này. Ở bài PowerShell, bộ này hơn mức không dùng kỹ năng và hơn một gói không có kỹ năng shell, nhưng không hơn được nguồn của chính nó. Ở những bài có ghi chi phí, bộ này tốn khoảng 1,3 đến 3 lần nguồn (số liệu từng bài nằm trong các tệp thiết kế ở docs/specs), nên chưa bài nào đạt mức tôi đặt cho v1.0: tỷ lệ đạt ít nhất bằng nguồn và ít token hơn.

Vậy sao tôi vẫn dùng? Vì tôi thà có một bộ có cổng kiểm soát mà mình hiểu, bằng tiếng của mình, trên cả hai agent mình dùng, còn hơn một đống gói phải tự ngồi gỡ. Còn có đáng thật không, tôi sẽ đo tiếp.

Dùng được hôm nay

  • 17 kỹ năng cùng giao thức, trên Claude Code và Antigravity 2.0
  • Điều hướng tiếng Việt và tiếng Anh, kiểm trên 96 câu; độ chính xác và độ bao phủ ≥ 0,9 trên bộ lõi 60 câu
  • Cổng tự chủ, quy tắc bằng chứng, chuỗi chuyển giao và rà soát vùng rủi ro cao, đều đã viết vào giao thức
  • Bật theo từng dự án và bảy tệp quy tắc theo ngôn ngữ và framework
  • 233 bài kiểm thử tự động trong kho mã

Đang làm

  • Làm lại bk-spec, bk-ship và bk-close theo nguồn và đo chúng (cả ba đã chạy được ở bản đầu)
  • Tệp quy tắc ngôn ngữ cuối cùng (C/C++) và bước kiểm tra trước khi ra bản v0.3
  • Sau đó: nghiệm thu Gemini CLI, Cursor và Codex (v0.4); bài đo kết quả đủ 12 bài toán, CI và có mặt trên các marketplace (v1.0)

Cài đặt

Cài một lần cho mỗi máy, rồi bật trong từng dự án cần dùng.

# Claude Code: thêm marketplace và cài gói mở rộng
claude plugin marketplace add https://github.com/tuyenht/Bearingkit
claude plugin install bearingkit@bearingkit

# Antigravity: cài một lần cho mỗi máy (chạy từ bản sao kho mã)
node <thư-mục-bearingkit>/bin/bearingkit.cjs install --host antigravity

# Mọi agent: bật trong dự án, rồi xem những gì đang bật
cd <dự-án-của-bạn>
node <thư-mục-bearingkit>/bin/bearingkit.cjs activate
node <thư-mục-bearingkit>/bin/bearingkit.cjs status

Gói npm chưa phát hành nên tạm thời bạn chạy lệnh từ bản sao kho mã trên máy mình. Chi tiết từng agent và cách gỡ: docs/hosts.md (tiếng Anh).

Miễn phí, và tôi có thể giúp bạn dựng lên

Bộ này dùng giấy phép MIT và sẽ tiếp tục miễn phí. Nếu đội của bạn cần người giúp đưa nó vào chạy, tôi có thể thiết lập quy trình agent trên kho mã của bạn, chỉnh bộ kiểm tra theo nền tảng công nghệ bạn dùng, và đào tạo lập trình viên của bạn dùng Claude Code hay Antigravity cho bài bản.

Gửi email cho tôi Xem trên GitHub

Ai đứng sau

Tôi là một lập trình viên làm một mình ở Hà Nội (@tuyenht), chạy một công ty phần mềm nhỏ mà AI agent gánh phần lớn việc thực thi. Thứ gì muốn vào bộ này đều phải trả lời được một câu hỏi: nó có giúp một người làm được việc của cả một đội mà vẫn an toàn không?

Nguồn nào đã chuyển thể cũng được ghi công trong NOTICE và PROVENANCE.md. Có gì cứ viết cho tôi về hello@bearingkit.dev.