Chapter 10: 자주 묻는 질문 (FAQ)

일반

Superpowers는 어떤 플랫폼을 지원합니까?

Superpowers는 여러 AI 코딩 플랫폼과 함께 작동하도록 설계되었습니다:

플랫폼	상태	참고 사항
Claude Code	완전 지원	주요 플랫폼; 모든 기능 사용 가능
Cursor	완전 지원	v4.3.1 (2026년 2월)에서 공식 지원 추가
Gemini CLI	완전 지원	v5.0.1 (2026년 3월)에서 extension 지원 추가
Codex	실험적	v3.3.0 (2025년 10월)부터 사용 가능
OpenCode	지원됨	v3.5.0에서 추가

각 플랫폼은 동일한 skill 파일과 CLAUDE.md 설정을 사용합니다. 플랫폼별 차이점(있는 경우)은 해당 지원을 도입한 버전의 릴리스 노트에 문서화되어 있습니다.

Superpowers는 일반 AI 코딩 agent와 어떻게 다릅니까?

Superpowers 없이 AI 코딩 agent를 사용하는 것은 안전 매뉴얼 없이 강력한 도구를 사용하는 것과 같습니다. Agent는 유능하지만 품질에 대한 강제된 규율이 없고, 체계적인 debugging 프로토콜도 없으며, 가장 일반적인 실패 모드에 대한 안전장치도 없습니다.

Superpowers를 사용하면:

모든 기능은 실패하는 test로 시작합니다. "구현하고 바라는" 방식은 없습니다.
모든 완료 선언은 증거를 필요로 합니다. "작동해야 합니다"는 없습니다.
모든 버그는 근본 원인 조사를 필요로 합니다. 추측은 없습니다.
Skills는 도메인별 best practice를 강제합니다. Agent는 각 작업 유형에 맞는 올바른 접근 방식을 자동으로 따릅니다.
코드를 작성하기 전에 계획을 작성합니다. 아키텍처 결정은 프로덕션이 아닌 계획 단계에서 이루어집니다.

결과는 더 느린 agent가 아닙니다 — 신뢰할 수 있는 작업을 하는 agent입니다. debugging, 되돌리기, 엉킨 codebase를 풀어내는 데 절약되는 시간이 초기 엄격함을 충분히 보상합니다.

팀에서 Superpowers를 사용할 수 있습니까?

예. Superpowers는 AI agent를 사용하는 모든 팀원에게 일관된 관행을 강제하기 때문에 팀 환경에 특히 적합합니다.

권장 팀 설정:

CLAUDE.md를 repository에 commit하세요. 모든 팀원이 동일한 설정을 사용합니다. 프로젝트에서 작업하는 AI agent는 동일한 규칙을 적용합니다.
.claude/skills/ 디렉토리를 commit하세요. Skills가 공유됩니다. 프로젝트를 위해 만든 custom skill은 모든 사람이 사용할 수 있습니다.
Worktree 격리 정책을 시행하세요. 각 개발자와 각 AI agent는 격리된 worktree에서 작업합니다. Main branch 보호 규칙이 직접 commit을 방지합니다.
PR 기반 code review를 사용하세요. Code review 프로토콜(Chapter 7)은 GitHub/GitLab workflow와 직접 통합됩니다.

이 설정으로 한 팀원을 위해 작업하는 AI agent는 다른 팀원을 위해 작업하는 AI agent — 또는 팀의 코딩 표준을 따르는 인간 개발자 — 와 동일한 기준을 따릅니다.

TDD & 품질

TDD는 필수입니까? 예외가 있습니까?

예. TDD는 필수입니다. 예외는 없습니다.

이것이 Iron Law 1입니다: "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST."

예외에 대한 일반적인 주장과 그것이 거부되는 이유:

"작은 변경입니다." 작은 변경도 버그를 도입합니다. 작은 변경에 대한 test 작성 시간 비용은 분 단위로 측정됩니다. 테스트되지 않은 작은 변경으로 인한 regression을 debugging하는 시간 비용은 시간 단위로 측정됩니다.

"빠르게 진행 중입니다, 나중에 test를 추가하겠습니다." 구현 후에 추가된 test는 요구사항이 아닌 구현을 기반으로 형성됩니다. 코드가 해야 하는 것이 아닌 코드가 하는 것을 test합니다. 거짓 확신을 제공합니다. "나중에"는 거의 오지 않습니다.

"코드가 UI입니다, test하기 어렵습니다." UI 동작은 test할 수 있습니다. Component test, snapshot test, interaction test, end-to-end test 모두 존재합니다. 어려움은 면제가 아닙니다.

"이 코드가 올바르다는 것을 알고 있습니다." 이것이 가장 위험한 주장입니다. 미래의 자신이나 동료는 현재의 확신을 공유하지 않습니다. Test는 그 확신을 문서화하고 보존합니다.

각 작업 유형에 권장되는 모델은 무엇입니까?

모델 선택은 작업 요구사항에 따라 다릅니다:

작업 유형	권장 모델	이유
아키텍처 계획, 복잡한 추론	Claude Sonnet 4.5+ (Thinking 모드)	확장된 추론이 더 나은 계획을 생성합니다
기능 구현, TDD	Claude Sonnet 4.5	속도와 품질의 균형
Code review, debugging	Claude Sonnet 4.5	강력한 분석 능력
간단한 refactoring, 포맷팅	Claude Haiku 3.5	기계적 작업에 빠르고 비용 효율적
Multi-agent 병렬 작업	Claude Haiku 3.5 (subagent)	규모에서 비용 효율적

Gemini CLI 사용자: 구현 작업에는 Gemini 2.0 Flash를, 아키텍처 및 계획에는 Gemini 2.5 Pro를 권장합니다.

Cursor 사용자: 기능 작업에는 Cursor의 composer에서 Claude Sonnet 모델을 사용하세요. Cursor의 내장 chat은 빠른 질문에 더 작은 모델을 사용할 수 있습니다.

설치 & 업데이트

Superpowers의 새 버전으로 어떻게 업데이트합니까?

Superpowers는 repository의 파일 집합(CLAUDE.md, skills 디렉토리, 관련 설정)으로 배포됩니다. 업데이트는 Superpowers repository에서 최신 버전을 pull하여 적용됩니다.

표준 업데이트 프로세스:

# 1. 업데이트 worktree 생성 (Chapter 8 프로토콜 따르기)
git worktree add ../myapp--superpowers-update -b chore/update-superpowers

# 2. 업데이트 worktree에서 최신 Superpowers 파일 다운로드
# (특정 설정에 맞는 설치 지침을 따르세요)

# 3. 전체 test suite를 실행하여 깨진 것이 없는지 확인
npm test

# 4. breaking change에 대한 changelog (Chapter 11) 검토

# 5. 일반 code review 프로토콜에 따라 PR로 merge

업데이트 전:

업데이트할 버전의 changelog를 읽으세요
설정 업데이트가 필요한 breaking change를 메모하세요
업데이트를 시작하기 전에 현재 모든 test가 통과하는지 확인하세요

새 skill을 어떻게 추가합니까?

Skills는 .claude/skills/ 디렉토리(Claude Code용) 또는 플랫폼에 맞는 동등한 위치에 있는 파일입니다.

새 skill 추가 프로세스:

도메인을 식별하세요. 이 skill이 커버하는 개발의 특정 영역은 무엇입니까? 정확하게 — "React 성능 최적화"를 위한 skill이 "React"를 위한 skill보다 낫습니다.
먼저 실패하는 test를 작성하세요 (Iron Law 4). skill을 작성하기 전에 skill이 생성해야 할 동작을 정의하세요.
Skill 파일을 작성하세요. Skills는 특정 구조를 가진 markdown 파일입니다: trigger 조건, context, 규칙, 예시.
Skill을 테스트하세요. 실제 세션에서 호출하세요. 올바른 input에서 trigger되고 올바른 guidance를 생성하는지 확인하세요.
Repository에 commit하세요. Repository에 commit된 skills는 모든 팀원과 agent가 사용할 수 있습니다.

자세한 skill 생성 가이드는 superpowers:writing-skills skill을 사용하세요.

호환성

Superpowers는 Windows에서 작동합니까?

예. Superpowers는 Windows, macOS, Linux에서 작동합니다.

Windows 사용자는 몇 가지 플랫폼별 고려 사항을 알고 있어야 합니다:

경로 구분자: Skills와 설정 파일은 슬래시(forward slash)를 사용합니다. Windows는 대부분의 context에서 이를 올바르게 처리하지만 일부 shell script는 조정이 필요할 수 있습니다.
줄 끝 문자: 줄 끝 문자를 일관되게 처리하도록 git을 설정하세요: git config core.autocrlf input.
예시의 shell 명령어: 일부 예시는 bash 문법을 사용합니다. Windows 사용자는 최적의 경험을 위해 WSL2(Windows Subsystem for Linux) 또는 Git Bash를 사용해야 합니다.
Worktree 경로: 공백이 없는 경로를 사용하세요. C:\projects\myapp--feature는 작동합니다; C:\My Projects\myapp feature는 문제를 일으킬 수 있습니다.

전용 Windows fix는 해당되는 경우 플랫폼에 포함되며 changelog에 기록됩니다.

Claude Code 없이 Superpowers를 사용할 수 있습니까?

예. Superpowers가 원래 Claude Code를 위해 설계되었지만, 핵심 원칙 — TDD, 체계적인 debugging, 완료 전 검증, 코드 전 계획 — 은 플랫폼에 구애받지 않습니다.

Skill 시스템은 각 플랫폼에서 다르게 구현됩니다:

Claude Code: 마크다운 skill 파일이 있는 .claude/skills/ 디렉토리
Cursor: 적응된 skill 내용이 있는 Cursor rules 파일
Gemini CLI: Extension 설정

이 가이드에 설명된 Iron Laws와 프로토콜은 어떤 플랫폼을 사용하든 적용됩니다. 특정 호출 메커니즘은 다르지만 강제하는 동작은 동일합니다.

문제 해결

Skill이 올바르게 trigger되지 않습니다. 어떻게 해야 합니까?

Skill 파일이 플랫폼에 맞는 올바른 위치에 있는지 확인하세요.
Skill 파일의 trigger 설명을 확인하세요. Trigger 조건은 호출에 사용하는 언어와 일치해야 합니다.
명시적으로 하세요. Agent가 올바른 skill을 추론하기를 바라는 대신, 직접 이름을 지정하세요: "이것에 superpowers:systematic-debugging skill을 사용하세요."
충돌을 확인하세요. 두 개의 skill이 겹치는 trigger 조건을 가지고 있으면 agent가 잘못된 것을 선택할 수 있습니다. Skill 설정을 검토하세요.
Skill 파일을 다시 읽으세요. Skills는 codebase가 변경될 때 오래될 수 있습니다. Skill이 올바르게 trigger되고 있지만 더 이상 적용되지 않는 조언을 생성할 수 있습니다.

Test가 로컬에서는 통과하지만 CI에서는 실패합니다. 어떻게 해야 합니까?

이것은 근본 원인 조사 문제입니다. debugging 프로토콜의 Phase 1을 따르세요(Chapter 6):

CI 에러 출력을 주의 깊게 읽으세요 — 요약하지 마세요
로컬과 CI 간의 차이를 확인하세요(환경 변수, Node 버전, OS, 파일 권한, 네트워크 접근)
가능하면 로컬에서 CI 환경을 재현하세요(Docker, 일치하는 Node 버전)
전역 상태, 파일 시스템 상태, 또는 타이밍에 의존하는 test를 확인하세요

가장 일반적인 원인: CI에 환경 변수가 설정되지 않음, 로컬 파일 경로에 대한 암묵적 의존성으로 작성된 test, CI 부하 하에서 실패하는 타이밍 가정이 있는 test.