Claude Code là gì: CLI, IDE, Web, SDK và anatomy của 1 session

Bạn gõ claude trong terminal, một REPL hiện ra, bạn hỏi nó sửa code, nó sửa. Đó là Claude Code đối với phần lớn dev. Câu chuyện kết thúc ở đó.

Nhưng “Claude Code” không phải tên của REPL kia. Đó là tên của một agentic coding system, và REPL chỉ là một trong bốn cách để chạy nó. Cùng một core (model, tool loop, permission system) có thể truy cập qua CLI, qua IDE extension, qua web app, hoặc qua SDK lập trình. Bốn entry point chia sẻ chung một core nhưng hành xử rất khác về context, state, và những gì bạn có thể làm.

Bài này phân tích bốn entry point đó, rồi mổ xẻ anatomy của một session đơn lẻ: năm lớp được nạp vào prompt mỗi turn, và lý do tại sao bạn cần biết các lớp này trước khi customize bất cứ gì.

Bốn entry point

                            Claude Code
                                |
        +-----------+-----------+-----------+
        |           |           |           |
       CLI       IDE ext      Web app      SDK
   (terminal)  (VS Code,   (claude.ai/  (programmatic
              JetBrains)    code)        agents)

Cùng tên, khác hình hài.

CLI (terminal)

Khởi động bằng claude trong terminal. Là cách phổ biến nhất và là cách được nhắc đến mặc định khi ai đó nói “Claude Code”. Có REPL, có slash command (/init, /clear, /compact…), có plan mode, có Bash tool, có quyền truy cập filesystem cục bộ.

Đặc điểm: stateful theo session, mỗi session là một process. Khi đóng terminal hoặc gõ /exit, session kết thúc. State được lưu vào ~/.claude/projects/<workdir-hash>/sessions/ để có thể --resume.

State per-machine. Cài CC trên hai máy là có hai bộ config độc lập, trừ khi bạn chủ động đồng bộ ~/.claude/ (xem bài 22 về branch-per-machine).

IDE extension

VS Code, JetBrains, Cursor (qua extension). Cài extension xong, một panel bên cạnh editor cho phép chat. Khác CLI ở chỗ:

Tự động gửi context về file đang mở, vị trí cursor, selection (selection được wrap trong tag <ide_selection> khi gửi vào prompt).
Có UI riêng cho diff (preview before apply), không phải chỉ output text.
Thường chia sẻ session với CLI nếu cùng workdir. Mở extension trong project mà CLI đang chạy session là đôi khi thấy session đó.

Extension không có một core riêng. Nó vẫn gọi binary claude bên dưới và nhận stream về. Khác biệt nằm ở lớp trình bày và context tự động, không phải engine.

Web app (claude.ai/code)

Truy cập từ trình duyệt tại claude.ai/code. Không cần cài gì lên máy. Không có quyền filesystem cục bộ. Code bạn cho nó xem phải paste vào, hoặc bạn liên kết một sandbox cloud.

Đối tượng chính: pair-programming nhẹ, review snippet, kiểm tra ý tưởng nhanh. Không phù hợp cho công việc dài hơi cần truy cập filesystem hoặc chạy command thực tế.

State lưu trên server Anthropic. Bạn có thể quay lại sau và thấy lịch sử chat, nhưng không thể bring vào setup CLI cục bộ (và ngược lại).

SDK (Claude Agent SDK)

Library lập trình cho phép embed CC engine vào ứng dụng của bạn. Bạn code Python hoặc TypeScript, gọi query(), nhận stream response, control tool permissions, control session lifecycle.

Khác cả ba phía trên ở chỗ: không có UI sẵn. Bạn tự dựng frontend, tự lưu state, tự handle permissions. Engine bên trong vẫn là core đó.

Use case điển hình: chatbot công ty, agent autonomous chạy headless trên server, bridge tích hợp CC vào tool nội bộ (CCBot Telegram là một ví dụ thuộc loại này).

Core dùng chung: ba thành phần luôn có

Bốn entry point khác nhau nhưng chia sẻ ba thứ:

1. Model

Một instance Claude (Opus, Sonnet, hoặc Haiku tùy chọn). Đây là LLM thật sự sinh ra token. Nếu bạn quen với cách LLM hoạt động (xem series LLM từ zero) thì đây không có gì lạ.

Model không phải là Claude Code. Nó chỉ là một thành phần. Phần “Code” trong tên đến từ lớp xung quanh model: tool loop, system prompt, permission, hooks, memory. Đó mới là thứ phân biệt CC với việc gọi trực tiếp Anthropic API.

2. Tool use loop

Vòng lặp:

1. Model nhận prompt
2. Model output text + optional tool calls
3. Tool calls được thực thi (bởi binary, IDE, hoặc SDK runtime)
4. Kết quả tool được nối lại vào conversation
5. Quay lại bước 1

Loop tiếp tục cho đến khi model output không có tool call nữa (end-of-turn), hoặc đến khi user gửi message mới.

Tool gồm: Bash, Read, Edit, Write, Grep, Glob, TodoWrite, WebFetch, WebSearch, NotebookEdit, và một số tool deferred (load on demand). Plus tool tự tạo qua MCP.

Khác biệt giữa các entry point: CLI có đủ tool (vì có terminal thực), IDE extension cộng thêm tool tương tác với editor (open file, show diff), Web app thiếu Bash và filesystem tool, SDK cho phép bạn chỉ định subset tool nào agent được dùng.

3. Permission system

Trước khi tool chạy, binary check permission. Có 4 mode chính:

Mode	Hành vi
`ask`	Mặc định. Hỏi user mỗi tool call không nằm trong allowlist.
`auto`	Skip prompt nếu tool nằm trong allowlist của `settings.json`.
`acceptEdits`	Tự động accept mọi edit không cần xác nhận. Risky.
`bypassPermissions`	Bỏ qua toàn bộ permission check. Rất nguy hiểm.

Có cả deny list để hard-block một số tool. Ví dụ trong ~/.claude/settings.json bạn có thể chặn aws s3 rm để không xóa nhầm bucket (tôi đã từng học bài này theo cách đắt nhất, xem bài 4 về permission model).

Web app permission đơn giản hơn nhiều vì không có filesystem. SDK cho phép bạn lập trình permission callback của riêng mình.

Anatomy của 1 session: 5 lớp prompt

Đây là phần quan trọng nhất của bài, và cũng là phần ít được nói đến trong doc chính thức.

Mỗi turn (mỗi lần bạn nhấn Enter gửi message), binary dựng một prompt từ 5 lớp xếp chồng:

+----------------------------------+
|  L5: User message + history     |  <- bạn gõ vào
+----------------------------------+
|  L4: Auto-context (memory,      |
|       recent files, IDE sel)    |  <- binary tự thêm
+----------------------------------+
|  L3: Tools available             |  <- enum tool list
+----------------------------------+
|  L2: User instructions           |
|       (CLAUDE.md + rules)        |  <- auto-loaded
+----------------------------------+
|  L1: System prompt               |  <- binary-controlled
+----------------------------------+

Hiểu mỗi lớp là gì, đến từ đâu, và làm sao để ảnh hưởng đến nó là toàn bộ công cuộc “customize Claude Code”.

L1: System prompt

Đây là instruction gốc của binary. “Bạn là Claude Code, CLI chính thức của Anthropic…” Có quy tắc về tone, về cách dùng tool, về git workflow defaults, về cách xử lý risky action.

Bạn không sửa được lớp này trực tiếp. Nó bị compiled vào binary. Khi nâng cấp CC, lớp này có thể đổi (và đôi khi đổi behavior một cách bất ngờ, nên check release notes).

Implication: nếu hành vi của CC làm bạn khó chịu (ví dụ nó hay ask về việc gì đó bạn coi là an toàn), bạn không thể “ghi đè” L1. Bạn chỉ có thể thêm chỉ dẫn trái ngược ở L2, hy vọng L2 đè được. Đôi khi không đè được, đó là lúc bạn cần hook để force behavior.

L2: User instructions (CLAUDE.md và rules)

Lớp bạn kiểm soát nhiều nhất, và là chỗ phần lớn customize xảy ra.

~/.claude/CLAUDE.md. Global, auto-loaded cho mọi session. Là một file markdown duy nhất. Trên máy tôi nó dài khoảng 200 dòng và chứa convention cá nhân về git, về memory submodule, về branch-per-machine workflow.
<project>/CLAUDE.md. Project-scoped. Auto-loaded khi cwd ở trong project đó. Dùng để declare convention riêng của project (build command, test command, important paths).
~/.claude/rules/*.md. Modular: thay vì một CLAUDE.md monolithic, bạn chia thành nhiều file rule nhỏ. Mỗi file có thể có frontmatter paths: để chỉ load khi đang edit file match pattern. Ví dụ rules/frontend/react.md với paths: "**/*.tsx" chỉ load khi đang edit file .tsx, không load khi đang edit Python.

CLAUDE.md project-level và global stack lại (cả hai được include). Rule có path-scope chỉ vào prompt khi điều kiện match. Đây là cơ chế progressive context: không nhồi tất cả mọi rule vào mọi session, chỉ nhồi rule cần thiết theo file đang touch.

Mỗi đợt nâng cấp CC, lớp này được parse và lắp ráp theo công thức cố định. Phần “Codebase and user instructions are shown below” trong system reminder chính là output của khâu lắp ráp này.

L3: Tools available

Một enum tool có sẵn cho turn này, kèm schema từng tool.

Thay đổi theo:

Entry point: Web app không có Bash, Read filesystem; CLI có đủ.
Plugin và MCP enabled: thêm MCP server qua claude mcp add thì tool list dài thêm. Disable plugin thì tool ngắn lại.
Deferred tools: một số tool không load sẵn. Khi cần model gọi ToolSearch để fetch schema. Lý do: tiết kiệm token cho các tool ít dùng.
Skill / subagent context: spawn subagent với tools: Read,Grep thì subagent đó chỉ thấy 2 tool đó.

Bạn không add tool tùy ý vào L3. Tool đến từ binary, từ MCP server, hoặc từ deferred registry. Cách add tool mới chuẩn là viết MCP server.

L4: Auto-context

Lớp này binary tự thêm vào mà bạn ít khi để ý. Bao gồm:

Memory. Nội dung ~/.claude/projects/<workdir-hash>/memory/MEMORY.md (hoặc folder chỉ định qua autoMemoryDirectory). Đây là cơ chế khiến CC có vẻ “nhớ” được giữa các session.
Recent files. Một số file vừa thao tác trong session.
IDE selection. Nếu chạy từ IDE extension, code đang highlight được nhét vào tag <ide_selection>.
Date / shell / OS / platform info. Binary biết hôm nay là 2026-05-17, biết shell là zsh, biết workdir là gì.
System reminder. Tag <system-reminder> chèn trước user message, gồm reminder về CLAUDE.md, available skills, deferred tools còn available, và đôi khi reminder về việc dùng TodoWrite.

L4 là phần “ma sát thấp nhất” để add context vào prompt mà không cần model tự đi tìm. Một skill tốt biết dùng L4 thay vì yêu cầu model lặp lại các bước Grep / Read mỗi lần.

L5: User message và conversation history

Phần bạn gõ vào, cộng với toàn bộ message trước đó trong session (cả message user và message assistant).

Khi conversation dài đến gần giới hạn context window (Opus 4.7 có 1M token context), binary tự động chạy compaction: tóm tắt các message cũ thành một summary, thay thế các message gốc bằng summary, giữ lại context để continue. Đây là lý do session dài đôi khi cảm giác “hơi mơ hồ” về điều đã làm 30 phút trước. Bài 5 đi sâu vào compaction.

Prompt cache (1h TTL với ENABLE_PROMPT_CACHING_1H=1) cache các lớp L1-L4 vì chúng ít thay đổi giữa các turn. Chỉ L5 thay đổi mỗi turn, nên chỉ phần đó tốn token mới. Đó là lý do session với cache warmed tốc độ phản hồi nhanh và rẻ hơn nhiều so với session đầu turn.

Tại sao phải biết 5 lớp?

Bởi vì mọi customize đều quy về việc “tác động vào lớp nào”.

Bạn muốn…	Tác động lớp
Thay đổi tone CC trả lời	L2 (CLAUDE.md / rules)
Thêm tool mới	L3 (MCP server)
CC nhớ một quyết định kiến trúc	L4 (memory)
Force CC chạy command trước commit	Hook (chèn vào tool loop)
Wrap một workflow phức tạp thành 1 lệnh	Skill (kết hợp L2 + L3 trigger)
Spawn agent song song	SDK pattern (multiple session)

Nhìn qua bảng này thì việc “skill khác hook thế nào” tự trả lời. Skill là instruction dạng markdown nhét vào L2 + L4 khi trigger. Hook là shell script chen vào tool loop. Khác bản chất, nên phối hợp khác nhau.

Phần 2 của series sẽ đi sâu vào từng lớp customize đó. Nhưng trước đó, hai bài tiếp theo (2 và 3) sẽ mô tả kỹ hơn cách L1-L5 được lắp ráp mỗi turn và cách tool loop chạy bên dưới.

Khi nào chọn entry point nào

Quay lại bốn entry point ở đầu bài. Bảng tóm tắt:

Use case	Entry point phù hợp
Coding hàng ngày, dự án thực	CLI
Pair-programming nhanh trong editor	IDE extension
Review một snippet, test ý tưởng, không cần filesystem	Web app
Build chatbot / agent autonomous embed vào ứng dụng	SDK
Mobile coding khi đang đi đường	SDK với bridge custom (ví dụ Telegram)
Workflow chia 5-10 agent song song	CLI với team mode

Tôi dùng CLI ~95% thời gian, IDE extension ~3%, SDK ~2% (cho mobile bridge), Web app gần như không. Pattern này khá phổ biến với dev senior.

Tóm tắt và bài tiếp theo

Claude Code không phải là REPL terminal. Đó là tên của một system có 4 entry point: CLI, IDE, Web, SDK. Mỗi entry point chia sẻ core (model, tool loop, permission) nhưng khác nhau về state, context tự động, và tool available.
Mỗi session là một prompt được dựng từ 5 lớp xếp chồng: L1 system prompt (binary, không sửa), L2 user instructions (CLAUDE.md, rules), L3 tools, L4 auto-context (memory, IDE selection, system reminder), L5 user message và history.
Mọi customize đều quy về việc tác động vào một trong các lớp đó. Hiểu lớp nào ăn cái gì là điều kiện cần để biết khi nào dùng skill, khi nào dùng hook, khi nào chỉ cần thêm vào CLAUDE.md.

Bài 2 sẽ mổ xẻ chi tiết cách binary lắp ráp 5 lớp này mỗi turn, kèm ví dụ thực tế kéo log một session để thấy prompt được build ra sao.

Bài thuộc series Claude Code từ zero. Series plan tại bài giới thiệu.