Agent Brainstormer

Agent brainstormer là cố vấn kỹ thuật và kiến trúc sư giải pháp của bạn, người khám phá nhiều phương pháp, thách thức các giả định, đặt câu hỏi về các yêu cầu và cung cấp các đánh giá trung thực một cách thẳng thắn trước khi bất kỳ dòng mã nào được viết.

Brainstormer làm gì

  • Khám phá nhiều phương pháp kỹ thuật với phân tích ưu/nhược điểm chi tiết
  • Thách thức các giả định và đặt câu hỏi về các yêu cầu không rõ ràng
  • Cung cấp các đánh giá trung thực về khả năng thực thi của việc triển khai
  • Đánh giá sự đánh đổi giữa các giải pháp cạnh tranh
  • Xem xét các tác động UX/DX của các quyết định kiến trúc
  • Xác định nợ kỹ thuật và các vấn đề bảo trì
  • Áp dụng các nguyên tắc YAGNI, KISS và DRY vào thiết kế giải pháp

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

Sử dụng brainstormer khi:

  • Đánh giá nhiều phương pháp kiến trúc trước khi cam kết thực hiện
  • Thảo luận về các quyết định kỹ thuật với các sự đánh đổi cạnh tranh
  • Thách thức các giả định hiện có về các yêu cầu
  • Giải quyết các vấn đề phức tạp đòi hỏi các giải pháp sáng tạo
  • Đánh giá tính khả thi của các yêu cầu tính năng đầy tham vọng
  • Lập kế hoạch cho các nỗ lực tái cấu trúc (refactoring) lớn
  • Thiết kế kiến trúc hệ thống cho các tính năng mới
  • Cần một “ý kiến thứ hai” về hướng đi kỹ thuật

Ví dụ nhanh

# Thảo luận các phương pháp cho một tính năng
/brainstorm [nên sử dụng REST API hay GraphQL cho ứng dụng di động của chúng ta?]

Điều gì xảy ra:

  1. Brainstormer phân tích cả hai phương pháp một cách thấu đáo
  2. Brainstormer đánh giá ưu/nhược điểm cho bối cảnh cụ thể của bạn
  3. Brainstormer thách thức các giả định về các yêu cầu
  4. Kết quả: Phân tích toàn diện kèm theo đề xuất

Cách thức hoạt động

Bước 1: Phân tích yêu cầu

Brainstormer bắt đầu bằng cách đặt câu hỏi và làm rõ:

Yêu cầu người dùng: "Thêm bộ nhớ đệm để cải thiện hiệu suất"
    ↓
Câu hỏi của Brainstormer:
- Chúng ta đang giải quyết vấn đề hiệu suất nào?
- Nút thắt cổ chai ở đâu? (Cơ sở dữ liệu, API, frontend?)
- Thời gian phản hồi hiện tại là bao nhiêu?
- Thời gian phản hồi chấp nhận được là bao nhiêu?
- Dữ liệu thay đổi thường xuyên như thế nào?
- Chúng ta đang phục vụ bao nhiêu người dùng?

Điều này đảm bảo các giải pháp giải quyết các vấn đề thực tế, không phải những vấn đề tưởng tượng.

Bước 2: Khám phá phương pháp

Brainstormer khám phá nhiều phương pháp hợp lệ:

Vấn đề: "Phản hồi API chậm"
    ↓
Phương pháp A: Bộ nhớ đệm trong bộ nhớ (Redis)
Phương pháp B: Tối ưu hóa truy vấn cơ sở dữ liệu
Phương pháp C: CDN cho nội dung tĩnh
Phương pháp D: Bộ nhớ đệm phản hồi (HTTP)
Phương pháp E: Không làm gì cả (Đo lường trước)

Bước 3: Phân tích sự đánh đổi

Đối với mỗi phương pháp, brainstormer đánh giá:

  • Độ phức tạp triển khai: Thời gian và nỗ lực cần thiết
  • Gánh nặng bảo trì: Chi phí duy trì lâu dài
  • Tác động hiệu suất: Cải thiện tốc độ thực tế
  • Hệ lụy chi phí: Chi phí cơ sở hạ tầng và vận hành
  • Nợ kỹ thuật: Tính linh hoạt và tái cấu trúc trong tương lai
  • Tác động UX/DX: Thay đổi trải nghiệm người dùng và nhà phát triển
  • Đánh giá rủi ro: Những gì có thể sai sót

Bước 4: Sự trung thực thẳng thắn

Brainstormer cung cấp đánh giá không bộ lọc:

✅ “Đây là quá kỹ thuật (overengineering). Hãy bắt đầu với các chỉ mục cơ sở dữ liệu trước.” ⚠️ “Điều này sẽ hoạt động nhưng tạo ra sự phụ thuộc chặt chẽ (tight coupling). Hãy xem xét rủi ro này.” ❌ “Phương pháp này sẽ gây ra nhiều vấn đề hơn là giải quyết chúng.” 💡 “Bạn đã xem xét giải pháp thay thế đơn giản hơn này chưa?”

Công cụ & Khả năng

Brainstormer có quyền truy cập vào:

  • Agent Planner: Tham khảo chi tiết triển khai
  • Agent Docs-Manager: Xem xét tài liệu kiến trúc hiện tại
  • WebSearch: Nghiên cứu các mô hình kiến trúc và nghiên cứu điển hình
  • Kỹ năng docs-seeker: Tìm kiếm tài liệu công nghệ liên quan
  • Kỹ năng gemini-vision: Phân tích sơ đồ kiến trúc
  • psql: Truy vấn cơ sở dữ liệu để phân tích trạng thái hiện tại
  • Kỹ năng sequential-thinking: Chia nhỏ các vấn đề phức tạp một cách hệ thống
  • repomix: Hiểu toàn bộ bối cảnh mã nguồn
  • Agent Scout: Định vị các tệp liên quan trong mã nguồn

Định dạng đầu ra

Brainstormer tạo các báo cáo tóm tắt bằng markdown toàn diện với cấu trúc rõ ràng.

Ví dụ đầu ra:

# Phiên thảo luận: Quyết định kiến trúc API

**Câu hỏi**: Nên sử dụng REST API hay GraphQL cho ứng dụng di động của chúng ta?

**Bối cảnh**: Xây dựng ứng dụng di động iOS/Android hiển thị hồ sơ người dùng, bài đăng, bình luận và thông báo. Backend là Node.js + PostgreSQL. Nhóm có kinh nghiệm REST, chưa có kinh nghiệm GraphQL.

---

## Các giả định bị thách thức

Trước khi đi sâu vào các giải pháp, hãy đặt câu hỏi về tiền đề:

❓ **Giả định**: "Chúng ta cần chọn một cái"
**Thực tế**: Bạn có thể sử dụng cả hai. Bắt đầu với REST, thêm GraphQL cho các trường hợp sử dụng cụ thể sau.

❓ **Giả định**: "GraphQL luôn tốt hơn cho di động"
**Thực tế**: GraphQL thêm độ phức tạp. REST có thể tuyệt vời cho di động với thiết kế API phù hợp.

❓ **Giả định**: "Hiệu suất là mối quan tâm chính"
**Thực tế**: Năng suất của nhà phát triển và việc bảo trì có thể quan trọng hơn ở giai đoạn này.

---

## Phương pháp A: REST API (Được khuyến nghị)

### Mô tả
API RESTful truyền thống với các điểm cuối được đánh số phiên bản, phản hồi JSON và các phương thức HTTP tiêu chuẩn.

### Ưu điểm
✅ **Kiến thức nhóm**: Nhóm của bạn đã biết rõ về REST
✅ **Công cụ**: Hệ sinh thái trưởng thành (Swagger, Postman, v.v.)
✅ **Sự đơn giản**: Mô hình yêu cầu/phản hồi trực tiếp
✅ **Bộ nhớ đệm**: Bộ nhớ đệm HTTP tích hợp, thân thiện với CDN
✅ **Giám sát**: Các công cụ APM tiêu chuẩn hoạt động ngay lập tức
✅ **Bắt đầu nhanh**: Có thể xuất xưởng MVP trong 1-2 tuần

### Nhược điểm
❌ **Lấy dư dữ liệu (Over-fetching)**: Ứng dụng di động nhận được nhiều dữ liệu hơn mức cần thiết
❌ **Nhiều yêu cầu**: Cần các cuộc gọi riêng biệt cho dữ liệu liên quan
❌ **Phiên bản**: Việc đánh số phiên bản API có thể trở nên phức tạp
❌ **Tính linh hoạt**: Thay đổi yêu cầu có nghĩa là thay đổi API

### Độ phức tạp triển khai
**Thấp** - 2-3 ngày cho nhóm giàu kinh nghiệm

### Gánh nặng bảo trì
**Thấp-Trung bình** - Việc đánh số phiên bản có thể trở thành gánh nặng khi API phát triển

### Tốt nhất cho
- Nhóm có kinh nghiệm GraphQL hạn chế
- Các MVP yêu cầu phân phối nhanh
- API công khai được sử dụng bởi nhiều khách hàng
- Các hệ thống yêu cầu bộ nhớ đệm rộng rãi

---

## Phương pháp B: GraphQL API

### Mô tả
Điểm cuối duy nhất với ngôn ngữ truy vấn GraphQL cho phép khách hàng yêu cầu chính xác dữ liệu họ cần.

### Ưu điểm
✅ **Dữ liệu chính xác**: Ứng dụng di động chỉ yêu cầu những gì nó cần
✅ **Yêu cầu duy nhất**: Lấy dữ liệu liên quan trong một truy vấn
✅ **Tự kiểm tra (Introspection)**: Tài liệu API được tạo tự động
✅ **An toàn kiểu**: Kiểu dữ liệu mạnh giúp ngăn ngừa lỗi
✅ **Trải nghiệm nhà phát triển**: Sân chơi (Playground) để khám phá API

### Nhược điểm
❌ **Đường cong học tập**: Nhóm cần học GraphQL
❌ **Độ phức tạp**: Yêu cầu bộ giải (resolvers), thiết kế lược đồ, xử lý truy vấn N+1
❌ **Bộ nhớ đệm**: Bộ nhớ đệm HTTP không hoạt động, cần giải pháp tùy chỉnh
❌ **Giám sát**: Khó giám sát và gỡ lỗi hơn
❌ **Hiệu suất**: Dễ dàng viết các truy vấn tốn kém
❌ **Thời gian triển khai**: 3-4 tuần để nhóm học và triển khai

### Độ phức tạp triển khai
**Cao** - 3-4 tuần cho nhóm chưa có kinh nghiệm

### Gánh nặng bảo trì
**Trung bình** - Cần quản lý lược đồ, bộ giải và tối ưu hóa truy vấn

### Tốt nhất cho
- Nhóm có kinh nghiệm GraphQL
- Các mối quan hệ dữ liệu phức tạp và phân cấp sâu
- Thay đổi giao diện người dùng thường xuyên yêu cầu tính linh hoạt của API
- API nội bộ với các khách hàng được kiểm soát

---

## Phương pháp C: Hỗn hợp (Thực dụng)

### Mô tả
Bắt đầu với REST API cho các điểm cuối đơn giản, thêm GraphQL cho việc lấy dữ liệu phức tạp sau.

### Triển khai

Giai đoạn 1 (Tuần 1-2): REST API

  • POST /auth/login
  • GET /users/
  • GET /posts
  • GET /posts/

Giai đoạn 2 (Tuần 3-4): Thêm GraphQL cho các truy vấn phức tạp

  • Nguồn cấp dữ liệu người dùng với bài đăng, bình luận, lượt thích (truy vấn duy nhất)
  • Tìm kiếm trên nhiều thực thể
  • Đăng ký thời gian thực (Subscriptions)

### Ưu điểm
✅ **Áp dụng dần dần**: Học GraphQL từng bước
✅ **Giảm thiểu rủi ro**: Chuyển hướng sang REST nếu có vấn đề với GraphQL
✅ **Tính linh hoạt**: Sử dụng đúng công cụ cho từng trường hợp sử dụng
✅ **Phát triển nhóm**: Nâng cao kỹ năng cho nhóm theo thời gian

### Nhược điểm
❌ **Độ phức tạp**: Duy trì hai phong cách API
❌ **Sự không nhất quán**: Khách hàng cần biết cái nào để sử dụng
❌ **Tài liệu**: Cần ghi lại cả hai phương pháp

---

## Đánh giá trung thực thẳng thắn

### Sự thật về tình huống của bạn

🎯 **Điều quan trọng nhất**: Xuất xưởng ứng dụng di động trong 6 tuần

⚠️ **Rủi ro thực tế**: Nhóm học GraphQL trong khi xây dựng MVP sẽ gây ra sự chậm trễ

💡 **Tùy chọn bị bỏ qua**: Thiết kế REST API tốt giải quyết 90% mối quan tâm của bạn

🔍 **Giả định tiềm ẩn**: Bạn nghĩ GraphQL là cần thiết vì các công ty công nghệ lớn sử dụng nó. Họ cũng có hơn 100 kỹ sư và các ràng buộc khác nhau.

### Cái bẫy của việc quá kỹ thuật (Over-Engineering)

GraphQL mạnh mẽ nhưng có thể là quá mức nếu:
- Bạn có < 5 loại khách hàng API khác nhau
- Các mối quan hệ dữ liệu không được phân cấp sâu
- Nhóm có kinh nghiệm GraphQL hạn chế
- Thời hạn MVP eo hẹp

### Tôi sẽ làm gì?

Nếu đây là dự án của tôi:

1. **Tuần 1-2**: Xây dựng REST API với thiết kế tốt
   - Sử dụng phân trang (`limit`, `offset`)
   - Hỗ trợ lọc trường (`?fields=id,name,email`)
   - Cho phép nhúng (`?embed=posts,comments`)
   - Triển khai các tiêu đề bộ nhớ đệm phù hợp

2. **Tuần 3-4**: Xây dựng ứng dụng di động dựa trên REST API
   - Đo lường hiệu suất API thực tế
   - Xác định các điểm đau (pain points) thực tế
   - Ghi lại những gì chậm hoặc bất tiện

3. **Tuần 5-6**: Tối ưu hóa dựa trên dữ liệu
   - Nếu việc lấy dư dữ liệu là vấn đề thực tế, hãy thêm GraphQL
   - Nếu không, hãy cải thiện REST với những bài học kinh nghiệm

---

## Đề xuất

### Cho bối cảnh của bạn

**Hãy chọn REST API** vì những lý do sau:

1. ⏰ **Áp lực thời gian**: Thời hạn 6 tuần ủng hộ công nghệ đã biết
2. 👥 **Kinh nghiệm nhóm**: Tận dụng chuyên môn REST hiện có
3. 📱 **Trường hợp sử dụng di động**: Không đủ phức tạp để biện minh cho đường cong học tập GraphQL
4. 🎯 **Mục tiêu MVP**: Đưa ra thị trường nhanh chóng, tối ưu hóa sau

### Tiêu chí thành công

REST API sẽ thành công nếu:
- Thời gian phản hồi < 200ms cho phân vị thứ 95
- Ứng dụng di động thực hiện < 5 cuộc gọi API mỗi màn hình
- Việc lấy dư dữ liệu chiếm < 30% tải trọng phản hồi
- Tốc độ phát triển vẫn duy trì ở mức cao

Nếu các tiêu chí này không được đáp ứng sau khi khởi chạy MVP, thì hãy xem xét lại GraphQL.

### Lộ trình di chuyển

Nếu bạn cần GraphQL sau này:

```typescript
// Bạn có thể thêm GraphQL bên cạnh REST
app.use('/api/v1', restRoutes);      // Giữ REST hiện tại
app.use('/graphql', graphqlRouter);   // Thêm GraphQL

Không cần phải viết lại mọi thứ. Cải tiến dần dần.

Các nguyên tắc cốt lõi được áp dụng

YAGNI (Bạn sẽ không cần nó đâu)

Đừng thêm độ phức tạp của GraphQL cho đến khi bạn có bằng chứng cụ thể rằng bạn cần nó.

KISS (Giữ cho nó đơn giản)

REST đơn giản hơn cho nhóm của bạn lúc này. Đơn giản thì xuất xưởng nhanh hơn.

DRY (Đừng lặp lại chính mình)

Cả hai phương pháp đều có thể là DRY. Đây không phải là yếu tố quyết định.

Câu hỏi mở cho bạn

Trước khi hoàn tất quyết định:

  1. Yêu cầu hiệu suất thực tế của bạn là gì? (ví dụ: “phân vị thứ 95 < 200ms”)
  2. Mức độ lấy dư dữ liệu nào là chấp nhận được? (ví dụ: “lãng phí 30% là ổn”)
  3. Nhóm có sẵn sàng trì hoãn MVP để học GraphQL một cách bài bản không?
  4. Bạn có ngân sách cho các công cụ và giám sát GraphQL không?
  5. Kế hoạch của bạn là gì nếu các vấn đề về hiệu suất GraphQL phát sinh?

Các bước tiếp theo

Đường dẫn được khuyến nghị:

  1. Chấp nhận quyết định REST ✅
  2. Chạy: /plan [xây dựng REST API cho ứng dụng di động]
  3. Thiết kế các điểm cuối với các thực hành tốt (phân trang, lọc, nhúng)
  4. Đo lường các mẫu sử dụng API sau khi ra mắt
  5. Xem xét lại quyết định GraphQL với dữ liệu thực tế sau 3 tháng

Đường dẫn thay thế (nếu bạn khăng khăng muốn GraphQL):

  1. Phân bổ 1 tuần để đào tạo GraphQL cho nhóm
  2. Xây dựng nguyên mẫu đơn giản với Apollo Server
  3. Đánh giá độ phức tạp trước khi cam kết triển khai đầy đủ
  4. Kéo dài thời gian thêm 2-3 tuần để tính đến đường cong học tập

Độ tin cậy của tôi: Cao (các dự án tương tự, có kinh nghiệm với cả hai phương pháp) Rủi ro chính: Đánh giá thấp đường cong học tập GraphQL Yếu tố thành công: Chọn dựa trên các ràng buộc (thời gian, nhóm, độ phức tạp), không phải sự thổi phồng (hype)


## Thực hành tốt nhất

✅ **Nên**:
- Trình bày các ràng buộc cụ thể (mốc thời gian, ngân sách, kỹ năng của nhóm)
- Sẵn sàng thách thức các giả định của bạn
- Xem xét chi phí bảo trì, không chỉ việc triển khai
- Suy nghĩ về khả năng của nhóm và đường cong học tập
- Hỏi "chúng ta có thực sự cần độ phức tạp này không?"

❌ **Không nên**:
- Bắt đầu bằng "Tôi đã quyết định rồi, chỉ cần xác nhận nó thôi"
- Bỏ qua đánh giá trung thực thẳng thắn
- Bỏ qua phần "câu hỏi mở"
- Chọn các giải pháp dựa trên sự thổi phồng hoặc xu hướng
- Từ bỏ các giải pháp thay thế đơn giản hơn một cách sớm hơn

## Các vấn đề thường gặp

### Vấn đề: Phòng thủ về các ý tưởng hiện có

**Vấn đề**: Trở nên phòng thủ khi brainstormer thách thức phương pháp của bạn

**Giải pháp**:
Hãy nhớ vai trò của brainstormer là cứu bạn khỏi những sai lầm tốn kém. Thách thức các ý tưởng sớm sẽ rẻ hơn so với việc sửa chữa các quyết định sai lầm sau này.

### Vấn đề: Tê liệt phân tích

**Vấn đề**: Quá nhiều lựa chọn, không thể quyết định

**Giải pháp**:
- Tập trung vào phần "đề xuất"
- Sử dụng "tiêu chí thành công" để hướng dẫn quyết định
- Bắt đầu với phương pháp đơn giản nhất
- Lập kế hoạch lộ trình di chuyển nếu bạn cần thay đổi sau này

### Vấn đề: Bỏ qua nguyên tắc YAGNI

**Vấn đề**: Muốn xây dựng giải pháp phức tạp "để phòng hờ"

**Giải pháp**:
Brainstormer sẽ gọi tên điều này. Hãy tin tưởng vào đánh giá YAGNI. Hãy xây dựng những gì bạn cần bây giờ, không phải những gì bạn có thể cần vào một ngày nào đó.

## Liên quan

- [Agent Planner](/vi/docs/engineer/agents/planner) - Tạo các kế hoạch triển khai chi tiết sau khi phương pháp được quyết định
- [Agent Researcher](/vi/docs/engineer/agents/researcher) - Cung cấp dữ liệu cho các quyết định thảo luận
- [Agent Docs-Manager](/vi/docs/engineer/agents/docs-manager) - Duy trì các hồ sơ quyết định kiến trúc
- [Lệnh /brainstorm](/vi/docs/engineer/commands/core/brainstorm) - Kích hoạt phiên thảo luận

---

**Tiếp theo**: Khi phương pháp đã được quyết định, hãy sử dụng [agent planner](/vi/docs/engineer/agents/planner) để tạo kế hoạch triển khai

**Hãy nhớ**: Brainstormer không triển khai bất cứ thứ gì. Nó chỉ tư vấn, thách thức và đề xuất. Việc triển khai diễn ra sau khi bạn đã đưa ra các quyết định sáng suốt.