Hướng Dẫn Đầy Đủ Plugin Superpowers cho Claude Code

Superpowers biến Claude Code từ một "thực tập sinh nhiệt tình hay bỏ qua bước quan trọng" thành một "đội phát triển có kỷ luật" — tự động lên kế hoạch, viết test trước khi code, và tự review lại kết quả.

1. Superpowers là gì?

Superpowers (repo: obra/superpowers) là một agentic skills framework mã nguồn mở, được tạo bởi Jesse Vincent vào tháng 10/2025 — đúng ngày Anthropic ra mắt hệ thống plugin cho Claude Code.

Về bản chất, đây là một bộ quy trình kỹ thuật phần mềm được viết thành các file markdown (SKILL.md), inject vào Claude Code thông qua plugin và session hook. Không có model fine-tuned, không có SDK riêng — chỉ là plain text, nhưng hiệu quả đến mức:

• Tháng 1/2026: được Anthropic chính thức chấp nhận vào Claude plugins marketplace

• Tháng 3/2026: vượt 93,000 GitHub stars, tăng ~2,000 stars/ngày

• Tháng 6/2026: hơn 170,000 stars, một trong những dự án open-source tăng trưởng nhanh nhất năm

Plugin hỗ trợ nhiều nền tảng: Claude Code, Cursor, Gemini CLI, GitHub Copilot CLI, Codex, OpenCode — dùng chung một bộ skills.

2. Tại sao cần Superpowers?

Claude Code mặc định có một vấn đề quen thuộc: nhảy thẳng vào viết code mà không hỏi yêu cầu, không viết test trước, không review lại.

Superpowers giải quyết bằng cách bắt buộc Claude đi theo đúng quy trình — không phải gợi ý, mà là ràng buộc có kiểm soát:

3. Yêu cầu trước khi cài

• Claude Code phiên bản 2.0.13 trở lên (hỗ trợ plugin marketplace)

• Node.js đã được cài (yêu cầu của Claude Code)

• Kết nối internet để fetch plugin từ marketplace

Kiểm tra phiên bản Claude Code:

claude --version

4. Cài đặt

Phương pháp 1: Qua Official Anthropic Marketplace (Khuyến nghị)

Mở Claude Code, chạy lệnh sau trong session:

/plugin install superpowers@claude-plugins-official

Phương pháp 2: Qua Superpowers Community Marketplace

Đây là marketplace do chính tác giả Jesse Vincent duy trì, cập nhật nhanh hơn:

/plugin marketplace add obra/superpowers-marketplace
hoặc
/plugin install superpowers@superpowers-marketplace

Hai phương pháp cài cùng một bộ skills. Chọn một trong hai là đủ.

Sau khi cài: Restart Plugin

/reload-plugin

Lưu ý: Plugin dùng cơ chế SessionStart hook — mỗi khi bạn mở session mới (startup, clear, compact), hook tự động inject bộ skills vào context. Không cần làm gì thêm.

5. Xác nhận cài đặt thành công

Sau khi restart, chạy lệnh kiểm tra:

/plugin

Bạn sẽ thấy superpowers trong danh sách với trạng thái active.

Acceptance Test: Reload plugin và nhắn:

Tôi muốn xây dựng một tính năng đăng nhập bằng email và password.

Nếu Superpowers hoạt động đúng, Claude sẽ không bắt đầu viết code ngay. Thay vào đó, nó sẽ hỏi lại các câu như:

• Đây là web app hay mobile app?

• Cần hỗ trợ đăng nhập qua bên thứ ba (Google, GitHub) không?

• Có cần chức năng "Remember me" không?

Đó chính là skill brainstorming đang hoạt động.

6. Các skill chính và cách dùng

Superpowers có 12+ skill có tài liệu đầy đủ. Dưới đây là 6 skill quan trọng nhất:

brainstorming

Trigger tự động: Khi bạn mô tả một tính năng hoặc task cần xây dựng.

Slash command: /superpowers:brainstorm

Skill này áp dụng phương pháp Socratic — hỏi để làm rõ yêu cầu thật sự trước khi code. Output là một design document được lưu lại để các bước tiếp theo tham chiếu. Phiên bản 5.0 còn có Visual Brainstorming Companion — giao diện trực quan trên browser để thiết kế UI/mockup ngay trong session.

writing-plans

Trigger: Sau khi design được bạn approve.

Slash command: /superpowers:write-plan

Chia nhỏ task thành các đơn vị 2–5 phút, mỗi task có:

• Đường dẫn file cụ thể

• Code đầy đủ cần viết

• Bước verification rõ ràng

• Chú thích phụ thuộc giữa các task

Kế hoạch này được lưu lại như một technical specification nhẹ có thể tham khảo sau.

subagent-driven-development

Trigger: Sau khi có implementation plan.

Slash command: /superpowers:execute-plan

Dispatch từng subagent riêng biệt cho mỗi task trong plan. Mỗi subagent bắt đầu với context sạch (chỉ có plan và test). Sau khi hoàn thành, có two-stage review:

1. Spec compliance — đúng với kế hoạch không?

2. Code quality — chất lượng code có đạt chuẩn không?

Các task độc lập có thể chạy song song, giảm đáng kể thời gian tổng thể của project phức tạp.

test-driven-development

Trigger: Khi bạn đề cập đến "TDD", "viết test", "test-driven".

Luật Sắt (Iron Law): Không được viết production code nếu chưa có failing test.

Nếu Claude phát hiện bạn (hoặc nó) đã viết code trước test, skill này yêu cầu xóa code đó và bắt đầu lại đúng quy trình. Chu trình bắt buộc: RED (test fail) → GREEN (code pass) → REFACTOR.

systematic-debugging

Trigger: Khi có bug hoặc lỗi cần xử lý.

Quy trình 4 bước bắt buộc:

1. Reproduce — Tái hiện lỗi ổn định

2. Understand — Hiểu root cause, cấm sửa khi chưa hiểu

3. Fix — Sửa đúng nguyên nhân gốc

4. Verify — Test và linter phải pass

Skill này cấm pattern "thử sửa xem sao" — không có fix nào được phép nếu chưa xác định root cause.

verification-before-completion

Trigger: Khi implementation xong và bạn muốn mark task là done.

Checklist tự động: tất cả test pass, linter sạch, không có code tạm thời còn lại, integration đã được verify. Khi thấy các từ như "should", "probably", "seems to" — skill này sẽ cảnh báo.

7. Quy trình làm việc đầy đủ với Superpowers

Đây là luồng hoàn chỉnh cho một feature từ đầu đến cuối:

User mô tả feature
        ↓
[brainstorming] — Hỏi làm rõ yêu cầu, đề xuất design
        ↓
User approve design
        ↓
[using-git-worktrees] — Tạo branch mới, worktree riêng biệt
        ↓
[writing-plans] — Chia nhỏ thành task 2–5 phút có checkpoint
        ↓
User xem xét và approve plan
        ↓
[subagent-driven-development] — Dispatch subagent per task
        ↓ (bên trong mỗi subagent)
[test-driven-development] — RED → GREEN → REFACTOR
        ↓
[requesting-code-review] — Subagent độc lập review kết quả
        ↓
[verification-before-completion] — Gate kiểm tra cuối
        ↓
      DONE ✓

Bạn không cần nhớ hay gọi thủ công từng skill. Các skill tự trigger dựa trên context — Superpowers tự nhận biết bạn đang ở giai đoạn nào và áp dụng skill phù hợp.

8. Xử lý lỗi thường gặp

Skills không tự trigger sau khi cài

# Kiểm tra plugin đã được load chưa
/plugin list

# Nếu superpowers không có trong list, re-register marketplace
/plugin marketplace add obra/superpowers-marketplace

# Gỡ và cài lại
/plugin uninstall superpowers
/plugin install superpowers@superpowers-marketplace

Hook không chạy khi start session

# Kiểm tra thư mục plugin
ls -la ~/.claude/plugins/superpowers/

# Fix quyền thực thi cho hook script
chmod +x ~/.claude/plugins/superpowers/hooks/session-start.sh

# Xem cấu hình hook
cat ~/.claude/plugins/superpowers/hooks/hooks.json

Warning về thư mục skills cũ

Nếu thấy cảnh báo về ~/.config/superpowers/skills (từ phiên bản cũ):

# Backup skills tùy chỉnh nếu có
cp -r ~/.config/superpowers/skills ~/backup-custom-skills

# Xóa thư mục cũ
rm -rf ~/.config/superpowers/skills

Nhiều skills trigger cùng lúc gây hỗn loạn

Tạm thời disable một số skills trong cấu hình:

# ~/.superpowers/config.yaml
superpowers:
  skills:
    enabled:
      - brainstorming
      - writing-plans
      - test-driven-development
    disabled:
      - subagent-driven-development  # tạm tắt

Lỗi khi tạo git worktree

# Yêu cầu Git >= 2.5
git --version

# Dọn dẹp stale worktrees
git worktree prune

Cập nhật lên phiên bản mới nhất

/plugin update superpowers

9. Mẹo sử dụng hiệu quả

Lộ trình onboarding theo tuần

Nếu bạn mới dùng Superpowers, không nên bật tất cả mọi thứ cùng lúc:

• Tuần 1: brainstorming + writing-plans — làm quen với design-first workflow

• Tuần 2: thêm test-driven-development — bắt đầu thực hành TDD

• Tuần 3: thêm systematic-debugging — xây dựng kỷ luật debug

• Tuần 4: subagent-driven-development — tận dụng parallel execution cho project lớn

Khi nào nên dùng Superpowers

Superpowers phù hợp nhất cho:

• Code cần maintain lâu dài

• Feature phức tạp với nhiều edge case

• Team project cần consistency

Không cần dùng Superpowers cho:

• Script nhanh, prototype dùng một lần

• Task đơn giản không cần test

Với dự án Python + DDD/Hexagonal Architecture

Superpowers đặc biệt phù hợp cho các dự án có kiến trúc phân lớp như Hexagonal. Khi brainstorming, hãy cung cấp thêm context về cấu trúc thư mục và layer hiện tại — skill writing-plans sẽ tạo ra các task với file path chính xác theo đúng kiến trúc của bạn.

Tổng kết

Superpowers không thêm khả năng mới cho Claude — nó thêm kỷ luật. Đó là điểm mấu chốt. Claude đã biết TDD, đã biết cách lên kế hoạch, nhưng hay bỏ qua các bước "boring" đó. Superpowers tạo ra speed bump thực sự, không phải biển báo.

Với overhead ban đầu 10–20 phút cho brainstorming và planning, bạn sẽ thu lại thời gian gấp nhiều lần từ việc ít bug hơn, ít refactor hơn, ít debug hơn về sau.

Tài nguyên:

• GitHub: github.com/obra/superpowers

• Anthropic Marketplace: claude.com/plugins/superpowers

• Report issues: github.com/obra/superpowers/issues