TL;DR

Claude Code đi kèm 5 layer kiến trúc mà phần lớn engineer không bao giờ đụng vào. Không phải tính năng. Không phải cài đặt. Đây là các layer - mỗi cái giải quyết một vấn đề riêng mà LLM đơn thuần không thể giải quyết bằng prompting.

  • Layer 1 - CLAUDE.md: bộ nhớ luôn active, không bao giờ cần nhắc lại
  • Layer 2 - Skills: tri thức theo module, load đúng lúc cần
  • Layer 3 - Hooks: guardrail deterministic, không phải AI - layer team hay bỏ qua nhất và hối hận nhất
  • Layer 4 - Subagents: delegation với ranh giới cứng, context sạch
  • Layer 5 - Plugins: đóng gói và phân phối cho cả team

Bao quanh 5 layer này là MCP Servers (kết nối GitHub, database, API bên ngoài) và Agent Teams (thực thi song song, ra mắt tháng 2/2026 cùng Opus 4.6).

Tại sao prompting không đủ

Phần lớn engineer tiếp cận Claude Code như một chatbot nâng cấp - paste context vào đầu session, nhắc lại rules mỗi lần, hy vọng model nhớ. Đây là cách tiếp cận sai hoàn toàn.

Vấn đề không phải ở model. Vấn đề là kiến trúc. Một nghiên cứu từ VILA Lab (arxiv 2604.14228, tháng 4/2026) phân tích source code v2.1.88 của Claude Code và phát hiện: 98.4% codebase là operational infrastructure, chỉ 1.6% là AI decision logic. Phần lớn engineering nằm ở các hệ thống bao quanh model - permission pipeline, context compaction, hook registry, subagent orchestration.

5 layer ADK chính là phần 98.4% đó. Bỏ qua chúng nghĩa là bạn đang dùng 1.6% của công cụ.

Giải phẫu 5 layer

Layer 1 - CLAUDE.md: Bộ nhớ không bao giờ quên

CLAUDE.md không phải README. Boris Cherny - creator của Claude Code tại Anthropic - mô tả nó là "onboarding docs cho AI teammate." Mỗi lỗi Claude mắc phải, bạn thêm một rule. Sau 3 tháng, agent ngừng mắc các junior mistakes.

Cơ chế kỹ thuật: CLAUDE.md được load dưới dạng user context (không phải system prompt), tức là model tuân theo theo xác suất - khoảng 70% là rule được follow. Vì vậy, nếu rule là critical, bạn phải dùng Hooks để enforce deterministic. Hai scope chính:

  • ~/.claude/CLAUDE.md - global, áp dụng cho mọi project
  • .claude/CLAUDE.md - project-level, có thể commit vào git

Giới hạn quan trọng: Anthropic khuyến nghị giữ dưới 200 dòng / 150 instructions. Vượt qua ngưỡng này, model bắt đầu bỏ qua rules trong noise.

Layer 2 - Skills: Tri thức theo yêu cầu

Mỗi SKILL.md có một trường description. Claude đọc description đó khi cần, fork skill vào một isolated subagent, rồi trả kết quả về. On-demand, không phải always-on.

Điểm khác biệt với CLAUDE.md: Skills không inflate context window. Chỉ có description ngắn nằm trong prompt cho đến khi skill được invoke. Đây là lý do skill phù hợp với tri thức chuyên biệt (code review patterns, migration guides, analytics workflows) trong khi CLAUDE.md giữ architectural rules cốt lõi.

Layer 3 - Hooks: Layer đội hay bỏ qua và hối hận nhất

Hooks là không phải AI. Đây là deterministic event-driven shell commands. Claude Code có 27 hook event types bao gồm PreToolUse, PostToolUse, SessionStart, Stop, SubagentStop, CwdChanged, TaskCompleted...

Cơ chế đơn giản: event fire - matcher check - command run. Exit 0 = allow. Exit 2 = hard block. Không qua model. Không qua prompting.

Các use case production thực tế:

  • PreToolUse: block rm -rf cứng; route git push --force lên Opus để human approve
  • PostToolUse: auto-format code sau mỗi Write/Edit
  • Stop / TaskCompleted: verify test suite pass trước khi agent mark task là done
  • CwdChanged: reload env vars khi agent cd sang project khác

Hooks có context cost bằng zero. Đây là cách để enforce quality ở infrastructure level - không phải prompt level.

Layer 4 - Subagents: Delegation với ranh giới cứng

Mỗi subagent có context window riêng, model riêng, tool set riêng, permission riêng. Main agent delegate xuống, nhận summary lên. Full transcript của subagent được lưu dưới dạng sidechain (.jsonl riêng) - không inflate parent context.

Hai constraint quan trọng: (1) Subagents không thể spawn subagent khác. (2) Agent Teams (nhiều subagents chạy song song) tiêu tốn khoảng 7x token so với session thường.

Worktree isolation: subagent có thể chạy trong Git worktree riêng biệt. Nếu nó break build hay hallucinate, main repo không bị ảnh hưởng. Đây là blast-radius control ở filesystem level - không cần Docker.

Layer 5 - Plugins: Phân phối cho cả team

Plugin bundle skills + agents + hooks + commands + MCP servers thành một package. Một lần install, cả team thừa hưởng toàn bộ behavior. Giống npm packages, nhưng cho những gì agent biết cách làm.

Lưu ý bảo mật: plugin subagents bị strip các trường hooks, mcpServers, và permissionMode. Nếu cần những quyền này, phải copy agent file vào .claude/agents/ hoặc ~/.claude/agents/ thay vì dùng qua plugin.

So sánh với các framework khác

FrameworkApproachHạn chế
AutoGenPeer agents share full transcriptsContext explosion khi nhiều agent
SWE-Agent / OpenHandsDocker container isolationCần container infra, không fine-grained
LangGraphExplicit state graph, typed edgesRigid, constrain model's decision latitude
AiderGit rollback là safety net duy nhấtPost-hoc, không pre-emptive
Claude CodeSummary-only subagents + deny-first hooks + Git worktrees7x token cost khi dùng Agent Teams

Triết lý cốt lõi: model reasons, harness enforces. Model chỉ emit tool_use blocks. Harness parse, check permissions, dispatch, collect results. Ngay cả khi model bị compromise, nó không thể override sandbox hay deny-first rules vì reasoning và enforcement nằm ở separate code paths.

Cái giá phải trả

Không layer nào là miễn phí. Một số tradeoff cần biết:

  • CLAUDE.md compliance là probabilistic (~70%), không phải guaranteed. Rules critical phải backup bằng Hooks.
  • Pre-trust initialization: hooks và MCP servers resolve trước khi trust dialog hiện ra - nguồn gốc của CVE-2025-59536 (CVSS 8.7) và CVE-2026-21852 (CVSS 5.3).
  • Bash >50 subcommands: fallback về single approval prompt, bỏ qua per-subcommand deny-rule checks.
  • Agent Teams tiêu tốn 7x token so với session thường. Async hooks không thể block action.
  • Parallel subagents thiếu global context: có thể re-implement solutions đã tồn tại ở nơi khác trong codebase.

Bắt đầu từ layer nào?

Nếu bạn chưa có layer nào - bắt đầu với CLAUDE.md. Chạy /init để Claude tự scaffold từ codebase của bạn. Giữ dưới 200 dòng. Mỗi lỗi Claude mắc: thêm một rule.

Khi team bắt đầu rely vào Claude Code cho production tasks - cài Hooks ngay. PostToolUse auto-lint, Stop verify tests, PreToolUse block destructive commands. Đây là layer hầu hết team bỏ qua và là layer họ hối hận đầu tiên.

Khi có workflows lặp lại - đóng gói thành Skills. Khi team scale - distribute qua Plugins. Dùng Subagents để isolate noisy tasks (codebase exploration, security audit, parallel research) khỏi main context.

5-layer stack trong một câu: CLAUDE.md sets rules - Skills provide expertise - Hooks enforce quality - Subagents delegate work - Plugins distribute to the team. Hầu hết production failures trong agentic systems đều trace về một layer bị thiếu.

Nguồn: Dive into Claude Code (VILA Lab, Apr 2026), Claude Code Hooks Docs, Claude Code Subagents Docs, Designing CLAUDE.md correctly (2026).