Chương 10: Câu Hỏi Thường Gặp

Tổng Quan

Superpowers hỗ trợ những platform nào?

Superpowers được thiết kế để hoạt động trên nhiều platform AI coding:

Platform	Trạng thái	Ghi chú
Claude Code	Hỗ trợ đầy đủ	Platform chính; tất cả tính năng đều có sẵn
Cursor	Hỗ trợ đầy đủ	Hỗ trợ chính thức được thêm vào trong v4.3.1 (Tháng 2/2026)
Gemini CLI	Hỗ trợ đầy đủ	Hỗ trợ extension được thêm vào trong v5.0.1 (Tháng 3/2026)
Codex	Thử nghiệm	Có từ v3.3.0 (Tháng 10/2025)
OpenCode	Được hỗ trợ	Thêm vào trong v3.5.0

Mỗi platform đều sử dụng chung các file skill và cấu hình CLAUDE.md. Những khác biệt theo từng platform (nếu có) được ghi lại trong release notes của phiên bản đã giới thiệu hỗ trợ đó.

Superpowers khác gì so với việc dùng một AI coding agent thông thường?

Dùng AI coding agent mà không có Superpowers giống như sử dụng một công cụ mạnh mà không có hướng dẫn an toàn. Agent có năng lực, nhưng không có kỷ luật cưỡng bức về chất lượng, không có quy trình debug có hệ thống, và không có biện pháp bảo vệ trước những lỗi phổ biến nhất.

Với Superpowers:

Mỗi tính năng đều bắt đầu bằng một failing test. Không còn chuyện "implement và hy vọng."
Mọi tuyên bố hoàn thành đều cần bằng chứng. Không còn "nên hoạt động được."
Mỗi bug đều cần điều tra root cause. Không còn chuyện đoán mò.
Skills cưỡng bức các best practice theo từng domain. Agent tự động theo đúng hướng tiếp cận cho từng loại tác vụ.
Plans được viết trước khi code được viết. Các quyết định kiến trúc diễn ra trên giấy, không phải trong production.

Kết quả không phải là một agent chậm hơn — mà là một agent mà bạn có thể tin tưởng vào công việc của nó. Thời gian tiết kiệm được khi debug, revert, và gỡ rối codebase lộn xộn bù đắp hơn cả cho sự nghiêm ngặt ban đầu.

Tôi có thể dùng Superpowers với một team không?

Có. Superpowers đặc biệt phù hợp với môi trường team vì nó cưỡng bức các practices nhất quán cho tất cả thành viên team khi sử dụng AI agents.

Thiết lập được khuyến nghị cho team:

Commit CLAUDE.md vào repository. Tất cả thành viên team dùng chung cấu hình. AI agents làm việc trên dự án sẽ nhận các quy tắc giống nhau.
Commit thư mục .claude/skills/. Skills được chia sẻ. Các custom skills được tạo cho dự án của bạn đều có sẵn cho mọi người.
Áp dụng worktree isolation policy. Mỗi developer và mỗi AI agent đều làm việc trong một worktree riêng biệt. Quy tắc bảo vệ main branch ngăn direct commit.
Dùng PR-based code review. Quy trình code review (Chương 7) tích hợp trực tiếp với workflow GitHub/GitLab.

Với thiết lập này, một AI agent làm việc cho một thành viên team tuân theo cùng tiêu chuẩn như AI agent làm việc cho thành viên khác — hoặc một developer người tuân theo coding standards của team.

TDD & Chất Lượng

TDD có bắt buộc không? Có ngoại lệ không?

Có. TDD là bắt buộc. Không có ngoại lệ.

Đây là Iron Law 1: "KHÔNG CÓ PRODUCTION CODE NÀO ĐƯỢC VIẾT MÀ KHÔNG CÓ FAILING TEST TRƯỚC."

Các lý lẽ phổ biến xin ngoại lệ và tại sao chúng bị bác bỏ:

"Chỉ là một thay đổi nhỏ thôi." Những thay đổi nhỏ cũng gây ra bugs. Chi phí thời gian để viết test cho một thay đổi nhỏ tính bằng phút. Chi phí thời gian để debug một regression từ thay đổi nhỏ chưa được test tính bằng giờ.

"Chúng ta đang chạy nhanh, sẽ thêm tests sau." Tests thêm sau khi implement được định hình xung quanh implementation, không phải requirement. Chúng test những gì code làm, không phải những gì code nên làm. Chúng tạo ra sự tự tin giả. "Sau" hiếm khi đến.

"Code là UI, khó test lắm." Hành vi UI có thể được test. Component tests, snapshot tests, interaction tests, và end-to-end tests đều tồn tại. Khó khăn không phải là lý do miễn trừ.

"Tôi biết code này đúng." Đây là lý lẽ nguy hiểm nhất. Bản thân bạn trong tương lai, hoặc một đồng nghiệp, không có sự chắc chắn hiện tại của bạn. Test ghi lại sự chắc chắn đó và bảo tồn nó.

Model nào được khuyến nghị cho từng loại tác vụ?

Lựa chọn model phụ thuộc vào yêu cầu của tác vụ:

Loại tác vụ	Model được khuyến nghị	Lý do
Lập kế hoạch kiến trúc, lập luận phức tạp	Claude Sonnet 4.5+ (Thinking mode)	Extended reasoning tạo ra plans tốt hơn
Implement tính năng, TDD	Claude Sonnet 4.5	Cân bằng tốc độ và chất lượng
Code review, debugging	Claude Sonnet 4.5	Khả năng phân tích mạnh
Refactoring đơn giản, formatting	Claude Haiku 3.5	Nhanh và tiết kiệm chi phí cho các tác vụ cơ học
Multi-agent parallel tasks	Claude Haiku 3.5 (subagents)	Hiệu quả chi phí ở quy mô lớn

Đối với người dùng Gemini CLI: Gemini 2.0 Flash được khuyến nghị cho các tác vụ implement; Gemini 2.5 Pro cho kiến trúc và lập kế hoạch.

Đối với người dùng Cursor: Dùng model Claude Sonnet trong Cursor's composer cho công việc tính năng. Chat tích hợp của Cursor có thể dùng các model nhỏ hơn cho các câu hỏi nhanh.

Cài Đặt & Cập Nhật

Làm thế nào để cập nhật lên phiên bản mới của Superpowers?

Superpowers được phân phối dưới dạng một tập hợp các file trong repository của bạn (CLAUDE.md, thư mục skills, và các cấu hình liên quan). Các cập nhật được áp dụng bằng cách kéo phiên bản mới nhất từ repository Superpowers.

Quy trình cập nhật tiêu chuẩn:

# 1. Tạo một update worktree (làm theo giao thức Chương 8)
git worktree add ../myapp--superpowers-update -b chore/update-superpowers

# 2. Trong update worktree, tải về các file Superpowers mới nhất
# (làm theo hướng dẫn cài đặt cho thiết lập cụ thể của bạn)

# 3. Chạy toàn bộ test suite để xác minh không có gì bị hỏng
npm test

# 4. Xem lại changelog (Chương 11) để tìm các breaking changes

# 5. Merge qua PR theo quy trình code review thông thường

Trước khi cập nhật:

Đọc changelog của phiên bản bạn đang cập nhật lên
Lưu ý các breaking changes yêu cầu cập nhật cấu hình
Đảm bảo tất cả tests hiện tại đều pass trước khi bắt đầu cập nhật

Làm thế nào để thêm một skill mới?

Skills là các file trong thư mục .claude/skills/ (đối với Claude Code) hoặc tương đương trên platform của bạn.

Quy trình thêm skill mới:

Xác định domain. Skill này bao gồm lĩnh vực phát triển cụ thể nào? Hãy chính xác — một skill cho "React performance optimization" tốt hơn một skill cho "React."
Viết failing test trước (Iron Law 4). Xác định hành vi mà skill nên tạo ra trước khi viết skill.
Viết skill file. Skills là các file markdown với cấu trúc cụ thể: trigger conditions, context, rules, và examples.
Test skill. Kích hoạt nó trong một session thực tế. Xác minh nó trigger đúng với các input và tạo ra hướng dẫn đúng.
Commit vào repository. Skills được commit vào repo đều có sẵn cho tất cả thành viên team và agents.

Để được hướng dẫn tạo skill chi tiết, hãy dùng skill superpowers:writing-skills.

Tương Thích

Superpowers có hoạt động trên Windows không?

Có. Superpowers hoạt động trên Windows, macOS, và Linux.

Người dùng Windows nên lưu ý một số vấn đề đặc thù của platform:

Dấu phân cách đường dẫn: Skills và các file cấu hình dùng dấu gạch chéo xuôi (forward slashes). Windows xử lý đúng trong hầu hết các context, nhưng một số shell scripts có thể cần điều chỉnh.
Line endings: Cấu hình git để xử lý line endings nhất quán: git config core.autocrlf input.
Lệnh shell trong ví dụ: Một số ví dụ dùng cú pháp bash. Người dùng Windows nên dùng WSL2 (Windows Subsystem for Linux) hoặc Git Bash để có trải nghiệm tốt nhất.
Đường dẫn worktree: Dùng các đường dẫn không có khoảng trắng. C:\projects\myapp--feature hoạt động được; C:\My Projects\myapp feature có thể gây ra vấn đề.

Các bản sửa lỗi Windows chuyên dụng được đưa vào platform khi áp dụng và được ghi chú trong changelog.

Tôi có thể dùng Superpowers mà không cần Claude Code cụ thể không?

Có. Mặc dù Superpowers ban đầu được thiết kế cho Claude Code, các nguyên tắc cốt lõi — TDD, systematic debugging, verification before completion, plan-before-code — đều không phụ thuộc vào platform.

Hệ thống skill được triển khai khác nhau trên mỗi platform:

Claude Code: Thư mục .claude/skills/ với các file skill dạng markdown
Cursor: Cursor rules files với nội dung skill được điều chỉnh
Gemini CLI: Extension configuration

Các Iron Laws và giao thức được mô tả trong hướng dẫn này áp dụng bất kể bạn dùng platform nào. Cơ chế kích hoạt cụ thể khác nhau, nhưng hành vi mà chúng cưỡng bức thì giống nhau.

Xử Lý Sự Cố

Một skill không trigger đúng cách. Tôi phải làm gì?

Kiểm tra file skill tồn tại ở đúng vị trí cho platform của bạn.
Xác minh trigger description trong file skill. Điều kiện trigger phải khớp với ngôn ngữ bạn dùng để kích hoạt nó.
Hãy rõ ràng. Thay vì hy vọng agent tự suy ra đúng skill, hãy đặt tên trực tiếp: "Dùng skill superpowers:systematic-debugging cho cái này."
Kiểm tra xung đột. Nếu hai skill có trigger conditions chồng chéo nhau, agent có thể chọn nhầm cái. Xem lại cấu hình skill của bạn.
Đọc lại file skill. Skills có thể trở nên lỗi thời khi codebase thay đổi. Skill có thể đang trigger đúng nhưng đưa ra lời khuyên không còn phù hợp nữa.

Tests pass ở local nhưng fail trong CI. Tôi phải làm gì?

Đây là bài toán điều tra root cause. Làm theo Phase 1 của debugging protocol (Chương 6):

Đọc kỹ CI error output — đừng tóm tắt nó
Xác định sự khác biệt giữa local và CI (environment variables, phiên bản Node, OS, file permissions, network access)
Tái tạo môi trường CI ở local nếu có thể (Docker, phiên bản Node phù hợp)
Kiểm tra các test phụ thuộc vào global state, file system state, hoặc timing

Các nguyên nhân phổ biến nhất: environment variables không được set trong CI, tests được viết với implicit dependencies vào local file paths, và tests có timing assumptions thất bại dưới tải CI.