AI ToolingFoundationClaude Code

Claude Code · Skills · CLAUDE.md · Smart Router · Gemini CLI

AkiClaudeDoc: Chia Sẻ Claude Code Rules Giữa Nhiều Dự Án

Cách đóng gói rule Claude Code, skill, và CLAUDE.md thành gói cài đặt tái sử dụng với smart router akirule 3 tầng.

Kết luận 80/20: Một lần đóng gói, cài đặt một lệnh, mọi dự án nhận cùng rule. Smart router tự chọn file cần load, không thừa, không thiếu.

Vấn đề: Rule AI bị drift giữa các dự án

Copy-paste thủ công

CLAUDE.md từ dự án này copy sang dự án khác, dần dần mỗi nơi một kiểu. Không có nguồn sự thật duy nhất.

Context bloat

Load toàn bộ rule vào mọi session, kể cả khi chỉ sửa một dòng CSS. Tốn token, AI bị loãng tập trung.

Không nhất quán

Claude Code biết rule A, Gemini CLI không biết. Một máy update rule, máy kia không hay. Kết quả AI mỗi nơi mỗi khác.

Giải pháp: Một gói, một lệnh cài đặt

AkiClaudeDoc là Git repo chứa toàn bộ rule corpus và skill definition. Chạy một lệnh là mọi máy nhận cùng baseline.

One-line install

curl -fsSL https://raw.githubusercontent.com/lacvietanh/AkiClaudeDoc/master/install.sh | bash

Wrapper qua dev.akitao.com

curl -fsSL https://dev.akitao.com/claudedoc/install.sh | bash

Hoặc từ local checkout

git clone https://github.com/lacvietanh/AkiClaudeDoc
cd AkiClaudeDoc && bash install.sh

Script cố tình đơn giản — nên đọc qua trước khi chạy. Git repo là nguồn sự thật; dev.akitao.com chỉ là lớp trình bày.

Kiến trúc: 2 vùng tách biệt

~/.aki/claudedoc/

Rule corpus: thư viện tĩnh, neutral. Bất kỳ tool nào cũng có thể đọc.

RULE-*.md: constraint rules
METHOD-*.md: analytical frameworks
index.md: master index

~/.claude/skills/akirule/

Skill definition: activation mechanism chỉ cho Claude Code.

SKILL.md: smart router prompt
Force-ON qua skillOverrides
Đọc file từ ~/.aki/claudedoc/ on demand

repo/payload/          →  install.sh  →  ~/.aki/claudedoc/     (rule corpus)
repo/claude/           →  install.sh  →  ~/.claude/            (5 skill + hook + CLAUDE.md)

~/.claude/skills/akirule/SKILL.md
  ├── @index.md                    ← Tier 1: luôn load
  ├── @RULE-agent-behavior.md      ← Tier 1: luôn load
  ├── @RULE-coding.md              ← Tier 1: luôn load
  └── "Read FILE NOW if..."        ← Tier 2: on demand, Tier 3: full load theo lệnh

5 skill đi kèm

Ngoài akirule (router thầm lặng), gói còn 4 skill gọi trực tiếp bằng lệnh.

Skill	Kích hoạt	Mục đích
akirule	tự động, mọi conversation	Smart rule router 3 tầng. Ẩn khỏi menu / theo thiết kế.
akithink	/akithink	Phiên deep-think có cấu trúc 5 pha cho quyết định lớn, khó đảo ngược, hoặc chưa rõ mục tiêu — chốt bằng một decision record trong docs/.
akihtmlreport	/akihtmlreport	Kết tinh một phân tích đã có sẵn trong hội thoại thành một file REPORT.html tự chứa, không phân tích thêm, 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 index.md và frontmatter skill tại runtime — không bao giờ lỗi thời.
akigitcommit	/akigitcommit	Biến working tree lộn xộn thành vài Conventional Commit gọn gàng theo nhóm logic. Stage theo path cụ thể, không bao giờ git add -A hay tự push.

Smart Router: 3 tầng load thông minh

Tier 1: Core

Luôn load

Nhúng cứng vào skill qua cú pháp @. Load 100% mọi conversation, không phụ thuộc tín hiệu.

index.mdRULE-agent-behavior.mdRULE-coding.md

Tier 2: Contextual (on-signal)

On demand

Claude tự Read file khi task khớp trigger — gồm cả constraint rules lẫn 2 phương pháp phân tích (METHOD-*). Độ nhạy cố tình cao: sai dương tốn vài token, sai âm gây hành vi sai.

RULE-design-core.mdRULE-ui-pattern.mdRULE-docs.mdRULE-content-write.mdRULE-stack-akiNuxtCf.mdRULE-seo.mdRULE-release.mdRULE-db-design.mdMETHOD-flow-audit.mdMETHOD-deep-think.md

Tier 3: Full load

On demand

Escape hatch tường minh: gõ đúng cụm này để ép đọc toàn bộ RULE-*.md và METHOD-*.md cùng lúc, không cần khớp tín hiệu.

nạp fullload all rules

Full load override: Gõ nạp full hoặc load all rules vào prompt để ép load toàn bộ RULE-*.md và METHOD-*.md cùng lúc.

Bind vào project: CLAUDE.md pattern

Mỗi project chỉ cần một CLAUDE.md ngắn, chứa context riêng của project. Không cần liệt kê lại rule, akirule đã lo.

# CLAUDE.md

## Aki Rules
Shared rules live at `~/.aki/claudedoc/`. Read `~/.aki/claudedoc/index.md`
for the full rule index and loading policy.
Claude Code loads these automatically via the `akirule` skill.
Gemini reads them directly from that path.

---

## THIS PROJECT
- **Name**: my-project
- **Stack**: Nuxt 4, Cloudflare Pages
- **Specific Config**: ...project-specific facts only...

Rule riêng máy: CLAUDE.local.md

Installer chỉ tạo ~/.claude/CLAUDE.local.md nếu file chưa tồn tại — sau đó không bao giờ ghi đè. Đây là nơi đặt constraint chỉ đúng cho máy này: quy tắc build, đường dẫn IDE, cờ remote-only.

Sống sót qua mọi lần reinstall, vì nó nằm ngoài payload dùng chung.

Update notification — notify-only

Hook SessionStart so sánh CHANGELOG.md đã cài với bản public, tối đa 1 lần/24h, fail-silent, không bao giờ chặn session. Khi có bản mới, chỉ in ra thông báo và lệnh git pull && bash install.sh — không tự tải, không tự cài.

Hỗ trợ cả Claude Code và Gemini CLI

Agent	Cơ chế kích hoạt	Load rules	Dynamic load
Claude Code	skillOverrides: "on"	Tự động, không cần nhắc	Dùng Read tool theo trigger
Gemini CLI	Đọc GEMINI.md → CLAUDE.md	Cần có CLAUDE.md rõ ràng	Đọc trực tiếp từ đường dẫn

Gemini auto-load GEMINI.md → redirect sang CLAUDE.md → đọc trực tiếp ~/.aki/claudedoc/ khi cần.

Quy ước đặt tên file

RULE-*.md
Constraint rules: quy định phải/không được làm. Load theo tầng 1 hoặc 2.
METHOD-*.md
Analytical frameworks: cách làm, phương pháp. Signal-loaded ở tầng 2 giống RULE-*, chỉ khi task đủ sâu (refactor, kiến trúc, tradeoff).

Cập nhật rule

1. Sửa file trong repo Git (nguồn sự thật duy nhất).
2. Chạy lại bash install.sh trên mỗi máy.
3. Claude Code và Gemini đều nhận rule mới ngay lập tức.

install.sh tạo timestamped backup trước khi ghi đè. An toàn để chạy nhiều lần.

Mã nguồn & Cài đặt

AkiClaudeDoc là open source. Xem README để hiểu toàn bộ kiến trúc, quy ước file, và cách install hoạt động chi tiết.

github.com/lacvietanh/AkiClaudeDoc