Nền tảng kỹ thuật phần mềm khi tích hợp Claude

Thêm Claude vào một service không làm các quy tắc kỹ thuật phần mềm thông thường biến mất. Lời gọi Claude vẫn là một lời gọi mạng có thể chậm hay lỗi; prompt và tên model vẫn là cấu hình cần review; phần tích hợp vẫn cần test.

Bài này giúp bạn trả lời: gọi Claude từ code thế nào cho đúng, và những thực hành nào (version control, review, test, CI, refactor) vẫn áp dụng?

Ví dụ xuyên suốt: service phân loại phản hồi của hợp tác xã cà phê

Một hợp tác xã cà phê có khoảng 300 đại lý. Mỗi ngày đại lý gửi khoảng 800 phản hồi qua ứng dụng: hàng giao trễ, bao bì rách, khách khen hương vị. Đội 4 lập trình viên viết một service web bất đồng bộ (async) bằng Python: nhận phản hồi, gọi Claude để phân loại và tóm tắt, lưu kết quả vào database.

Service chạy được 6 tháng. Phần code xử lý prompt bắt đầu rối: logic lặp lại ở nhiều chỗ, tên model viết thẳng trong code, chưa có test cho phần gọi Claude.

Claude API là một REST API nói JSON

Một lần gọi Messages API là một yêu cầu HTTPS POST tới https://api.anthropic.com/v1/messages, gửi JSON và nhận JSON. Yêu cầu cần vài header: khoá API trong Authorization: Bearer <khoá> (header cũ x-api-key vẫn được nhận), phiên bản API (anthropic-version), và content-type: application/json. SDK chính thức gửi các header này giúp bạn.

Vì API không giữ trạng thái, hội thoại phải được lưu ở phía bạn. Cách đơn giản là lưu chính danh sách messages dưới dạng JSON, theo mã hội thoại, rồi đọc ra và thêm lượt mới mỗi lần gọi. Trong ví dụ, một phản hồi có thể có vài lượt hỏi lại ("đơn này giao trễ mấy ngày?"), nên mỗi phản hồi có một bản ghi JSON riêng.

Gọi chặn, async, streaming hay gửi rồi hỏi sau

Lời gọi Claude là chờ mạng (I/O), không phải tính toán nặng. Đó đúng là chỗ lập trình bất đồng bộ phát huy: trong lúc chờ Claude, service vẫn phục vụ được yêu cầu khác. SDK Python có hai client với cùng giao diện: Anthropic (đồng bộ) và AsyncAnthropic (bất đồng bộ).

from anthropic import AsyncAnthropic

client = AsyncAnthropic()

async def phan_loai(noi_dung: str):
    return await client.messages.create(model=MODEL, max_tokens=512, messages=[...])

Trong service async, gọi client đồng bộ sẽ chặn event loop: mọi yêu cầu khác phải đứng chờ. Cũng tránh để nhiều coroutine cùng sửa một danh sách messages dùng chung; mỗi phản hồi nên có danh sách riêng.

SDK còn lo sẵn vài việc bạn không nên tự viết lại:

• Thử lại: lỗi kết nối, 408, 409, 429 và lỗi 5xx được thử lại 2 lần mặc định, chờ tăng dần (exponential backoff). Đổi bằng max_retries.
• Timeout: mặc định 10 phút, đổi bằng timeout. SDK báo lỗi trước nếu một yêu cầu không streaming có thể kéo dài quá khoảng 10 phút.
• Mã yêu cầu: mỗi phản hồi có _request_id lấy từ header request-id; ghi vào log để tra lỗi.

Version control, review, test và CI

Prompt và tên model quyết định hành vi của ứng dụng y như code. Chúng cần được lưu trong version control, đổi qua pull request và được review như code.

Một chiến lược test có ba tầng, mỗi tầng bắt một loại lỗi:

Pipeline CI chạy trên mọi pull request nên gồm đủ các cổng chất lượng đội đã áp cho service khác (lint, test, quét bảo mật), cộng thêm test tích hợp Claude. Ứng dụng dùng AI không được miễn kỷ luật thông thường.

Refactor nhỏ và refactor lớn

Sau 6 tháng, code xử lý prompt của service đã rối tới mức thêm tính năng nào cũng chậm. Khi nợ kỹ thuật đã cản trở trực tiếp việc thêm tính năng, hoãn thêm ngày nào là trả giá thêm ngày đó. Hướng hợp lý là lên kế hoạch một đợt refactor: gộp logic lặp lại, tách các phần có trách nhiệm khác nhau, làm gọn luồng điều khiển, rồi mới làm tính năng mới.

Khi làm refactor với Claude Code, docs đưa vài mẹo: làm từng bước nhỏ kiểm được bằng test, giữ tương thích ngược khi cần, và chạy test sau mỗi bước. Với một thay đổi máy móc trên rất nhiều file (như đổi mọi handler sang helper mới), lệnh /batch chia việc thành 5 tới 30 phần độc lập, trình kế hoạch cho bạn duyệt, rồi chạy mỗi phần trong một worktree riêng và mở pull request cho từng phần. Một phiên Claude Code thứ hai, hay /code-review, có thể đóng vai người review độc lập cho phần vừa viết.