Cách Thiết Lập 5 AI Agent Xây Dựng API Hoàn Chỉnh (Từ Đặc Tả Đến Kiểm Thử)

Đừng sử dụng một trợ lý AI đa năng cho mọi việc. Hãy thiết lập 5 tác nhân chuyên biệt để xây dựng một API hoàn chỉnh: Kiến trúc sư Backend thiết kế hệ thống, Bộ tối ưu hóa cơ sở dữ liệu xem xét lược đồ, Lập trình viên Frontend xây dựng client, Người đánh giá mã kiểm tra bảo mật và Người kiểm tra thực tế xác thực trước khi triển khai.

Dùng thử Apidog ngay hôm nay

Bạn cần xây dựng một API nhanh chóng. Cám dỗ: yêu cầu một AI làm tất cả. Nó sẽ thiết kế cơ sở dữ liệu, viết các endpoint, xây dựng UI, review mã và kiểm thử kết quả.

Kết quả: cơ sở dữ liệu thiếu chỉ mục, endpoint dính lỗ hổng, UI bỏ qua trạng thái lỗi, kiểm thử chỉ là "trông có vẻ ổn".

Khắc phục: dùng các tác nhân chuyên biệt. Mỗi tác nhân nắm rõ lĩnh vực, có checklist, sản phẩm đầu ra rõ ràng. Kiến trúc sư Backend lo mở rộng, Bộ tối ưu hóa cơ sở dữ liệu phát hiện thiếu index, Người đánh giá mã tìm lỗ hổng, Người kiểm tra thực tế đòi bằng chứng.

Bài này hướng dẫn bạn thiết lập 5 tác nhân từ The Agency và chạy quy trình xây dựng API hoàn chỉnh. Bạn sẽ tích hợp với Apidog để kiểm thử và tài liệu hóa API, đảm bảo endpoint được xác thực theo OpenAPI trước khi triển khai.

5 Tác Nhân Bạn Sẽ Sử Dụng

Tác nhân	Bộ phận	Trách nhiệm
Kiến trúc sư Backend	Kỹ thuật	Thiết kế API, lược đồ cơ sở dữ liệu, xác thực
Bộ tối ưu hóa cơ sở dữ liệu	Kỹ thuật	Đề xuất chỉ mục, tối ưu hóa truy vấn
Lập trình viên Frontend	Kỹ thuật	Các thành phần React, client API, quản lý trạng thái
Người đánh giá mã	Kỹ thuật	Kiểm toán bảo mật, an toàn kiểu dữ liệu, xử lý lỗi
Người kiểm tra thực tế	Kiểm thử	Xác thực dựa trên bằng chứng, bằng chứng ảnh chụp màn hình

Cài đặt các tác nhân:

# Clone The Agency repo
git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents

# Copy agents to Claude Code
cp engineering/engineering-backend-architect.md ~/.claude/agents/
cp engineering/engineering-database-optimizer.md ~/.claude/agents/
cp engineering/engineering-frontend-developer.md ~/.claude/agents/
cp engineering/engineering-code-reviewer.md ~/.claude/agents/
cp testing/testing-reality-checker.md ~/.claude/agents/

Bước 1: Kiến Trúc Sư Backend Thiết Kế Hệ Thống

Bắt đầu một phiên Claude Code mới:

Activate Backend Architect mode.

Design a REST API for an e-commerce platform with:
- User authentication (JWT with refresh tokens)
- Product catalog with categories and filtering
- Shopping cart management
- Order processing with status tracking
- Payment webhook integration

Output:
1. OpenAPI 3.0 specification
2. PostgreSQL database schema with relationships
3. Project folder structure (Express.js + TypeScript)
4. Authentication flow diagram

Sản phẩm đầu ra:

• Thông số kỹ thuật OpenAPI (một phần):

openapi: 3.0.0
info:
  title: E-commerce API
  version: 1.0.0
paths:
  /auth/login:
    post:
      summary: User login
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email: { type: string, format: email }
                password: { type: string, minLength: 8 }
      responses:
        '200':
          description: JWT tokens
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessToken: { type: string }
                  refreshToken: { type: string }

• Lược đồ Cơ sở dữ liệu:

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE TABLE products (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    description TEXT,
    price DECIMAL(10, 2) NOT NULL CHECK (price >= 0),
    category_id UUID REFERENCES categories(id),
    inventory_count INTEGER DEFAULT 0,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE TABLE orders (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    total_amount DECIMAL(10, 2) NOT NULL,
    status VARCHAR(50) DEFAULT 'pending',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

• Cấu trúc thư mục:

src/
├── controllers/
│   ├── auth.controller.ts
│   ├── products.controller.ts
│   └── orders.controller.ts
├── middleware/
│   ├── auth.middleware.ts
│   └── validation.middleware.ts
├── routes/
│   ├── auth.routes.ts
│   ├── products.routes.ts
│   └── orders.routes.ts
├── services/
│   ├── auth.service.ts
│   ├── products.service.ts
│   └── orders.service.ts
├── models/
│   ├── User.ts
│   ├── Product.ts
│   └── Order.ts
└── index.ts

Lưu kết quả đầu ra để chuyển cho tác nhân tiếp theo.

Bước 2: Bộ Tối Ưu Hóa Cơ Sở Dữ Liệu Xem Xét Lược Đồ

Mở một phiên mới:

Activate Database Optimizer mode.

Review this PostgreSQL schema for an e-commerce API:

[Paste the schema from Step 1]

Check for:
1. Missing indexes on foreign keys and frequently queried columns
2. Query performance on product search (name, category, price range)
3. Proper constraints for data integrity
4. Missing tables for common e-commerce features (reviews, wishlists)
5. Soft delete patterns for audit trails

Output specific ALTER TABLE statements and new table definitions.

Sản phẩm đầu ra:

• Đề xuất chỉ mục:

-- Add indexes on foreign keys
CREATE INDEX idx_products_category_id ON products(category_id);
CREATE INDEX idx_orders_user_id ON orders(user_id);

-- Add index for product search
CREATE INDEX idx_products_name_search ON products USING gin(to_tsvector('english', name));
CREATE INDEX idx_products_price ON products(price) WHERE inventory_count > 0;

-- Add composite index for category filtering
CREATE INDEX idx_products_category_price ON products(category_id, price);

• Bảng bị thiếu:

CREATE TABLE reviews (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    product_id UUID REFERENCES products(id),
    user_id UUID REFERENCES users(id),
    rating INTEGER CHECK (rating >= 1 AND rating <= 5),
    comment TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    UNIQUE(product_id, user_id)
);

CREATE TABLE cart_items (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    product_id UUID REFERENCES products(id),
    quantity INTEGER DEFAULT 1 CHECK (quantity > 0),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    UNIQUE(user_id, product_id)
);

• Các ràng buộc cần thêm:

-- Email format validation
ALTER TABLE users ADD CONSTRAINT chk_email_format
    CHECK (email ~* '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$');

-- Soft delete column
ALTER TABLE products ADD COLUMN deleted_at TIMESTAMP WITH TIME ZONE NULL;
CREATE INDEX idx_products_deleted_at ON products(deleted_at) WHERE deleted_at IS NULL;

Áp dụng các đề xuất vào lược đồ.

Bước 3: Lập Trình Viên Frontend Xây Dựng Client

Mở một phiên mới:

Activate Frontend Developer mode.

Build a React dashboard for this e-commerce API:

[Paste OpenAPI spec from Step 1]

Requirements:
- TypeScript with strict mode
- React Query for server state management
- Product list with filters (category, price range, search)
- Shopping cart with real-time updates
- Order history with status tracking
- Proper error handling and loading states
- Responsive design (mobile, tablet, desktop)

Output:
1. Project setup (Vite + React + TypeScript)
2. API client with React Query hooks
3. Core components (ProductList, ProductCard, Cart, OrderHistory)
4. Error boundary and loading skeletons

Các đoạn mã thực thi:

• Client API:

// src/lib/api-client.ts
import { QueryClient, useQuery, useMutation } from '@tanstack/react-query';

const API_BASE = 'http://localhost:3000/api';

async function fetcher<T>(endpoint: string, options?: RequestInit): Promise<T> {
  const response = await fetch(`${API_BASE}${endpoint}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      ...options?.headers,
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Request failed');
  }

  return response.json();
}

export function useProducts(filters?: ProductFilters) {
  const params = new URLSearchParams(filters as Record<string, string>);
  return useQuery({
    queryKey: ['products', filters],
    queryFn: () => fetcher<Product[]>(`/products?${params}`),
  });
}

export function useAddToCart() {
  return useMutation({
    mutationFn: (item: CartItem) =>
      fetcher<CartItem>('/cart', {
        method: 'POST',
        body: JSON.stringify(item),
      }),
  });
}

• Thành phần ProductList:

// src/components/ProductList.tsx
import { useProducts } from '@/lib/api-client';
import { ProductCard } from './ProductCard';
import { FilterSidebar } from './FilterSidebar';
import { Skeleton } from './ui/skeleton';

export function ProductList() {
  const [filters, setFilters] = useState<ProductFilters>({});
  const { data: products, isLoading, error } = useProducts(filters);

  if (error) {
    return <Alert variant="destructive">{error.message}</Alert>;
  }

  return (
    <div className="flex gap-4">
      <FilterSidebar filters={filters} onFilterChange={setFilters} />
      <div className="flex-1 grid grid-cols-1 md:grid-cols-3 gap-4">
        {isLoading ? (
          Array.from({ length: 6 }).map((_, i) => (
            <Skeleton key={i} className="h-64" />
          ))
        ) : products?.length === 0 ? (
          <EmptyState message="No products found" />
        ) : (
          products?.map(product => (
            <ProductCard key={product.id} product={product} />
          ))
        )}
      </div>
    </div>
  );
}

• Error Boundary:

// src/components/ErrorBoundary.tsx
export class ErrorBoundary extends React.Component<
  { children: React.ReactNode },
  { hasError: boolean; error: Error | null }
> {
  constructor(props: { children: React.ReactNode }) {
    super(props);
    this.state = { hasError: false, error: null };
  }

  static getDerivedStateFromError(error: Error) {
    return { hasError: true, error };
  }

  render() {
    if (this.state.hasError) {
      return (
        <div className="p-4 bg-red-50 border border-red-200 rounded">
          <h2 className="text-lg font-semibold text-red-800">Something went wrong</h2>
          <p className="text-red-600">{this.state.error?.message}</p>
          <Button onClick={() => window.location.reload()} className="mt-2">
            Reload
          </Button>
        </div>
      );
    }

    return this.props.children;
  }
}

Bước 4: Người Đánh Giá Mã Kiểm Tra Mọi Thứ

Mở một phiên mới:

Activate Code Reviewer mode.

Review this codebase for:

1. Security vulnerabilities:
   - SQL injection risks
   - XSS vulnerabilities
   - CSRF protection
   - Authentication bypass possibilities

2. TypeScript strict mode compliance:
   - No implicit any
   - Proper type definitions
   - Null/undefined handling

3. Error handling gaps:
   - Uncaught promise rejections
   - Missing try/catch blocks
   - Silent failures

[Paste the code from Steps 1-3]

Output a report with severity ratings (Critical, High, Medium, Low) and specific fixes.

Báo cáo mẫu:

Các Vấn Đề Nghiêm Trọng

1. Lỗi SQL Injection trong Tìm kiếm sản phẩm

Vị trí: src/controllers/products.controller.ts:24

Vấn đề: Dữ liệu đầu vào nối trực tiếp vào truy vấn SQL

// VULNERABLE
const query = `SELECT * FROM products WHERE name LIKE '%${search}%'`;

Khắc phục: Sử dụng truy vấn tham số hóa

const query = 'SELECT * FROM products WHERE name LIKE $1';
await db.query(query, [`%${search}%`]);

Các Vấn Đề Mức Độ Cao

2. Thiếu Bảo Vệ CSRF

Vị trí: src/index.ts

Vấn đề: Không có middleware CSRF cho các thao tác thay đổi trạng thái

Khắc phục: Thêm middleware csurf

import csrf from 'csurf';
app.use(csrf({ cookie: true }));

Các Vấn Đề Trung Bình

3. Kiểu dữ liệu 'any' ngầm định trong phản hồi API

Vị trí: src/lib/api-client.ts:8

Vấn đề: Kiểu any chung cho hàm fetcher

Khắc phục: Thêm ràng buộc kiểu dữ liệu

async function fetcher<T extends Record<string, unknown>>(
  endpoint: string,
  options?: RequestInit
): Promise<T> { ... }

Báo cáo An toàn kiểu dữ liệu (Type Safety):

## Các vi phạm TypeScript

1. `products.controller.ts:45` - Thiếu chú thích kiểu trả về
2. `auth.middleware.ts:12` - Kiểu 'any' ngầm định trong khối catch
3. `orders.service.ts:78` - Đối tượng có thể không được định nghĩa

Chạy `tsc --noEmit` để xem danh sách đầy đủ. Khắc phục trước khi triển khai.

Áp dụng các bản sửa lỗi trước khi chuyển bước tiếp.

Bước 5: Người Kiểm Tra Thực Tế Xác Thực Trước Khi Triển Khai

Mở một phiên mới:

Activate Reality Checker mode.

This e-commerce API is ready for production validation.

Run your mandatory reality check process:

1. Verify files exist
2. Cross-reference claimed features with actual code
3. Require screenshot evidence from Playwright tests
4. Review test-results.json for performance metrics

Project URL: http://localhost:3000
Test results: ./public/qa-screenshots/test-results.json

Output: PASS or NEEDS WORK with specific blocking issues.

Lệnh kiểm tra thực tế:

# 1. Verify files exist
ls -la src/controllers/ src/services/ src/routes/
ls -la src/components/ src/lib/

# 2. Cross-reference claimed features
grep -r "jwt\|jsonwebtoken" . --include="*.ts" || echo "NO JWT FOUND"
grep -r "bcrypt\|argon2" . --include="*.ts" || echo "NO PASSWORD HASHING FOUND"
grep -r "rateLimit\|express-rate-limit" . --include="*.ts" || echo "NO RATE LIMITING FOUND"

# 3. Run Playwright screenshot capture
npx playwright test --config=qa-playwright.config.ts --grep "@screenshot"

# 4. Review test results
cat public/qa-screenshots/test-results.json

Báo cáo xác thực:

## Kết quả kiểm tra thực tế

### Xác minh tệp: ĐẠT
- Tất cả các tệp controller đều có mặt
- Tất cả các tệp component đều có mặt

### Xác minh tính năng: CẦN SỬA
- Xác thực JWT: ĐÃ TÌM THẤY
- Băm mật khẩu: ĐÃ TÌM THẤY
- Giới hạn tỷ lệ: KHÔNG TÌM THẤY (gây chặn)

### Bằng chứng ảnh chụp màn hình: CẦN SỬA
- Bố cục trên máy tính để bàn: ĐẠT
- Bố cục trên máy tính bảng: ĐẠT
- Bố cục trên điện thoại di động: THẤT BẠI (lưới sản phẩm bị hỏng ở 375px)

### Các chỉ số hiệu suất: CẦN SỬA
- Thời gian tải trung bình: 2.3s (mục tiêu: <1s)
- Lỗi console: 3 (mục tiêu: 0)
- Yêu cầu mạng thất bại: 1 (mục tiêu: 0)

## Trạng thái cuối cùng: CẦN SỬA

### Các vấn đề gây chặn:
1. Giới hạn tỷ lệ chưa được triển khai
2. Bố cục trên điện thoại di động bị hỏng ở danh sách sản phẩm
3. Cần sửa 3 lỗi console
4. Thời gian tải vượt quá mục tiêu 1s

### Không gây chặn:
- Thêm hiệu ứng loading skeletons vào lịch sử đơn hàng
- Cải thiện thông báo lỗi

Khắc phục các vấn đề gây chặn và chạy lại Trình kiểm tra thực tế.

Tóm tắt Quy trình làm việc

┌─────────────────────────────────────────────────────────────────┐
│  Kiến trúc sư Backend                                           │
│  → Thông số kỹ thuật OpenAPI, lược đồ cơ sở dữ liệu, cấu trúc thư mục              │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  Bộ tối ưu hóa cơ sở dữ liệu                                            │
│  → Đề xuất chỉ mục, các bảng bị thiếu, ràng buộc           │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  Lập trình viên Frontend                                            │
│  → Các thành phần React, client API, xử lý lỗi                 │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  Người đánh giá mã                                                  │
│  → Kiểm toán bảo mật, an toàn kiểu dữ liệu, các lỗ hổng xử lý lỗi             │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  Người kiểm tra thực tế                                                │
│  → Xác thực dựa trên bằng chứng, bằng chứng ảnh chụp màn hình, ĐẠT/KHÔNG ĐẠT       │
└─────────────────────────────────────────────────────────────────┘

Thực thi tác nhân song song (Nâng cao)

Chạy các tác nhân song song để rút ngắn thời gian:

# Terminal 1: Kiến trúc sư Backend
claude "Activate Backend Architect. Design e-commerce API..."

# Terminal 2: Bộ tối ưu hóa cơ sở dữ liệu (đợi lược đồ)
claude "Activate Database Optimizer. Review this schema..."

# Terminal 3: Lập trình viên Frontend (đợi thông số kỹ thuật API)
claude "Activate Frontend Developer. Build React dashboard..."

# Terminal 4: Người đánh giá mã (đợi mã)
claude "Activate Code Reviewer. Review this codebase..."

# Tất cả các terminal: Người kiểm tra thực tế (xác thực cuối cùng)
claude "Activate Reality Checker. Run mandatory checks..."

Thực thi song song giúp hoàn thành quy trình chỉ trong 2-4 giờ thay vì 6-8 giờ.

Những Gì Bạn Đã Xây Dựng

Sản phẩm	Tác nhân	Kết quả đầu ra
Thiết kế API	Kiến trúc sư Backend	Thông số kỹ thuật OpenAPI, lược đồ cơ sở dữ liệu, cấu trúc thư mục
Tối ưu hóa lược đồ	Bộ tối ưu hóa cơ sở dữ liệu	Đề xuất chỉ mục, các bảng bổ sung, ràng buộc
Giao diện người dùng	Lập trình viên Frontend	Các thành phần React, client API, ranh giới lỗi
Kiểm toán bảo mật	Người đánh giá mã	Báo cáo lỗ hổng, sửa lỗi an toàn kiểu dữ liệu
Xác thực cuối cùng	Người kiểm tra thực tế	Bằng chứng ảnh chụp màn hình, chứng nhận ĐẠT/KHÔNG ĐẠT

---

Các Bước Tiếp Theo

Triển khai API:

• Thiết lập PostgreSQL production với connection pooling
• Cấu hình biến môi trường cho secrets
• Thêm các endpoint kiểm tra sức khỏe (health check)
• Thiết lập giám sát (Prometheus, Grafana)

Mở rộng quy trình:

• Thêm tác nhân Performance Benchmarker để kiểm thử tải
• Thêm tác nhân Technical Writer để viết tài liệu
• Thêm tác nhân DevOps Automator cho pipeline CI/CD

Tái sử dụng mẫu:

• Lưu các prompt thành template
• Tạo script workflow để chuỗi các phiên tác nhân
• Chia sẻ với nhóm

Năm tác nhân chuyên biệt. Một API hoàn chỉnh. Không lời khuyên chung chung.

Đó là sức mạnh của chuyên môn hóa: mỗi tác nhân rõ vai trò, có checklist, có sản phẩm cụ thể.

Đến lượt bạn: chọn dự án, kích hoạt các tác nhân và triển khai nhanh hơn.

Những Điểm Chính

• Tác nhân chuyên biệt vượt trội hơn trợ lý đa năng — Mỗi tác nhân có chuyên môn, checklist và sản phẩm rõ ràng
• Quy trình tuần tự đảm bảo chất lượng — Kiến trúc sư Backend thiết kế, Bộ tối ưu hóa cơ sở dữ liệu xem xét, Lập trình viên Frontend xây dựng, Người đánh giá mã kiểm toán, Người kiểm tra thực tế xác thực
• Phê duyệt dựa trên bằng chứng ngăn lỗi phát sinh — Người kiểm tra thực tế yêu cầu ảnh chụp màn hình, kết quả grep, số liệu hiệu suất trước khi cấp ĐẠT
• Thực thi song song giảm thời gian tổng thể — Chạy 4 terminal cùng lúc để hoàn thành trong 2-4 giờ thay vì 6-8 giờ
• Lưu prompt thành mẫu — Tái sử dụng cùng một kích hoạt tác nhân cho kết quả nhất quán giữa các dự án

---

Câu hỏi thường gặp

Tác nhân AI dành cho developer là gì?

Tác nhân AI là trợ lý AI chuyên biệt trong một lĩnh vực. Không như chatbot đa năng, các tác nhân như Kiến trúc sư Backend, Người đánh giá mã có checklist rõ ràng và tạo ra sản phẩm nhất quán.

Làm thế nào để cài các tác nhân từ The Agency?

Clone repo tại github.com/msitarzewski/agency-agents, sau đó copy các file .md vào ~/.claude/agents/ cho Claude Code hoặc dùng script setup cho tool khác.

Tác nhân Reality Checker là gì?

Reality Checker là tác nhân QA dựa trên bằng chứng, từ chối phê duyệt nếu không có bằng chứng. Nó đòi ảnh chụp màn hình, kết quả grep, số liệu hiệu suất trước khi cấp ĐẠT.

Có thể chạy nhiều tác nhân song song không?

Có. Mở nhiều terminal và kích hoạt các tác nhân khác nhau. Chuyển giao sản phẩm bằng cách copy kết quả hoặc dùng MCP memory để tự động chuyển giao.

Chuyển ngữ cảnh giữa các tác nhân thế nào?

Copy kết quả đầu ra của tác nhân này dán vào đầu vào tác nhân kế tiếp. Để tự động, dùng MCP memory để lưu sản phẩm cho tác nhân tiếp theo truy xuất.

Nếu một tác nhân báo CẦN SỬA (NEEDS WORK) thì sao?

Sửa các vấn đề blocking mà tác nhân chỉ ra, rồi chạy lại tác nhân đó. Reality Checker sẽ liệt kê rõ cần sửa gì trước khi cấp ĐẠT.

Có cần cả 5 tác nhân cho mọi dự án không?

Không. Có thể chỉ dùng Kiến trúc sư Backend và Người đánh giá mã cho dự án API. Thêm các tác nhân còn lại tùy quy mô và yêu cầu dự án.