obra/superpowers: Chuẩn hóa quy trình lập trình cho AI — hướng dẫn cài đặt và dùng

Tóm tắt nhanh
obra/superpowers là plugin và framework skill cho coding agent, biến yêu cầu tự nhiên thành quy trình phát triển phần mềm có brainstorming, lập kế hoạch, TDD, review và kiểm tra kết quả. Repo hỗ trợ nhiều harness như Claude Code, Codex, Cursor, Gemini CLI và các công cụ khác; cách cài chủ yếu là lệnh plugin riêng của từng công cụ nên không quá khó nếu bạn đã cài harness phù hợp.
obra/superpowers là một framework skill giúp coding agent làm phần mềm theo quy trình rõ ràng, thay vì vừa nghe yêu cầu đã lao ngay vào viết code. Nó bổ sung một phương pháp phát triển gồm làm rõ ý định, thống nhất thiết kế, lập kế hoạch, triển khai, viết test, review và xác minh kết quả.
Repo phù hợp với lập trình viên dùng Claude Code, Codex, Cursor, Gemini CLI hoặc một trong các harness được hỗ trợ. Người mới cũng có thể dùng vì các skill tự kích hoạt khi agent nhận ra loại công việc phù hợp. Giá trị lớn nhất là biến một cuộc trò chuyện với AI thành quy trình có điểm kiểm tra, giúp giảm code đoán mò, giảm bỏ sót yêu cầu và dễ phát hiện lỗi hơn.
Theo số liệu được cung cấp, repo hiện có khoảng 317048 sao và 28223 fork. Repo dùng giấy phép MIT, ngôn ngữ chính là Shell và vẫn còn được cập nhật. Đây là công cụ hỗ trợ quy trình làm việc, không phải một mô hình AI độc lập và cũng không thay thế coding agent mà bạn đang dùng.
obra/superpowers
Bộ skill giúp coding agent làm rõ yêu cầu, lập kế hoạch, viết test, review và triển khai code theo quy trình có kiểm chứng.
I.Superpowers làm được gì
Làm rõ yêu cầu trước khi viết code. Skill
brainstorminghỏi lại để hiểu bạn thực sự muốn xây gì, vì sao cần nó và phạm vi đến đâu. Với dự án lớn, agent có thể tạo tài liệu thiết kế để bạn xem và chỉnh trước khi triển khai.Lập kế hoạch đủ chi tiết để thực hiện. Skill
writing-planschia công việc thành các nhiệm vụ nhỏ, thường chỉ mất vài phút mỗi nhiệm vụ. Kế hoạch có đường dẫn tệp, phần code cần làm và cách kiểm tra, nên người mới vào dự án cũng dễ theo dõi hơn.Tổ chức phát triển theo TDD. Skill
test-driven-developmentyêu cầu đi theo vòng RED-GREEN-REFACTOR: viết test đang hỏng, quan sát test hỏng, viết lượng code tối thiểu để test chạy qua rồi mới refactor. Cách này giúp bạn có bằng chứng cụ thể thay vì chỉ tin vào lời khẳng định của agent.Tách công việc bằng subagent. Quy trình
subagent-driven-developmentcó thể giao từng nhiệm vụ cho agent riêng, sau đó kiểm tra mức độ đúng với đặc tả và chất lượng code. Điều này hữu ích khi một yêu cầu có nhiều phần độc lập hoặc cần review ở từng chặng.Làm việc an toàn hơn với Git worktree. Skill
using-git-worktreestạo không gian làm việc cô lập trên nhánh mới, chạy bước thiết lập dự án và kiểm tra trạng thái test ban đầu. Bạn có thể thử thay đổi mà không làm lẫn với nhánh đang dùng.Review code theo kế hoạch. Skill
requesting-code-reviewkiểm tra kết quả so với kế hoạch và báo vấn đề theo mức độ nghiêm trọng. Các lỗi quan trọng có thể chặn việc đi tiếp, thay vì để chúng bị che khuất bởi những thay đổi nhỏ.Debug có phương pháp. Skill
systematic-debuggingdùng quy trình tìm nguyên nhân gốc, truy vết nguyên nhân, chờ theo điều kiện và bổ sung lớp phòng vệ. Nó phù hợp khi lỗi không thể giải quyết an toàn bằng vài lần sửa đoán.Xác minh trước khi tuyên bố hoàn tất. Skill
verification-before-completionbuộc agent kiểm tra bằng bằng chứng phù hợp trước khi nói rằng lỗi đã được sửa hoặc tính năng đã xong.Hoàn tất nhánh phát triển có trật tự. Khi nhiệm vụ kết thúc,
finishing-a-development-branchkiểm tra test rồi đưa ra các lựa chọn như merge, tạo pull request, giữ lại hoặc dọn worktree.Chẩn đoán phiên làm việc gặp vấn đề. Khi skill kích hoạt sai, im lặng, lặp lại hoặc tiêu tốn nhiều token bất thường, bạn có thể yêu cầu agent tìm hiểu điều gì đã xảy ra với Superpowers trong phiên đó. Skill
diagnosing-superpowersđọc transcript, đưa ra bằng chứng theo dòng và có thể chuẩn bị gói dữ liệu đã loại bỏ thông tin nhạy cảm để báo lỗi.Hỗ trợ tạo skill mới.
writing-skillscung cấp quy trình tạo và kiểm thử skill. Đây là phần dành cho nhóm muốn mở rộng phương pháp làm việc, không cần thiết nếu bạn chỉ muốn dùng các skill có sẵn.
II.Cần chuẩn bị gì
Bạn cần một coding agent hoặc harness được Superpowers hỗ trợ. README nêu các lựa chọn gồm Claude Code, Antigravity, Codex App, Codex CLI, Cursor, Devin CLI, Factory Droid, Gemini CLI, GitHub Copilot CLI, Grok Build CLI, Kimi Code, OpenCode, Pi, Qwen Code, Hermes Agent và Muse.
Bạn cần chọn đúng hướng dẫn cài cho harness đang dùng. Nếu dùng nhiều harness, README yêu cầu cài Superpowers riêng cho từng harness. Cài ở một công cụ không tự động làm plugin xuất hiện ở công cụ khác.
README không nêu một phiên bản Windows, macOS hay Linux bắt buộc. README cũng không ghi yêu cầu về phiên bản Node.js, Python, GPU, tài khoản trả phí hay API key riêng cho Superpowers. Những điều kiện đăng nhập, mô hình và chi phí của coding agent bạn dùng vẫn phụ thuộc vào chính harness đó.
Với một số lựa chọn, bạn cần có quyền chạy lệnh cài plugin hoặc extension. Với Codex App, README hướng dẫn cài qua giao diện Plugins. Với Claude Code, Cursor, Kimi Code và một số công cụ khác, bạn cần mở giao diện hoặc terminal của chính công cụ đó.
Superpowers có thể làm agent tự động hơn và có thể thao tác trên mã nguồn, nhánh Git hoặc worktree. Hãy xem lại thiết kế, kế hoạch, diff và kết quả test trước khi chấp nhận thay đổi. README không mô tả việc Superpowers tự cung cấp mô hình hay API key.
III.Cài đặt từng bước
- Chọn harnessXác định coding agent bạn muốn tích hợp
- Mở đúng giao diệnDùng terminal, cửa sổ chat hoặc plugin manager của harness
- Cài SuperpowersChạy lệnh hoặc chọn plugin theo hướng dẫn tương ứng
- Khởi động lại phiênĐể hook và skill được nạp đúng cách khi cần
- Kiểm tra kích hoạtGửi một yêu cầu xây dựng tính năng và quan sát brainstorming
A.Chọn coding agent đang dùng
Superpowers không có một lệnh cài chung cho mọi công cụ. Bạn cần chọn đúng phần bên dưới. Nếu chưa dùng harness nào, README chỉ liệt kê các harness tương thích; tài liệu được cung cấp không hướng dẫn cài các harness đó từ đầu.
B.Cài trên Claude Code
Claude Code có hai marketplace. Cách đầu tiên dùng marketplace chính thức:
/plugin install superpowers@claude-plugins-officialHoặc đăng ký marketplace Superpowers rồi cài plugin:
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplaceCác lệnh này được chạy trong Claude Code. Hãy chọn một trong hai cách, không cần dùng cả hai cho cùng một lần cài. Nếu bạn dùng nhiều harness, vẫn phải cài riêng cho từng harness.
C.Cài trên Antigravity
Chạy lệnh sau trong môi trường Antigravity:
agy plugin install https://github.com/obra/superpowersREADME cho biết Antigravity sẽ liệt kê mô tả của từng skill. Mô tả của using-superpowers nhắc model nạp skill ở đầu cuộc trò chuyện. Khi muốn cập nhật, chạy lại đúng lệnh trên.
D.Cài trên Codex App
Trong Codex App, mở mục Plugins ở thanh bên. Tìm Superpowers trong nhóm Coding, bấm dấu + cạnh Superpowers rồi làm theo các bước hiển thị.
README không đưa lệnh terminal cho Codex App. Vì vậy, bạn không nên tự đổi lệnh của Codex CLI để dùng cho Codex App. Sau khi cài xong, mở một phiên mới để kiểm tra plugin đã được nạp.
E.Cài trên Codex CLI
Mở giao diện tìm plugin:
/pluginsSau đó tìm:
superpowersChọn Install Plugin. Hai dòng trên là thao tác trong Codex CLI, không phải lệnh cài npm. Nếu bạn đang ở terminal hệ điều hành nhưng chưa mở Codex CLI, hãy mở Codex CLI trước rồi mới nhập.
F.Cài trên Cursor
Trong cửa sổ Cursor Agent chat, nhập:
/add-plugin superpowersREADME cũng cho phép tìm superpowers trong plugin marketplace. Cách này phù hợp nếu bạn đã mở sẵn Cursor và đang làm việc trong một project. Sau khi cài, nên bắt đầu cuộc trò chuyện mới để kiểm tra skill bootstrap.
G.Cài trên Devin CLI
Cài plugin bằng:
devin plugins install obra/superpowersKhi muốn cập nhật:
devin plugins update superpowersĐừng dùng lệnh cập nhật trước khi plugin đã được cài. README không nêu thêm biến môi trường hay tệp cấu hình cần sửa.
H.Cài trên Factory Droid
Đăng ký marketplace:
droid plugin marketplace add https://github.com/obra/superpowersCài plugin:
droid plugin install superpowers@superpowersHai lệnh cần chạy trong môi trường có Factory Droid. Nếu lệnh không được nhận diện, trước hết kiểm tra bạn đã cài và mở đúng Droid CLI; tài liệu repo không hướng dẫn cài Droid.
I.Cài trên Gemini CLI
Cài extension:
gemini extensions install https://github.com/obra/superpowersKhi muốn cập nhật:
gemini extensions update superpowersExtension phải được cài trong Gemini CLI. Không dùng lệnh plugin của Claude Code thay cho lệnh extension này.
J.Cài trên GitHub Copilot CLI
Đăng ký marketplace:
copilot plugin marketplace add obra/superpowers-marketplaceCài plugin:
copilot plugin install superpowers@superpowers-marketplaceNếu bạn sử dụng Copilot trong một môi trường khác với GitHub Copilot CLI, hãy xem đúng tài liệu của môi trường đó. README chỉ đưa lệnh cho Copilot CLI.
K.Cài trên Grok Build CLI
Cài từ marketplace chính thức của xAI:
grok plugin install superpowers@xai-official --trustHoặc mở marketplace trong giao diện TUI:
/marketplaceLưu ý lệnh có cờ --trust. Chỉ xác nhận cài khi bạn hiểu rằng plugin sẽ được tin cậy trong môi trường của mình.
L.Cài trên Kimi Code
Trong Kimi Code, mở plugin manager:
/pluginsĐi tới Marketplace > Superpowers rồi cài. Hoặc cài trực tiếp từ repo:
/plugins install https://github.com/obra/superpowersREADME chỉ tới tài liệu chi tiết tại docs/README.kimi.md. Nếu cách cài trong giao diện thay đổi, đây là nơi nên xem tiếp trong bản checkout của repo.
M.Cài trên OpenCode
OpenCode có cách cài plugin riêng. Gửi cho OpenCode yêu cầu sau:
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.mdREADME nhấn mạnh rằng OpenCode cần được cài riêng, kể cả khi bạn đã dùng Superpowers trong harness khác. Làm theo tệp cài đặt mà OpenCode tải về, không tự đoán tên thư mục hoặc biến môi trường.
N.Cài trên Pi
Cài Superpowers như một package của Pi:
pi install git:github.com/obra/superpowersNếu phát triển cục bộ và muốn chạy Pi với checkout tạm thời:
pi -e /path/to/superpowersĐường dẫn /path/to/superpowers là mẫu trong README. Khi dùng thật, bạn phải thay bằng đường dẫn đến checkout của mình. Package nạp các skill và extension nhỏ để chèn bootstrap using-superpowers khi phiên bắt đầu và sau khi compact. Pi có native skills nên không cần compatibility Skill tool.
O.Cài trên Qwen Code
Cài plugin từ marketplace kiểu Claude Code và chọn superpowers khi được hỏi:
qwen extensions install obra/superpowersCập nhật sau này bằng:
qwen extensions update superpowersREADME không yêu cầu bạn tự đăng ký marketplace riêng trong hai lệnh này.
P.Cài trên Hermes Agent
Cài plugin và bật luôn:
hermes plugins install obra/superpowers --enableSau khi cài, khởi động lại các phiên Hermes đang chạy. README lưu ý Hermes không có post-compaction hook. Nếu một phiên rất dài bị compact sau lượt đầu và skill không còn kích hoạt, hãy bắt đầu phiên mới.
Q.Cài trên Muse
Cách cài từ một checkout cục bộ:
muse plugins install ./
muse plugins approve superpowersHoặc clone rồi cài:
git clone https://github.com/obra/superpowers.git
muse plugins install ./superpowers
muse plugins approve superpowersCập nhật bằng:
muse plugins update superpowersKhởi động lại phiên Muse sau khi cài để hook SessionStart có hiệu lực. README nói hook cần được phê duyệt ở lần cài đầu. Để kiểm tra, bắt đầu phiên mới và gửi:
Let's make a react todo listMột bản cài hoạt động sẽ tự kích hoạt brainstorming trước khi viết code.
IV.Kiểm tra đã chạy được chưa
Cách kiểm tra chung là mở một phiên mới trong harness vừa cài và yêu cầu agent xây một tính năng, thay vì yêu cầu nó viết code ngay. Ví dụ, mô tả một ứng dụng hoặc thay đổi bạn muốn làm. Theo workflow của README, agent hoạt động sẽ bắt đầu bằng việc hỏi để làm rõ ý định hoặc kích hoạt skill brainstorming.
Khi thiết kế được thống nhất, bạn nên thấy quy trình chuyển sang lập kế hoạch. Kế hoạch phải có nhiệm vụ nhỏ, đường dẫn tệp, code cần viết và cách kiểm tra. Trong giai đoạn triển khai, Superpowers có thể kích hoạt TDD, review và xác minh trước khi hoàn tất.
Với Muse, README đưa phép kiểm tra cụ thể là bắt đầu phiên mới rồi gửi Let's make a react todo list. Nếu cài đúng, brainstorming được kích hoạt trước khi code được viết.
Nếu agent nhảy thẳng vào code mà không làm rõ yêu cầu, hãy kiểm tra bạn đã cài đúng marketplace hoặc đúng plugin cho harness chưa, sau đó khởi động phiên mới. Với Hermes, đặc biệt cần phiên mới nếu phiên cũ đã compact và bootstrap không còn hoạt động.
V.Dùng vào việc thật
A.Chủ shop muốn làm trang quản lý đơn hàng
Bạn có thể mô tả mục tiêu theo cách tự nhiên: “Mình muốn thêm trang quản lý đơn hàng cho shop, có lọc theo trạng thái, tìm theo số điện thoại và không làm hỏng phần thanh toán hiện tại.”
Superpowers nên bắt đầu bằng việc hỏi các điểm còn mơ hồ như trạng thái đơn hàng, quyền truy cập, dữ liệu hiện có và cách hiển thị. Sau khi bạn xác nhận, agent tạo thiết kế rồi lập kế hoạch. Khi triển khai, quy trình TDD giúp các bộ lọc và điều kiện trạng thái có test trước khi viết phần logic chính.
Kết quả thực tế là bạn có thể xem thiết kế và kế hoạch trước, thay vì phát hiện sau nhiều giờ rằng agent hiểu sai quy trình xử lý đơn.
B.Nhân viên văn phòng cần tự động hóa báo cáo
Một nhân viên có thể yêu cầu: “Hãy giúp mình tạo công cụ đọc dữ liệu báo cáo hiện có, tổng hợp theo bộ phận và xuất kết quả. Trước khi sửa file, hãy hỏi mình về định dạng đầu vào và quy tắc tính.”
Skill brainstorming phù hợp để kéo các yêu cầu ẩn ra trước: cột nào là bắt buộc, dữ liệu thiếu xử lý ra sao, ai được dùng công cụ và tiêu chí nào xác nhận báo cáo đúng. Sau đó, writing-plans chia phần đọc dữ liệu, tính toán, xuất kết quả và kiểm tra thành nhiệm vụ rõ ràng.
Bạn nhận được một quy trình dễ duyệt với người phụ trách nghiệp vụ. Nếu có lỗi, systematic-debugging hướng agent tìm nguyên nhân thay vì sửa từng triệu chứng.
C.Lập trình viên mới xây tính năng nhỏ
Với yêu cầu như “Thêm chức năng đổi mật khẩu, có kiểm tra mật khẩu cũ và test cho các trường hợp sai”, Superpowers có thể hướng dẫn bạn đi từ làm rõ đặc tả đến kế hoạch.
using-git-worktrees giúp tạo nhánh và không gian làm việc riêng. test-driven-development yêu cầu viết test thất bại trước, rồi mới viết logic tối thiểu. Sau mỗi phần, requesting-code-review kiểm tra kết quả so với kế hoạch.
Cách này giúp người mới học được trình tự làm phần mềm: hiểu yêu cầu, viết test, sửa nhỏ, kiểm tra và review. Bạn không cần nhớ toàn bộ quy trình ngay từ đầu vì agent được bootstrap bằng các skill tương ứng.
D.Nhóm dev xử lý một dự án nhiều phần
Khi cần làm nhiều việc như cập nhật API, sửa giao diện và bổ sung test, bạn có thể yêu cầu agent lập kế hoạch rồi dùng subagent-driven-development. Mỗi nhiệm vụ được giao cho một subagent mới, có kiểm tra mức độ đúng với đặc tả và review chất lượng sau đó.
Nếu nhóm muốn tự kiểm soát việc hợp nhất, finishing-a-development-branch sẽ kiểm tra test và đưa ra lựa chọn merge, tạo pull request, giữ lại hoặc dọn worktree. Quy trình này phù hợp khi có nhiều nhánh và cần biết rõ thay đổi nào đã được xác minh.
AI viết code nhanh hơn khi nó hiểu đúng việc cần làm và phải chứng minh kết quả.
Ông T
VI.Lỗi hay gặp và cách xử lý
A.Cài đúng repo nhưng dùng sai harness
Các lệnh cài của Claude Code, Codex CLI, Gemini CLI và OpenCode không thay thế cho nhau. Hãy đối chiếu tên công cụ bạn đang mở với đúng mục trong README, rồi cài lại bằng lệnh tương ứng. Nếu dùng nhiều harness, cài Superpowers riêng cho từng cái.
B.Plugin đã cài nhưng phiên hiện tại không kích hoạt skill
Một số hook chỉ có hiệu lực khi phiên bắt đầu. Hãy đóng hoặc kết thúc phiên hiện tại rồi mở phiên mới. Muse yêu cầu khởi động lại phiên sau khi cài; Hermes cũng yêu cầu khởi động lại phiên đang chạy.
C.Phiên dài bị compact và skill ngừng chạy
README nêu rõ Hermes không có post-compaction hook. Nếu skill ngừng kích hoạt sau khi compact, hãy bắt đầu một phiên Hermes mới. Với các harness khác, kiểm tra tài liệu cài riêng của chúng thay vì tự thêm hook.
D.Agent tự viết code trước khi làm rõ yêu cầu
Có thể plugin chưa được nạp, cài sai marketplace hoặc phiên chưa nhận bootstrap. Hãy kiểm tra bằng một phiên mới và gửi yêu cầu xây dựng tính năng có nhiều điểm cần làm rõ. Với Muse, dùng đúng câu kiểm tra trong README: Let's make a react todo list.
E.Agent báo đã xong nhưng chưa có bằng chứng
Hãy yêu cầu nó thực hiện kiểm tra theo kế hoạch và xem diff, test cùng kết quả review. Superpowers có skill verification-before-completion, nhưng bạn vẫn nên tự duyệt thay đổi trước khi merge, đặc biệt khi agent có quyền thao tác trên mã nguồn hoặc Git worktree.
VII.Có nên dùng không
Bạn nên dùng obra/superpowers nếu thường xuyên làm việc với coding agent và muốn một quy trình lặp lại được. Bộ skill bao phủ khá đầy đủ các giai đoạn: hiểu yêu cầu, thiết kế, lập kế hoạch, TDD, debug, review, làm việc song song và hoàn tất nhánh. Repo có giấy phép MIT, hỗ trợ nhiều harness và các skill tự kích hoạt nên bạn không phải gọi thủ công cho từng bước.
Điểm mạnh khác là cách tiếp cận thiên về bằng chứng. Agent không chỉ được khuyến khích viết code mà còn phải chạy test, review theo kế hoạch và xác minh trước khi tuyên bố hoàn tất. Điều này đặc biệt có ích với dự án có nhiều tệp, người mới hoặc nhóm muốn giảm lỗi do hiểu sai yêu cầu.
Giới hạn là Superpowers không tự cung cấp coding agent, mô hình, API key hay môi trường chạy. Bạn vẫn cần cài một harness tương thích và chịu các điều kiện, chi phí hoặc giới hạn của harness đó. README cũng không đưa một quy trình cài chung cho mọi hệ điều hành.
Bạn nên chọn cách khác nếu chỉ cần một lệnh sinh nhanh đoạn code nhỏ, không muốn agent đặt câu hỏi hoặc không có quyền cho plugin can thiệp vào quy trình Git. Với công việc quan trọng, Superpowers cũng không thay thế review của con người. Nó làm quy trình tốt hơn, nhưng quyết định cuối cùng vẫn nên thuộc về bạn và nhóm phát triển.
Câu hỏi thường gặp
Superpowers có miễn phí không?
Repo sử dụng giấy phép MIT. README không nêu phí riêng cho Superpowers, nhưng chi phí hoặc điều kiện sử dụng coding agent, mô hình và dịch vụ liên quan phụ thuộc vào harness bạn chọn.
Có cần GPU hoặc API key riêng không?
README không nêu yêu cầu GPU hay API key riêng cho Superpowers. Đây là plugin và bộ skill chạy trên coding agent có sẵn, nên yêu cầu mô hình và API phụ thuộc vào harness.
Có chạy được trên Windows không?
README không chỉ rõ phiên bản Windows hay danh sách hệ điều hành được hỗ trợ. Tài liệu chỉ hướng dẫn lệnh theo từng harness, vì vậy bạn cần kiểm tra yêu cầu của coding agent mình đang dùng.
Tôi có phải cài Superpowers riêng cho từng công cụ không?
Có. README nói nếu dùng nhiều harness thì phải cài Superpowers riêng cho từng harness. Cài trên một công cụ không tự làm plugin xuất hiện ở công cụ khác.
Làm sao biết Superpowers đã hoạt động?
Mở một phiên mới và yêu cầu agent xây một tính năng. Cài đặt hoạt động thường kích hoạt brainstorming để hỏi và làm rõ yêu cầu trước khi viết code; Muse có thêm câu kiểm tra cụ thể trong README.
Superpowers có tự viết và tự merge code không?
Superpowers hỗ trợ lập kế hoạch, triển khai, test, review và quy trình hoàn tất nhánh. README không nói rằng plugin tự động merge mà không cần bạn chọn; bạn vẫn nên xem diff, kết quả test và quyết định bước cuối.
Dữ liệu dự án có an toàn không?
README không mô tả chính sách dữ liệu chung của các coding agent. Phần telemetry được nêu là tùy chọn cho tính năng visual companion và không gửi chi tiết project, prompt hay coding agent; bạn vẫn cần xem chính sách của harness đang dùng.


