Superpowers는 AI 코딩 에이전트에 설계·구현·검증 절차를 어떻게 적용하나요?
Superpowers는 AI 코딩 에이전트가 설계·구현·검증 같은 개발 절차를 따르도록 돕는 방법론 사례입니다. 절차를 사용했다는 말보다 실제 계획, 변경 내용, 검사 결과가 남았는지를 확인하세요.
적용 조건·범위: Superpowers는 과정 필수 조건이 아닙니다. 설치하지 않으면 아래 절차를 수동 체크리스트로 사용합니다. 설치할 때는 호스트별 방식이 다르므로 원저장소 README를 기준으로 선택합니다.
본문 근거: 원저장소 README
핵심 기준
개발 방법론을 에이전트에 적용한다는 것은 프롬프트를 길게 만드는 일이 아니라 작업을 작은 단계로 쪼개고 각 단계의 완료 조건과 검증을 고정하는 것입니다. 도구가 바뀌어도 이 구조는 재사용할 수 있습니다.
요구사항
→ 계획
→ 작은 구현
→ 검증
→ 리뷰
→ 다음 작은 구현
AI 도구는 결과를 대신 책임지는 주체가 아닙니다. 사람이 작업 목표와 승인 기준을 정하고, 도구는 그 범위 안에서 탐색·수정·검증을 수행하는 구조로 보는 편이 안전합니다.
실무에 적용하는 순서
작은 버그 수정 하나를 선택해 다음 순서로 수행합니다.
문제 정의 → 재현 → 계획 → 최소 수정 → 테스트 → 리뷰 → 완료.
superpowers를 사용할 수 없는 환경에서도 동일한 순서를 수동 체크리스트로 재현할 수 있게 작성합니다.
작업을 시작할 때는 다음 정보를 짧게 고정합니다.
목표:
현재 상태:
허용 범위:
금지 범위:
완료 조건:
검증 방법:
실패 시 복구점:
이 문서가 있으면 대화가 길어져도 에이전트가 현재 위치를 다시 확인할 수 있습니다.
선택 설치와 최소 동작 확인
이 글은 선택 참고 학습입니다. 미설치 상태에서도 원리를 학습할 수 있고 필수 학습 경로는 6회차 → 9회차입니다. 7·8회차를 수행한 경우에만 해당 기록을 추가로 참고합니다.
Superpowers는 과정 필수 조건이 아닙니다. 설치하지 않으면 아래 절차를 수동 체크리스트로 사용합니다. 설치할 때는 호스트별 방식이 다르므로 원저장소 README를 기준으로 선택합니다.
Claude Code에서는 다음을 대화창에 입력하는 설치 방식이 제공됩니다.
/plugin install superpowers@claude-plugins-official
Codex 앱에서는 Plugins의 Superpowers를 선택하고 안내에 따라 설치합니다. CLI에서는 /plugins에서 Superpowers를 검색해 Install Plugin을 선택합니다. Cursor는 Agent 대화에서 /add-plugin superpowers를 제공합니다. 설치 후 새 작업에서 적용할 스킬과 절차를 설명하게 해 인식 여부를 확인합니다. 실제 설치와 활성화 화면은 이 본문 검수에서 실행하지 않았습니다.
직접 해볼 일 · 입력과 검토 기준
독자 질문: Superpowers 없이도 단계화의 이점을 확인할 수 있을까?
실습: 작은 필터 버그 하나를 재현→원인 가설→최소 수정 계획→테스트→리뷰 순서로 종이에 먼저 적으세요. 플러그인 설치는 선택입니다.
입력 예시: 완료 항목 숨기기 후 빈 목록 안내가 안 보입니다. 먼저 재현 절차와 기대 결과를 적고 관련 파일을 찾으세요. 수정 전 확인할 실패 조건, 허용 범위, 검증 방법을 제시한 뒤 승인받은 범위만 바꿔 주세요.
결과 검토: 재현이 실제인지, 계획과 diff가 일치하는지, 테스트가 실패 상태를 먼저 잡고 수정 후 통과했는지 확인합니다. 설치·호스트 지원은 obra/superpowers 저장소의 해당 환경 안내를 확인합니다.
수정 요청: 재현 없이 대규모 수정으로 넘어갔다면 변경을 보류하고 재현 가능한 가장 작은 사례부터 다시 작성합니다.
다음 학습: 8회차에서 같은 버그를 과도한 구현 없이 해결하는 안을 비교합니다.
확인 범위: 공식 자료 github.com를 대조했습니다. 이 글의 AI 도구 조작·저장소 변경·명령 실행은 편집자가 직접 수행하지 않았으므로 미확인입니다. 독자는 자신의 환경에서 결과를 기록해 주세요.
독립 실습: 재현부터 시작하는 버그 수정
“빈 입력을 넣으면 검색 결과가 사라진다”는 가상 버그를 정하고 기대 동작·재현 순서·관찰 결과부터 적습니다. 그다음 허용 파일, 최소 수정 계획, 검증 방법을 순서대로 정합니다. 테스트 환경이 있으면 실패 재현과 수정 후 성공을 비교하고, 없다면 재현 절차와 도입 필요성을 먼저 합의합니다.
가상 입력은 검색어가 빈 문자열인 경우이며 기대 동작은 전체 목록 유지입니다. 재현 기록 → 기존 검색 함수 확인 → 최소 변경 계획 → 빈 입력과 일반 입력 재확인의 순서가 결과물입니다. 플러그인을 설치하지 않아도 이 문서를 만들 수 있으며 설치 여부와 버그 수정 성공은 다른 결과입니다.
자주 발생하는 오류와 해결
워크플로우가 작은 문구 수정에도 과도한 설계를 요구하면 프로젝트 지침과 작업 규모에 맞춰 범위를 줄입니다. 병렬 작업은 독립 파일과 명확한 책임이 있을 때만 사용합니다. 설치 성공 자체를 코드 품질이나 테스트 통과로 기록하지 않습니다.
선택 실습: 같은 프로젝트로 연습하기
이 선택 실습은 TaskFlow 작업 관리 앱의 변경 요청을 AI와 함께 검토하는 연습입니다. 요청·코드·검증 결과를 구분해 기록합니다.
이번 주제: obra superpowers 소개 AI 코딩 에이전트에 개발 방법론을 입히는 방식.
선택: 연재 프로젝트와 전체 자료
연재 프로젝트를 이어 만드는 분을 위한 자료입니다. 이 글의 개념과 예제만 찾으셨다면 필요한 파일과 실행 방법만 펼쳐보세요.
TaskFlow 누적 적용
이어서 읽기: AI 에이전트가 실패하는 진짜 이유 모델 성능보다 상태 관리가 먼저다. 누적 작업 기록은 docs/ai-log.md에 회차별로 추가합니다. 새로 진입하면 실제 개발환경 시작 ZIP을 별도 폴더에 풉니다. 이 앱에는 상태 문구와 API URL 표시가 있으며 작업 목록·검색·완료 필터는 없습니다. 상단의 필터 예시는 독립 설계 문제이고, 현재 앱에서 그대로 실행된 기능으로 기록하지 않습니다.
Before: AI가 바로 코드를 수정
After: 설계/계획/실행/검증/리뷰가 분리된 작업 기록
변경 전후에는 Git을 기준으로 실제 결과를 확인합니다.
git status --short
git diff --stat
git diff
테스트나 build를 실행했다면 성공 여부뿐 아니라 어떤 명령을 실행했는지도 로그에 남깁니다. 외부 서비스가 필요한 검증은 실제로 실행하지 못했다면 미검증으로 표시합니다.
평가와 중단 기준
- superpowers를 필수 도구처럼 제시하지 않음
- 설치만으로 코드 품질이 보장된다고 설명하지 않음
- TDD·리뷰 규칙은 프로젝트 상황에 맞춰 적용
- 현재 저장소 문서와 실제 지원 환경을 본문 작성 시 재검증
에이전트가 더 많은 작업을 할 수 있다는 이유만으로 계속 진행하지 않습니다. 완료 조건을 충족했다면 멈추고 사람이 diff를 확인하는 것이 다음 단계입니다.
완료 체크리스트
- 도구 소개보다 워크플로우 원리가 중심
- TaskFlow 없이도 재현 가능한 독립 예제 포함
- 다음 회차에서 과도한 구현을 줄이는 판단 기준으로 연결
누적 기록과 실행 결과
이전 회차 ai-step-06-state-recovery에 남긴 기록을 시작점으로 사용합니다.
현재 구조는 기존 TaskFlow 소스와 package.json을 유지하고, 학습 기록은 새로 만드는 docs/ai-log.md에 누적합니다. 이 경로는 앱 실행 파일이 아닌 실습용 기록 위치입니다. 기존 동명 파일이 있으면 덮어쓰지 않고 회차 항목을 추가합니다. 앱 수정 파일은 저장소 탐색 후 계약에 확정하며 문서의 예시 경로를 실제 파일로 가정하지 않습니다.
Before는 해당 회차의 기록 항목이 없는 상태이고, 적용은 위 실습을 수행하며 관찰 내용을 채우는 과정입니다. After는 아래 항목의 근거와 미검증 범위가 남은 상태입니다. 문서 제목을 바꾸는 것만으로 기능 구현이 완료된 것은 아닙니다.
아래는 docs/ai-log.md에 추가하는 회차 항목 전체입니다. 앱 전체 코드가 아닌 개발 로그 양식이며, 빈칸은 직접 확인한 결과로 채웁니다.
체크포인트: ai-step-07-superpowers
작업 요청 / 목표 / 비목표:
시작 상태 / 적용 지침:
허용 파일 / 실제 변경 파일:
계획 / diff 요약:
실행 명령 / 실제 결과 / 증거 위치:
미검증 항목 / 필요한 조건:
사람이 확인·수정한 내용:
승인 여부 / 승인 대상:
commit: 미생성 또는 실제 확인한 식별자
실패 지점 / 복구점 / 다음 행동:
검증란은 성공·실패·미실행을 구분합니다. 이 양식 자체는 실행 성공이나 사람 승인 증거가 아닙니다. 앱을 바꿨다면 diff → pnpm lint·pnpm build → 필요한 브라우저 확인 → 사람 검토 → 승인 → commit 순서로 기록합니다. 로그만 편집한 단계는 내용 대조가 검증이며 앱 테스트 통과로 부풀리지 않습니다.
완료 체크포인트
ai-step-07-superpowers
다음 학습
8회차 Ponytail 소개: AI 코딩 에이전트의 과도한 구현 줄이기
제품 기능이나 명칭은 바뀔 수 있으므로 발행 시점에는 해당 도구의 공식 문서와 실제 UI를 다시 확인합니다.
글 소개·학습 준비·전체 목차
AI 코딩 도구 · 7 / 11
obra superpowers 소개 AI 코딩 에이전트에 개발 방법론을 입히는 방식
앞서 수동으로 수행한 설계 확인·계획·테스트·디버깅·리뷰 절차를 에이전트용 워크플로우로 묶는 사례로 superpowers를 다룹니다. 특정 프레임워크 사용 자체가 목표가 아니라 AI 작업을 단계화하는 설계 원리를 배우는 회차입니다.
선수 지식
AI 코딩 도구 하나를 사용할 수 있으면 됩니다. 플러그인 설치는 선택입니다.
이번 글에서 배우는 내용
- 코딩 전 요구사항·설계 확인
- 구현 계획과 실행 분리
- 테스트와 디버깅 단계를 명시적으로 강제하는 이유
- subagent 또는 병렬 작업 시 책임 범위 분리
- 코드 리뷰와 완료 판정
- 자동 워크플로우가 인간 승인 지점을 없애지 않는 이유
- 프로젝트 버전·설치·지원 호스트는 작성 시점 공식 저장소 확인
목차
이 글이 도움이 되었나요?
읽음 기록
읽음 — / 전체 11개 · 필수 9개
새 글 받아보기
RSS 리더에서 BlogFlow의 새 글을 확인할 수 있습니다.
