Claude Code ADK: 5 Tầng Kiến Trúc Mà Hầu Hết Engineer Chưa Bao Giờ Mở Ra

TL;DR

Claude Code đi kèm 5 architectural layers mà hầu hết engineers chưa bao giờ đụng đến. Không phải features. Không phải settings. Đây là layers - mỗi layer giải quyết một vấn đề riêng biệt mà LLM đơn thuần không thể giải quyết. Bốn trong số năm layers không liên quan gì đến việc viết prompt.

CLAUDE.md - bộ nhớ luôn active, không cần paste lại mỗi session
Skills - kiến thức on-demand, không bloat context window chính
Hooks - guardrails thuần deterministic, không phải AI
Subagents - workers độc lập với context riêng, không recurse vô hạn
Plugins - đóng gói toàn bộ stack, cả team install một lần

Từ Chatbot Đến Platform

Nhiều người dùng Claude Code như một công cụ autocomplete thông minh. Quick edits, boilerplate, giải thích code - rồi thôi. Vấn đề là cách tiếp cận này bỏ lại phần lớn sức mạnh thực sự của nó.

Claude Code trước khi hiểu ADK: bạn paste context, bạn nhắc nhở AI "đừng làm X", bạn lo lắng mỗi khi AI tự ý chạy lệnh nguy hiểm. Sau khi hiểu ADK: bạn cấu hình một lần, hệ thống tự enforce. Đây không phải cải tiến UX - đây là thay đổi mô hình.

Giải Phẫu 5 Tầng

Layer 1 - CLAUDE.md: Bộ Nhớ Không Bao Giờ Quên

CLAUDE.md là file markdown được load tự động mỗi khi Claude Code khởi động. Hai scope:

~/.claude/CLAUDE.md - global, áp dụng cho mọi project
.claude/CLAUDE.md - project-specific

Đây là nơi bạn đặt architecture rules, naming conventions, test expectations, repo map. Điểm khác biệt: bạn không cần paste lại vào mỗi session. Nó luôn ở đó.

Ngoài ra, Claude Code hỗ trợ nested CLAUDE.md theo từng thư mục. File src/db/CLAUDE.md chứa database constraints chỉ được load khi Claude thực sự truy cập vào thư mục đó (lazy loading) - giữ context window chính gọn nhẹ cho đến khi cần.

Layer 2 - Skills: Kiến Thức Theo Yêu Cầu

Mỗi SKILL.md chứa một description. Claude match nó lúc runtime và fork skill vào một isolated subagent. On-demand, không phải always-on.

Ví dụ thực tế: bạn đang dùng Dexie.js (IndexedDB wrapper) nhưng Claude liên tục gợi ý API cũ. Bạn tạo một dexie-expert skill - mỗi khi Claude làm việc với database code, skill tự động fetch dexie.org/llms.txt trước khi viết bất kỳ dòng nào. Không còn hallucinate API outdated.

Skills nằm ở 4 tầng: Enterprise > Personal > Project > Plugin. Một skill's body chỉ load khi được invoke - chi phí gần như 0 cho đến khi cần, khác hoàn toàn với CLAUDE.md luôn chiếm context.

Layer 3 - Hooks: Layer Mà Mọi Team Bỏ Qua Đầu Tiên

Đây là layer quan trọng nhất và bị underestimate nhất.

Hooks không phải AI. Chúng là deterministic event-driven shell commands. Không thể hallucinate. Không thể bị thuyết phục bằng prompt.

Flow: Event fires → Matcher checks → Command runs

Claude Code fire hooks tại 25 lifecycle points. Những cái hay dùng nhất:

PreToolUse: chặn lệnh nguy hiểm trước khi execute. Exit code 2 = hard block, stderr được feed trực tiếp cho Claude như error message
PostToolUse: chạy linter ngay khi file được edit (ví dụ: oxlint sau mỗi Write)
SessionStart: inject project context tự động khi khởi động
Stop: gửi Slack notification khi Claude hoàn thành task

Một số con số cụ thể: hook output được inject vào context bị cap 10.000 characters (vượt quá sẽ lưu ra file). Command hooks timeout sau 600 giây, agent hooks 60 giây, prompt hooks 30 giây. Agent hooks (type: "agent") có thể spawn subagent với tool access - tối đa 50 agentic turns trước khi return structured JSON decision.

Ví dụ đơn giản nhất: một PreToolUse hook inspect mọi Bash command, block ngay nếu phát hiện rm -rf. Quality enforced ở tầng infrastructure, không phải tầng prompt.

Layer 4 - Subagents: Workers Với Bộ Nhớ Riêng

Mỗi subagent chạy trong context window riêng, với model riêng, tools riêng, permissions riêng. Main agent delegate xuống, nhận kết quả lên. Chỉ có vậy.

Quy tắc cứng: subagents không thể spawn subagents. Không có infinite recursion. Main context luôn clean.

Ba built-in subagents:

Subagent	Model	Tools	Dùng cho
Explore	Haiku	Read-only	Tìm kiếm codebase nhanh
Plan	Inherits	Read-only	Research trước khi lên kế hoạch
General-purpose	Inherits	All tools	Multi-step tasks phức tạp

Pattern hiệu quả nhất: giao cho subagent những operation tạo ra lượng lớn output (chạy test suite, parse log file, fetch docs). Output khổng lồ ở lại trong context của subagent, chỉ có summary đi về main conversation. Auto-compaction trigger tại 95% capacity.

Layer 5 - Plugins: npm Packages Cho Agent Behaviors

Plugin là cách bundle toàn bộ stack: skills + agents + hooks + commands thành một unit có thể cài đặt. Một install, cả team kế thừa behavior.

Lưu ý bảo mật quan trọng: plugin subagents có priority thấp nhất (Level 5) và bị ignore 3 frontmatter fields vì lý do security: hooks, mcpServers, và permissionMode. Nếu cần các fields này, copy agent file vào .claude/agents/.

Giới Hạn Cần Biết Trước

Subagents không thể spawn subagents - workflow nested delegation phải chain từ main conversation
Async hooks không thể block tool calls - action đã diễn ra trước khi hook return
CLAUDE.md bị context drift trong long sessions - instructions đầu session có thể bị deprioritize theo thời gian
Forked subagents (inherits toàn bộ conversation history) vẫn là experimental, cần v2.1.117+ và CLAUDE_CODE_FORK_SUBAGENT=1
Agent Teams cũng experimental: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Nên Dùng Khi Nào

Bắt đầu từ đơn giản nhất: Skills dễ tạo nhất và cho giá trị ngay lập tức. Thêm Hooks khi cần enforcement deterministic. Dùng Subagents khi có parallel work hoặc cần isolation context. Build Plugin khi muốn distribute cho cả team.

Những team nhận ra Claude Code không phải chat interface mà là programmable platform - đó là những team tận dụng được ADK đúng nghĩa.

Hầu hết production failures trong agentic systems đều trace về một missing layer.