superpowers claude code — 설계 문서에서 PR까지 한 브랜치, 계획 1,222줄과 리뷰어가 잡은 2건

superpowers claude code, 깔면 무엇이 달라질까. 저희 답은 한 브랜치의 기록입니다.

이 블로그의 레이아웃 개편 하나를 이 플러그인의 스킬로 설계 문서에서 PR까지 끌고 갔습니다.

설계 문서에서 PR까지 한 브랜치를 스킬이 끌고 갔습니다.

잘된 것은 표가 말합니다. 아래는 스킬이 무엇을 해 줬고 어디서 틀렸는지입니다. 계획이 틀린 자리 둘, 완료를 거짓으로 기록한 스크립트 하나, 빌드에서만 드러난 함정 하나.

환경

• Claude Code 2.1.287, superpowers 6.4.1 (공식 마켓플레이스). 스킬 15개 중 이 브랜치에서 7개를 썼습니다
• 작업은 이 블로그의 레이아웃 개편. 머리글과 본문의 폭을 하나로 맞추기, 왼쪽 묶음 트리, 글 머리의 배경 그림, 읽기 진행 막대. Astro 정적 사이트이고 런타임 JS 0은 그대로입니다
• 스펙과 계획은 리서치 레포(비공개)에, 코드는 이 블로그 레포(공개)에 있습니다. PR 번호는 블로그 레포 기준입니다
• 2026년 10월 3일 브레인스토밍부터 10월 5일 고침 PR 머지까지

스킬은 무엇을 바꾸나?

Claude Code의 스킬은 SKILL.md 파일 하나입니다. 앞에 언제 쓰는지가 적혀 있고 뒤에 따라야 할 절차가 적혀 있습니다. Claude가 관련 있다고 보면 알아서 읽고, 사람이 /스킬이름으로 직접 부를 수도 있습니다. 플러그인이 스킬을 묶어 배포하면 이름 앞에 플러그인 이름이 붙습니다.

superpowers는 그런 스킬 15개 묶음입니다.

코드를 더 잘 쓰는 능력이 아닙니다. 순서를 강제하는 문서입니다. 브레인스토밍으로 설계를 확정하기 전에는 코드를 쓰지 못하고, 계획 없이 실행하지 못하고, 실패하는 테스트를 먼저 보지 않으면 구현을 지우라고 합니다.

이 브랜치에서 쓴 일곱 개와 횟수입니다.

리서치 레포에서는 brainstorming만 열두 번 불렀습니다. 가장 많이 쓰는 스킬은 코드를 쓰는 쪽이 아니라 쓰기 전에 묻는 쪽이었습니다.

계획은 무엇을 담았나?

스펙이 164줄이고 계획이 1,222줄입니다.

계획이 스펙의 일곱 배입니다.

그 길이가 어디서 오는지는 단계 하나를 보면 됩니다. 단계마다 할 일, 돌릴 명령, 기대값이 한 묶음입니다. 기대값은 숫자입니다. 머리글의 x 좌표가 몇 픽셀이어야 하는지, 트리의 링크 수가 발행 글 수와 같아야 하는지 같은 것입니다.

작업 7개, 단계 45개.

Review Focus 5개. 테스트가 못 덮는 입력을 계획이 미리 적습니다. 목차가 없는 글, 예약돼서 아직 공개되지 않은 글, 묶음에 글이 하나뿐인 경우, 트리 안 긴 영어 토큰, 제목이 세 줄로 꺾이는 글.

스펙과 다른 결정 6개. 계획을 쓰면서 스펙과 달리 가기로 한 것을 실행 전에 따로 적어 운영자가 봤습니다. 그림의 폭, 산문 페이지의 정렬, 트리 안 글 순서 같은 것입니다.

계획을 쓰는 스킬은 한 가지 원칙 위에 있습니다. 계획이 생각을 끝냈으니 실행은 그대로 옮기라는 것입니다. 그 원칙이 어디까지 맞고 어디서 틀렸는지가 아래입니다.

실행은 어떻게 돌아갔나?

같은 세션이 작업을 순서대로 실행했습니다.

원장 파일이 하나 있습니다. git이 무시하는 폴더에 두고, 작업 하나가 끝나면 스크립트가 테스트를 돌린 뒤 통과했을 때만 완료 줄을 씁니다. 계획과 다르게 간 결정은 Ruling이라는 줄로 남깁니다.

작업이 7개인데 시작 스크립트가 21번 돈 것은 한 작업을 여러 번 다시 잡았기 때문입니다. 완료 스크립트 25번도 같은 이유이고, 그중 한 번은 아래 사고입니다.

압축 2번은 원장이 받았습니다. 압축 뒤 세션이 기억에서 이어 가지 않고 원장을 읽어 어느 작업까지 끝났는지 확인했습니다. 같은 작업을 두 번 한 일은 없었습니다.

계획 커밋이 05시 39분, 마지막 구현 커밋이 06시 13분입니다.

커밋 9개가 34분 안에 있습니다.

그 앞의 브레인스토밍과 스펙은 이틀 전이었습니다.

완료를 거짓으로 기록한 것은 무엇이었나?

완료 스크립트는 작업의 테스트 명령을 돌리고, 통과하면 원장에 완료 줄을 씁니다.

한 작업의 테스트는 헤드리스 크롬으로 페이지의 요소 위치를 재는 탐침이었습니다. 미리보기 서버가 떠 있어야 하는데 그때 서버가 꺼져 있었습니다.

탐침은 모든 선택자에 「(없음)」을 찍고 종료 코드 0으로 끝났습니다.

크롬의 오류 페이지도 load 이벤트를 내기 때문입니다. 접속이 실패했는데 페이지는 로드됐고, 요소는 없고, 스크립트는 성공했습니다. 완료 스크립트는 그 0을 보고 원장에 완료라고 적었습니다.

출력을 읽다가 전부 없음인 것을 보고 알았습니다.

원장의 그 줄을 지웠고, 탐침은 접속 실패를 실패로 끝내게 고쳤습니다. 서버를 띄우고 다시 돌려 완료 줄을 다시 썼습니다.

그 고침은 지금 탐침 파일의 주석으로 남아 있습니다.

검사 스크립트가 접속 실패를 성공으로 돌려주면 원장은 거짓을 성실하게 기록합니다.

리뷰어는 무엇을 잡았나?

실행이 끝난 뒤 새 서브에이전트를 띄워 브랜치 전체를 보게 했습니다. 공식 문서대로 서브에이전트는 새 컨텍스트에서 시작하고 쓴 세션의 대화를 보지 못합니다. 계획, 스펙, Review Focus, 원장의 Ruling 줄을 넘겼습니다.

Important 둘은 둘 다 빌드와 CI 검사 네 종 어디에도 안 걸리는 종류였습니다.

① 카테고리 페이지의 안내문이 색을 잃었다 홈 첫 화면을 옮기면서 계획이 지우라고 한 스타일 규칙 하나를 지웠는데, 그 규칙을 카테고리 페이지 둘도 쓰고 있었습니다. 안내문이 본문색으로, 아래 여백이 20px로 나가고 있었습니다.

② 포커스 링이 잘렸다 배경 그림 컨테이너에 걸어 둔 overflow 가 첫 포커스 대상의 링 왼쪽을 잘랐습니다. 키보드로 다니는 사람만 보는 결함입니다.

둘을 고치는 PR이 커밋 2개로 나갔습니다.

색은 측정값으로 실패를 먼저 보고 고쳤습니다. 링은 헤드리스 크롬에서 재현이 안 돼 계산 스타일로만 확인했고, 그 한계를 PR에 적었습니다.

계획은 어디서 틀렸나?

셋입니다.

① 지우라고 한 규칙이 다른 페이지의 것이었다 위의 Important 1번입니다. 스펙의 스크린샷 대상에 카테고리 페이지가 없었고, 계획은 스펙에서 나왔습니다. 계획대로 했고 계획이 틀렸습니다.

② 한 줄의 숫자가 틀렸다 계획 한 줄이 본문 폭을 720으로 적었습니다. 맞는 값은 680입니다. 리뷰어가 Minor로 잡았습니다.

③ 계획에 없던 함정 스크롤에 따라 움직이는 배경은 CSS 한 줄로 되는데, 빌드의 CSS 압축기가 그 속성을 단축 속성 안에 접어 넣었습니다. 크롬은 단축 안의 그 값을 몰라 선언 전체를 버립니다. 개발 서버에서는 멀쩡하고 검사도 전부 통과합니다. 빌드 산출물을 브라우저에서 돌려 보고서야 보였고, 압축기를 바꿔 고쳤습니다.

계획은 생각을 대신합니다. 산출물을 보는 눈은 대신하지 못합니다.

남는 것

스킬은 능력이 아니라 순서입니다. 설계를 확정하기 전에 코드를 못 쓰게 하고, 실패하는 테스트를 먼저 보게 합니다. 가장 많이 부른 스킬은 쓰기 전에 묻는 쪽이었습니다.

계획은 생각을 끝내지만 눈을 대신하지 못합니다. 틀린 지시 하나, 틀린 숫자 하나, 계획 밖 함정 하나. 셋 다 산출물을 보고서야 잡혔습니다.

완료 기록은 실패도 기록해야 기록입니다. 접속 실패를 종료 코드 0으로 돌려주는 스크립트 하나가 원장에 거짓 완료를 적었습니다. 원장의 기록은 그 아래 명령이 정직한 만큼만 정직합니다.

리뷰는 다른 컨텍스트가 합니다. 쓴 세션은 CI 통과를 봤고 새 컨텍스트는 카테고리 페이지를 봤습니다. Important 2건은 둘 다 검사가 못 보는 자리에 있었습니다.

블로그 레포는 공개라 PR과 커밋 시각은 누구나 셀 수 있습니다. 스펙과 계획 문서는 비공개 레포에 있어 줄 수만 적었습니다.

# 플러그인 설치와 스킬 수
/plugin install superpowers@claude-plugins-official
ls ~/.claude/plugins/cache/claude-plugins-official/superpowers/*/skills | wc -l
# 이 브랜치의 PR 세 개와 커밋 시각
gh pr view 124 --repo wndudtjd/anchorforest-blog --json commits --jq '.commits[] | .committedDate + " " + .messageHeadline'
gh pr view 125 --repo wndudtjd/anchorforest-blog --json commits --jq '.commits | length'
gh pr view 126 --repo wndudtjd/anchorforest-blog --json body --jq '.body' | grep -E 'Critical|Minor'
# 접속 실패를 실패로 끝내게 고친 탐침 (주석에 그날 기록이 있다)
curl -sS https://raw.githubusercontent.com/wndudtjd/anchorforest-blog/main/scripts/layout-probe.mjs | grep -n 'errorText'

자주 묻는 질문

Q. claude code skills 와 플러그인은 뭐가 다른가요?

스킬은 SKILL.md 파일 하나이고 플러그인은 그 파일들을 묶어 배포하는 단위입니다.

플러그인에서 온 스킬은 이름 앞에 플러그인 이름이 붙습니다. superpowers의 brainstorming 은 /superpowers:brainstorming 입니다. 직접 만든 스킬은 레포의 .claude/skills/ 아래에 두면 그 레포에서만 읽힙니다.

Q. claude code 서브에이전트는 언제 쓰나요?

이 브랜치에서는 한 번, 리뷰에만 썼습니다.

작업마다 서브에이전트를 띄우는 방식도 스킬에 있지만 저희는 같은 세션이 실행하고 끝에 한 번 새 컨텍스트로 보게 했습니다. 비용이 작고, 쓴 세션이 못 보는 것을 보는 데는 한 번으로 충분했습니다. Important 2건이 그 한 번에서 나왔습니다.

Q. claude code 워크플로우를 매번 다 돌리나요?

아닙니다.

레이아웃 개편처럼 파일 여럿을 함께 바꾸는 일에만 브레인스토밍에서 리뷰까지 다 돌립니다. 한 줄 고침은 바로 고치고, 글을 쓰는 일은 별도의 글쓰기 가이드 문서가 그 자리를 맡습니다. 스킬이 길을 정하는 것은 길을 잃을 만큼 긴 일일 때입니다.

Q. superpowers 설치는 어떻게 하나요?

공식 마켓플레이스에서 한 줄입니다.

/plugin install superpowers@claude-plugins-official

설치하면 세션이 시작할 때 using-superpowers 스킬이 먼저 읽히고, 그 스킬이 나머지를 언제 부를지 정합니다.

참고 자료

• Extend Claude with skills 는 스킬이 SKILL.md 파일이고 Claude 가 알아서 쓰거나 /스킬이름으로 부른다는 것, 플러그인 스킬에 플러그인 이름이 붙는다는 것의 근거입니다.
• Create custom subagents 는 서브에이전트가 새 컨텍스트에서 시작해 쓴 세션의 대화를 보지 못한다는 것의 근거입니다.
• obra/superpowers 는 스킬 묶음의 구성과 브레인스토밍에서 마무리까지의 순서, MIT 라이선스의 근거입니다.
• 블로그 레포 PR #126 은 리뷰어가 잡은 Important 2건과 미룬 Minor 8건의 기록입니다.
• scripts/layout-probe.mjs 는 접속 실패를 실패로 끝내게 고친 탐침이고, 주석에 그날의 거짓 통과가 적혀 있습니다.
• codex vs claude code 글 과 claude code 세션 이어서 글 은 같은 운영의 다른 두 면입니다.

이 사이트의 수치는 주 1회 DB와 다시 대조하고, 판단이 바뀌면 지우지 않고 글 안에 덧붙입니다. 갱신은 RSS로 받을 수 있습니다.