Hướng dẫn Claude Code: Thiết lập, Tái cấu trúc và Gỡ lỗi trong Thực tiễn

Claude Code là gì?

Claude Code là công cụ hoạt động trực tiếp trong terminal của bạn, hiểu codebase và hỗ trợ các tác vụ phát triển bằng các lệnh ngôn ngữ tự nhiên. Công cụ tích hợp với môi trường phát triển của bạn với thiết lập tối thiểu, giúp bạn tập trung vào việc viết và cải thiện mã.

Dưới đây là một vài khả năng chính của Claude Code:

• Chỉnh sửa và tái cấu trúc: Sửa đổi, tối ưu và nâng cấp codebase với gợi ý hỗ trợ bởi AI.
• Sửa lỗi: Xác định và khắc phục lỗi, thiếu phụ thuộc và các nút thắt hiệu năng.
• Hiểu mã: Đặt câu hỏi về kiến trúc, logic và phụ thuộc của mã.
• Kiểm thử và linting tự động: Chạy và sửa bài kiểm thử thất bại, chạy lint, và cải thiện chất lượng mã.
• Tích hợp Git: Tìm kiếm lịch sử git, giải quyết xung đột merge, tạo commit và tạo pull request dễ dàng.

Dù bạn làm việc với dự án nguồn mở hay quản lý codebase cấp doanh nghiệp, Claude Code có thể hỗ trợ tự động hóa thông minh thích ứng với phong cách lập trình và yêu cầu dự án của bạn. Các cập nhật gần đây đã bổ sung auto mode (ít bị ngắt quãng xin quyền hơn), plan mode (quy trình thiết kế trước), và Routines (các agent đám mây theo lịch chạy theo trigger mà không cần máy của bạn hoạt động).

Một số nhóm người dùng lý tưởng cho dịch vụ này:

• Nhà phát triển phần mềm: Cải thiện chất lượng và khả năng bảo trì mã.
• Cộng tác viên mã nguồn mở: Hiểu và nâng cấp các codebase không quen thuộc.
• Kỹ sư DevOps: Tự động hóa review mã và linting.

Claude Code hiện mặc định dùng Claude Opus 4.7 trên các gói Max và Team Premium. Người dùng Pro khởi đầu với Sonnet 4.6 nhưng có thể chuyển sang Opus cho các tác vụ nặng. Bạn có thể chuyển mô hình giữa phiên bằng lệnh /model hoặc điều chỉnh độ sâu lập luận bằng thanh trượt /effort. Bạn cũng có thể xây dựng agent AI độc lập bằng Claude Agents SDK.

Anthropic cũng đã giới thiệu Cowork để hỗ trợ dạng agent cho các tác vụ tệp và tài liệu hằng ngày ngoài việc viết mã. Tính năng này khả dụng cho tất cả thuê bao trả phí (Pro, Max, Team, Enterprise) trong ứng dụng Claude Desktop.

Bắt đầu với dự án thực hành.

Bước 1: Thiết lập Claude Code

Để bắt đầu với Claude Code, bạn cần một terminal, một dự án mã để làm việc và một trong hai: gói thuê bao Claude (Pro/Max/Teams/Enterprise) hoặc tài khoản Claude Console với hóa đơn API đang hoạt động.​

Cài đặt Claude Code đơn giản bằng cách chạy một trong các lệnh sau trên terminal, tùy theo hệ điều hành và terminal của bạn.

macOS / Linux / WSL: 

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell: 

irm https://claude.ai/install.ps1 | iex

Windows CMD:  

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Lưu ý: Cài đặt qua npm install -g @anthropic-ai/claude-code vẫn tồn tại nhưng đã bị phản khuyến nghị, vì vậy bạn nên ưu tiên quy trình cài đặt gốc nêu trên. Nếu trước đây bạn cài qua npm, có thể di chuyển bằng claude install.

Sau khi cài xong, điều hướng đến thư mục dự án của bạn và khởi động Claude bằng lệnh:

cd your-project-directory
claude

Về xác thực, bạn sẽ được hỏi muốn dùng Claude Code dựa trên gói thuê bao trả phí hay tính phí theo mức sử dụng API.

Tiếp theo, bạn sẽ nhận được liên kết đăng nhập dẫn đến mã xác minh cần nhập trong terminal đang chạy Claude Code. Sau đó, hoàn tất, và một không gian làm việc “Claude Code” riêng sẽ tự động được tạo để theo dõi mức sử dụng và quản lý chi phí.

Giờ đây, Claude Code đã sẵn sàng sử dụng.

Bước 2: Thiết lập môi trường phát triển

Trong demo này, tôi sẽ dùng thư viện Supabase Python supabase-py, một client Python mã nguồn mở để tương tác với Supabase, dịch vụ backend-as-a-service xây dựng trên PostgreSQL. Supabase cung cấp bộ công cụ gồm xác thực, đăng ký thời gian thực, lưu trữ và API sinh tự động.

Bắt đầu bằng cách clone kho và thiết lập môi trường phát triển.

1. Mở terminal, điều hướng đến thư mục nơi bạn muốn clone kho Supabase-py (ví dụ cd Desktop), và chạy lệnh sau:

git clone https://github.com/supabase/supabase-py.git
cd  supabase-py

2. Tiếp theo, tạo môi trường ảo và cài các phụ thuộc cần thiết bằng cách chạy lần lượt các lệnh sau trong terminal

python3 -m venv env
source env/bin/activate  # On Windows, use ./env/Scripts/activate
pip install -e .

Môi trường Python của bạn hiện đã được thiết lập với mọi phụ thuộc cần thiết để chạy thư viện Supabase, và kho mã của bạn đã sẵn sàng để khám phá. 

Bước 3: Xác định khu vực có thể đóng góp

Một cách hay để đóng góp là khám phá thẻ Issues trên GitHub. Trong kho Supabase, tôi xác định một vấn đề trong client.py liên quan đến khả năng đọc mã, cấu trúc và thiếu chú thích có ý nghĩa.

Đây là những gì chúng ta sẽ làm với Claude Code:

• Chúng ta sẽ tái cấu trúc mã để nâng cao khả năng đọc, bảo trì và tổ chức.
• Thêm docstring và chú thích nội tuyến có ý nghĩa để làm rõ mục đích của các thành phần.
• Xác định và sửa lỗi bằng cách phân tích issues và các lỗi tiềm ẩn khác.

Bước 4: Thử nghiệm với Claude Code

Vì chúng ta đang ở thư mục supabase-py, hãy điều hướng đến thư mục supabase chứa tệp client.py và chạy Claude Code:

cd supabase
claude

Giờ đây Claude Code có quyền truy cập mọi tệp và thư mục trong thư mục Supabase-py. Hãy cùng thử nghiệm.

Tái cấu trúc mã

Trong nỗ lực cải thiện Supabase Python SDK, hãy tái cấu trúc tệp client.py để nâng cao khả năng đọc, bảo trì và tổ chức. Chỉ cần nhập lời nhắc sau trong dòng lệnh:

Prompt: Tái cấu trúc mã trong tệp client.py nằm trong thư mục Supabase.

Claude sẽ hỏi xác nhận trước khi tiếp tục. Nhấn Enter để phê duyệt thay đổi. Sau khi hoàn tất, Claude Code sẽ cập nhật tệp, hiển thị các chỉnh sửa trong terminal và cung cấp tóm tắt các thay đổi đã thực hiện.

Sử dụng Claude Code, chúng tôi đã áp dụng các cải tiến sau cho client.py:

• Tổ chức import: Claude Code nhóm các import liên quan thành các phần logic (lỗi auth, kiểu API, lỗi function), đổi tên import cho rõ ràng và loại bỏ bí danh thừa để nhất quán.
• Tăng khả năng đọc: Công cụ thêm chú thích theo phần để phân loại import và loại bỏ trùng lặp trong danh sách __all__ cho tổ chức gọn gàng hơn.
• Đơn giản hóa tùy chọn client: Đồng thời giảm số dòng bằng cách gộp các import tương tự vào một câu lệnh.

Dưới đây là so sánh song song giữa mã gốc và mã đã tái cấu trúc.

Viết tài liệu cho mã

Bên cạnh tái cấu trúc, Claude Code có thể tạo, cập nhật và chuẩn hóa tài liệu mã trên toàn dự án. Công cụ có thể xác định phần chưa có tài liệu, tạo docstring hay chú thích có cấu trúc, và kiểm tra tuân thủ tiêu chuẩn tài liệu của dự án.

Chúng tôi dùng Claude Code để cải thiện tài liệu trong client.py, thu được:

• Docstring cấp mô-đun rõ ràng giải thích mục đích của tệp.
• Chú thích theo phần chi tiết để phân loại import (các loại lỗi, triển khai client, dịch vụ lưu trữ).
• Chú thích nội tuyến mô tả các loại lỗi, hàm client và các thành phần quan trọng.

Dưới đây là so sánh song song giữa mã đã tái cấu trúc và mã đã được viết tài liệu.

Prompt: Viết tài liệu cho mã client.py bằng cách thêm chú thích để cải thiện khả năng hiểu.

Sau khi thêm tài liệu, bạn có thể kiểm tra mức độ tuân thủ tiêu chuẩn dự án của mình bằng cách nhắc Claude:

Prompt: Kiểm tra xem tài liệu có tuân theo tiêu chuẩn dự án của chúng ta không.

Sửa lỗi

Gỡ lỗi có thể tốn thời gian, nhưng Claude Code rút ngắn vòng lặp bằng cách phân tích thông báo lỗi, xác định nguyên nhân gốc và đề xuất cách sửa. Dù bạn gặp thiếu import, lỗi runtime hay vấn đề logic, công cụ thu hẹp phạm vi tìm kiếm và đưa ra chỉnh sửa có trọng tâm.

Cách dùng Claude Code để gỡ lỗi:

1. Xác định vấn đề:  Chia sẻ thông báo lỗi với Claude.
2. Nhận khuyến nghị sửa: Hỏi Claude về các giải pháp khả thi.
3. Áp dụng và xác minh bản sửa:  Triển khai gợi ý của Claude và kiểm tra vấn đề đã được giải quyết chưa.

Claude Code đã thực hiện các sắp xếp sau để giải quyết vấn đề liên quan đến import trong tệp client.py: 

• Chú thích bỏ qua kiểu: Thêm chú thích # type: ignore để ẩn cảnh báo của IDE và kiểm tra kiểu với các import không giải quyết được.
• Phân loại lỗi nhất quán: Claude Code đảm bảo các import lỗi từ authentication, database, storage và functions được nhóm rõ ràng.
• Duy trì khả năng đọc mã: Thêm chú thích để nêu lý do một số import bị bỏ qua thay vì xóa chúng.

Dưới đây là so sánh song song giữa mã gốc và mã đã sửa lỗi.

Prompt: Tôi thấy một số lỗi, như 'Import gotrue.errors' không thể giải quyết. Hãy giúp tôi sửa mọi lỗi trong client.py.

Các lệnh của Claude Code

Dưới đây là một vài lệnh để bạn thử với Claude.

Để tìm hiểu sâu hơn, tôi khuyến nghị xem hướng dẫn slash commands của Claude Code.

Các tính năng nâng cao của Claude Code

Khi đã quen với cơ bản về tái cấu trúc và gỡ lỗi, bạn có thể mở rộng khả năng của Claude Code bằng cách tùy chỉnh cách công cụ hoạt động. Hooks và Plugins cho phép bạn tự động hóa tác vụ lặp lại và tích hợp hệ thống bên ngoài.

Claude Code hooks

Claude Code hooks là các trigger tự động thực thi lệnh shell khi sự kiện cụ thể xảy ra trong phiên Claude Code của bạn. Chúng tự động hóa các tác vụ như định dạng mã, chạy kiểm thử và kiểm tra bảo mật mà Claude có thể bỏ qua.

Hooks dùng hệ thống event-action, nơi bạn định nghĩa ba thứ:

• Sự kiện: Khi nào hook được kích hoạt?

• Trình khớp (matcher): Hành động nào bị ảnh hưởng?

• Lệnh: Chạy gì khi hook kích hoạt?

Ví dụ, một hook có thể kích hoạt sau khi Claude ghi tệp Python và tự động chạy black để định dạng mã. Hooks nhận ngữ cảnh JSON về những gì đã xảy ra, cho phép quyết định thông minh dựa trên loại tệp hoặc đường dẫn. Chúng có thể xuất ra bản ghi hội thoại của Claude hoặc gửi lỗi trực tiếp cho Claude để chặn thao tác.

Các trường hợp dùng phổ biến cho hooks gồm

• Định dạng mã: Tự động chạy linters và formatters sau khi ghi mã

• Kiểm thử: Chạy test suite sau khi chỉnh sửa để bắt lỗi sớm

• Bảo mật: Chặn thay đổi các tệp nhạy cảm như cấu hình production hoặc khóa API

• Tài liệu: Tự động sinh tài liệu API khi tệp nguồn thay đổi

• Tự động hóa Git: Tạo commit thông minh và xác thực chính sách bảo vệ nhánh

• Thông báo: Cảnh báo nhóm của bạn qua Slack khi tệp quan trọng thay đổi

• Tuân thủ: Áp đặt header giấy phép hoặc tiêu chuẩn mã trước khi cho phép sửa đổi

Thiết lập hooks bằng lệnh /hooks trong Claude Code hoặc chỉnh trực tiếp ~/.claude/settings.json.

Claude Code plugins

Plugins là các phần mở rộng kết nối Claude Code với công cụ, dịch vụ và API bên ngoài. Trong khi hooks tự động hóa lệnh shell cục bộ, plugins tích hợp với hệ sinh thái phát triển rộng hơn như pipeline CI/CD, công cụ quản lý dự án và nền tảng giao tiếp nhóm.

Plugins có thể đóng gói nhiều thành phần—subagent (trợ lý Claude chuyên biệt cho tác vụ cụ thể), máy chủ MCP (tích hợp công cụ chuẩn hóa) và hooks—thành một gói duy nhất để điều phối cùng nhau.

Một plugin có thể phân tích thay đổi mã và tự động tạo issue trong Jira, hoặc kết nối đến hạ tầng kiểm thử nội bộ. Plugins phản hồi các sự kiện giống hooks nhưng gửi dữ liệu tới dịch vụ bên ngoài và xử lý phản hồi để ảnh hưởng tới quy trình của Claude.

Một số tác vụ mà plugins của Claude Code làm rất tốt:

• Tích hợp CI/CD: Kích hoạt build, kiểm thử và triển khai khi tệp thay đổi

• Quản lý dự án: Tự động tạo hoặc cập nhật issue trong Jira, GitHub hoặc Linear

• Giao tiếp nhóm: Đăng cập nhật lên Slack hoặc Teams khi có thay đổi

• Review mã: Tự động tạo pull request và quản lý review trên GitHub/GitLab

• Phân tích bên ngoài: Gọi SonarQube, CodeClimate hoặc Snyk để quét mã cấp doanh nghiệp

• Công cụ tùy chỉnh: Tích hợp với hệ thống và quy trình độc quyền của công ty

• Phần mở rộng IDE: Thêm lệnh tùy chỉnh và công cụ hỗ trợ điều hướng

Cài đặt plugins từ kho hoặc xây dựng nội bộ cho tổ chức của bạn, rồi cấu hình sự kiện mà chúng phản hồi. Hooks và plugins cùng nhau tạo nên nền tảng có thể mở rộng, điều chỉnh Claude Code với hạ tầng sẵn có của bạn.

Các tính năng nâng cao khác

Claude Code đã bổ sung một số khả năng lớn khác trong năm 2026, mở rộng cách và nơi bạn có thể dùng công cụ:

• Plan mode: Quy trình ưu tiên thiết kế, nơi Claude tạo kế hoạch triển khai chi tiết trước khi viết mã. Tôi dùng cho mọi tác vụ không tầm thường.
• Auto mode: Trình phân loại quyền cho phép Claude làm việc với ít gián đoạn hơn, hữu ích cho tác vụ dài khi bạn không muốn duyệt từng lần ghi tệp.
• Routines: Agent đám mây theo lịch chạy theo cron, sự kiện GitHub (như mở PR) hoặc webhook. Máy của bạn không cần chạy.
• Tích hợp IDE: Claude Code có tiện ích chính thức cho VS Code, Cursor và JetBrains IDEs với diff nội tuyến, checkpoint và hỗ trợ đa phiên.
• Điều khiển từ xa và Channels: Chạy phiên Claude Code và tương tác từ điện thoại hoặc thiết bị khác.

Tổng kết

Trong hướng dẫn này, tôi đã dùng Claude Code để tái cấu trúc, viết tài liệu và gỡ lỗi một tệp trong Supabase Python SDK. Chúng ta đã cải thiện khả năng đọc mã, thêm tài liệu có cấu trúc và giải quyết vấn đề import.

Claude Code đang phát triển tích cực với các tính năng như plan mode, auto mode và Routines, nên đáng để bạn thử nghiệm với dự án của riêng mình để xem công cụ phù hợp với quy trình làm việc ra sao.

Để tiến thêm bước nữa, tôi khuyến khích bạn đọc hướng dẫn Claude Code Best Practices dạy cách tận dụng tối đa cửa sổ ngữ cảnh của Claude. Nếu bạn muốn xây dựng dự án từ đầu, tôi khuyên đọc hướng dẫn Spec-Driven Development with Claude Code.