포스트

AI 코딩이 바로 구현부터 시작한다면: obra/superpowers 작업 규율

AI 코딩 에이전트가 요구사항을 확인하기 전에 구현부터 시작한다면, obra/superpowers는 브레인스토밍, 계획, 테스트, 마무리 순서를 명시하는 작업 규율로 검토할 만합니다. 이 저장소는 모델의 지능을 바꾸기보다 에이전트가 따라야 할 절차를 스킬로 제공해 성급한 구현과 근거 없는 완료 보고를 줄이려 합니다. 효과는 스킬 이름이나 절차 수가 아니라 실제 diff와 테스트 품질로 판단해야 합니다.

Superpowers는 모델이 아니라 무엇을 바꾸는가?

이 저장소의 초점은 새 모델이나 새 코딩 도구가 아닙니다. 에이전트가 언제 질문하고, 언제 계획을 쓰며, 어떤 검증을 거쳐 작업을 끝낼지 스킬 형태로 정의합니다. 원문이 소개한 흐름은 /brainstorm, /plan, /finish로 이어지며, 테스트 주도 개발과 명세 확인을 그 사이에 배치합니다.

가치는 결과를 자동으로 정답으로 만드는 데 있지 않습니다. 구현 전에 모호한 요구를 드러내고, 변경 범위를 쪼개고, 끝났다는 주장 앞에 테스트와 diff 확인을 두는 데 있습니다. 즉흥적인 대화보다 반복 가능한 체크리스트가 필요한 팀에 더 잘 맞습니다.

예를 들어 “로그인을 개선해 달라”는 요청은 곧바로 코드를 고치기에는 범위가 넓습니다. 브레인스토밍 단계에서는 어떤 사용자의 어떤 실패를 줄일지 묻고, 계획 단계에서는 손댈 파일과 검증할 동작을 나누며, 완료 단계에서는 처음 합의한 조건이 테스트와 결과에 반영됐는지 확인합니다. 절차의 목적은 더 긴 답변이 아니라, 모호한 결정을 코드 변경 전에 드러내는 것입니다.

반대로 한 줄짜리 오탈자처럼 요구와 검증이 이미 명확한 작업에 같은 길이의 브레인스토밍을 적용하면 비용만 늘 수 있습니다. 팀은 모든 스킬을 항상 호출하기보다, 위험도와 모호성에 따라 필요한 단계를 선택할 수 있는지 확인해야 합니다. 절차가 판단을 돕지 못하고 형식적인 문서만 늘린다면 도입 목적과 어긋납니다.

SKILL.md에서 어떤 지침을 먼저 확인해야 할까?

스킬은 “이름이 멋진가”보다 다음 내용을 실제로 요구하는지 읽어야 합니다.

  • 발동 조건과 발동하지 말아야 할 조건이 구분되어 있는가
  • 계획 단계가 구현 파일과 검증 방법까지 구체화하는가
  • 테스트 실패나 요구 충돌이 생겼을 때 중단 경로가 있는가
  • 완료 단계에서 테스트 결과와 변경 내역을 직접 확인하는가

TDD라는 단어가 들어 있어도 에이전트가 의미 있는 실패 테스트를 작성했다는 보장은 없습니다. 생성된 테스트가 구현을 그대로 복제하거나 중요한 예외를 건너뛰는지 사람이 살펴야 합니다.

발동 조건은 특히 중요합니다. 너무 넓으면 단순 질문에도 구현 절차가 끼어들고, 너무 좁으면 위험한 변경에서 검증 단계가 생략됩니다. 스킬끼리 충돌할 때 어떤 지침을 먼저 따를지, 필요한 정보가 없을 때 질문하고 멈추는지도 실제 작업 안정성에 영향을 줍니다.

계획의 품질은 항목 수보다 검증 가능성으로 판단할 수 있습니다. “기능을 구현한다”는 계획은 완료 여부를 판별하기 어렵지만, 어떤 동작을 어떤 테스트로 확인할지 적으면 실패를 드러낼 수 있습니다. 완료 스킬 역시 “테스트했다”는 문장만 요구하기보다 실행 결과와 변경 범위를 확인하게 하는지 읽어야 합니다.

설치 명령을 그대로 실행해도 될까?

아래 명령은 원문에 실린 OpenCode 구성 예시입니다. 현재 버전의 보편적인 설치법이 아니라 특정 디렉터리 구조를 전제로 한 스냅샷입니다. OpenCode가 이미 설치되어 있어야 하고, 대상 경로가 존재하면 clone이나 심볼릭 링크 생성이 실패할 수 있습니다.

1
2
3
4
5
6

mkdir -p ~/.config/opencode
git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
mkdir -p ~/.config/opencode/plugins
mkdir -p ~/.config/opencode/skills
ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/opencode/plugins/superpowers.js
ln -s ~/.config/opencode/superpowers/skills ~/.config/opencode/skills/superpowers

실행 전에는 저장소의 현재 안내와 로컬 경로를 대조해야 합니다. Claude Code와 OpenCode의 설정 위치를 같은 것으로 가정하거나, 기존 디렉터리를 덮어쓰면 안 됩니다.

이 명령은 저장소를 특정 위치에 복제하고 플러그인과 스킬 경로에 심볼릭 링크를 만듭니다. 따라서 먼저 대상 디렉터리에 기존 설정이 있는지, 링크가 가리킬 파일이 실제로 존재하는지 확인해야 합니다. 조직 환경이라면 가져온 코드와 지침을 검토하고 버전을 고정할지 결정하는 과정도 필요합니다.

설치 성공과 동작 성공도 구분해야 합니다. 링크가 만들어졌어도 도구가 해당 위치를 읽지 않거나 스킬 발동 조건을 인식하지 못할 수 있습니다. 작은 테스트 요청에서 어떤 스킬이 왜 발동했는지 확인한 뒤 실제 저장소에 적용하는 편이 안전합니다.

팀 도입 효과를 어떻게 작은 작업으로 검증할까?

먼저 요구가 명확하고 테스트 가능한 작은 변경 하나를 고릅니다. 같은 작업을 기존 방식과 스킬 적용 방식으로 수행한 뒤 질문 수, 계획 수정 횟수, 실패 테스트의 질, 최종 diff의 불필요한 변경을 비교하면 됩니다. 작업 시간이 길어졌는데 결함이 줄지 않았다면 절차가 과하거나 팀 환경과 맞지 않는 것입니다.

비교 작업은 결과 난도가 비슷해야 합니다. 한쪽에는 익숙한 수정, 다른 쪽에는 복잡한 신규 기능을 주면 절차의 효과와 과제 차이를 분리할 수 없습니다. 같은 요구사항과 같은 테스트 환경에서 누락된 조건, 재작업 횟수, 사람이 검토하는 시간을 함께 기록하는 편이 좋습니다.

실패 조건도 미리 정합니다. 계획이 실제 변경과 계속 어긋나거나, 테스트가 구현 세부사항만 확인하거나, 모든 작업에 불필요한 승인 단계가 붙는다면 스킬 구성을 줄이거나 수정해야 합니다. 반대로 요구 누락과 무관한 diff가 줄고 완료 근거가 명확해진다면 팀 규율로서 가치가 있습니다.

Superpowers는 에이전트에게 파일 권한이나 실행 도구를 새로 주지 않으며, 저장소의 코드와 지침을 신뢰할 수 있게 만들어 주지도 않습니다. 설치 전 내용을 검토하고, 제한된 권한과 별도 브랜치에서 시험하며, 완료 보고보다 실제 테스트 로그와 변경 내역을 우선해야 합니다.

결론적으로 이 저장소가 맞는 팀은 AI 코딩의 속도보다 과정의 재현성과 검토 근거가 필요한 팀입니다. 이미 짧고 엄격한 자체 절차가 잘 작동한다면 중복 여부부터 확인해야 하고, 절차가 없어서 같은 실수가 반복된다면 작은 작업으로 검증할 이유가 있습니다. 채택 여부는 에이전트가 더 자신 있게 말하는지가 아니라 사람이 더 쉽게 오류를 발견하고 되돌릴 수 있는지로 결정해야 합니다.

브레인스토밍, 계획, 완료 단계마다 무엇을 남겨야 할까?

브레인스토밍의 산출물은 장황한 아이디어 목록이 아니라 결정해야 할 질문과 채택한 범위입니다. 사용자가 원하는 동작, 바꾸지 말아야 할 동작, 확인한 가정을 남기면 이후 구현이 목표에서 벗어났는지 비교할 수 있습니다. 중요한 질문에 답하지 못한 상태라면 코드를 쓰기보다 중단하는 것도 올바른 결과입니다.

계획은 실제 파일과 검증 방법에 연결돼야 합니다. 각 단계가 어느 동작을 바꾸고 어떤 테스트가 먼저 실패해야 하는지 적으면 구현을 끝낸 뒤 계획을 거꾸로 맞추기 어렵습니다. 작업 중 예상과 다른 구조를 발견했다면 계획을 조용히 무시하지 말고 수정 이유와 새 검증 방법을 남겨야 합니다.

완료 단계에서는 테스트 명령의 종료 상태, 변경된 파일, 남은 위험을 확인합니다. 테스트가 통과했어도 요구하지 않은 파일이 바뀌었거나 사용자 동작을 놓쳤다면 끝난 작업이 아닙니다. 테스트할 수 없는 조건이 있다면 성공이라고 단정하지 말고 무엇을 확인하지 못했는지 명시해야 합니다.

세 산출물이 서로 연결되는지가 판단 기준입니다. 처음 합의한 조건이 계획의 테스트가 되고 그 결과가 완료 근거로 이어지지 않는다면 스킬은 형식만 추가한 것입니다. 작은 작업에서 이 연결을 검토한 뒤 팀 전체 적용 여부를 결정하는 편이 안전합니다.

팀 규칙과 스킬 지침이 충돌할 때의 우선순위도 정해야 합니다. 저장소의 테스트 명령, 리뷰 요구, 보안 제한을 외부 스킬이 덮어쓰면 절차를 추가한 것이 오히려 기존 통제를 약화시킬 수 있습니다. 파일별 지침과 프로젝트 문서를 먼저 읽고, 충돌을 발견하면 자동으로 선택하기보다 사람에게 드러내야 합니다.

스킬 버전을 올릴 때는 같은 대표 작업을 다시 실행합니다. 이름이 같아도 발동 조건이나 완료 기준이 바뀌면 질문 수와 diff 범위가 달라질 수 있습니다. 검토한 커밋과 설정을 기록하고 예상 밖의 행동이 생기면 이전 버전으로 돌아갈 수 있어야 합니다.

마지막으로 절차 준수율과 결과 품질을 분리합니다. 에이전트가 모든 단계를 말로 언급했어도 실패 테스트가 없거나 실제 diff를 보지 않았다면 준수했다고 볼 수 없습니다. 반대로 간단한 작업에서 일부 형식을 생략했어도 핵심 위험을 검증했다면 불필요한 단계를 줄일 근거가 됩니다.

팀은 이런 예외를 문서화해 다음 작업자가 같은 판단을 반복하지 않게 해야 합니다. 예외가 기본값이 되면 스킬의 통제 효과도 사라집니다.

함께 읽으면 이해가 이어지는 글

THE END / OPSOAI

여기까지 읽었습니다

핵심 장면을 한 번 더 떠올려 보세요. 이해가 남았다면 이 책은 제 역할을 다했습니다.

다른 책 고르기
표지 1 —

←→ 키와 좌우 스와이프를 지원합니다. 읽던 페이지는 이 기기에 저장됩니다.

CONTENTS

이 책의 목차

    6개 장 18 분읽는 시간