# obra/superpowers

> 프레임워크는 안 들였습니다. 그런데 이 분석의 진짜 산출은 수확이 아니라, 대상이 가르쳐준 방법으로 제 판정 둘을 스스로 부순 것이었습니다.

- 수치: 수확 3 → 1
- 사람이 보는 화면: https://aitryed.com/ko/teardowns/harness/superpowers/
- 반대 언어: https://aitryed.com/en/teardowns/harness/superpowers/index.md
- 저장소: https://github.com/obra/superpowers
- 이 사이트 안내(AI용): https://aitryed.com/ko/llms.txt

---

**AI에게 개발을 시키는 «방법론 + 도구 묶음»입니다. 10개월 만에 「좋아요」 27만 개가 붙었습니다. 통째 도입은 기각했는데, 이 편이 남을 이유는 그다음입니다 — 이 창고가 자기 문서에 써 둔 검증법을 «이 창고 자신»에게 돌리자 제 수확 셋 중 둘이 무너졌습니다.**

> **[도판]** 스킬 14종을 세는 것으로는 이 물건이 안 보인다. 저절로 켜지게 만드는 배선이 정체다.
>
> 이 프로젝트의 본체는 스킬 문서가 아니라 스킬이 저절로 켜지게 만드는 세 겹의 배선이다. 세션 시작 훅이 부트스트랩을 매 세션 주입하고, 확장자 없는 한 파일이 배치이자 셸로 동작하며, 주입되는 본문이 선택권이 없다고 선언한다. 그 배선이 켜는 것은 설계를 캐묻고 태스크로 쪼개 태스크마다 새 에이전트를 띄우는 흐름이다.

## 이 물건이 하는 일

「이거 만들자」고 하면 **바로 코드로 뛰어들지 않게** 만듭니다. 대신 이 순서로 갑니다.

1. **캐물어서** 뭘 만들지 확정
2. 계획으로 쪼갬
3. **일감마다 새 AI를 띄워** 만들고 검토

그리고 이게 **저절로 발동**합니다. 사람이 「이제 이 단계 해」라고 안 해도 됩니다. 그 **배선이 이 물건의 정체**입니다 — 도구 14개를 세는 걸로는 안 보입니다.

## 제일 배울 만했던 것 — 「판정하되 멈추지 않는다」

AI를 무인으로 돌릴 때 제일 어려운 문제가 이겁니다. **애매한 상황이 나오면 어떻게 하나.**

| 흔한 답 | 문제 |
|---|---|
| **멈추고 물어본다** | 사람이 자리에 없으면 **밤새 멈춰 있음** |
| **알아서 하고 간다** | 나중에 보면 **왜 그렇게 했는지 모름** |

이 창고의 답은 이렇습니다.

> **판정하고 계속 간다. 대신 「무엇을 정했나 — 왜 — 틀렸으면 비용이 얼마인가」를 남긴다.**

그리고 **정말 멈추는 경우를 넷으로 한정**합니다 — **되돌릴 수 없는 일 · 보안 문제 · 작업 공간 밖에 영향 · 모든 길이 추측일 때.**

그 넷 말고는 전부 판정하고 갑니다. 그래서 **밤새 돌아도 아침에 진도가 나가 있고, 무슨 판단이 있었는지도 읽을 수 있습니다.**

## 그리고 그 기록을 마지막에 전부 모읍니다

위 규칙에 짝이 되는 규칙이 있습니다. 작업 공간을 지우기 전에, **남긴 판정을 빠짐없이 모아 최종 보고에 한 절로** 넣습니다.

근거 문장이 이렇습니다.

> **기록과 함께 죽은 판정은, 비밀리에 내린 결정이다.**

판정을 남기는 것만으로는 부족합니다. **그 기록이 작업 공간과 함께 지워지면 안 남긴 것과 같습니다.**

## 또 하나 — 「고치는 횟수에 상한과 «차단기»가 있습니다」

검토에서 지적이 나오면 고칩니다. 그런데 **무한히 고치면 안 됩니다.**

이 창고는 **일감당 5번**으로 제한하고, 그 안에서도 담당을 바꿉니다.

| 회차 | 누가 고치나 | 왜 |
|---|---|---|
| 1~3 | **원래 만든 AI가 이어서** | **자기 코드를 알고 있음** |
| 4~5 | **상위 모델 + 새 AI** | 세 번 실패했으면 **보는 눈이 바뀌어야 함** |
| 그 뒤 | **차단기가 내려감** | 항목별로 보류/최소수정 판정 |

**세 번 실패한 뒤에 같은 사람이 네 번째를 하는 건 대체로 소용없습니다.** 그걸 규칙으로 박았습니다.

## 그리고 「검토자에게 미리 답을 주지 마라」

작은데 중요한 규칙입니다.

검토를 시킬 때 <strong>「이건 지적하지 마」</strong>를 넣으면, 검토자가 **거기서 생각을 멈춥니다.**

오탐 같아 보여도 **검토자가 올리게 두고, 판정은 다음 단계에서** 합니다. **거르는 자리와 판정하는 자리를 나눈 것**입니다.

## 값나간 실측 하나 — 「붙여넣은 것은 끝까지 따라다닙니다」

이 창고가 잰 숫자 중 제일 인상적이었던 것입니다.

작업을 넘길 때 **내용을 붙여넣으면**, 그게 **세션이 끝날 때까지 계속 실려** 다닙니다. 매 순간 다시 읽힙니다.

실측한 것 하나가 **42,000자**였는데, **그중 99%가 붙여넣은 과거 이력**이었습니다.

→ 그래서 규칙이 <strong>「붙여넣지 말고 파일로 넘겨라」</strong>입니다. 파일은 **필요할 때만 읽힙니다.**

## 또 하나 — 「싼 모델이 더 비쌀 수 있습니다」

역설적인 실측입니다.

| | 단가 | 실제 총액 |
|---|---|---|
| 비싼 모델 | 높음 | **적은 횟수로 끝냄** |
| **싼 모델** | 낮음 | **2~3배 더 주고받아서 총액이 더 큼** |

**단가가 아니라 총액을 봐야** 합니다.

그리고 함정이 하나 더 있습니다 — **일감에 모델을 «안 적으면» 제일 비싼 모델을 물려받습니다.** 아껴 쓰라고 만든 규정이 **적는 걸 깜빡하는 순간 조용히 무력화**됩니다.

## 그런데 이 창고가 가르쳐 준 방법으로 제 수확이 무너졌습니다

여기가 이 편의 본론입니다.

1차에서 저는 **세 개를 배워 오겠다**고 적었습니다.

그리고 이 창고의 문서에 <strong>「이렇게 검증해라」</strong>는 방법이 적혀 있었습니다. 그 방법을 **이 창고 자신에게** 돌렸습니다.

**셋 중 둘의 근거가 무너졌습니다.**

특히 한 줄이 결정적이었습니다. 저쪽 규칙에 이렇게 적혀 있었습니다.

> **비교군이 실패를 안 보이면, 거기서 멈춰라.**

즉 **「이게 좋다」를 말하려면 「이게 없을 때 나쁘다」를 먼저 보여야** 합니다. 제 수확 둘이 그 조건을 못 넘겼습니다 — **비교군 없이 제 것만 재고 있었습니다.**

그리고 **제 것만 재면, 이미 믿던 것이 확인됩니다.**

그래서 **그대로 멈췄습니다.** 셋이 하나가 됐습니다.

## 그런데 이 분석이 실제로 바꾼 것은 그 하나가 아니었습니다

마지막이 제일 중요합니다.

수확은 1건인데, **이 분석이 실제로 바꾼 것은 제 다른 파이프라인 두 곳의 구멍을 찾아 막은 것**이었습니다.

남의 것에서 가져온 게 아니라, **남의 기준으로 제 것을 재다가 나온 결과**입니다.

이 칸에서 반복해서 나오는 결론이 여기서도 나왔습니다 — **가져온 개수로 성과를 세면 절반을 놓칩니다.**

## 통째 도입을 기각한 이유

제 작업 파이프라인이 **같은 장치를 이미 갖고** 있었습니다 — 단계별 모델 지정, 재시도 상한, 기계 판정 게이트, 중단 지점에서 재개하기. 그리고 **일부는 제 쪽이 더 정교**했습니다.

참고로 상시 비용은 **약 1,511토큰**으로 작습니다(전체의 0.76%). 비용 때문에 기각한 게 아닙니다.

## 여기부터는 자세한 기록입니다

**프레임워크 통째 도입은 기각했습니다.** 제 테스트케이스 파이프라인이 같은 기제(단계별 모델 지정·재시도 상한·결정론 게이트·해시 기반 재개)를 이미 갖고 있고 일부는 더 정교합니다. 여기까지는 흔한 결론입니다. **이 편이 남길 만한 이유는 그다음입니다** — 1차에서 세 개를 수확하겠다고 적었는데, 대상이 자기 문서에 써 둔 검증 방법을 **대상 자신에게 돌리자 그중 둘의 근거가 무너졌습니다.** 남은 건 1종입니다. 그런데 정작 이 분석이 실제로 바꾼 것은 그 1종이 아니라, **제 다른 파이프라인 두 곳에서 구멍을 찾아 막은 것**이었습니다.



## 무엇을 하는 물건인가

**코딩 에이전트용 개발 방법론 + 스킬 라이브러리 14종입니다.** *"뭘 만들자"* 고 하면 코드로 바로 뛰어들지 않고, 설계를 캐물어 스펙으로 만들고 → 플랜으로 쪼개고 → **태스크마다 새 에이전트를 띄워 구현하고 리뷰**하는 흐름이 자동으로 발화합니다. 하네스 13종을 지원합니다.

**중요한 건 스킬 문서가 아니라 배선입니다.** 세션 시작 훅이 안내문 63줄을 매 세션 주입하고, 그 63줄이 *"1%라도 적용될 것 같으면 반드시 호출한다 / 선택권이 없다 / 합리화로 빠져나갈 수 없다"* 를 선언한 뒤 **곧바로 합리화 반박표 12행**을 붙입니다.

| 항목 | 실측 (2026-08-15) |
|---|---|
| 규모 | 스타 272,335 · 포크 24,345 · **10개월 만에** |
| 라이선스 / 의존성 | MIT · **외부 패키지 0** (자칭 "제로 의존성" 코드로 확인) |
| 기여자 | 1위 523커밋, 2위 79 — **버스팩터 1** |
| PR | 병합 167 / 미병합 종료 943 / 열림 182 |
| 상시 컨텍스트 비용 | **≈1,511 토큰** (200k의 0.76%) |
| 호출 시 비용 | 가장 큰 스킬 하나가 ≈8,084 토큰 |

## 대표 기법

읽을 값이 있는 건 컨트롤러 운영 기제 쪽입니다. **에이전트를 무인으로 굴릴 때 무엇이 문제가 되는지를 이미 다 겪은 사람이 쓴 문서**로 읽힙니다.

| 기법 | 내용 |
|---|---|
| **판정하되 멈추지 않는다** | 돌아가는 플랜은 사람을 기다리지 않습니다. 충돌·모호·상한 초과는 컨트롤러가 판정하고 `결정 — 이유 — 틀렸을 때 비용`으로 남깁니다. 멈추는 건 **비가역·보안·워크스페이스 밖 부작용·모든 길이 추측일 때** 넷뿐 |
| **판정 전량 최종 보고** | 워크스페이스를 지우기 전에 판정 줄을 빠짐없이 모아 최종 보고의 한 절로 넘깁니다. *"원장과 함께 죽은 판정은 비밀리에 내린 결정이다"* |
| **수정 루프 상한 + 차단기** | 태스크당 5라운드. 1~3은 **원 구현자를 이어서** (자기 코드를 압니다), 4~5는 상위 모델 + 새 구현자. 그 뒤엔 차단기가 내려가고 항목별로 보류/최소수정 판정 |
| **리뷰어 선판정 금지** | 리뷰어 프롬프트에 *"이건 플래그하지 마"* 가 들어가면 거기서 멈춥니다. 오탐 같아도 리뷰어가 올리게 두고 루프에서 판정 |
| **산출물은 파일로 넘긴다** | 붙여넣은 것은 세션 끝까지 컨텍스트에 상주하며 매 턴 재독됩니다. 실측 디스패치 하나가 42k자였고 **99%가 붙여넣은 과거 이력** |
| **모델을 안 쓰면 최고가를 상속한다** | 디스패치에 모델을 안 적으면 세션 모델을 물려받아 절약 규정이 조용히 무력화됩니다. 동시에 **턴 수가 단가를 이깁니다** — 최저가 모델이 2~3배 턴을 써 총액이 더 듭니다 |

**그리고 스킬 저작 방법론 쪽에 이 편의 주인공이 있습니다** — 「실패 유형에 형식을 맞춰라」. 가이던스를 쓰기 전에 **베이스라인 실패를 먼저 분류**하라는 것이고, 한 실패에 방탄인 형식이 다른 실패에서는 측정 가능하게 역효과를 낸다는 주장입니다.

| 베이스라인 실패 | 맞는 형식 | 틀린 형식 |
|---|---|---|
| 알면서 어긴다 | 금지 + 합리화 반박표 | 부드러운 권고 |
| **지키는데 출력 형태가 틀리다** | **긍정 레시피** — 출력이 무엇인지를 순서대로 | 금지 목록 |
| 필수 요소를 빠뜨린다 | 템플릿의 필수 슬롯 | 템플릿 옆 산문 리마인더 |
| 조건에 따라 달라져야 한다 | 관측 가능한 술어 기반 조건문 | 무조건 규칙 + 예외 조항 |

## 깨본 결과 — 비판 넷 중 둘은 비판 쪽이 틀렸다

**커뮤니티 비판을 그대로 인용하면 안 됐습니다.**

- **"설치하면 22k 토큰이 상시로 나간다"** — **낡았습니다.** 그 이슈는 8개월 전 것이고, 현재 버전을 직접 재니 **상시분은 1,511 토큰**입니다. 훅 코드를 읽어보면 실제로 한 파일만 주입합니다. **비판을 인용할 때 버전을 안 붙이면 그 인용 자체가 오류가 됩니다.**
- **"최근 커밋이 급감했다"** — **제 오판이었습니다.** 주 커밋이 `4,1,0,1`이라 정체처럼 보였는데, 이 레포는 **메인이 릴리스 브랜치**이고 모든 PR은 개발 브랜치를 탑니다. 그쪽은 조밀합니다. **브랜치 구조를 안 보고 활동을 판정하면 틀립니다.**
- **"스타 272k에 워치가 0.38%면 비정상"** — **코호트 정상이었습니다.** 동시대 AI 툴링 레포가 전부 0.6% 안팎입니다. 낮은 워치 비율은 조작 신호가 아니라 **북마크성 스타**의 특징입니다.
- **"69% 감축안이 무회귀인데 안 받았다"** — 사실이지만 **방침과 일치**합니다. *"행동을 만드는 콘텐츠는 코드다"* 라고 명문화해 뒀습니다.

**적대검증을 통과하고 남은 진짜 약점은 셋입니다.** 버스팩터 1. 백로그 334건에 거절률 85%인데 **열린 이슈들이 배선 버그가 아니라 방법론 내부의 논리 결함**을 지적합니다. 그리고 ⚠ **성능 주장의 재현 경로가 레포 밖에 있습니다** — *"증거 없이는 못 고친다"* 가 방침인데 그 증거가 별도 저장소에 있어 **주장을 검증할 수도 반박할 수도 없습니다.**

## 내 환경에 대봤다 — 그리고 내 판정이 뒤집혔다

「실패 유형에 형식을 맞춰라」를 제 규칙 문서에 그대로 대 봤습니다. <strong>금지형 대 레시피형이 12.6~28.6배, 레시피형은 사실상 0%</strong>였습니다. 그래서 1차에 *"내 코퍼스가 이상하다"* 고 적고 1순위로 채택했습니다.

**그런데 대상 자신의 규칙이 이 상황의 처리를 이미 정해 놨습니다.**

> 무가이던스 대조군을 반드시 넣어라. 대조군이 실패를 안 보이면 고칠 게 없으니 멈추고, 가이던스를 쓰지 마라.

**제 대조군은 참조 구현입니다.** 같은 스크립트를 돌렸습니다.

> **[도판]** 1차의 실수는 수치가 틀린 게 아니라 대조군 없이 내 것만 재고 「이상하다」고 판정한 것이었다.
>
> 금지형 대 레시피형 비율을 참조 구현과 내 규칙 문서에 같은 방법으로 재봤다. 참조 구현 전체가 26.6배로 가장 편중돼 있고, 그 주장을 한 문서 자신도 18.5배다. 내 코퍼스는 12.6에서 23.0배 사이로 오히려 덜 편중돼 있다. 그래서 내 코퍼스가 이상하다는 1차 판정이 무너졌다.

## 판정

| 항목 | 1차 → 2차 | 사유 · 재개 조건 |
|---|---|---|
| 형식을 실패 유형에 맞추기 | **채택 → 보류** | 참조 구현이 더 편중. 재개 = **구체적인 형태 실패가 실제로 관측될 때**, 그 규칙 하나에만 |
| **판정 전량 롤업** | **채택 유지** | 공격했으나 안 깨졌습니다. 등가물 0건이고 비용은 보고서에 절 하나 |
| 대조군 arm 추가 | **채택 → 보류** | ⚠ 붙일 대상 도구 둘 다 **실제 실행 0회**였습니다. 한 번도 안 돌린 도구에 붙이는 건 부채입니다. 재개 = 처음 돌릴 때 같이 |
| 프레임워크 도입 | **기각 유지** | 근거는 바꿨습니다 — 아래 |

⚠ **기각 사유를 하나 철회했습니다.** 1차에 *"강제 게이트가 제 「플랜모드 자동 시작 금지」와 정면 충돌하고 끌 수가 없다"* 고 썼는데, **대상이 마지막 절에 "사용자 지시가 스킬보다 우선한다"고 명시해 뒀습니다.** 제 표현이 과장이었습니다.

**그래도 결론은 유지합니다 — 근거를 바꿉니다.** 우선순위 문장은 63줄 중 **맨 끝 한 줄**이고, 앞은 *"선택권이 없다 · 협상 불가"* 입니다. 그리고 **대상 자신이 실측으로 발견한 두 가지가 정확히 이 구조를 겨눕니다** — *"설명이 워크플로를 요약하면 에이전트가 본문 대신 설명을 따른다"*, *"면제 조항은 스코프가 안 잡힌다"*. **우선순위 한 줄이 바로 그 면제 조항입니다.**

## 그런데 실제로 바뀐 건 수확이 아니었다

**「에이전트 성공 보고를 신뢰하지 마라」는 렌즈로 제 파이프라인을 다시 봤습니다.**

[테스트케이스 파이프라인](/ko/built/tc-team/index.md)은 이미 해결돼 있었습니다 — 저장 직후 크기·참조 개수·절단 흔적을 **결정론 코드가 확인**하고, 어긋나면 시작을 막습니다. **그런데 형제 둘은 아니었습니다.** [게임 QA 서버](/ko/built/android-qa/index.md)와 [게임 제작 팀](/ko/built/moon-studio/index.md)의 단계 전이는 **전부 다른 에이전트의 리뷰 판정**이고, 산출물이 실제로 존재하는지 확인하는 결정론 지점이 검색해도 0건이었습니다.

**이 실패는 제 환경에서 이미 한 번 일어났습니다.** 83행을 한 번에 만들려다 사고가 나 손실 88.3분을 기록해 뒀고, 그래서 테스트케이스 파이프라인에는 분할과 게이트를 붙였습니다. ⚠ **그 교훈이 형제 파이프라인으로 이관되지 않았습니다.** 설계 산출물을 같은 방식으로 잃으면 다음 단계는 잘린 입력을 받고, 그다음 검수는 원본이 잘린 줄 모른 채 통과시킵니다. **종료 코드가 0이라 아무도 안 멈춥니다.**

두 곳에 인수 게이트를 붙였습니다. 실패 케이스 10건 전부 잡고 정상 12건 전부 통과, 오탐 0.

**이 편에서 값을 치른 교훈은 기법이 아니라 순서입니다 — 대조군 없이 내 것만 재면, 그 수치는 내가 이미 믿고 있던 것을 확인해 줍니다.** 1차의 1순위 근거가 그렇게 만들어졌고, 대상이 알려준 방법을 대상 자신에게 돌리고 나서야 무너졌습니다.

그리고 ⚠ **가져온 게 없어도 분석은 값을 합니다.** 실제 수확은 1종인데, 이 조사가 남긴 건 **제 다른 파이프라인 두 곳에 게이트를 붙인 것**이었습니다. 도구는 안 들였고 렌즈만 빌렸습니다.