Claude Code · Codex · Gemini · Cursor · Kiro · Grok · OpenCode
AkiDevRule 3.8: rule dùng chung cho coding agent
AkiDevRule 3.8.0 là bộ AI rule cài một lệnh cho Claude Code, Codex, Gemini, Cursor, Kiro, Grok, OpenCode: 13 RULE, 7 METHOD, 11 skill.
Vì sao rule bị phân mảnh giữa các agent, và gói chung giải quyết gì?
AI rule (airule) là bộ chỉ dẫn viết thành file Markdown mà một coding agent như Claude Code đọc trước khi làm việc, để nó theo cùng một chuẩn hành vi ở mọi dự án. AkiDevRule đóng gói bộ đó, ghi bởi lacvietanh, thành một gói cài bằng một lệnh. Không có gói chung, ba vấn đề sau xuất hiện.
Copy-paste thủ công
CLAUDE.md hoặc GEMINI.md bị sao chép tay giữa các dự án, dẫn đến phiên bản lỗi thời (drift) ở từng nơi.
Context bloat
Nạp toàn bộ quy tắc vào mọi session làm cạn token và khiến AI loãng tập trung thay vì chỉ nạp những gì cần.
Mâu thuẫn engine
Claude Code và Antigravity có cách đọc file khác nhau. Viết rule 1 lần nhưng làm sao áp dụng tốt cho cả hai?
Cài và kiểm tra AkiDevRule 3.8 thế nào?
AkiDevRule là Git repo chứa toàn bộ rule corpus và skill definition (open standard). Chạy một lệnh (cần Node.js 18+) để biến máy trắng thành môi trường tiêu chuẩn cho mọi agent CLI đã cài; chạy lại cùng lệnh là cách cập nhật, và --check chỉ so phiên bản đã cài với bản mới nhất.
One-line install
npx @akinet/akidevrule@latestHoặc từ local checkout
git clone https://github.com/lacvietanh/akidevrule
cd akidevrule && node install.mjsScript cố tình đơn giản. Git repo là nguồn sự thật; lệnh cài đặt chỉ là công cụ phân phối file đến đúng vị trí.
Rule được phân phối tới từng agent như thế nào?
Shared (~/.aki/akidevrule/)
Rule corpus trung lập (Nguồn sự thật).
RULE-*.md: constraint rulesMETHOD-*.md: analytical frameworksagskills/: shared skill tree cho AG
Agent Specific
Cấu hình riêng cho từng nền tảng.
- Claude Code: ~/.claude/skills/ và CLAUDE.md
- Antigravity: ~/.gemini/config/rules/ và GEMINI.md overrides
- Codex: khối quản lý trong ~/.codex/AGENTS.md, skill ở ~/.agents/skills/
repo/payload/ → install.mjs → ~/.aki/akidevrule/ (Raw rules)
repo/skills/ → install.mjs → ~/.claude/skills/ VÀ ~/.gemini/config/skills/ (11 SKILL CHUNG)
repo/claude/ → install.mjs → ~/.claude/ (CLAUDE.md)
repo/claude/hooks/ → install.mjs → ~/.claude/hooks/ (aki-update-check, aki-route-guard, aki-compact-reread)
repo/payload/route-map.json → install.mjs → ~/.aki/akidevrule/route-map.json (bản đồ đường dẫn → rule cho hook và audit)
sàn hành vi + router → install.mjs → ~/.codex/AGENTS.md (khối quản lý, chỉ ghi đè phần giữa hai marker)
repo/payload/GEMINI.md → install.mjs → ~/.gemini/GEMINI.md (Antigravity Behavior Overrides)AkiDevRule có những skill nào?
Bộ công cụ open standard SKILL.md, cài cho mọi CLI được hỗ trợ.
| Skill | Kích hoạt | Mục đích |
|---|---|---|
| akirule | tự động, mọi conversation | Router rule theo nghĩa của tác vụ, kèm biên nhận [RULES] bắt buộc. Trên Claude Code được @-import, nơi khác là skill. |
| akiflow | /akiflow | Agent council có điều phối viên cho quyết định phức tạp. Chứa các subagent chuyên biệt, audit phân luồng, chạy trong workspace riêng. |
| akithink | /akithink | Phiên deep-think có cấu trúc 5 pha cho quyết định lớn, khó đảo ngược — chốt bằng decision record. |
| akihtmlreport | /akihtmlreport | Kết tinh phân tích từ hội thoại thành file REPORT.html cực rộng, tự chứa, không rơi rớt chi tiết. |
| akihelp | /akihelp | Giới thiệu trực tiếp toàn bộ hệ thống Aki đang cài đặt, đọc file thật tại runtime — không bao giờ lỗi thời. |
| akigitcommit | /akigitcommit | Biến working tree lộn xộn thành Conventional Commit gọn gàng, triage file đang dở dang. Không bao giờ tự push. |
| aki-article-writer | /aki-article-writer | Pipeline viết bài hoàn chỉnh: research, SEO, schema. Tự động spawn Image Scout subagent chuyên làm ảnh. |
| akidevsync-notes | tự động | Đọc và sửa danh sách việc .akidevsync/notes.json mà app Aki Dev Sync ghi ra. |
| akilint | /akilint | Quét cơ học lỗi bẻ dòng và comment lảm nhảm; phán xét vẫn thuộc về phiên làm việc. |
| akiopen | /akiopen | Bản tóm tắt đầu phiên, chỉ đọc: working tree, task notes, plan đang mở, [Unreleased]; báo tối đa bảy việc còn tồn theo mức nghiêm trọng. |
| akiship | /akiship | Chạy trọn nghi thức release bằng một lệnh: kiểm tra đầu vào rồi thực thi checklist B7 không giám sát, commit qua akigitcommit; chỉ dừng khi gặp mơ hồ lịch sử công khai hay mâu thuẫn thiết kế. |
3.8 đổi gì trong cách agent làm việc với bạn?
Từ AkiDevRule 3.8.0, agent không hành động khi bạn chỉ hỏi: một câu hỏi chỉ nhận câu trả lời và không file nào đổi, còn mệnh lệnh thì chạy đến cùng mà không hỏi lại. Sáu thay đổi của bản này:
Hỏi thì chỉ trả lời, ra lệnh thì làm đến cùng
agent.A3Một câu hỏi, một lời nghĩ to hay một lời sửa cho việc chưa ai ra lệnh nhận về câu trả lời và không file nào đổi. Một mệnh lệnh ("sửa X", "sửa X được không?") chạy đến cùng, không hỏi lại. Trước lệnh đầu tiên làm thay đổi trạng thái, agent phải nêu được chính những chữ của bạn đã ra lệnh; không có chữ nào, hoặc chữ đọc được hai nghĩa, thì không gọi.
Yêu cầu là toàn bộ phạm vi
agent.B1PR, push, deploy hay tag chưa ai nhờ không được làm chỉ vì đó là bước thường lệ của quy trình. Làm xong việc được nêu tên rồi dừng và báo cáo. Agent dọn mọi thứ nó hoặc lệnh nó chạy tạo ra ngoài scratchpad của harness.
Việc còn mở mang mã Q / T / N
agent.A4Q: im lặng thì việc đứng yên, bạn phải trả lời. T: agent đã tự quyết trong phạm vi lệnh, im lặng thì chạy tiếp, bạn có thể chỉnh. N: ghi chú, im lặng không đổi gì. Hết Q là bạn đọc xong.
Bớt rác, ít chạy lặp
agent.C5, coding.B3File tạm đi vào scratchpad hoặc không được tạo; một lần chạy cho mỗi trạng thái thay đổi, output dài lưu lại rồi grep thay vì chạy lại.
Rule chỉ được tính là đã đọc khi đọc trọn file
aki-route-guardLần đọc có limit hoặc offset không còn được tính; hook tự mở rộng lần đọc một phần của file rule thành đọc trọn file. Hook cũng đếm lần đọc trong Cursor, và bản đồ đường dẫn tới rule nằm trong một file dữ liệu route-map.json.
Trình cài gọn hơn
install.mjsKhông còn file *.akidevrule-backup-* để lại sau mỗi lần cài; cấu hình rtk chỉ ghi khi bạn đồng ý (hỏi mặc định là không, hoặc cờ --rtk).
Nguồn: Release Notes 3.8.0, gói npm @akinet/akidevrule, trang dự án AkiDevRule.
Smart router nạp rule nào cho tác vụ của bạn?
Thường trú
Luôn loadHai file nạp mọi phiên qua @-import trong ~/.claude/CLAUDE.md, không cần model quyết định: sàn hành vi và bảng định tuyến luôn có mặt.
RULE-agent-behavior.mdakirule (router)Theo route, có cổng chặn
On demandĐọc khi nghĩa của tác vụ khớp (lĩnh vực chạm tới và hành động: tạo, quyết định, audit, ship), bằng bất kỳ ngôn ngữ nào. Trên Claude Code, hook aki-route-guard từ chối lần sửa đầu tiên của mỗi loại file cho tới khi rule tương ứng đã được đọc trọn file sau lần nén ngữ cảnh gần nhất (đọc một phần không được tính); hook aki-compact-reread nhắc một lần sau mỗi lần nén. Lượt chỉ đọc hay giải thích không nạp gì thêm.
RULE-coding.mdRULE-pattern-core.mdRULE-test.mdRULE-docs.mdRULE-content-write.mdRULE-ui-pattern.mdRULE-stack-*.mdRULE-seo.mdRULE-release.mdRULE-db-design.mdRULE-biz.mdMETHOD-*.mdNạp toàn bộ
On demandKhi bạn yêu cầu nạp cả kho rule, bằng bất kỳ cách diễn đạt nào, agent đọc mọi file RULE-* và METHOD-* cùng lúc.
RULE-*.mdMETHOD-*.mdDeep Think chạy ở những chế độ nào?
METHOD-deep-think.md là bộ khung phân tích chuẩn (khơi mục tiêu, nguyên tắc đầu tiên, phản biện bắt buộc). Được dùng qua 3 cách:
- 1. Passive (Bị động) Smart router
akiruletự động nạp inline khi hội thoại có tính chất phân tích ("có nên...", "tradeoff ra sao..."). Agent suy nghĩ ngắn gọn, hỏi lại tối đa một câu. - 2. Triggered (Tự chạy) Khi gặp các tín hiệu trong agent.A3, agent tự chạy khung này, không hỏi lại, và kết thúc bằng quyết định rồi làm luôn:
Decided: X · because Y · rejected Z · reopen if W. Không bao giờ dừng lại để mời người dùng mở /akithink. - 3. Active (Chủ động) Người dùng gõ
/akithink. Với quyết định thật, agent tự chạy và chốt; chỉ đi qua 5 pha tương tác khi người dùng yêu cầu. Kết quả là một decision record lưu trong docs/ của dự án.
AkiDevRule chạy trên những CLI nào?
| Nền tảng | Điều phối Rules | Đích Cài Đặt Skills | Cấu Hình Gốc |
|---|---|---|---|
| Claude Code | Router akirule @-import, cổng aki-route-guard | ~/.claude/skills/ | CLAUDE.md, settings.json, hooks/ |
| Antigravity (Gemini) | GEMINI.md global overrides + rule native | Native ~/.gemini/config/skills/ | YAML trigger trong config/rules/ |
| Codex CLI | Sàn hành vi + router thành khối quản lý | ~/.agents/skills/ | ~/.codex/AGENTS.md, config.toml |
| Cursor | Skill dùng chung; hook ~/.claude cũng chạy, lần đọc rule được đếm | ~/.agents/skills/ | ~/.cursor/cli-config.json (quyền chạy script skill) |
| OpenCode | Chỉ cấp quyền chạy script skill | Không có thư mục skill riêng trong gói | ~/.config/opencode/opencode.json |
| Kiro CLI, Grok CLI | Chỉ nhận skill | ~/.kiro/skills/, ~/.grok/skills/ | Không có |
Gemini (Antigravity) được override cứng bằng GEMINI.md để vá các điểm yếu đặc thù, Claude dùng akirule để load động, Codex nhận sàn hành vi và router qua khối quản lý trong ~/.codex/AGENTS.md.
Rule Riêng Máy
Installer tạo CLAUDE.local.md và GEMINI.local.md nếu chưa có — không bao giờ ghi đè lại. Đây là nơi chứa quy tắc đặc thù của máy (đường dẫn IDE, Emulator) và luôn tồn tại an toàn qua các lần update.
Update Hook An Toàn
Hook SessionStart tự kiểm tra mã nguồn (chỉ 1 lần/ngày). fail-silent và không chặn session. Nếu có bản mới, nó thông báo báo cập nhật chứ không tự tải, không tự cài.
Mã nguồn & Cài đặt
akidevrule là kho kiến trúc tiêu chuẩn. Hãy xem README để hiểu rành rọt cơ chế smart router, cách tổ chức file và quá trình cài đặt.
github.com/lacvietanh/akidevrule