cat ./series/claude-code-tu-zero

Claude Code từ zero: hiểu để dùng sâu 27 parts

All posts

Roadmap 25 bài về Claude Code dành cho dev đã quen gõ /commands nhưng muốn hiểu kiến trúc bên dưới. Mental model trước, customization sau: rules, skills, agents, hooks, memory, MCP, worktree, team mode. Mỗi bài đứng độc lập, đọc tuần tự sẽ tích lũy đúng thứ tự.

Read intro: Claude Code từ zero: Series Plan
  1. [1/27] Claude Code là gì: CLI, IDE, Web, SDK và anatomy của 1 session Phần lớn dev nghĩ Claude Code là cái terminal có thể code. Thực tế nó có 4 entry point khác nhau, chia sẻ chung một core (model, tool loop, permissions) nhưng hành xử rất khác về state và context. Bài mở hộp đen: anatomy của một session, 5 lớp prompt được dựng mỗi turn, và lý do biết các lớp này quan trọng cho mọi customize sau này. ~10 min read
  2. [2/27] Context window: prompt được dựng thế nào mỗi turn Mỗi lần bạn nhấn Enter, Claude Code không chỉ gửi câu hỏi của bạn lên model. Binary lắp ráp 5 lớp riêng biệt thành một prompt hoàn chỉnh trước khi gọi API. Bài này mổ xẻ từng lớp đó, kèm dữ liệu thực từ session log và số token cache để thấy rõ chi phí của mỗi turn. ~8 min read
  3. [3/27] Tool use loop: vòng giữa model và tool, retry, parallel calls Bài 1 giới thiệu tool loop trong 5 bước. Bài này đi sâu vào cơ chế bên dưới: khi nào model gửi nhiều tool call trong một turn, binary executor xử lý thế nào, lỗi được handle ra sao, và điều gì khiến vòng lặp dừng lại. Kèm ví dụ cụ thể 1 turn với 3 tool call chạy song song. ~9 min read
  4. [4/27] Permission model: ask, auto, acceptEdits, bypassPermissions và deny list Bốn mode permission của Claude Code, cách cấu hình allowlist và deny list trong settings.json, và lý do tôi đã mất một bucket production để học bài này. Bài này cũng cover PreToolUse hook và cách truyền mode khi spawn agent. ~8 min read
  5. [5/27] Compaction và prompt cache: cách CC quản lý conversation dài Context window 1M token nghe to, nhưng một session làm việc thực vẫn chạm giới hạn sau vài giờ. Bài này đi sâu vào compaction: binary detect khi nào trigger, nó làm gì với history cũ, và tại sao session dài đôi khi quên chi tiết làm 30 phút trước. Kèm theo: prompt cache 1h TTL hoạt động thế nào và tại sao nó quan trọng hơn bạn nghĩ. ~11 min read
  6. [6/27] CLAUDE.md và rules: kiến trúc instructions hierarchical, path-scoping Bài 6 đi sâu vào L2 của prompt stack: ba mức CLAUDE.md từ global đến project, và cách rule modular với frontmatter paths dùng progressive context để chỉ load instruction cần thiết theo file đang touch. ~8 min read
  7. [7/27] Skills: SKILL.md frontmatter, slash command, và disable-model-invocation Skill trong Claude Code không phải là tính năng built-in mà là một convention thư mục. Bài này mổ xẻ anatomy của một skill từ frontmatter, body, đến cách model quyết định khi nào trigger, và khi nào bạn cần tắt auto-trigger để tránh skill chạy lúc không mong muốn. ~8 min read
  8. [8/27] Subagents: anatomy, tools whitelist, system prompt, và examples block Subagent trong Claude Code không phải là session chia sẻ với main session. Nó là một session riêng biệt, có persona riêng, có tool subset riêng, và chạy độc lập. Bài này mổ xẻ cấu trúc một agent definition file: frontmatter, body system prompt, examples block, và cách spawn từ main session. ~8 min read
  9. [9/27] Hooks: lifecycle events, exit codes, và các kiểu hook thực tế Hook là shell script wired vào lifecycle event của Claude Code qua settings.json. Khác hoàn toàn với skill hay subagent: hook chạy ngoài model loop, không cần model invoke, không tiêu token. Bài này giải phẫu cơ chế hook, exit code semantics, stdin JSON payload, và hai ví dụ thực tế từ worktree đến notification. ~8 min read
  10. [10/27] Settings.json load-bearing: env, permissions, hooks, plugins Ba file settings của Claude Code, thứ tự precedence, và các field thực sự điều khiển hành vi: permissions allow/deny, hooks lifecycle, env vars theo nhóm chức năng. Biết cái nào cần commit, cái nào phải gitignore. ~8 min read
  11. [11/27] Plugins: khác skill thế nào, marketplace, khi nào dùng Plugin không phải skill lớn hơn. Đó là một cơ chế đóng gói khác: nhiều thành phần liên quan được bundle vào một đơn vị cài đặt. Bài này phân biệt plugin với skill, giải thích marketplace, và chỉ ra khi nào nên tự build thay vì dùng có sẵn. ~7 min read
  12. [12/27] Auto-memory: file-based, MEMORY.md index, các loại memory Claude Code không có database hay embedding store bên trong. Memory là một folder chứa file .md, và MEMORY.md là index được nạp vào prompt mỗi session. Bài này giải thích cấu trúc folder, 4 type memory, cách model đọc index, và khi nào nên hoặc không nên save. ~9 min read
  13. [13/27] Memory submodule pattern: share memory cross-machine an toàn Memory của Claude Code là file-based, mỗi máy giữ một bản độc lập. Dev có nhiều máy thì memory không tự đồng bộ. Bài này trình bày pattern dùng git submodule để biến memory folder thành repo riêng, sync được giữa MacBook, server, và mọi máy khác mà không cần tool bổ sung. ~6 min read
  14. [14/27] autoMemoryDirectory: chia memory theo project hoặc client Memory mặc định của Claude Code là per-workdir và không sync. Nếu bạn có nhiều client hoặc nhiều project, không tách memory là recipe cho context leak. Bài này giải thích autoMemoryDirectory, cách cấu hình trong settings.local.json, và ba use case thực tế để giữ context đúng nơi đúng lúc. ~6 min read
  15. [15/27] MCP servers: context bên ngoài, khi nào tự build, khi nào dùng có sẵn MCP (Model Context Protocol) là cơ chế để Claude Code kết nối ra external system: database, GitHub, Slack, browser. Bài này giải thích cách MCP hoạt động, khác hooks ở chỗ nào, và khi nào bạn nên tự build thay vì dùng server có sẵn. ~10 min read
  16. [16/27] Spawning patterns: foreground, background, sequential, teammate Main session khởi tạo subagent theo 4 pattern khác nhau, mỗi pattern phù hợp với một nhóm tình huống cụ thể. Hiểu 4 pattern này giúp bạn ra quyết định đúng thay vì spawn agent theo quán tính. ~8 min read
  17. [17/27] Worktree isolation: vì sao tách working tree và base branch hook Khi spawn agent mà để nó edit chung working tree với main session, bạn đang chấp nhận race condition và stale view. Bài này phân tích isolation: worktree, cách CC tạo git worktree riêng, tại sao base branch phải là HEAD thay vì origin/main, và hook WorktreeCreate làm gì bên dưới. ~7 min read
  18. [18/27] TeamCreate và SendMessage: persistent addressable agents Bài này đi vào team mode của Claude Code: cách tạo agent có tên, có thể resume xuyên turn qua SendMessage, khác gì so với one-shot Agent call, và khi nào dùng team thay vì spawn agent thông thường. ~8 min read
  19. [19/27] Cross-agent communication: tránh race, slice theo file scope Chạy nhiều agent song song không đồng nghĩa với làm việc nhanh hơn nếu hai agent cùng đụng vào một file. Bài này phân tích ba cấp isolation, anti-pattern hay gặp nhất, và các coordination pattern giúp N agent chạy cùng lúc mà không có race condition. ~10 min read
  20. [20/27] Plan mode: state file, exit prompt, plan vs todo vs memory Plan mode là cơ chế CC buộc model viết kế hoạch trước và chờ user approve trước khi thực thi. Bài giải thích workflow, file state, khi nào cần dùng, và sự khác biệt giữa plan, todo, và memory. ~8 min read
  21. [21/27] Worktree hotfix trong khi main session đang debug production Scenario thực tế nhất của worktree agent: main session đang tail log, edit .env.production, scp script lên server. Một file cần hotfix. Nếu bạn checkout sang branch mới, mất hết scratch state. Worktree agent là pattern đúng, và bài này cho thấy chính xác cách làm. ~7 min read
  22. [22/27] Branch-per-machine: sync ~/.claude/ giữa các máy Bạn có MacBook ở nhà, server homelab, và có thể thêm một laptop nữa. Mỗi máy một bộ CC config. Không sync thì drift. Sync naively thì merge conflict mỗi lần pull. Bài này trình bày pattern branch-per-machine: một git branch cho mỗi máy, workflow để cherry-pick config từ máy khác, và skill tự động hóa quá trình đó. ~7 min read
  23. [23/27] Mobile coding qua Telegram bridge Laptop ở nhà, bạn đang trên tàu, nhưng cần CC chạy một task deploy hoặc fix typo gấp. Bài này mô tả pattern dùng Telegram bot làm bridge điều khiển Claude Code từ điện thoại: architecture, các thách thức kỹ thuật, và những chỗ dễ làm sai về security. ~9 min read
  24. [24/27] Anatomy của 1 skill production-grade: từ ý tưởng đến SKILL.md Skill trong Claude Code không phải là macro đơn giản. Một skill tốt có trigger rõ ràng, scope hẹp, xử lý failure, và lifecycle rõ ràng như bất kỳ module code nào. Bài này đi từng bước build 1 skill từ ý tưởng đến file SKILL.md cuối cùng, kèm các anti-pattern thường gặp. ~9 min read
  25. [25/27] Anatomy của 1 hook production-grade: shell script và exit codes Hook khác skill ở chỗ nó không phải gợi ý cho model mà là code chạy ngoài vòng lặp model, không thể bị bỏ qua. Bài này đi từ khái niệm đến script thực tế: chọn lifecycle event, parse stdin, dùng exit code đúng, handle idempotency và timeout, rồi wire vào settings.json. Bài cuối của series. ~11 min read
  26. [26/27] Một vài session không phải là không xuất hiện, mà là xuất hiện trễ Bóc tách kiến trúc daemon của Claude Code 2.x: roster.json, spare worker pool, và cơ chế orphan adoption khiến một session foreground chỉ hiện ra trong `claude agents` sau một khoảng thời gian, không phải ngay lập tức. ~7 min read
  27. [27/27] Background session và worktree: setting worktree.bgIsolation từ 2.1.143 Từ CC 2.1.143, có setting worktree.bgIsolation cho phép background session (session chạy nền, không phải subagent) edit working copy trực tiếp thay vì bị force vào worktree riêng. Bài giải thích tại sao background session cần một cơ chế isolation khác, khi nào nên tắt isolation, và khác gì so với isolation: worktree khi spawn subagent. ~8 min read