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 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, 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 hóa và nâng cấp codebase với gợi ý do AI hỗ trợ.
• Sửa lỗi: Xác định và khắc phục lỗi, thiếu phụ thuộc và 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ử & lint tự động: Chạy và sửa các bài kiểm thử thất bại, chạy lệnh 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 merge, tạo commit và tạo pull request dễ dàng.

Dù bạn làm việc trên dự án mã 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 chế độ auto (ít bị gián đoạn xin quyền hơn), chế độ plan (quy trình thiết kế trước) 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 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 chưa quen thuộc.
• Kỹ sư DevOps: Tự động hóa việc rà soát 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ể đổi mô hình ngay trong phiên bằng lệnh /model hoặc điều chỉnh độ sâu suy luận với thanh trượt /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 để hỗ trợ dạng tác tử với các tác vụ tệp và tài liệu hằng ngày vượt ra ngoài lập trình. Tính năng này có 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 của chúng ta.

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à thuê bao 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 đơn giản 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à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 đặt, điều hướng đến thư mục dự án của bạn và khởi động 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 thuê bao trả phí hay tính phí theo mức sử dụng API.

Tiếp theo, bạn sẽ nhận được một liên kết đăng nhập dẫn tới mã xác minh mà bạn phải 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 dụ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 bản 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, nền tảng backend-as-a-service xây dựng trên PostgreSQL. Supabase cung cấp một bộ công cụ gồm xác thực, đăng ký thời gian thực, lưu trữ và API tự động sinh.

Hãy 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 đã được thiết lập với đầy đủ phụ thuộc cần thiết để chạy thư viện Supabase và kho đã 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 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.

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

• Tái cấu trúc mã để tăng 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 vào thư mục supabase chứa tệp client.py và chạy Claude Code:

cd supabase
claude

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

Tái cấu trúc mã

Là một phần của việc cải thiện SDK Python của Supabase, hãy tái cấu trúc tệp client.py để tăng 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:

Lời nhắc: Hãy 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ến hành. Nhấn Enter để chấp thuận các 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 bản 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 hợp lý (lỗi xác thực, kiểu API, lỗi hàm), đổi tên import cho rõ ràng và loại bỏ bí danh dư thừa để nhất quán.
• Cải thiện 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__ cho bố cục gọn gàng hơn.
• Đơn giản hóa tùy chọn client: Công cụ cũng giảm số dòng bằng cách kết hợp các import tương tự vào một câu lệnh duy nhất.

Dưới đây là so sánh cạnh nhau 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à 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 hoặc 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, với kết quả:

• Docstring cấp mô-đun 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 (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 cạnh nhau giữa mã đã tái cấu trúc và mã đã được viết tài liệu.

Lời nhắc: 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.

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:

Lời nhắc: Kiểm tra liệu 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 lỗi: Hỏi Claude các giải pháp khả dĩ.
3. Áp dụng và xác minh bản vá:  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 sắp xếp 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 với import chưa được giải quyết.
• Phân loại lỗi nhất quán: Claude Code đảm bảo các import về 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 để chỉ ra lý do một số import bị bỏ qua thay vì xóa chúng.

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

Lời nhắc: 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 của Claude Code

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

Tôi cũng khuyến nghị xem các hướng dẫn chính thức của Anthropic và cẩm nang thực hành tốt với Claude Code của chúng tôi.

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

Khi bạn đã thoải mái với các bước 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 biến cách nó hoạt động. Hooks và Plugins cho phép bạn tự động hóa các tác vụ lặp lại và tích hợp hệ thống bên ngoài.

Hooks của Claude Code

Hooks của Claude Code 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ụ lặp lại 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 yếu tố:

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

• Bộ khớp: 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 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 sử 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 bộ kiểm thử sau khi sửa đổi để phát hiện 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ự độ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

  li>

• 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.

Plugins của Claude Code

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ể 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. Plugins phản hồi cùng sự kiện như 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 đến quy trình của Claude.

Một vài 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 issues 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

• Rà soát 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 biến: Tích hợp với hệ thống và quy trình độc quyền của công ty

• Tiện ích IDE: Thêm lệnh tùy chỉnh và công cụ điều hướng

Cài đặt plugins 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. Hooks và plugins cùng nhau tạo nên nền tảng mở rộng, điều chỉnh Claude Code phù hợp 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 cách thức và nơi bạn có thể sử dụng:

• Chế độ Plan: Quy trình “thiết kế trước” 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.
• Chế độ Auto: 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 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 chạy.
• Tích hợp IDE: Claude Code có tiện ích chính thức cho VS Code, Cursor và các IDE JetBrains 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.

Lời 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à xử lý vấn đề import.

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

Để tiến thêm một bước, tôi khuyến khích bạn đọc hướng dẫn Best Practices cho Claude Code của chúng tôi, giúp bạn 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 đề xuất đọc hướng dẫn Phát triển theo đặc tả với Claude Code.