Cài đặt và chạy Claude Code lần đầu

English title: Install and Run Claude Code — First Time

Bài 2 trong chuỗi 20 bài về Claude Code. Ở bài 1 bạn đã hiểu Claude Code và agent harness là gì. Bài này giúp bạn chạy được lần đầu trong vài phút: kiểm tra phiên bản CLI, cài plugin hoặc copy components (agents, commands, rules), và gõ một slash command để thấy kết quả. Mục tiêu: từ zero đến "có thứ chạy được", không đi sâu từng file.

Mở đầu: 2 phút từ zero đến chạy lệnh

Bạn đã cài Claude Code CLI (hoặc dùng qua IDE). Bước tiếp: làm sao để không chỉ "chat" mà còn có commands, rules, và (tuỳ chọn) skills? Hai con đường phổ biến: (1) cài qua plugin marketplace — một lệnh là có agents + commands + hooks; (2) copy thủ công — clone một bộ config mẫu từ cộng đồng rồi copy vào thư mục cấu hình của bạn. Lưu ý: nhiều nền tảng không phân phối rules qua plugin (giới hạn upstream), nên rules thường phải cài tay. Bài này mô tả các bước chung; chi tiết theo từng OS và phiên bản nên xem tài liệu chính thức.

1. Đi sâu: Tại sao cần cài đặt đúng và phiên bản

Tại sao quan trọng: Plugin và hooks thường phụ thuộc phiên bản CLI. Cài sai phiên bản có thể dẫn đến lỗi "hooks không load", "command không tìm thấy", hoặc duplicate hooks. Biết yêu cầu tối thiểu giúp bạn tránh mất thời gian debug.

Hiểu sai thường gặp: "Cài plugin xong là xong hết." Thực tế, rules (guidelines luôn áp dụng) trên nhiều nền tảng không đi kèm plugin — bạn phải copy rules vào đúng thư mục (user-level hoặc project-level). Nếu không, bạn vẫn có commands và agents nhưng thiếu lớp "luôn follow quy tắc này".

Bản chất đúng: Kiểm tra claude --version (hoặc tương đương) đạt yêu cầu tối thiểu (vd. v2.1+). Cài plugin để có agents, commands, hooks; cài rules thủ công nếu nền tảng không gửi kèm. Chọn đúng ngôn ngữ (common + TypeScript hoặc Python hoặc Go…) để không bị thừa file không dùng.

2. Khái niệm

• CLI (Claude Code CLI): Ứng dụng dòng lệnh để chạy Claude Code. Bạn gõ lệnh trong terminal; phiên bản CLI quyết định tính năng (plugin, hooks, v.v.).
• Plugin / marketplace: Cơ chế cài "gói" gồm agents, commands, skills, hooks từ một nguồn (vd. GitHub). Một lệnh cài thay vì copy từng file. Rules thường không nằm trong gói plugin (theo giới hạn của nền tảng).
• Config root: Thư mục chứa cấu hình Claude Code — thường là ~/.claude (user) hoặc .claude trong project. Bên trong có các thư mục con: agents, commands, skills, rules, hooks (nếu có).
• Slash command: Lệnh bắt đầu bằng /, vd. /plan "Add auth". Khi bạn gõ, hệ thống tìm command tương ứng và chạy (có thể kèm skill hoặc agent).

3. Code / lệnh mẫu

Kiểm tra phiên bản:

claude --version

Đảm bảo phiên bản đạt mức tối thiểu (xem tài liệu chính thức; thường là v2.1 trở lên cho plugin và hooks đầy đủ).

Cài plugin (ví dụ qua marketplace):

/plugin marketplace add <source>
/plugin install <plugin-name>

Tên và nguồn cụ thể phụ thuộc nền tảng; xem docs. Sau khi cài, commands và agents thường dùng dạng namespaced (vd. /plugin-name:plan "Add auth") hoặc short form nếu bạn cài thủ công.

Cài rules (thủ công): Copy nội dung từ thư mục rules/common và rules/<ngôn ngữ> của bộ config mẫu vào ~/.claude/rules/ (user) hoặc .claude/rules/ (project). Chỉ copy những ngôn ngữ bạn dùng.

4. Workflow: Các bước cài đặt và chạy lần đầu

1. Chuẩn bị: Cài Claude Code CLI (hoặc mở IDE đã tích hợp). Chạy claude --version và so với yêu cầu tối thiểu trong tài liệu.
2. Cài plugin (khuyến nghị): Thêm marketplace (nếu có), cài plugin để có agents + commands + hooks. Đọc README của plugin để biết lệnh chính xác.
3. Cài rules: Nếu plugin không gửi kèm rules, clone bộ config mẫu (từ nguồn cộng đồng uy tín), copy rules/common và rules/<ngôn ngữ> vào thư mục rules của bạn. Chỉ giữ common + 1–2 ngôn ngữ cần thiết.
4. Chạy lệnh đầu tiên: Mở Claude Code, gõ một slash command (vd. /plan "Add a login button" hoặc tương đương namespaced). Kiểm tra có response đúng (plan, gợi ý, hoặc bước thực hiện).
5. Làm quen cấu trúc: Mở thư mục config (vd. ~/.claude hoặc .claude trong repo). Xem qua các thư mục: agents, commands, skills, rules. Không cần chỉnh gì ngay — chỉ cần biết "thứ mình vừa chạy nằm ở đâu".

Sau bước này bạn đã có môi trường cơ bản. Bài 3 sẽ nói về agents — subagents và khi nào delegate.

5. Ứng dụng trong AI-centric engineering

Sau khi cài xong, bạn có thể:

• Dùng ngay commands: /plan, /tdd, /code-review (hoặc tên tương đương) để chạy quy trình có sẵn thay vì mô tả bằng lời mỗi lần.
• Chuẩn bị cho chuỗi bài sau: Các bài tiếp theo (agents, skills, rules, hooks) sẽ giả định bạn đã có môi trường chạy được; bạn có thể vừa đọc vừa thử trên project thật.
• Tùy biến dần: Khi quen, bạn có thể thêm bớt rules, tạo command riêng, hoặc gắn skill cho workflow của team. Luôn bắt đầu ít, chỉ cài thêm khi cần.

Nếu gặp lỗi "duplicate hooks" hoặc "command not found", kiểm tra lại phiên bản CLI và hướng dẫn của plugin; một số nền tảng không khai báo hooks trong manifest để tránh trùng. Chi tiết xem tài liệu chính thức Claude Code.

Bài tiếp: Agents — subagents và khi nào delegate (bài 3).