Fullstack Developer Agent (Đại lý Phát triển Fullstack)

Chuyên gia thực thi của bạn - Biến các kế hoạch thành mã nguồn sẵn sàng cho sản xuất.

Đại lý này làm gì

Bạn đã có một kế hoạch triển khai chi tiết cho hệ thống chiến dịch email của mình. Sơ đồ cơ sở dữ liệu đã được thiết kế, các điểm cuối API đã được chỉ định, các thành phần giao diện người dùng đã được phác thảo. Nhưng bây giờ, cần có người thực sự bắt tay vào viết mã.

Vấn đề: Việc triển khai thực tế rất mất thời gian. Viết các API backend, các thành phần frontend, các bản di chuyển cơ sở dữ liệu (migrations), các bài kiểm tra (tests) và tài liệu là một công việc đòi hỏi sự tỉ mỉ. Việc giữ chất lượng mã nguồn cao trong khi vẫn phải di chuyển nhanh là một thách thức lớn. Bạn cần mã nguồn thực sự hoạt động ổn định trên môi trường sản xuất, chứ không chỉ là chạy được ở môi trường phát triển.

Giải pháp: Fullstack Developer Agent thực thi các kế hoạch triển khai với mã nguồn tiêu chuẩn sản xuất. Nó xây dựng các API backend, các thành phần frontend, tích hợp cơ sở dữ liệu và thiết lập cơ sở hạ tầng—tuân thủ nghiêm ngặt các tiêu chuẩn và thực hành tốt nhất của dự án. Bạn sẽ nhận được các tính năng hoạt động thực tế, chứ không chỉ là các bản demo (proof-of-concepts).

Bắt đầu nhanh

Thực hiện một giai đoạn triển khai:

# Sau khi Planner tạo ra các giai đoạn (phases)
/dev "Implement phase 1: database schema and migrations"

Đại lý sẽ đọc tệp giai đoạn, triển khai chính xác những gì được chỉ định, chạy các bài kiểm tra và báo cáo kết quả hoàn thành.

Khả năng

Phát triển Backend

Xây dựng các hệ thống backend mạnh mẽ:

  • APIs: Các điểm cuối RESTful, các trình phân giải (resolvers) GraphQL.
  • Services: Logic nghiệp vụ, xử lý dữ liệu.
  • Database: Truy vấn, di chuyển dữ liệu (migrations), tích hợp ORM.
  • Xác thực: JWT, OAuth, quản lý phiên (sessions).
  • Webhooks: Xác minh chữ ký, xử lý sự kiện.
  • Tác vụ nền: Xử lý hàng đợi, các tác vụ được lên lịch (cron jobs).

Phát triển Frontend

Tạo ra các thành phần giao diện người dùng hiện đại:

  • React/Next.js: Các thành phần, trang, bố cục (layouts).
  • TypeScript: Mã nguồn an toàn về kiểu dữ liệu (type-safe), dễ bảo trì.
  • Forms: Xác thực dữ liệu, gửi biểu mẫu, xử lý lỗi.
  • Quản lý trạng thái: React Query, Zustand, Context API.
  • Styling: Tailwind CSS, thiết kế đáp ứng (responsive).
  • Khả năng tiếp cận: Tuân thủ tiêu chuẩn WCAG AA.

Tích hợp Cơ sở dữ liệu

Xử lý lớp dữ liệu một cách chuyên nghiệp:

  • Thiết kế sơ đồ (Schema): Bảng, mối quan hệ, các ràng buộc (constraints).
  • Migrations: Các kịch bản nâng cấp/hạ cấp (up/down scripts) với khả năng hoàn tác (rollback).
  • Truy vấn: Được tối ưu hóa, lập chỉ mục và kiểm tra kỹ lưỡng.
  • Giao dịch (Transactions): Đảm bảo tính toàn vẹn của dữ liệu.
  • Seeding: Tạo dữ liệu mẫu cho môi trường phát triển và kiểm tra.
  • Connection Pooling: Quản lý tài nguyên kết nối hiệu quả.

Triển khai Kiểm tra (Testing)

Đảm bảo chất lượng mã nguồn:

  • Unit Tests: Kiểm tra các thành phần và hàm đơn lẻ.
  • Integration Tests: Kiểm tra sự phối hợp giữa API và cơ sở dữ liệu.
  • E2E Tests: Xác thực toàn bộ luồng trải nghiệm người dùng.
  • Độ bao phủ (Test Coverage): Đáp ứng các yêu cầu khắt khe của dự án.
  • Kịch bản lỗi: Xác thực khả năng xử lý khi có sự cố xảy ra.

Cơ sở hạ tầng & DevOps

Thiết lập các hệ thống hỗ trợ:

  • Docker: Container hóa và điều phối (composition).
  • CI/CD: GitHub Actions, các quy trình triển khai tự động.
  • Cấu hình môi trường: Quản lý tệp .env và các bí mật (secrets).
  • Giám sát: Ghi nhật ký (logging), theo dõi lỗi.
  • Hiệu suất: Bộ nhớ đệm (caching), tối ưu hóa tài nguyên.

Khi nào nên sử dụng

Sử dụng Fullstack Developer Agent khi bạn cần:

  • Thực hiện các giai đoạn triển khai từ kế hoạch có sẵn.
  • Xây dựng các tính năng mới từ đầu đến cuối (end-to-end).
  • Tái cấu trúc (refactor) mã nguồn hiện có để cải thiện chất lượng.
  • Thêm các bài kiểm tra vào mã nguồn chưa được test.
  • Triển khai di chuyển cơ sở dữ liệu.
  • Thiết lập cơ sở hạ tầng hoặc quy trình CI/CD.
  • Sửa lỗi (bugs) với các giải pháp toàn diện.

Ví dụ quy trình làm việc

Thực hiện một giai đoạn từ kế hoạch

# Planner đã tạo các tệp giai đoạn trong thư mục plans/251229-email-campaign/
/dev "Execute phase-01-database-schema.md"

Nhà phát triển sẽ:

  1. Đọc tệp giai đoạn từ thư mục kế hoạch.
  2. Xác minh quyền sở hữu tệp (chỉ chỉnh sửa các tệp được phân công).
  3. Kiểm tra các phụ thuộc từ các giai đoạn trước đó.
  4. Triển khai từng nhiệm vụ theo thứ tự:
    • Tạo các tệp sơ đồ cơ sở dữ liệu.
    • Viết các kịch bản migration (lên và xuống).
    • Thêm các mô hình (models) và kiểu dữ liệu TypeScript.
    • Tạo dữ liệu mẫu (seed data) cho môi trường phát triển.
  5. Chạy kiểm tra kiểu dữ liệu và các bài kiểm tra.
  6. Sửa bất kỳ lỗi nào phát sinh.
  7. Xác nhận các tiêu chí thành công đã được đáp ứng.
  8. Tạo báo cáo triển khai.

Bạn sẽ nhận được:

## Báo cáo triển khai giai đoạn

### Giai đoạn đã thực hiện
- Giai đoạn: phase-01-database-schema
- Kế hoạch: plans/251229-email-campaign
- Trạng thái: hoàn thành ✅

### Các tệp đã chỉnh sửa
- db/schema/campaigns.ts (thêm 128 dòng)
- db/migrations/001_create_campaigns.sql (thêm 45 dòng)
- db/models/Campaign.ts (thêm 87 dòng)
- db/seed/campaigns.ts (thêm 34 dòng)

### Các nhiệm vụ đã hoàn thành
✅ Thiết kế sơ đồ bảng campaigns
✅ Tạo các kịch bản migration (up/down)
✅ Thêm các kiểu dữ liệu và mô hình TypeScript
✅ Tạo dữ liệu mẫu cho phát triển
✅ Thêm các chỉ mục (indexes) để tối ưu hiệu suất

### Trạng thái kiểm tra
- Kiểm tra kiểu dữ liệu: ✅ Đạt
- Unit tests: ✅ 12/12 đạt (độ bao phủ 100%)
- Integration tests: ✅ 5/5 đạt
- Kiểm tra migration: ✅ Đã xác minh nâng cấp/hoàn tác

### Vấn đề gặp phải
Không có - việc triển khai hoàn tất thành công.

### Các bước tiếp theo
- Giai đoạn 2 có thể bắt đầu (các phụ thuộc đã được thỏa mãn)
- Sơ đồ dữ liệu đã sẵn sàng cho việc triển khai API
- Dữ liệu mẫu đã có sẵn cho quá trình phát triển

Xây dựng một tính năng hoàn chỉnh

/dev "Implement webhook signature verification for Stripe and SePay"

Triển khai bao gồm:

  • Backend: Các điểm cuối xử lý webhook.
  • Tiện ích (Utilities): Logic xác minh chữ ký.
  • Cơ sở dữ liệu: Sơ đồ nhật ký (log) cho webhook.
  • Kiểm tra: Các bài unit test và integration test.
  • Tài liệu: Cập nhật tài liệu API.
  • Xử lý lỗi: Các kịch bản lỗi toàn diện.

Quy tắc sở hữu tệp

QUAN TRỌNG: Nhà phát triển luôn tôn trọng ranh giới của từng giai đoạn:

  • Chỉ chỉnh sửa các tệp được liệt kê trong phần “File Ownership” của tệp giai đoạn.
  • Không bao giờ chạm vào các tệp thuộc sở hữu của các giai đoạn đang chạy song song.
  • Báo cáo xung đột ngay lập tức nếu phát hiện vi phạm quyền sở hữu tệp.
  • Dừng lại ngay nếu quyền sở hữu tệp không rõ ràng.

Điều này giúp ngăn chặn xung đột khi gộp mã (merge conflicts) khi có nhiều giai đoạn được thực hiện cùng lúc.

Quy trình thực hiện

1. Phân tích giai đoạn:

  • Đọc tệp giai đoạn được phân công.
  • Xác minh danh sách quyền sở hữu tệp.
  • Kiểm tra thông tin về các tác vụ song song.
  • Hiểu các chiến lược ngăn ngừa xung đột.

2. Xác thực trước khi triển khai:

  • Xác nhận không có sự chồng chéo tệp với các giai đoạn khác.
  • Đọc tài liệu dự án (codebase-summary.md, code-standards.md).
  • Xác minh các phụ thuộc từ giai đoạn trước đã hoàn thành.
  • Kiểm tra xem tệp đã tồn tại hay cần tạo mới.

3. Triển khai:

  • Thực hiện các bước theo thứ tự trong tệp giai đoạn.
  • CHỈ chỉnh sửa các tệp trong phần “File Ownership”.
  • Tuân thủ chính xác kiến trúc và yêu cầu đề ra.
  • Viết mã nguồn sạch, dễ bảo trì và có tài liệu đi kèm.
  • Thêm các bài kiểm tra cho tất cả các chức năng mới.

4. Đảm bảo chất lượng (QA):

  • Chạy kiểm tra kiểu dữ liệu (npm run typecheck).
  • Chạy các bài kiểm tra (npm test).
  • Sửa các lỗi kiểu dữ liệu hoặc lỗi kiểm tra.
  • Xác nhận tiêu chí thành công của giai đoạn.

5. Báo cáo hoàn thành:

  • Liệt kê các tệp đã chỉnh sửa.
  • Tài liệu hóa các nhiệm vụ đã hoàn thành.
  • Báo cáo trạng thái của các bài kiểm tra.
  • Ghi chú các vấn đề còn tồn đọng (nếu có).
  • Cập nhật trạng thái vào tệp giai đoạn.

Tiêu chuẩn chất lượng mã nguồn

Nhà phát triển tuân thủ:

  • Các nguyên tắc YAGNI, KISS, DRY.
  • Tiêu chuẩn mã nguồn của dự án (trong docs/code-standards.md).
  • An toàn kiểu dữ liệu (chế độ nghiêm ngặt của TypeScript).
  • Xử lý lỗi (try-catch, ghi nhật ký phù hợp).
  • Kiểm tra (unit + integration tests).
  • Tài liệu (các chú thích JSDoc, cập nhật README).
  • Khả năng tiếp cận (WCAG AA khi có thể áp dụng).

An toàn khi thực thi song song

Khi làm việc trên các giai đoạn song song:

  • Làm việc độc lập mà không cần kiểm tra các giai đoạn khác.
  • Tin tưởng vào các phụ thuộc đã được liệt kê là đã hoàn thành.
  • Chỉ sử dụng các giao diện (interfaces) đã được xác định rõ ràng (không kết nối trực tiếp các tệp).
  • Báo cáo hoàn thành để kích hoạt các giai đoạn phụ thuộc tiếp theo.
  • Không bao giờ chỉnh sửa các tệp dùng chung mà không có quyền sở hữu rõ ràng.

Ngăn xếp công nghệ (Tech Stack)

Nhà phát triển thành thạo:

Backend:

  • Node.js, TypeScript
  • NestJS, Fastify, Express
  • PostgreSQL, MongoDB, Redis
  • Prisma, TypeORM, Mongoose

Frontend:

  • React, Next.js 14+
  • TypeScript, TSX
  • Tailwind CSS, shadcn/ui
  • React Query, Zustand

Kiểm tra (Testing):

  • Jest, Vitest
  • React Testing Library
  • Playwright, Cypress

DevOps:

  • Docker, Docker Compose
  • GitHub Actions
  • Cloudflare, Vercel

Các đại lý liên quan

  • Planner - Tạo ra các giai đoạn triển khai.
  • Tester - Xác thực chất lượng triển khai.
  • Database Admin - Tối ưu hóa mã nguồn cơ sở dữ liệu.
  • Git Manager - Thực hiện commit mã nguồn đã triển khai.

Các lệnh liên quan

  • /dev - Thực hiện tác vụ phát triển.
  • /implement - Triển khai một tính năng.

Mẹo

Tuân thủ Kế hoạch: Các tệp giai đoạn quy định chính xác những gì cần xây dựng. Đừng thêm các tính năng thừa hoặc làm sai lệch so với đặc tả. YAGNI (Bạn sẽ không cần đến nó đâu).

Kiểm tra mọi thứ: Hãy viết các bài kiểm tra trong lúc viết mã, chứ không phải sau đó. Nếu một bài kiểm tra khó viết, có lẽ mã nguồn đó cần được tái cấu trúc.

Tôn trọng quyền sở hữu tệp: Trong quá trình thực thi song song, việc chạm vào các tệp ngoài quyền sở hữu của bạn sẽ phá hỏng mọi thứ. Khi nghi ngờ, hãy hỏi.

Kiểm tra phụ thuộc: Trước khi bắt đầu một giai đoạn, hãy xác minh xem tất cả các giai đoạn trước đó mà nó phụ thuộc vào đã thực sự hoàn thành chưa.

Báo cáo trung thực: Nếu bạn gặp bế tắc hoặc không thể hoàn thành việc gì đó, hãy nói rõ trong báo cáo. Đừng đánh dấu hoàn thành cho những nhiệm vụ chưa xong.

Fullstack Developer Agent là “động cơ thực thi” của bạn. Nó không tranh luận hay thiết kế lại—nó tiếp nhận các đặc tả rõ ràng và tạo ra mã nguồn hoạt động tốt, đã được kiểm tra và sẵn sàng cho sản xuất.