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/main/install.sh | bash

Hoặc từ local checkout

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

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/skills/    →  install.sh  →  ~/.claude/skills/     (skill)

~/.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+3: on demand

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.

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

Tier 2: On-signal Rules

On demand

Claude tự đọc file khi task khớp trigger. Ví dụ: chỉnh UI text → load RULE-content-write.md; code Nuxt → load RULE-stack-akiNuxtCf.md.

RULE-docs.mdRULE-content-write.mdRULE-stack-akiNuxtCf.md

Tier 3: Analytical Methods

On demand

Load khi task có chiều sâu phân tích: refactor, kiến trúc, tradeoff. Không load cho task đơn giản.

METHOD-flow-audit.mdMETHOD-techbiz-optimizer.md

Full load override: Thêm [load full] 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...

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. Chỉ load khi task đủ sâu (tầng 3).

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