obra/superpowers 소개: AI 코딩 에이전트에 개발 방법론을 입히는 방식

목표: 방법론과 실제 실행 결과를 구분하기

obra/superpowers는 AI 에이전트에 개발 절차를 적용하기 위한 스킬 프레임워크입니다. 요구 정리, 계획, 테스트, 검토 같은 작업을 상황에 맞는 스킬로 다룹니다. 이 글에서는 각 단계가 어떤 증거를 남겨야 하는지 작은 버그 과제로 살펴봅니다. 함수 테스트와 Git의 기본 사용을 알고 있다는 전제입니다.

스킬 이름을 호출한 것과 해당 단계가 성공한 것은 다릅니다. 계획 파일은 의도를 보여 주고, 테스트 결과는 특정 조건의 동작을 보여 줍니다. 완료 판단에는 실제 변경과 검사 결과가 필요합니다.

공식 흐름을 프로젝트 과제로 번역하기

2026-09-13 확인한 저장소에는 brainstorming, writing-plans, test-driven-development, verification-before-completion 등 개발 절차를 다루는 스킬이 안내되어 있습니다. 설치 방식과 지원 환경은 저장소의 현재 README를 확인하세요. 과거 글에 있던 명령을 모든 클라이언트에 공통으로 실행할 수 있다고 가정하지 않습니다.

단계	남길 산출물	다음 단계로 넘어갈 근거
요구 정리	입력·출력과 제외 범위	무엇이 오류인지 설명 가능
구현 계획	대상 파일과 확인 순서	관련 없는 변경이 섞이지 않음
문제 재현	실패하는 입력과 기대 결과	기존 코드가 왜 잘못됐는지 확인
수정	목적에 맞는 diff	요구를 만족시키는 변경
검증·검토	실행 로그와 변경 설명	해당 검사 통과 및 남은 한계 명시

작은 과제: 무료 주문의 배송비가 다시 붙는 오류

가상의 장바구니에서 0원 주문도 명시된 가격으로 취급해야 하는데 기본값 처리 때문에 배송비가 더해지는 상황을 생각해 봅니다. 문제를 “결제 전체를 개선해 달라”로 확장하지 말고 가격 값이 0일 때의 처리 하나로 좁힙니다. 실제 결제 시스템에 적용하기 위한 완성 코드는 아닙니다.

먼저 입력의 단위를 정합니다. 가격은 원 단위 정수이며 null과 undefined는 가격 누락, 0은 유효한 가격이라는 계약입니다. 빈 문자열과 음수는 허용할지 별도로 결정합니다. 모델이 테스트를 만들기 전에 이 계약을 정해야 테스트가 구현을 따라가며 잘못 통과하는 일을 줄일 수 있습니다.

과제 범위 예시
대상: src/cart/price.js의 누락값 기본 처리
재현: 0을 전달했을 때 0 대신 기본 가격이 선택됨
기대: 0은 유지하고 null/undefined에만 기본값 적용
제외: 결제 API, 통화 변환, 장바구니 UI 재설계
검토: 기존 호출부가 빈 문자열을 전달하는지 확인
검증: 0, 양수, null, undefined 케이스와 기존 회귀 검사

수정 계획과 테스트를 읽는 순서

계획에는 현재 기본값 식의 위치, 호출부 입력, 변경할 조건, 실행할 기존 테스트 명령을 적습니다. “전체 리팩터링 후 확인”보다 실패 경계가 명확합니다. 코드가 바뀌기 전에 0을 넣는 재현이 실패하는지 확인하고 수정 뒤 같은 입력으로 다시 확인합니다.

이 예시에서 논리 OR를 nullish coalescing으로 바꾸는 선택이 후보가 될 수 있지만, 모든 호출부가 같은 계약을 쓰는지 먼저 봐야 합니다. 빈 문자열을 누락으로 처리하던 기존 요구가 있다면 연산자 한 개 교체만으로는 충분하지 않습니다. 방법론의 목적은 짧은 수정 자체가 아니라 이 판단을 드러내는 데 있습니다.

도입 여부를 판단하는 실무 기준

스킬이 많다는 사실을 생산성 증가의 증거로 삼지 않습니다. 작은 과제에서 요구 변경 횟수, 관련 없는 diff, 실패 재현의 존재, 검토자가 추가로 물은 내용을 기록해 보세요. 계획서만 길어지고 오류 원인을 좁히지 못한다면 절차를 사용한 목적을 다시 봐야 합니다.

이 글은 Superpowers를 설치해 수행한 벤치마크를 보고하는 글이 아닙니다. 공식 저장소의 방향을 확인하고 독자가 적용할 과제와 검토 산출물을 설계한 개념 설명입니다. 팀의 승인 절차와 사용자의 명시적 작업 범위를 함께 읽어야 하며, 스킬 문서를 권한 통제를 우회하는 수단으로 쓰면 안 됩니다.

관련 학습

• Ponytail 소개: AI 코딩 에이전트에게 게으른 시니어 개발자의 판단을 입히는 도구
• AI 하네스 파일 사용법: AGENTS.md와 Codex 지침 구조 이해하기
• 개발자가 AI 코딩 도구를 쓸 때 생기는 검토 부채 문제

공식 자료와 확인 범위

공식 자료 확인일은 2026-09-13입니다. 제품 설명은 아래 원문을 기준으로 확인했으며, 본문의 판단 표와 가상 과제는 독자가 적용할 수 있도록 구성한 설명입니다.

• https://github.com/obra/superpowers
• https://github.com/obra/superpowers/releases