brainstorming

Tổng quan

Kỹ năng brainstorming làm gì

Kỹ năng brainstorming áp dụng một nguyên tắc rõ ràng: thiết kế và đặc tả đi trước, triển khai đi sau. Khi được bật, brainstorming hướng dẫn bạn khai thác ý định người dùng, yêu cầu và thiết kế cấp cao trước khi viết code, tạo scaffolding cho project, hoặc gọi bất kỳ kỹ năng triển khai nào.

Kỹ năng này được xây dựng xung quanh đối thoại cộng tác. Bạn bắt đầu từ một ý tưởng thô, làm rõ bối cảnh và ràng buộc thông qua các câu hỏi có chủ đích, rồi hội tụ về một bản thiết kế và bản spec cụ thể để người dùng xem, góp ý và phê duyệt. Chỉ sau khi vượt qua “cổng” phê duyệt này, bạn mới nên chuyển sang giai đoạn build hoặc refactor.

Đối tượng nên dùng brainstorming

Hãy dùng kỹ năng brainstorming nếu bạn:

• Làm việc với Claude hoặc các agent tương tự về tính năng sản phẩm, component, luồng UI, hoặc thay đổi kiến trúc
• Muốn tránh anti‑pattern “việc này đơn giản quá, không cần thiết kế đâu”
• Cần các cuộc trao đổi thiết kế có tính lặp lại, có thể audit, trước khi đổi code
• Thường xuyên xây dựng hoặc chỉnh sửa frontend, UI/UX, hoặc các hệ thống nặng về workflow

Kỹ năng này phù hợp với dev làm việc một mình, product engineer, designer, và các team muốn có quy trình “design‑first” nhẹ nhàng nhưng nhất quán.

Những vấn đề kỹ năng này giải quyết

Kỹ năng brainstorming được thiết kế để ngăn chặn:

• Lao thẳng vào viết code mà chưa làm rõ mục tiêu
• Các giả định ẩn chỉ lộ ra muộn trong quá trình triển khai
• Thay đổi UI/UX được build mà không có user journey hoặc định hướng visual rõ ràng
• Spec quá mơ hồ nên không thể lập kế hoạch hoặc giao việc đáng tin cậy

Bằng cách ép phải có một checkpoint thiết kế, brainstorming giúp giảm rework, triển khai lệch hướng và “nợ thiết kế”.

Khi nào brainstorming phù hợp (hoặc không phù hợp)

Rất phù hợp khi:

• Bạn đang lên kế hoạch cho tính năng mới, thay đổi hành vi, hoặc thiết kế luồng UI/UX
• Bạn muốn một template có cấu trúc cho việc lên ý tưởng, thu thập bối cảnh và phê duyệt thiết kế
• Bạn được lợi từ mockup/diagram trực quan khi cân nhắc các phương án

Kém phù hợp khi:

• Bạn chỉ làm các chỉnh sửa cơ học (sửa typo, đổi tên biến, cập nhật constant mà không đổi hành vi)
• Bạn đã có spec chi tiết và được phê duyệt, và giờ chỉ việc thực thi (trong trường hợp đó, bạn nên dùng các kỹ năng tập trung vào triển khai)

Ngay cả các tác vụ tưởng như nhỏ nhặt như chỉnh một config hay viết một utility một hàm cũng có thể hưởng lợi từ một lượt thiết kế nhanh; nhưng bạn có thể giữ lượt đó rất ngắn trong khi vẫn dùng quy trình brainstorming.

Cách sử dụng

Cài đặt và thiết lập

1. Cài kỹ năng brainstorming

Dùng skills CLI để thêm kỹ năng brainstorming từ repository obra/superpowers:

npx skills add https://github.com/obra/superpowers --skill brainstorming

Lệnh này sẽ tải về định nghĩa skill cùng các prompt hỗ trợ và script helper tùy chọn dưới thư mục skills/brainstorming.

2. Khám phá các file chính

Sau khi cài đặt, hãy xem qua các file sau để hiểu workflow và các helper sẵn có:

• SKILL.md – Mô tả cốt lõi về quy trình brainstorming, bao gồm cổng bắt buộc thiết kế‑trước‑khi‑viết‑code và checklist các bước cần thiết.
• spec-document-reviewer-prompt.md – Prompt template cho subagent review spec, dùng để kiểm tra mức độ đầy đủ, nhất quán và rõ ràng của spec.
• visual-companion.md – Hướng dẫn dùng visual companion chạy trên trình duyệt để hiển thị mockup, diagram và các phương án visual.
• scripts/frame-template.html – Template HTML frame mà visual companion dùng để tạo layout tập trung vào UI.
• scripts/helper.js – Helper phía client để xử lý sự kiện chọn và live reload trong visual companion.
• scripts/server.cjs, scripts/start-server.sh, scripts/stop-server.sh – Các script chạy và quản lý server cho visual companion.

Bạn không cần chỉnh sửa các file này để bắt đầu sử dụng workflow brainstorming, nhưng việc biết chúng có gì sẽ giúp bạn dễ tích hợp vào setup riêng.

Quy trình brainstorming cốt lõi

1. Bắt đầu từ bối cảnh project

Mở đầu bất kỳ session brainstorming nào bằng cách định hình xung quanh project hiện tại. Checklist trong SKILL.md nhấn mạnh:

• Xem các file và tài liệu liên quan
• Lướt qua các commit gần đây để lấy bối cảnh
• Xác định phần nào của hệ thống sẽ bị ảnh hưởng

Khi dùng Claude hoặc agent khác, hãy nhắc agent tìm hiểu bối cảnh project trước thay vì yêu cầu đổi code ngay.

2. Đề xuất dùng visual companion cho các câu hỏi mang tính visual

Nếu task có yếu tố UI/UX hoặc các chủ đề mang tính hình ảnh, hãy đề xuất dùng visual companion như một bước riêng. Quy tắc trong visual-companion.md là:

Quyết định theo từng câu hỏi, không phải theo cả session. Hãy hỏi: người dùng sẽ hiểu cái này tốt hơn khi nhìn thấy hay khi đọc?

Dùng visual companion trên trình duyệt cho:

• Mockup UI và các phương án layout
• Diagram kiến trúc và luồng
• So sánh song song các hướng thiết kế
• Thảo luận về khoảng cách, phân cấp, độ “trau chuốt” về visual

Ở lại trong terminal (chỉ văn bản) cho:

• Phạm vi, yêu cầu và định nghĩa các khái niệm
• Cân nhắc về tradeoff khái niệm và lựa chọn mô hình API/data
• Các câu hỏi làm rõ mà câu trả lời là chữ, không phải hình

3. Hỏi các câu hỏi làm rõ từng bước một

Kỹ năng brainstorming kỳ vọng một cuộc đối thoại có kỷ luật, không phải một mega‑prompt duy nhất. Hãy dùng chuỗi câu hỏi tập trung, ví dụ:

• "Who are the primary users of this feature?"
• "What constraints do we have on performance or deployment?"
• "Which platforms and screen sizes matter most?"

Hỏi từng câu một, chờ câu trả lời, rồi dần dần tinh chỉnh hiểu biết của bạn.

4. Tạo ra thiết kế và spec cụ thể

Khi đã có đủ bối cảnh, hãy tổng hợp thành một bản thiết kế mà người dùng có thể thực sự phê duyệt. Tùy task, phần này có thể gồm:

• Mục tiêu cấp cao và tiêu chí thành công
• User story hoặc ví dụ luồng sử dụng
• Mô tả layout UI và định hướng visual (có thể có visual companion hỗ trợ)
• Cấu trúc dữ liệu, interface hoặc điểm tích hợp
• Các yêu cầu phi chức năng ảnh hưởng đến triển khai

Viết tất cả thành một tài liệu spec có cấu trúc tại vị trí bạn ưa thích (ví dụ, dưới docs/superpowers/specs/ nếu bạn theo convention của repo).

5. Thực thi “cổng” thiết kế bắt buộc

Một quy tắc then chốt trong SKILL.md là cổng cứng:

Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it.

Quy tắc này áp dụng ngay cả khi công việc có vẻ đơn giản. Thiết kế có thể chỉ vài câu với một thay đổi nhỏ, nhưng nó vẫn phải tồn tại và được xác nhận rõ ràng trước khi tiến bước.

Sử dụng template review tài liệu spec

1. Soạn bản spec

Sau khi brainstorming, hãy soạn spec theo cấu trúc phù hợp với project của bạn. Lưu nó vào một đường dẫn dễ tham chiếu, ví dụ:

docs/superpowers/specs/my-feature-spec.md

2. Gọi subagent review spec

Khi spec sẵn sàng để được kiểm tra, hãy dùng spec-document-reviewer-prompt.md như template để khởi tạo một subagent chuyên review spec. Thay [SPEC_FILE_PATH] trong prompt bằng đường dẫn đến file spec của bạn.

Reviewer này sẽ:

• Kiểm tra các mục còn thiếu, các TODO hoặc chỗ “TBD”
• Tìm các mâu thuẫn và yêu cầu không nhất quán
• Đánh dấu các yêu cầu mơ hồ có thể dẫn đến triển khai sai
• Đảm bảo phạm vi đủ hẹp để lập một kế hoạch mạch lạc duy nhất

Kết quả review sẽ có trạng thái Approved | Issues Found và danh sách issue, mỗi issue gắn với lý do tại sao nó quan trọng cho việc lập kế hoạch triển khai.

3. Lặp lại cho đến khi được phê duyệt

Nếu reviewer phát hiện vấn đề, hãy cập nhật spec và chạy review lại. Khi spec được phê duyệt, bạn đã có nền tảng vững chắc cho các kỹ năng triển khai và công cụ lập kế hoạch.

Sử dụng visual brainstorming companion

1. Khởi động server cho visual companion

Từ thư mục scripts, bạn có thể khởi chạy brainstorm server bằng:

./start-server.sh --project-dir /path/to/your/project

Một số tùy chọn hữu ích:

• --project-dir <path> – Lưu file session dưới <path>/.superpowers/brainstorm/ thay vì /tmp để giữ lại lâu dài.
• --host <bind-host> – Bind vào một interface cụ thể (ví dụ 0.0.0.0 trong container hoặc môi trường remote).
• --url-host <display-host> – Kiểm soát hostname hiển thị trong JSON URL trả về.
• --foreground hoặc --background – Chọn để server chạy trong terminal hiện tại hoặc như một process nền.

Khi khởi động, script sẽ in ra JSON chứa URL của session. Mở URL đó trong trình duyệt để truy cập khung brainstorming dạng visual.

2. Render các phương án visual

Server theo dõi một thư mục chứa file HTML và luôn serve file mới nhất. Pattern điển hình:

1. Claude (hoặc agent của bạn) ghi một file HTML vào screen_dir đã cấu hình, dùng frame-template.html làm nền.
2. Trình duyệt tự động reload qua helper.js khi có file mới được tạo.
3. Người dùng có thể click các option hoặc card trong UI, và các sự kiện đó được gửi ngược qua WebSocket cho agent xử lý.

Cách này giúp bạn dễ dàng hiển thị:

• Nhiều phương án layout dưới dạng card có thể click
• Diagram luồng và state machine
• So sánh visual về màu sắc, khoảng cách hoặc các biến thể component

3. Dừng server khi xong việc

Khi session kết thúc, hãy dừng brainstorm server một cách sạch sẽ bằng:

./stop-server.sh <session_dir>

Với các session dưới /tmp, lệnh này cũng dọn dẹp file sinh ra. Các thư mục persistent dưới .superpowers/ được giữ lại để bạn có thể xem lại mockup và diagram sau này.

Tích hợp brainstorming vào workflow riêng của bạn

• Như một bước chuẩn trước khi commit: Yêu cầu phải có một lượt brainstorming và spec đã được phê duyệt trước khi merge feature branch.
• Kết hợp với các kỹ năng khác: Chạy brainstorming trước, ghi lại spec, sau đó bàn giao cho các kỹ năng triển khai, refactor hoặc test.
• Cho công việc UI/UX: Kết hợp brainstorming dạng hội thoại với visual companion để kiểm chứng layout và ý tưởng tương tác trước khi viết bất kỳ CSS hoặc code component nào.

Hãy điều chỉnh đường dẫn thư mục, cách đặt tên và format spec sao cho phù hợp với repo hiện có, nhưng vẫn giữ pattern cốt lõi: bối cảnh → câu hỏi → thiết kế/spec → review → triển khai.

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

Kỹ năng brainstorming chỉ dành cho project lớn, phức tạp thôi sao?

Không. Kỹ năng brainstorming được thiết kế rõ ràng để tránh anti‑pattern “việc này quá đơn giản, không cần thiết kế”. Ngay cả một thay đổi config nhỏ hoặc một utility dùng một lần cũng có thể ẩn nhiều giả định. Với task rất nhỏ, thiết kế có thể chỉ là một mô tả ngắn gọn, nhưng bạn vẫn nên diễn đạt và xác nhận nó trước khi triển khai.

Tôi có thể bỏ qua brainstorming nếu đã có spec sẵn không?

Nếu bạn đã có một spec đầy đủ, cập nhật và được phê duyệt, bạn có thể không cần cả một session brainstorming đầy đủ. Tuy nhiên, bạn vẫn có thể dùng template reviewer trong spec-document-reviewer-prompt.md để kiểm tra lại spec trước khi triển khai. Nếu review phát hiện khoảng trống hoặc điểm mơ hồ, hãy chạy một lượt brainstorming rút gọn để lấp chúng.

Brainstorming phối hợp với các kỹ năng triển khai như thế nào?

Kỹ năng brainstorming được dùng trước bất kỳ kỹ năng triển khai nào. Nó tạo ra:

• Một bản thiết kế rõ ràng, đã được người dùng phê duyệt
• Một tài liệu spec có thể review và tiếp tục chỉnh sửa

Chỉ sau khi vượt qua “cổng” phê duyệt này, bạn mới nên gọi các kỹ năng coding hoặc refactor. Sự tách bạch này giúp ý định thiết kế luôn rõ ràng và giảm bớt việc qua lại trong quá trình triển khai.

Tôi có bắt buộc phải dùng visual companion mới hưởng lợi từ brainstorming không?

Không. Visual companion là tùy chọn.

• Nếu công việc của bạn chủ yếu là backend, API hoặc hạ tầng, bạn có thể dùng brainstorming hoàn toàn ở dạng văn bản.
• Nếu bạn làm UI/UX, product design hoặc frontend, việc dùng visual companion từ visual-companion.md và thư mục scripts/ sẽ giúp so sánh phương án và thu thập phản hồi dễ dàng hơn nhiều.

Hãy quyết định dựa trên việc hình ảnh có thực sự giúp cuộc trao đổi trở nên rõ ràng hơn hay không.

Điều gì xảy ra nếu tôi bỏ qua “cổng” thiết kế và bắt đầu viết code luôn?

Bỏ qua cổng thiết kế đồng nghĩa bạn đã loại bỏ lợi ích chính của kỹ năng brainstorming: phát hiện lệch hướng sớm. Bạn có thể nhận kết quả:

• Tính năng không khớp kỳ vọng người dùng
• UI phải build lại sau khi nhận feedback
• Spec đi sau code và trở thành “nợ tài liệu”

Hãy coi cổng này như một quy tắc quy trình: đừng viết hoặc yêu cầu viết code cho đến khi thiết kế đã được viết, review và phê duyệt rõ ràng.

Tôi có thể tùy chỉnh tiêu chí review spec không?

Có. spec-document-reviewer-prompt.md định nghĩa các nhóm tiêu chí như tính đầy đủ, nhất quán, rõ ràng, phạm vi và cân nhắc YAGNI. Bạn có thể điều chỉnh template này cho domain riêng của mình (ví dụ thêm các kiểm tra về bảo mật, hiệu năng hoặc tuân thủ) trong khi vẫn giữ flow review giống nhau.

Brainstorming có bị buộc vào framework hay tech stack cụ thể không?

Không. Kỹ năng brainstorming độc lập với stack. Nó tập trung vào thu thập bối cảnh, làm rõ yêu cầu, diễn đạt thiết kế và khám phá visual, chứ không tập trung vào code đặc thù của framework. Bạn có thể dùng nó cho ứng dụng frontend, dịch vụ backend, tích hợp hay các hệ thống kết hợp.

Tôi gỡ cài đặt hoặc vô hiệu hóa kỹ năng brainstorming như thế nào?

Kỹ năng này chỉ là một phần của bộ kỹ năng obra/superpowers. Để ngừng sử dụng, bạn có thể:

• Xóa hoặc comment cấu hình của nó trong agent hoặc trình loader kỹ năng của bạn
• Ngừng gọi nó trong workflow và pipeline

Kỹ năng brainstorming không tạo thay đổi hệ thống ở cấp độ global, nên việc gỡ bỏ đơn giản chỉ là vấn đề cấu hình và cách bạn sử dụng.