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

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 mã nguồn 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 chỉ với vài bước thiết lậ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 mã nguồn với gợi ý do AI hỗ trợ.
• Sửa lỗi: Xác định và xử lý 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ã của bạn.
• Kiểm thử & lint tự động: Chạy và sửa các bài kiểm thử lỗi, thực thi lint và cải thiện chất lượng mã.
• Tích hợp Git: Tìm kiếm lịch sử git, xử lý xung đột hợp nhất, tạo commit và tạo pull request dễ dàng.

Dù bạn làm việc với dự án mã nguồn mở hay quản lý các mã nguồn 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 bản cập nhật gần đây đã bổ sung auto mode (ít bị ngắt quãng xin quyền hơn), plan mode (luồng công việc ưu tiên thiết kế) và Routines (tác tử đám mây theo lịch chạy theo trigger mà không cần máy của bạn bật).

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

• Lập trình viên phần mềm: Nâng cao 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à cải thiện các mã nguồn chưa quen thuộc.
• Kỹ sư DevOps: Tự động hóa quy trình review mã và lint.

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 bắt đầ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 /effort. Bạn cũng có thể xây dựng tác tử AI độc lập bằng Claude Agents SDK.

Anthropic cũng đã giới thiệu Cowork để trợ giúp theo kiểu tác tử cho các tác vụ tệp và tài liệu thường ngày ngoài việc viết mã. Tính năng này có sẵn cho tất cả gói trả phí (Pro, Max, Team, Enterprise) trong ứng dụng Claude Desktop.

Nếu bạn đang cân nhắc giữa Claude Code và tác tử terminal của xAI, bài so sánh Grok Build vs. Claude Code của chúng tôi kiểm thử cả hai trên cùng một tác vụ.

Bắt đầu với dự án thực hành 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à hoặc là đăng ký Claude (Pro/Max/Teams/Enterprise) hoặc tài khoản Claude Console với thanh toán đang hoạt động.​

Cài đặt Claude Code chỉ bằng cách chạy một trong các lệnh sau trong 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ách cài đặt qua npm install -g @anthropic-ai/claude-code vẫn tồn tại nhưng đã ngưng khuyến nghị, vì vậy bạn nên ưu tiên quy trình cài đặt gốc như 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 đặt, điều hướng đến thư mục dự án của bạn và khởi chạy Claude bằng cách chạy:

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 đăng ký trả phí hay thanh toán theo mức dùng API.

Tiếp theo, bạn sẽ nhận được một 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 đó là xong, và một không gian làm việc “Claude Code” chuyên biệt 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, một 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 tự sinh.

Hãy bắt đầu bằng cách nhân bản 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 đặt 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 đã được thiết lập với đầy đủ phụ thuộc cần thiết để chạy thư viện Supabase, và kho 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 đóng góp hiệu quả là khám phá thẻ Issues trên GitHub. Trong kho Supabase, tôi phát hiện một issue 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.

Chúng ta sẽ làm gì với Claude Code:

• 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 đã ở trong thư mục supabase-py, hãy điều hướng vào thư mục supabase chứa tệp client.py và chạy Claude Code:

cd supabase
claude

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

Tái cấu trúc mã

Là một phần cải thiện SDK Python của Supabase, 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 thực hiện. Nhấn Enter để chấp thuận thay đổi. 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 thay đổi.

Với 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 để đồng nhất.
• Nâng cao khả năng đọc: Công cụ thêm chú thích phân đoạn để phân loại import và loại bỏ trùng lặp trong danh sách __all__ để tổ chức gọn gàng hơn.
• Đơn giản hóa tùy chọn client: Công cụ cũng rút gọn nhiều 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ã

Ngoài tái cấu trúc, Claude Code có thể tạo, cập nhật và tiêu chuẩn hóa tài liệu mã trên toàn bộ dự án. Công cụ có thể xác định các 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 mức độ 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, mang lại:

• Docstring cấp module rõ ràng giải thích mục đích của tệp.
• Chú thích phân đoạn chi tiết để phân loại import (kiểu 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à 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ã đã bổ sung 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 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 lỗi 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ó mục tiêu.

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 đề xuất sửa: Hỏi Claude về các giải pháp khả dĩ.
3. Áp dụng và xác minh sửa lỗi:  Triển khai gợi ý của Claude và kiểm tra xem vấn đề đã được giải quyết chưa.

Claude Code đã thực hiện các điều chỉnh sau để xử lý 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 IDE và kiểm tra kiểu đối với 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ừ xác thực, cơ sở dữ liệu, lưu trữ và hàm được nhóm rõ ràng.
• Duy trì khả năng đọc mã: Thêm chú thích để giải thích vì sao 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 tất cả lỗi trong client.py.

Các lệnh 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 lệnh slash của Claude Code.

Tính năng nâng cao của Claude Code

Khi bạn đã quen với các thao tác cơ bản như 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 hành vi của nó. Hooks và Plugins cho phép 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 các 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ụ lặp 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 sự kiện - hành động, nơi bạn xác định ba thứ:

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

• Bộ khớp (matcher): Những 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 một 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 đưa ra 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 của Claude hoặc gửi thông báo 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à formatter sau khi ghi mã

• Kiểm thử: Chạy bộ kiểm thử sau khi sửa đổi để bắt lỗi sớm

• Bảo mật: Chặn sửa đổ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ự 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 sửa trực tiếp ~/.claude/settings.json.

Claude Code plugins

Plugin 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ộ, plugin 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.

Plugin có thể 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 với hạ tầng kiểm thử nội bộ của bạn. Plugin phản hồi cùng các sự kiện như hooks nhưng gửi dữ liệu đến dịch vụ bên ngoài và xử lý phản hồi để ảnh hưởng đến luồng công việc của Claude.

Một vài tác vụ mà plugin Claude Code thực hiện 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 nội bộ

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

Cài đặt plugin từ một registry 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. Kết hợp hooks và plugin tạo nên nền tảng mở rộng, giúp Claude Code thích ứng với hạ tầng hiệ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 phạm vi sử dụng:

• Plan mode: Luồng công việc ư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: Bộ 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 phê duyệt từng lần ghi tệp.
• Routines: Tác tử đá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 bật.
• Tích hợp IDE: Claude Code có tiện ích chính thức cho VS Code, Cursor và JetBrains IDE 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ã, bổ sung tài liệu có cấu trúc và xử lý các 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 trong chính dự án của mình để xem mức độ phù hợp với quy trình làm việc.

Để tiến xa hơn, tôi khuyến khích bạn đọc hướng dẫn Claude Code Best Practices hướng dẫn 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 một dự án từ đầu, tôi khuyến nghị đọc hướng dẫn Spec-Driven Development with Claude Code.