Superpowers가 커밋한 AI 스펙, ADR처럼 관리하라

Superpowers는 스펙과 구현 계획을 마크다운 파일로 작성하고 저장소에 커밋하는 스킬을 가진 Claude Code 플러그인(GitHub 스타 286,000개)이다. 기본값으로는 이런 파일 전부가 docs/superpowers/ 라는 폴더 하나에 쌓인다. 지난 6월, 파이썬 금융 라이브러리 Okama의 메인테이너들은 에이전트가 그곳에 작성한 구현 계획 8개가, 플러그인이 의도한 그대로 커밋된 채로, Read the Docs에 공개 웹페이지로 렌더링되어 있었다는 것을 발견했다. 발견한 시점은 릴리스가 나간 뒤였다.

이제 이걸 키워보자. 프런트엔드 팀 개발자 10명, 스쿼드 4개, 저장소 하나, 그리고 모든 개발자가 이런 파일을 만들어낸다. 세 가지 질문이 리드의 책상에 떨어진다. 정확히 무엇을 버전 관리할 것인가? 두 스프린트 전에 지운 경로를 스펙이 가리키고 있을 때 드리프트는 문제인가? 그리고 이 폴더는 누가 관리하는가? Okama의 유출은 커밋했기 때문에 일어난 게 아니다. 규칙 없이 커밋했기 때문에 일어났다. 이 글은 다섯 가지 규칙을 제시한다.

Superpowers는 커밋할지 물어보지 않는다. 이 플러그인의 plan 스킬 18번째 줄은 모든 계획을 docs/superpowers/plans/ 아래에 날짜와 함께 기능당 파일 하나로 저장한다. brainstorming 스킬은 설계 문서를 작성하고 같은 단계에서 그것을 커밋하는데, 이는 리드가 그 계획을 보기도 전이다.

이건 Superpowers만의 특이한 습관이 아니다. 스펙 주도 방식의 주요 툴들은 모두 같은 선택을 한다.

Tool	Publisher	Where specs live
Superpowers (286,000 stars)	obra	docs/superpowers/, 모든 것이 담기는 폴더 하나
Spec Kit (136,000 stars)	GitHub	기능당 번호가 붙은 폴더 하나, 해당 기능의 브랜치 위에
Kiro	Amazon	.kiro/specs/, 기능당 폴더 하나
AI-native SDLC playbook	Anthropic	단계마다 커밋되는 산출물 하나: 의도, 스펙, 계획, diff, 리뷰 결과, 인시던트 기록

Kiro는 기능별 폴더를 팀원들이 여러 기능을 동시에 작업할 수 있게 해주는 방식으로 판다. 8월에 공개된 Anthropic의 플레이북은 한발 더 나간다. 모든 단계가 다음 단계가 읽을 수 있는 산출물을 커밋한다. 그러니 커밋할지 여부는 애초에 질문이 아니었고, 어디에 저장할지는 모든 툴이 답을 갖고 있다. 파일을 누가 소유하는지, 그리고 그것이 언제 죽은 것인지는 답이 없다. 그 공백을 다섯 가지 규칙이 채운다.

커밋된 계획이 실패하는 방식은 세 가지로 갈린다.

실패 1: 문서 생성기. docs/ 아래 모든 마크다운 파일을 목차에 실렸는지와 무관하게 렌더링하는 문서 빌드는 계획 폴더까지 매뉴얼과 함께 배포해버린다. Okama에서 실제로 일어난 일이 바로 이것이다.

실패 2: 브랜치. Superpowers 이슈 1246은 brainstorm이 계획을 곧바로 main에 커밋한다고 보고한다. 한 사용자는 세션당 10~15개의 커밋을 센다고 하며, 몇 번의 변경마다 새 커밋이 생긴다. 그 스레드의 요청은 한 줄로 정리된다: main 브랜치에는 계획과 스펙을 두지 말 것.

실패 3: 드리프트. 스펙 드리프트는 조용한 실패다. 코드는 진화하고 스펙은 그대로 남는다. Thoughtworks의 Birgitta Böckeler는 스펙 주도 개발의 세 단계를 이름 붙인다.

Level	Meaning
Spec-first	작성되고 한 번만 쓰인다
Spec-anchored	그 기능이 살아있는 동안 유지·관리된다
Spec-as-source	사람은 오직 스펙만 수정한다

Superpowers는 spec-first 문서를 작성하고 그것을 영원히 보관한다. 기본값으로는 spec-anchored 저장 방식에 초안 수준의 유지보수가 붙는 셈이다. 아무도 파일을 업데이트하지 않고, 에이전트는 다음 분기에 그것을 진실로 읽는다. TrueFoundry는 이를 명료하게 말한다. 드리프트는 spec-first 방식에서는 피할 수 없고 spec-anchored 방식에서는 관리 가능하지만, 그 편차를 감지할 수 있을 때에만 그렇다.

스펙 41개와 에이전트 파일 9개를 가진 저장소는 정돈 문제를 가진 게 아니다. 버전 관리되지 않는 41개의 동작 입력값을 가진 것이다. Böckeler 본인의 반응은 이렇다. 그녀는 이 모든 마크다운 파일보다는 코드를 리뷰하고 싶다고 말한다. 다시 열어보지 않는 계획은 잡음이다. 에이전트가 읽는 계획은 지시다. 그리고 오래된 지시는 잘못된 지시다.

규칙 1: 폴더에는 소유자가 있고, 그 소유자는 플러그인이 아니라 스쿼드다. 버전 5부터 Superpowers는 프로젝트의 CLAUDE.md에 담긴 지시를 자기 기본값보다 우선시한다. 계획이 어디로 가야 하는지 말해두면 그곳으로 간다.

다만 경로를 나열한 표만으로는 부족하다. 이슈 939에서 한 사용자는 출력 경로 표를 작성했지만, 모델은 스킬에 박힌 구체적 경로를 따랐고 그 표는 건너뛰었다. 스킬 자체의 오버라이드 안내문은 괄호 하나로 처리돼 있다. 굵게 강조한 명령형 한 줄이 첫 시도에 문제를 고쳤다. 스펙은 반드시 여기에 저장하라, 저기가 아니라, 그리고 피해야 할 대상으로 기본 경로를 명시하는 방식으로.

레이아웃은 스쿼드(체크아웃, 검색, 계정, 디자인 시스템)당 폴더 하나이며, 각각 자기 스펙과 계획을 가진다. 모노레포에서는 그 한 줄을 해당 패키지 자체의 CLAUDE.md에 넣는다. Claude Code는 하위 디렉터리를 읽을 때 그 디렉터리의 파일을 온디맨드로 로드하며, 문서에는 각 디렉터리의 소유자가 보통 자기 파일을 관리한다고 적혀 있다. 플러그인을 설치하지 않은 엔지니어는 영향을 받지 않는다. 이 한 줄은 스킬이 저장 위치를 물을 때만 작동한다.

그다음엔 플랫폼이 소유권을 강제하게 둔다. 스쿼드 폴더당 CODEOWNERS 한 줄이면, 모든 스펙 리뷰가 그것과 함께 살아갈 사람들에게 도달한다. 한 가지 주의점: 이 오버라이드는 설정이 아니라 프롬프트다. 플러그인이 릴리스될 때마다 첫 스펙을 확인하라.

규칙 2: 모든 계획이 팀의 산출물은 아니다. Superpowers에 설정 가능한 저장 위치를 처음 요청한 사람(이슈 337)은 이렇게 정리했다. 계획 파일은 프로젝트 산출물이 아니라 개인의 작업 문서일 수 있다.

개인용 쪽에는 이미 그것을 위한 파일이 있다. CLAUDE.local.md는 공유 파일 옆에 있고 그 뒤에 로드되며, 문서는 이를 직접 git-ignore 하라고 안내한다. 개인 폴더로의 리다이렉트는 여기 두면 아무도 못 본다. 폴더 자체에 대해서는, Git에는 공유 트리를 절대 건드리지 않는 무시 파일이 있다. .git/info/exclude는 클론별로 존재하고 절대 커밋되지 않으며 풀 리퀘스트도 필요 없다. 플러그인은 이미 자신의 스크래치 공간에 이 방식을 쓴다. 버전 6.0.3부터 그 작업 디렉터리는 자기 안에 *만 담긴 .gitignore를 떨어뜨려서, 추적되는 파일을 건드리지 않고 스스로를 숨긴다.

공유 쪽은 brainstorm이 이미 실행하는 리뷰 게이트를 통과한 모든 것이다. 스펙 작성, 리뷰 요청, 다른 사람의 승인. 승인되면 스쿼드 폴더로 옮긴다. 승인되지 않으면 개인 영역에 남는다. 둘 다 브랜치 위에서 작성하며, 절대 main에서 쓰지 않는다. 공유 CLAUDE.md의 두 줄이 이를 해낸다: 스펙과 계획을 기능의 시작으로 취급하라, 그리고 그것을 작성하기 전에 워크트리를 만들어라.

한 가지 한계: git-ignore된 계획은 이동하지 않는다. Okama의 메인테이너들은 처음에 그 폴더 자체를 무시하려 했다가 되돌렸다. 계획이 기기와 에이전트 사이에서 동기화되지 않았기 때문이다. 개인용은 개인용으로 남는다.

규칙 3: 스펙에는 상태가 있고, 죽은 스펙은 그것을 밝힌다. 이 아이디어는 15년 됐다. 2011년 Michael Nygard는 아키텍처 결정 기록(ADR)을 저장소에 번호 붙은 파일 하나씩 보관하자고 제안했다. 결정은 제안되고, 그다음 채택된다. 이후 다른 기록이 그것을 바꾸면, 예전 기록은 deprecated 혹은 superseded로 표시되고 대체본을 참조한다. 결정이 뒤집히더라도 예전 기록은 지우지 않고 superseded로 표시한 채 남긴다.

이를 스펙에 적용하면, 공유되는 모든 스펙은 에이전트가 이미 읽고 있는 다섯 줄짜리 헤더로 시작한다.

Field	Purpose
status	proposed, accepted, superseded
superseded-by	대체하는 스펙
owner	담당 스쿼드
touches	스펙이 주장을 담고 있는 경로들
review date	마지막으로 확인한 시점

채택된 스펙을 다른 결정으로 고쳐 쓰지 않는다. 다음 스펙을 새로 쓰고 그것이 예전 것을 가리키게 하면 히스토리는 정직하게 남는다. 예외 하나는 Anthropic의 플레이북에 나온다. 구현이 계획에서 벗어날 때는 같은 커밋에서 계획을 함께 업데이트한다. 계획은 그것을 깨뜨린 diff와 함께 이동하며, 훅이 이를 강제할 수 있다.

Spec Kit은 스펙이 살아가는 세 가지 방식을 이름 붙인다. Flow-forward: 기능마다 새 폴더를 만들고, 예전 것은 히스토리로 남긴다. Living spec: 스펙이 곧 계약이고 나머지는 재생성된다. Flow-back: 빌드가 스펙의 모양을 다시 바꾼다. 이들의 규칙은 하나다. 스펙이 여전히 다른 걸 말하고 있다면 그 상태를 태스크나 코드에 남겨두지 말 것. 이건 의도적으로 spec-anchored를 선택하는 것이다.

한계: 상태는 사람이 설정하는 메타데이터다. CLAUDE.md가 지시하지 않는 한 에이전트는 자기 스펙을 스스로 superseded로 표시하지 않으며, 그렇게 하더라도 리뷰가 이를 알아차려야 한다.

규칙 4: 트리에 대해 거짓말을 하는 스펙은 빌드를 실패시킨다. 이 문제에 이름을 붙인 6월에 발표된 논문은 이를 silent spec-code drift라 부른다. 코드는 진화하고 스펙은 그대로 남으며, 그 편차는 고치는 비용이 커질 때까지 보이지 않는다. 논문의 해법은 드리프트 게이트, 즉 병합을 막는 차단 조건이다.

이 검사는 생각보다 작다. 헤더가 accepted라고 말하는 모든 스펙에 대해, 백틱 안이나 touches 줄에 적힌 경로를 뽑아내고, 각각이 실제로 존재하는지 테스트한다. 경로가 없으면 빌드는 실패하고, 로그에는 해당 스펙의 이름이 남는다. superseded와 proposed 파일은 건너뛴다. 트리에 대해 주장을 하는 것은 accepted 스펙뿐이므로, 검사도 accepted 스펙만 받는다. TrueFoundry는 이를 사고 이후의 고고학이 아니라 정기적인 diff로 규정한다. 스펙은 스캐폴드이고, 스펙의 변경은 정책의 변경이다.

사람들은 이미 수동 버전을 실행하고 있다. 한 댓글 작성자는 Claude에게 스펙 파일과 코드베이스를 비교시켜 누락된 것에 대해 티켓을 만들게 한다. 스크립트는 같은 일을 모든 풀 리퀘스트마다 공짜로 해준다.

두 번째 방어선은 Okama가 실제로 배포한 것이다. 문서 빌드에서 그 폴더를 제외하는 것. Sphinx 설정의 한 줄이면 파일은 Git에 남고 HTML에서는 빠진다.

한계: 경로 검사는 삭제된 파일을 잡아내지만 바뀐 동작은 잡지 못한다. 스펙은 존재하는 모든 파일을 정확히 나열하면서도 이미 사라진 API를 여전히 설명하고 있을 수 있다. 그건 리뷰와 같은 커밋 규칙이 맡을 몫이다.

규칙 5: 대부분의 작업은 스펙을 받을 자격이 없다. 스펙 주도 방식의 오버헤드에 대한 증거는 일관된다.

Experiment	Result
Marmelab, 현재 날짜를 보여주는 기능에 Spec Kit을 적용	파일 8개, 1,300줄짜리 스펙 텍스트
OpenSpec 베이크오프, 같은 요구사항을 스펙 툴 대 Claude Code 단독으로 비교	코드 50% 증가, 순환 복잡도 50% 증가, 시간 두 배, 비용 세 배
스펙 주도 개발을 몇 달간 운영한 팀	토큰 2~3배, 시간 약 두 배, 필요 없던 변경에 큰 조율 비용, 코드 개선의 증거는 없음

베이크오프는 하나의 실험일 뿐, 벤치마크는 아니며, 작성자 본인도 그렇게 말한다. 하지만 방향은 일관된다. 그래서 규칙은 이렇다. 작업이 스쿼드 경계를 넘거나 90일 뒤에도 다시 읽힐 것이라면 스펙을 쓴다. 그 외 나머지는 프롬프트로 충분하다.

Superpowers는 이미 모든 요청을 세 갈래로 나눈다: spike, bounded, architectural. architectural 경로만 스펙을 쓴다. bounded 경로는 bounded하게 유지하고, 스펙은 300줄 근처로 유지한다. 실무자들은 두 줄을 덧붙인다. 스펙을 너무 크게 쓰지 말 것, 그리고 생성된 스펙을 실제로 읽을 것.

한계는 양쪽으로 작동한다. 같은 베이크오프에서 평범한 실행이 놓친 세 가지 틈을 스펙이 찾아냈다. 스펙이 사는 것은 속도가 아니라 커버리지다. 커버리지가 중요한 곳에만 그 값을 지불하라.

리드의 세 가지 질문으로 돌아가자. 무엇을 버전 관리하는가: 승인된 스펙과 계획을, 브랜치 위에서, 스쿼드의 폴더 안에. 드리프트는: 상태 헤더와 CI 게이트. 거버넌스는: 소유자와 크기 규칙.

다섯 가지 규칙이지만, 오늘 그 어느 것도 툴이 강제하지 않는다. 오버라이드 이슈는 열려 있다. main 브랜치 이슈도 열려 있다. 지시문 순서를 바꾼 풀 리퀘스트는 병합되지 않고 닫혔다. 한 번 데인 팀은 그 관행을 계속 지켰다. 계획 8개와 스펙 6개, 커밋되고, 문서 빌드에서는 제외된 채로.

Böckeler의 반론은 여전히 유효하다. 상태 헤더와 크기 예산이 있으면, 읽어야 할 건 accepted된 스펙뿐이고, 그 수도 줄어든다. 그 대가로 얻는 것은 Anthropic의 플레이북이 말하는 감사 추적, 즉 누가 무엇을 요청했고 에이전트가 무엇을 만들었으며 누가 승인했는가다.

이건 툴링이 아니라 프로세스다. CLAUDE.md 파일 하나, CODEOWNERS 파일 하나, 헤더 하나, 그리고 열다섯 줄짜리 스크립트. 그리고 팀이 CODEOWNERS 요청조차 리뷰하지 않으려 한다면, 스펙도 리뷰하지 않을 것이다. 그런 경우라면 .gitignore가 오히려 정직한 선택이었다.