Khi nhiều AI cùng code một dự án: Bài toán kinh điển về Merge Conflict

Khi các công cụ AI coding thế hệ mới như Antigravity, Cursor hay Claude Code ngày càng phát triển, thói quen lập trình của nhiều kỹ sư phần mềm đã thay đổi hoàn toàn: Thay vì chỉ mở 1 cửa sổ chat duy nhất, chúng ta thường mở 3 đến 5 tab làm việc song song.

• Một tab giao cho AI viết Database Migrations và ORM schema.
• Một tab bảo AI dựng UI Storefront cho khách hàng.
• Một tab khác yêu cầu viết Dashboard CMS cho quản trị viên.

Thoạt nhìn, tốc độ bàn giao tính năng có vẻ tăng gấp 3 lần. Nhưng thực tế thường rơi vào kịch bản quen thuộc: Xung đột đè code (Merge Conflict) thảm khốc.

AI rất thông minh nhưng lại có thói quen “táy máy”. Khi được giao làm một nút bấm ở trang thanh toán, nó có thể tiện tay sửa luôn một helper function trong thư mục dùng chung, format lại file CSS toàn cục, hoặc đổi tên một thuộc tính trong schema mà không báo trước. Khi gộp các nhánh lại với nhau, bạn phải dành cả buổi tối chỉ để giải quyết hàng trăm dòng conflict hỗn loạn.

Để giải quyết triệt để vấn đề này, chúng ta không thể dựa vào sự may rủi. Thay vào đó, ta cần áp dụng một hệ thống chuẩn mực kết hợp giữa Modular Isolation (Cô lập mô-đun nghiêm ngặt), Contract-First Development (Thiết kế giao thức trước) và Git Branching Strategy.

---

1. Nguyên tắc 1: Phân rã hệ thống theo “Đường biên giới cứng” (Strict Boundaries)

Lý do số một dẫn đến conflict khi nhiều AI code cùng lúc là: hai thực thể cùng sửa đổi một tệp tin trong cùng một thời điểm.

Để ngăn chặn điều này, kiến trúc dự án phải được phân chia thành các Domain Module hoàn toàn độc lập. Mỗi AI Agent chỉ được xem là “chủ sở hữu” của một vùng lãnh thổ nhất định.

project-root/
├── contracts/                  # VÙNG BẤT KHẢ XÂM PHẠM (Chỉ con người cập nhật)
│   ├── types.ts                # TypeScript Interfaces chung
│   └── schemas.ts              # Zod validation schemas
├── src/
│   ├── modules/
│   │   ├── database/           # Agent 1 (Data & Migrations)
│   │   │   └── migrations/
│   │   ├── storefront/         # Agent 2 (Storefront UI)
│   │   │   ├── components/
│   │   │   └── pages/
│   │   └── admin/              # Agent 3 (Admin Portal)
│   │       ├── components/
│   │       └── pages/
│   └── shared/                 # Thư viện dùng chung dạng Read-Only cho Agent
└── .agent/
    └── MEMORY.md               # Sổ cái trạng thái & bàn giao ca

Thiết lập tệp ARCHITECTURE_RULES.md để “xích” hành vi của AI

Mỗi AI Agent khi bắt đầu phiên làm việc cần được nạp một file luật bất thành văn. File này nêu rõ danh sách thư mục được phép và bị cấm chỉnh sửa:

# AGENT DIRECTIVE: BẮT BUỘC TUÂN THỦ PHẠM VI CODE

Bạn là AI phụ trách module: [Storefront UI].

- PHẠM VI CHO PHÉP: Chỉ được tạo mới và chỉnh sửa file trong `src/modules/storefront/`.
- VÙNG CẤM TUYỆT ĐỐI:
  - KHÔNG CHỈNH SỬA bất kỳ file nào trong `contracts/`, `src/modules/database/`, `src/modules/admin/`.
  - KHÔNG TỰ Ý thay đổi tên thuộc tính hoặc interface chung.
- Khi cần dữ liệu mới: Hãy ghi chú vào tệp `.agent/MEMORY.md` để yêu cầu cập nhật contract.

Nhờ có đường biên giới cứng này, xác suất va chạm giữa các agent lập tức giảm đi 90%.

---

2. Nguyên tắc 2: Khóa cứng “Hợp đồng giao tiếp” (Contract-First via TypeScript & Zod)

Thay vì cho các AI code tự do rồi ghép nối sau, quy trình chuẩn Enterprise bắt buộc phải đi theo mô hình Contract-First:

1. Con người (Tech Lead) hoặc AI Data Architect định nghĩa trước toàn bộ Type, Interface và Schema trong thư mục contracts/.
2. Khóa (freeze) phiên bản contract đó.
3. Thả các Agent UI và Agent Logic vào làm việc dựa trên bản hợp đồng này.

Ví dụ về Contract bằng TypeScript & Zod

Một interface chuẩn mực bảo đảm cho cả Agent Database lẫn Agent UI đều hiểu chung một ngôn ngữ:

// contracts/product.ts
import { z } from 'zod';

export const ProductSchema = z.object({
  id: z.string().uuid(),
  sku: z.string().min(3),
  name: z.string().min(1),
  priceInCents: z.number().int().positive(),
  status: z.enum(['draft', 'published', 'archived']),
  createdAt: z.string().datetime(),
});

export type Product = z.infer<typeof ProductSchema>;

// Contract cho API Response
export const GetProductListResponseSchema = z.object({
  items: z.array(ProductSchema),
  total: z.number().int().nonnegative(),
  page: z.number().int().positive(),
});

export type GetProductListResponse = z.infer<typeof GetProductListResponseSchema>;

Khi Agent Storefront dựng giao diện danh sách sản phẩm:

• Nó bắt buộc phải import type Product từ contracts/product.ts.
• Nó không thể tự ý bịa ra trường cost_usd hay is_available vì TypeScript Compiler và linter sẽ ngay lập tức báo lỗi đỏ.
• Nếu thực sự cần thêm tính năng mới, Agent phải đề xuất bản cập nhật hợp đồng (Contract Revision) thay vì tự biên tự diễn.

---

3. Nguyên tắc 3: Chiến lược Git Branching & Quy tắc Code Ownership

Đừng bao giờ để các tab AI commit thẳng vào nhánh main hoặc merge ngang qua lại giữa các nhánh tính năng với nhau.

Mô hình nhánh chuẩn cho Multi-Agent

• Agent Database: chạy trên nhánh feature/agent-db-schema
• Agent Storefront: chạy trên nhánh feature/agent-storefront-ui
• Agent Admin CMS: chạy trên nhánh feature/agent-admin-cms

main ────────●───────────────●─────────────────────● (Merge sạch 100%)
              \             /                     /
feature/db     ●───────────● (Merge 1)           /
                \                               /
feature/store    ●─────────────────────────────● (Rebase main & Merge 2)

Bí quyết merge sạch 100% không conflict:

1. Tuyệt đối không merge chéo: Không gộp feature/agent-storefront-ui vào feature/agent-admin-cms.
2. Kỷ luật Rebase từ main: Định kỳ mỗi 30-60 phút, yêu cầu tab AI chạy:

   git fetch origin
   git rebase origin/main

3. Thứ tự gộp nhánh ưu tiên:
   • Bước 1: Merge nhánh Schema / Database vào main trước.
   • Bước 2: Các nhánh UI rebase code mới nhất từ main về.
   • Bước 3: Merge lần lượt từng nhánh module vào main.

Do mỗi Agent đã bị giới hạn trong thư mục riêng biệt của mình (src/modules/storefront/ vs src/modules/admin/), Git engine sẽ thực hiện Fast-forward / 3-Way Auto-Merge hoàn toàn tự động mà không gặp bất kỳ xung đột nào trên từng dòng code.

---

4. Nguyên tắc 4: Sổ cái điều phối — .agent/MEMORY.md làm “Biên bản bàn giao ca”

Khi làm việc trong môi trường đa tác vụ, việc trao đổi ngữ cảnh giữa các Agent là chìa khóa then chốt. Thư mục .agent/ với file MEMORY.md đóng vai trò như một Shared Blackboard (Bảng tin chung) hoặc Sổ bàn giao ca.

Mỗi khi một Agent hoàn thành một phần việc hoặc tạo ra component mới, nó phải ghi nhận lại:

# MULTI-AGENT STATE & HANDOVER LOG

## [2026-11-04 10:30] - Agent 1 (Database)

- Đã hoàn thành: Tạo migration bảng `products` và file type `contracts/product.ts`.
- File đã tạo: `supabase/migrations/20261104_init_products.sql`.
- Lưu ý cho các Agent khác: Đã mở cổng API query theo `sku` và `id`.

## [2026-11-04 10:45] - Agent 2 (Storefront UI)

- Trạng thái: Đã đọc contract `Product`.
- File đang làm việc: `src/modules/storefront/components/ProductCard.tsx`.
- Cần hỗ trợ: Cần thêm trường `thumbnail_url` trong phiên bản contract tiếp theo.

Trước khi bất kỳ tab AI nào bắt đầu sinh code, quy trình chuẩn là yêu cầu nó đọc tệp MEMORY.md. Điều này giúp Agent mới không phát minh lại bánh xe, không đặt trùng tên component và nắm rõ tiến độ tổng thể của toàn dự án.

---

Bảng so sánh: Tự do theo cảm tính vs. Kiến trúc Modular Isolation

Tiêu chí	Tiếp cận Ad-hoc (Tự do)	Kiến trúc Modular Isolation
Phân quyền thư mục	AI sửa bất kỳ file nào nó thích	Biên giới cứng theo Domain Module
Giao thức dữ liệu	AI tự định nghĩa type trong từng component	Contract-First bằng TypeScript & Zod
Chiến lược Git	Commit lộn xộn, merge chéo nhánh	Feature branch riêng biệt, rebase từ main
Nguy cơ Conflict	Rất cao (80% - 100%), tốn giờ sửa lỗi	Tiệm cận 0%, Git auto-merge mượt mà
Khả năng mở rộng	Giới hạn 1 - 2 tab chat	Mở rộng 5 - 10 Agent làm việc đồng thời

---

---