AI 코딩 프레임워크는 언제 도움이 될까

AI 코딩 프레임워크를 설치하면 더 체계적으로 일하는 느낌이 든다. 먼저 요구사항을 묻고, 계획을 만들고, 테스트를 강제하고, 서브에이전트에게 리뷰를 맡긴다. 반면 순정 Codex나 Claude Code는 훨씬 단순해 보인다.

Codex 반복 실험과 공개 연구가 가리킨 결론은 간단했다. 프레임워크는 에이전트에 없던 제약이 그 과제에 꼭 필요할 때만 도움이 됐다. 명확한 유지보수 과제에서는 순정, 짧은 지시, Ponytail이 모두 3회 구현에 성공했다. 반대로 요구 해석이 필요한 한 과제에서는 Superpowers 조건이 더 자주 성공했지만, 추가 정보와 여러 차례의 대화도 함께 들어갔다.

더 무거운 절차가 항상 더 좋은 결과를 만들지는 않았다. 성공률이 오른 경우도 있었고, 차이 없이 오버헤드만 생긴 경우도 있었다. 한 과제를 세 번씩 반복한 결과이므로 어느 도구가 보편적으로 우월하다고 말할 수는 없다. 대신 무엇을 측정해야 하는지는 선명해졌다.

그래서 “어떤 프레임워크가 1등인가”보다 다음 질문이 중요하다.

이 작업에서 줄이고 싶은 실패가 무엇이며, 그 실패를 줄이는 비용이 작업 자체보다 작은가?

비교 대상과 실험 설계

실험은 두 단계였다. 먼저 후보를 넓게 보기 위한 파일럿에서 로컬 pytest 버그와 정적 블로그의 다국어 태그 기능을 사용했다. 그 결과를 보고 반복 통제 실험은 별도의 공개 저장소 과제로 다시 구성했다.

• 명확한 유지보수: Flask에서 빈 blueprint 이름을 거부하는 작은 수정
• 모호한 요구 해석: p-limit의 안전한 재귀 사용법을 문서와 API 사용 예제로 설명하는 수정
• 제외된 복합 과제: 블로그 route·목록·SEO metadata의 일관성을 맞추는 수정

조건은 순정 Codex, 짧은 지시를 보탠 순정 Codex와 다음 도구들이었다. 같은 표에 놓았지만 해결하려는 문제는 다르다. 그래서 단발 구현형, 대화·승인형, 장기 산출물형을 구분해 해석했다.

Claude Code 구독은 없는 상태였기 때문에 직접 실험은 Codex로만 했다. Claude Code 부분은 공식 문서와 공개 연구만 사용했다.

근거의 무게도 구분했다.

반복 실험: 명확한 과제 vs 모호한 과제

탐색 파일럿에서 드러난 문제를 보완해 두 과제만 다시 고정하고, 각 조건을 3회씩 실행했다. Ponytail과 Superpowers를 같은 과제에서 직접 겨루지는 않았다. 각 도구가 해결하려는 문제에 맞춘 과제에서 순정·짧은 지시와 비교했으므로, 결과도 과제별로 나눠 해석했다.

• 명확한 유지보수 과제: 순정, 순정 + 짧은 지시, Ponytail
• 요구 해석이 필요한 문서·API 과제: 순정, 순정 + 짧은 지시, Superpowers
• 조건별 작업 공간과 실행 순서를 분리하고, 실행당 누적 20분 상한을 적용했다.
• 공개 테스트와 비공개 검증 조건을 모두 통과해야 구현 성공으로 판정했다.
• 공개·비공개 검증을 모두 통과한 경우를 구현 성공, 최종 응답까지 전달한 경우를 결과 보고로 기록했다. 코드는 맞지만 보고가 빠진 실행을 구현 실패와 섞지 않기 위해서다.
• 프레임워크가 내부적으로 만드는 서브에이전트는 허용하되 측정하고, 실험 통제와 채점에는 서브에이전트를 쓰지 않았다. 실제 유효 실행에서는 서브에이전트가 관찰되지 않았다.

실행 전에 프로토콜, 조건 행렬, 분석 제약을 고정했다. 실행기나 채점 문제를 발견했을 때는 결과를 덮어쓰지 않고 수정 이유와 영향을 기록했다.

원시 로그에는 로컬 경로가 포함돼 공개하지 않았다. 대신 독자가 표의 성공 횟수와 중앙값을 다시 계산할 수 있도록 개인정보나 로컬 경로가 없는 실행별 수치를 아래에 실었다.

Flask 유지보수에서는 세 조건이 모두 성공했다

세 조건 모두 구현 성공률이 같았다. 짧은 지시가 중앙값에서는 가장 빨랐지만 한 번은 9분 20초가 걸렸고, 순정도 한 번은 19분 57초가 걸렸다. 3회 표본에서 중앙값만 보고 “짧은 지시가 더 빠르다”고 일반화하면 안 되는 이유다. 이 결과로는 Ponytail이 있어야만 해결되는 품질 차이가 관찰되지 않았다고만 말할 수 있다.

Ponytail의 결과 보고 1회 누락은 구현 실패가 아니라 최종 응답을 전달하지 못한 경우였다. 그래서 성공률 하나만 보면 사라지는 실행 마찰도 따로 기록했다.

p-limit 문서 과제에서는 성공과 비용이 함께 늘었다

순정 계열은 대부분 완료를 선언했지만 숨겨 둔 검증 요구 중 하나 이상을 놓쳤다. 질문이 나오면 모든 조건에 미리 정해 둔 같은 답변을 한 번 제공했다. Superpowers가 성공한 두 실행에는 이후에도 미리 정한 승인 답변을 3–4회 더 제공했고, 추가 대화는 총 4–5회로 늘었다. 반면 질문 흐름이 시작되지 않은 Superpowers 실행은 49초 만에 코드 변경 없이 끝났다.

세 실행을 따로 보면 중앙값 뒤에 가려진 차이가 드러난다. 성공한 두 실행에서는 질문·승인 흐름이 길게 이어졌고 탐색 관련 로그도 더 많이 남았다.

표의 ID는 공개 결과 파일의 runId 앞부분이다. 예를 들어 r1은 r1__ambiguous-issue-2__superpowers와 연결된다. r1의 attempt: 2는 무효 인프라 시도 뒤의 재실행을 뜻한다.

탐색 명령 출현 지표는 사전 고정한 주평가지표가 아니라, 결과를 해석하려고 사후에 추가한 보조 수치다. rg, find, git status, ls 문자열의 출현 횟수에서 최초 한 번을 뺐기 때문에 실제 도구 호출이나 파일 재열람 횟수와는 다르다. 성공 실행의 35·38회와 실패 실행의 8회는 탐색 관련 로그도 함께 늘었다는 신호일 뿐, 성공 원인을 증명하지 않는다.

이 결과만으로 Superpowers가 순정보다 낫다고 말할 수는 없다. Superpowers 자체와 추가 정보, 후속 실행 기회를 분리하지 않았기 때문이다. Superpowers가 포함된 조건은 세 번 중 두 번 성공했고, 중앙값 기준 실행 시간 약 9분, 누적 입력 약 490만, 추가 상호작용 4회를 썼다.

중앙값끼리 비교하면 Superpowers는 순정보다 실행시간이 3.9배, 누적 입력이 20.6배, 출력 토큰이 8.9배였다. 이 배율은 이 과제의 세 번 실행을 요약한 값이다. 프레임워크 실행뿐 아니라 추가 질문과 후속 작업까지 모두 포함돼 있어 일반적인 Superpowers 비용으로 볼 수는 없다. 누적 입력도 각 대화 차례에서 Codex가 보고한 입력의 합이며 컨텍스트 창 크기나 청구 토큰과 같지 않다.

또한 공개 저장소 과제를 사용했지만 과제 선정, 미리 정한 답변, 비공개 검증 기준은 글 작성자가 설계했다. 숨은 테스트가 여러 형태의 정답을 허용하도록 만들었어도 설계자 편향을 완전히 제거할 수는 없다. 과제당 세 번뿐인 결과와 함께 해석해야 한다.

18회 실행 원자료

아래 CSV는 본문의 표를 계산한 최소 원자료다. durationMs는 모델 실행 시간, inputTokens는 각 대화 차례가 보고한 누적 입력의 합이다. success는 구현 성공, operational은 결과 보고 여부를 뜻한다.

runId,task,condition,success,operational,durationMs,inputTokens,outputTokens,interactions
r1__ambiguous-issue-2__superpowers,ambiguous-issue-2,superpowers,true,true,1015284,4906389,37064,4
r1__ambiguous-issue-2__vanilla,ambiguous-issue-2,vanilla,false,true,141238,216519,4148,1
r1__ambiguous-issue-2__vanilla-explicit,ambiguous-issue-2,vanilla-explicit,false,true,85013,165015,2349,1
r1__benchmark-2__ponytail,benchmark-2,ponytail,true,true,69974,241446,1928,0
r1__benchmark-2__vanilla,benchmark-2,vanilla,true,true,92272,347851,2676,0
r1__benchmark-2__vanilla-explicit,benchmark-2,vanilla-explicit,true,true,559697,183325,1971,0
r2__ambiguous-issue-2__superpowers,ambiguous-issue-2,superpowers,false,false,48672,156560,1707,0
r2__ambiguous-issue-2__vanilla,ambiguous-issue-2,vanilla,false,true,629383,421349,5205,1
r2__ambiguous-issue-2__vanilla-explicit,ambiguous-issue-2,vanilla-explicit,true,true,144004,264380,3992,1
r2__benchmark-2__ponytail,benchmark-2,ponytail,true,false,73670,233617,1975,0
r2__benchmark-2__vanilla,benchmark-2,vanilla,true,true,1196553,330715,2884,0
r2__benchmark-2__vanilla-explicit,benchmark-2,vanilla-explicit,true,true,68522,182503,1702,0
r3__ambiguous-issue-2__superpowers,ambiguous-issue-2,superpowers,true,true,549419,5539327,54029,5
r3__ambiguous-issue-2__vanilla,ambiguous-issue-2,vanilla,false,true,121979,238709,3911,1
r3__ambiguous-issue-2__vanilla-explicit,ambiguous-issue-2,vanilla-explicit,false,true,89419,187127,2507,1
r3__benchmark-2__ponytail,benchmark-2,ponytail,true,true,103841,293447,2183,0
r3__benchmark-2__vanilla,benchmark-2,vanilla,true,true,75441,216617,2006,0
r3__benchmark-2__vanilla-explicit,benchmark-2,vanilla-explicit,true,true,62555,157939,1775,0

세 번째 과제를 제외한 이유

원래는 장기 산출물형 GSD까지 포함한 세 번째 블록이 있었다. 그러나 실행 가능한 비공개 검증기의 실제 바이트가 사전에 고정한 SHA-256과 달랐고, 고정 당시의 원본을 복구할 수 없었다. 결과를 본 뒤 검증기를 다시 고정하면 설계자에게 유리한 채점기를 고를 수 있으므로 해당 블록 전체를 제외했다. 무효 시도 두 건은 기록에 남겼지만 18개 유효 실행에는 포함하지 않았다.

이 선택 때문에 GSD의 반복 통제 결과는 없다. 불완전한 숫자를 채우는 것보다 비교 범위를 줄이는 편이 설득력 있다. 현재 결과는 과제 2개 × 조건 3개 × 반복 3회, 총 18회이며 통계적 우위나 프레임워크 전체 순위를 주장하지 않는다.

에이전트보다 하네스가 먼저 실패할 수 있다

실행 중에는 모델 품질과 무관한 실패도 여러 번 나왔다. 패키지 lockfile이 빠져 모델 호출 전 준비가 실패했고, 얕은 복제본에 기준 commit이 없었으며, pytest의 텍스트 출력을 JSON으로 가정한 채점기가 정상 결과를 실패로 읽었다. 대화형 실행기는 대화 차례마다 20분을 새로 부여하고 첫 승인 뒤 멈추기도 했다.

이런 실패를 모델 점수로 넣지 않았다. 모델 호출 전 실패는 사전 실행 실패로 분리했다. 결과를 본 뒤 발견한 채점 오류는 기존 파일을 덮지 않고 원본 해시를 검증하는 파생 입력과 수정 이력을 남겼다. 채점 기준 자체가 잘못된 GSD 블록은 수정 후 재실행하지 않고 제외했다. 완벽한 설계였다는 뜻이 아니라, 어디까지가 모델 결과이고 어디부터가 측정 도구 오류인지 추적 가능하게 만들었다는 뜻이다.

탐색 파일럿에서 드러난 실패

통제 실험에 앞서 순정, 짧은 지시, Ponytail, Superpowers, BMAD, GSD, Spec Kit, Oh My Codex를 작은 버그와 중간 기능에 한 번씩 적용했다. 실행 방식과 실패 유형을 찾는 단계였기 때문에 성공률이나 순위를 계산하지 않았다.

관찰은 세 가지였다.

1. 작은 버그에서 순정·짧은 지시·Ponytail은 약 1분 안팎에 수정했지만, GSD와 Spec Kit은 계획과 명세를 만들며 누적 입력이 100만을 넘었다.
2. Superpowers와 BMAD는 질문이나 승인 단계에서 멈췄다. 이는 품질 실패라기보다 사람이 없는 단발 실행과 대화형 설계가 맞지 않은 경우다.
3. 중간 기능을 구현한 조건들은 자체 테스트를 상당 부분 통과했지만 모두 같은 모호한 요구를 다르게 해석했다. 테스트 수가 많아도 요구 해석이 자동으로 정확해지는 것은 아니었다.

파일럿은 조건당 한 번이고 실행 순서도 완전히 무작위화하지 않았다. 비공개 기준 역시 설계자의 해석을 담고 있어 절대 점수로 사용하지 않았다. 이 문제를 확인한 뒤 과제와 검증기를 새로 고정해 앞의 18회 반복 실험을 진행했다.

공개 연구 결과가 엇갈린 이유

탐색 파일럿은 조건당 한 번, 반복 실험도 과제당 세 번뿐이다. 평균 효과를 판단하려면 더 넓은 공개 연구가 필요하지만, 그 결과 역시 한쪽으로 모이지 않는다.

SkillsBench v4는 8개 분야의 87개 과제, 18개 모델·하네스 조합을 세 번씩 평가했다. 선별된 스킬을 제공했을 때 전체 평균 해결률은 33.9%에서 50.5%로 16.6%포인트 올랐다. 하지만 과제와 모델에 따른 편차가 컸고, 이는 소프트웨어 엔지니어링만의 결과가 아니다. SkillsBench v4

반대로 소프트웨어 개발에 범위를 좁힌 SWE-Skills-Bench는 Claude Haiku 4.5와 Claude Code로 49개 스킬, 약 565개 과제를 짝지어 비교했다. 평균 향상은 1.2%였고 49개 중 39개는 통과율을 높이지 못했다. 전문성이 잘 맞는 7개 스킬은 최대 30% 향상됐지만, 프로젝트 버전과 충돌한 3개는 최대 10% 낮아졌다. 통과율이 그대로인데 토큰이 최대 451% 늘어난 조건도 있었다. 다만 단일 모델·하네스에서 각 조합을 한 번 실행한 예비 연구라는 한계가 있다. SWE-Skills-Bench

두 연구 모두 프리프린트로 공개된 자료다. 현재 증거로는 유용하지만 모든 제품과 저장소에 그대로 적용할 수는 없다.

저장소 전체에 항상 들어가는 AGENTS.md와 CLAUDE.md도 비슷하다. 300개 SWE-bench Lite 과제와 개발자가 컨텍스트 파일을 커밋한 저장소의 138개 과제를 평가한 연구에서는 컨텍스트 파일이 전반적인 성공률을 높이지 못했고 추론 비용은 평균 20% 넘게 늘었다. 에이전트가 지시를 무시한 것이 아니라 더 넓게 파일을 탐색하고 테스트하면서 불필요한 요구까지 수행한 것이 원인으로 제시됐다. Evaluating AGENTS.md

반대 방향의 결과도 있다. 실제로 병합된 작은 PR 124개를 Codex로 재구성한 짝지은 실험에서는 AGENTS.md가 있을 때 중앙 실행 시간이 98.57초에서 70.34초로 28.64%, 출력 토큰 중앙값은 2,925개에서 2,440개로 16.58% 줄었다. 다만 모든 패치의 기능적 정답을 채점하지 않았고, 50개 출력에 비어 있지 않은 변경인지 최소 유효성만 수동 검토했다. 따라서 이는 성공률 향상이 아니라 운영 효율에 대한 초기 증거다. AGENTS.md 효율 연구

이 결과들은 모순이라기보다 적용 범위가 다르다. 과제에 필요한 절차 지식이 정확히 맞으면 스킬은 크게 도울 수 있지만, 이미 모델과 저장소가 아는 내용을 반복하거나 버전이 어긋나면 비용만 늘 수 있다. 그래서 “스킬이 효과적인가”보다 “이 스킬이 이 과제의 정보 부족을 메우는가”를 물어야 한다.

프레임워크가 도움이 되는 조건

좋은 프레임워크는 모델의 능력을 높이기보다 실수하기 쉬운 경로를 좁힌다.

1. 반복되는 팀 규칙을 매번 설명하지 않아도 된다

테스트 명령, 파일 위치, 보안 규칙, 완료 조건이 반복된다면 스킬로 묶을 가치가 있다. Codex 공식 문서도 플러그인을 반복 업무에 필요한 스킬과 앱을 포장하는 단위로 설명한다. Codex 플러그인 문서

이 경우 이득은 추론 능력 상승보다 누락 감소와 팀 일관성에 있다.

2. 도구 인터페이스가 모델에게 맞아지면 실제 성공률이 오른다

SWE-agent 연구는 GPT-4 Turbo로 실행한 300개 SWE-bench Lite 부분 실험에서, 기본 Linux 셸만 제공한 에이전트보다 모델 친화적인 검색·편집·피드백 인터페이스를 제공한 에이전트가 10.7%포인트 더 많은 문제를 해결했다고 보고했다. SWE-agent 논문

즉 적절한 검색 도구, 간결한 오류 피드백, 안전한 편집 명령은 효과가 있다. 이것은 “계획 문서를 많이 만들수록 좋다”와는 다른 주장이다.

3. 긴 작업은 상태를 외부 산출물로 넘겨야 한다

한 세션을 넘는 작업에서는 계획, 완료 항목, 다음 행동을 파일로 남기는 방식이 유효하다. Anthropic의 장기 에이전트 연구도 초기화 에이전트와 작업 에이전트를 나누고, 세션 사이에 명확한 산출물을 남기는 방식을 사용했다. 장기 에이전트 하네스

GSD, Spec Kit, Ralph Loop가 만들려는 가치도 이쪽에 가깝다. 하루 이상 이어지는 기능이라면 추가 문서가 다음 세션의 시작 비용을 낮출 수 있다.

4. 결정적인 규칙은 자연어보다 훅과 테스트가 강하다

“환경 파일을 수정하지 마라”는 지시는 모델이 해석하지만, 수정 시도를 차단하는 훅은 실행을 막는다. Claude Code 공식 문서도 반드시 지켜야 하는 가드레일은 스킬보다 훅에 두라고 권한다. Claude Code 확장 기능 비교

즉 반드시 지켜야 하는 규칙은 긴 프롬프트보다 짧고 결정적인 자동화가 더 적합할 때가 많다.

프레임워크가 방해가 되는 조건

컨텍스트는 용량이 아니라 주의력 예산이다

스킬 설명, 에이전트 역할, MCP 도구, 계획 파일, 테스트 로그가 모두 다음 추론의 입력이 된다. 컨텍스트 창에 들어간다고 해서 모델이 모든 정보를 똑같이 활용하는 것은 아니다. Lost in the Middle 연구는 관련 정보 위치에 따라 긴 컨텍스트 성능이 크게 달라질 수 있음을 보였다. 논문

Anthropic도 컨텍스트를 유한한 자원으로 보고, 토큰 수가 아니라 각 토큰의 효용을 최적화해야 한다고 설명한다. 컨텍스트 엔지니어링

탐색 파일럿의 작은 버그에서도 누적 입력은 순정 18.7만, GSD 104.7만, Spec Kit 114.9만이었다. 반복 실험의 모호한 과제에서는 Superpowers 중앙값이 490.6만, 순정이 23.9만이었다. 이 수치는 여러 대화 차례에서 반복 처리된 입력의 합이며 한 시점의 컨텍스트 크기나 비용이 아니다. 캐시 입력도 많이 포함됐다. 다만 같은 결과를 만들기 위해 실행 전체가 처리한 정보와 상호작용량이 얼마나 달라지는지는 보여준다.

상시 지침의 효과와 비용을 더 자세히 보려면 AGENTS.md는 도움이 될까: 성공률과 토큰 연구가 엇갈린 이유에서 별도로 정리했다.

외부 스킬은 공급망이기도 하다

스킬에는 문서뿐 아니라 모델이 따를 지침과 실행 코드가 들어갈 수 있다. 출처를 검토하지 않은 스킬이 새로운 프롬프트 인젝션 경로가 되는 이유다. Skill-Inject 연구는 12개 모델과 Codex CLI·Claude Code·Gemini CLI를 대상으로 202개 injection-task pair를 평가했고, 통제된 악성 스킬 조건에서 공격 성공률이 최대 80%에 이르렀다고 보고했다. 데이터 유출, 파괴적 명령, 랜섬웨어와 유사한 행동도 관찰됐다. Skill-Inject v3

이 수치는 일반 스킬 마켓의 악성 비율이 아니다. 연구진이 만든 공격 스킬에 대한 취약성이다. 그래도 설치 전 commit과 파일을 읽고, 불필요한 훅·셸 권한·외부 연결을 끄며, 사용자 전역보다 프로젝트 범위에서 먼저 시험해야 할 이유는 충분하다.

사람 승인용 절차와 무인 실행은 충돌한다

파일럿에서 Superpowers는 테스트 범위와 태그 충돌 정책을 물었고, BMAD는 구현 명세를 만든 뒤 승인을 기다렸다. 반복 실험에서 Superpowers의 승인 흐름을 끝까지 제공하자 세 번 중 두 번 구현에 성공했다. 대화형 세션에서는 요구를 확인하지 않고 밀어붙이는 것보다 안전한 동작일 수 있다.

하지만 CI나 야간 자동 실행에서는 코드가 하나도 나오지 않는다. 무인 실행을 원한다면 다음 중 하나가 필요하다.

• 승인 기준을 프롬프트에 미리 적는다.
• 질문이 생기면 권장 기본값으로 계속하라는 정책을 둔다.
• 계획 단계와 구현 단계를 서로 다른 실행으로 운영한다.
• 애초에 대화형 설계 프레임워크를 쓰지 않는다.

오케스트레이션이 작업보다 커질 수 있다

계획자, 구현자, 리뷰어, 검증자가 각자 저장소를 다시 읽으면 같은 맥락을 여러 번 구매한다. 장기 작업에서는 오류를 줄일 수 있지만 작은 수정에서는 중복 탐색이다.

서브에이전트는 독립적인 조사 결과만 메인으로 돌려줄 때 컨텍스트 격리에 도움이 된다. 하지만 같은 파일과 결정을 공유하는 작업을 여러 에이전트가 다시 읽으면 탐색·조정·요약 비용이 생긴다. Claude Code 공식 문서도 서브에이전트는 격리된 작업, 에이전트 팀은 서로 소통해야 하는 독립 작업에 배치하고, 각 팀원은 별도 인스턴스라 토큰 비용이 더 높다고 설명한다. Claude Code 확장 기능 비교

실제로 리뷰가 본 작업을 삼킨 사례

이 연구를 준비할 때도 첫 과제 풀 이후 검토 반복만 6시간 36분 이어졌다. 확인 가능한 서브에이전트 세션은 최소 14개, 동결 선언은 네 번, 관련 문서와 코드는 4,876줄까지 늘었지만 그 시점의 본 실험은 0회였다.

각 리뷰어는 문제를 찾았지만 전체 시간 예산과 최대 리뷰 횟수를 맡은 역할이 없었다. 모든 하위 작업이 성공하면서 전체 작업은 실패한 셈이다. 이 사례는 별도 글로 분리하고, 여기서는 서브에이전트에도 시간 상한·재위임 권한·남은 프로세스 정리·완료 산출물을 함께 지정해야 한다는 판단만 남긴다.

단순한 기준선을 너무 쉽게 무시한다

복잡한 에이전트가 언제나 이기는 것도 아니다. Agentless 연구는 코드 위치 찾기 → 수정 → 패치 검증의 단순한 파이프라인만으로 당시 SWE-bench Lite에서 경쟁력 있는 결과를 냈다. 연구진은 벤치마크 문제 자체의 불충분한 설명과 정답 패치 편향도 따로 분류했다. Agentless 논문

METR의 별도 비교에서도 Claude Code와 Codex가 그들이 사용하던 ReAct·Triframe 기준선보다 통계적으로 유의하게 낫다는 증거를 찾지 못했다. 이것은 제품이 나쁘다는 뜻이 아니라, 정교한 전용 하네스라는 사실만으로 모든 평가에서 우위가 보장되지 않는다는 뜻이다. METR 연구 노트

Claude Code에는 어떻게 적용할까

Claude Code를 직접 실행하지 않았기 때문에 Codex 결과를 Claude에 옮겨 붙일 수는 없다. 다만 공식 문서가 제시하는 선택 기준은 이번 관찰과 잘 맞는다.

Claude Code는 기본 파일 편집, 검색, 실행, 웹, 코드 인텔리전스 도구만으로 대부분의 코딩 작업을 처리하고, 처음에는 CLAUDE.md로 프로젝트 규칙을 넣은 뒤 구체적인 필요가 생길 때 확장을 추가하라고 안내한다. Claude Code 확장 개요

서브에이전트도 무조건 쓰라고 하지 않는다. 공식 문서는 빠른 표적 수정, 여러 단계가 같은 맥락을 공유하는 작업, 잦은 상호작용, 지연이 중요한 작업은 메인 대화를 권한다. 반대로 대량 로그 분석, 독립적인 조사, 결과 요약만 필요한 작업은 서브에이전트가 적합하다. 에이전트 팀은 각 작업자가 별도 Claude 인스턴스라 토큰 비용이 더 높다고 명시한다. Claude Code 서브에이전트 문서

이 기준은 Codex에서도 참고할 수 있는 일반 원칙이다. 다만 제품마다 컨텍스트 전달, 권한, 중단 방식은 다르다. 서브에이전트의 목적은 “더 많은 에이전트를 쓰기”가 아니라 “독립적인 작업이나 불필요한 중간 출력을 메인 컨텍스트에서 격리하기”여야 한다.

Claude Code의 사용량과 한 세션의 컨텍스트 한도는 다른 개념이다. 긴 세션을 언제 압축하거나 새로 시작할지는 Claude Code 사용량 제한과 컨텍스트 한도는 무엇이 다를까에서 다뤘다.

작업별 선택 기준

순정 Codex·Claude Code부터 시작할 작업

• 수정 위치가 대략 보이는 버그
• 한두 모듈 안에서 끝나는 기능
• 완료 조건이 테스트로 명확한 작업
• 사람이 결과를 바로 리뷰할 작업
• 속도와 작은 diff가 중요한 작업

프롬프트에는 역할극 대신 다음 네 가지만 넣으면 충분한 경우가 많다.

1. 원하는 동작
2. 바꾸지 말아야 할 경계
3. 완료를 확인할 테스트
4. 막힐 때 질문할지, 합리적 기본값으로 계속할지

가벼운 스킬 하나를 붙일 작업

• 같은 리뷰 체크리스트를 반복할 때
• 팀 고유 API·보안·마이그레이션 규칙이 있을 때
• 자주 틀리는 한 종류의 작업을 교정할 때
• 포맷, 테스트, 금지 경로처럼 범위가 선명할 때

이때는 범용 프레임워크 전체보다 작업 전용 스킬 하나가 낫다. 사용하지 않는 스킬 설명과 도구는 끄고, 자동 호출보다 명시 호출부터 시험하는 편이 안전하다. 외부 스킬은 최신 버전 이름만 믿지 말고 사용할 commit을 고정한 뒤 지침, 훅, 실행 스크립트, 요구 권한을 함께 검토한다.

GSD·Spec Kit·BMAD·Ralph류가 맞는 작업

• 여러 날 또는 여러 세션에 걸쳐 진행될 때
• 요구사항과 구현 사이 추적성이 필요할 때
• 팀원이 명세와 계획을 실제로 리뷰할 때
• 작업을 독립적인 단위로 나눌 수 있을 때
• 생성된 계획·PRD·체크리스트를 다음 작업에서도 재사용할 때

핵심은 산출물의 재사용이다. 아무도 읽지 않을 spec.md와 plan.md라면 품질 장치가 아니라 컨텍스트 쓰레기다.

10개 작업으로 도입 전 확인하기

GitHub 별 수나 데모 영상으로 결정하지 말고 자기 저장소의 최근 작업을 표본으로 쓰는 편이 낫다.

1. 작은 버그 5개와 중간 기능 5개를 고른다.
2. 순정과 후보 프레임워크 하나만 비교한다. 여러 개를 겹치지 않는다.
3. 실행 순서를 섞고 동일한 권한·시간 상한을 쓴다.
4. 성공 여부, 사람 개입 횟수, 벽시계 시간, 총·캐시 토큰, diff 크기를 기록한다.
5. 일주일 뒤 계획 문서와 리뷰 결과가 실제로 재사용됐는지 확인한다.

우위를 주장하려면 과제당 한 번으로 부족하다. 최소한 여러 날에 걸쳐 반복하고, 외부 공개 과제와 자체 과제를 섞으며, 채점 기준을 구현 전에 고정해야 한다. Anthropic의 평가 연구처럼 동일 모델·동일 하네스라도 자원과 시점 노이즈가 결과를 바꿀 수 있다.

이번 통제 실험의 유효 18회는 모델 실행 시간만 합쳐 약 85분 27초였다. 이 숫자에는 설치, 사전 보정, 무효 실행, 실패 복구, 채점기 수정, 수동 검토가 빠져 있다. 동일한 평균을 66회에 단순 적용하면 모델 실행만 약 5시간 13분이다.

대화형 조건과 20분 상한 때문에 분산도 크므로 실제 프로젝트 시간은 반나절을 쉽게 넘길 수 있다. 반복 수를 늘릴 때는 통계적 욕심만큼 실행 가능성과 중단 기준도 미리 고정해야 한다.

언제 프레임워크를 끌까

다음 신호가 보이면 프레임워크를 줄이거나 끄는 편이 낫다.

• 계획과 리뷰 파일은 늘지만 소스 diff가 생기지 않는다.
• 같은 질문이나 같은 검증이 반복된다.
• 서브에이전트가 저장소를 중복 탐색한다.
• 작은 작업의 누적 입력과 상호작용이 순정 대비 몇 배로 늘어난다.
• 사람이 승인할 수 없는 실행인데 승인 게이트에서 멈춘다.
• 프레임워크 설치·인증·런타임 문제 해결이 본 작업보다 오래 걸린다.
• 자체 테스트는 늘어나지만 실제 실패 조건은 계속 같다.

특히 “끝날 때까지 계속” 같은 지시는 위험하다. 종료 조건이 아니라 반복 허가로 해석될 수 있다. 시간 상한, 최대 반복 수, 구현 diff가 없을 때의 중단, 사람에게 돌려줄 조건을 함께 적어야 한다.

자주 묻는 질문

작은 버그에도 Superpowers나 Spec Kit을 써야 할까?

수정 위치와 실패 테스트가 보인다면 순정과 짧은 완료 조건부터 시작하는 편이 낫다. 설계 질문이 필요한 버그이거나 같은 종류의 실수가 반복될 때만 좁은 스킬을 추가한다. 명세 파일을 다음 작업에서 쓰지 않는다면 Spec Kit 같은 전체 절차의 비용을 회수하기 어렵다.

Claude Code나 Codex에 스킬을 많이 설치할수록 좋은가?

아니다. 설치 수보다 실제 로딩과 호출 범위가 중요하다. 항상 들어가는 지침, 자동 선택되는 스킬, 노출되는 도구가 현재 과제와 무관하면 탐색과 검증만 늘 수 있다. 처음에는 명시 호출로 효과를 확인하고, 반복적으로 도움이 되는 스킬만 자동화하는 편이 안전하다.

서브에이전트는 언제 메인 에이전트보다 유리한가?

대량 로그나 여러 문서를 읽고 짧은 요약만 돌려주는 독립 작업에 적합하다. 반대로 계획·구현·테스트가 같은 맥락을 계속 공유하거나 빠른 표적 수정이라면 메인 에이전트가 낫다. 병렬화하기 전 작업 간 의존성과 중복 탐색 비용부터 확인해야 한다.

내 저장소에서 프레임워크 효과를 어떻게 측정할까?

최근의 작은 버그와 중간 기능을 섞어 순정과 후보 하나를 비교한다. 실행 순서, 권한, 시간 상한과 채점 기준을 먼저 고정하고 성공 여부뿐 아니라 사람 개입, 누적 입력, 실행 시간, diff 크기, 산출물 재사용 여부를 기록한다. 한 번의 승패보다 어떤 실패가 반복해서 줄었는지를 본다.

결론

AI 코딩 스킬과 프레임워크는 모델 위에 얹는 품질 보너스가 아니다. 특정 실패를 줄이기 위해 시간, 컨텍스트, 상호작용을 지불하는 제어 장치다.

작고 명확한 작업은 순정 Codex나 Claude Code에 짧은 완료 조건을 주는 방식부터 시작하는 것이 낫다. 팀 규칙이 반복되면 좁은 스킬을 하나 추가한다. 여러 세션에 걸친 기능에서 명세·계획·서브에이전트 프레임워크를 우선 검토한다.

가장 좋은 구성은 기능이 가장 많은 구성이 아니다. 순정으로 실제로 발생한 실패를 확인한 뒤, 그 실패 하나를 가장 작은 비용으로 막는 구성이다.

출처 및 참고자료

본문에서 인용한 자료를 다시 찾기 쉽도록 성격별로 정리했다.

연구 및 벤치마크

• SkillsBench v4 — 여러 분야에서 선별된 스킬의 평균 효과를 비교한 벤치마크
• SWE-Skills-Bench — 소프트웨어 개발 스킬의 성공률과 토큰 비용을 비교한 예비 연구
• Evaluating AGENTS.md — 저장소 컨텍스트 파일이 성공률과 추론 비용에 미치는 영향
• AGENTS.md 효율 연구 — 실제 소규모 PR 재구성에서 실행 시간과 출력 토큰을 비교한 연구
• SWE-agent — 모델 친화적인 도구 인터페이스의 효과
• Lost in the Middle — 긴 컨텍스트에서 정보 위치에 따른 성능 차이
• Skill-Inject v3 — 외부 에이전트 스킬을 통한 프롬프트 인젝션 위험
• Agentless — 단순한 코드 탐색·수정 파이프라인의 경쟁력
• METR 연구 노트 — Claude Code·Codex와 기존 하네스의 시간 지평 비교

공식 문서

• OpenAI Codex 플러그인 문서 — 반복 작업을 스킬과 앱으로 구성하는 방법
• Anthropic 장기 에이전트 하네스 — 여러 세션에 걸친 작업의 상태 인수인계 방식
• Anthropic 컨텍스트 엔지니어링 — 에이전트 컨텍스트를 유한한 자원으로 다루는 원칙
• Claude Code 확장 기능 비교 — 스킬·훅·서브에이전트·에이전트 팀의 선택 기준
• Claude Code 서브에이전트 문서 — 서브에이전트가 적합한 작업과 비용 특성

비교한 도구

• Ponytail
• Superpowers
• BMAD
• GSD
• Spec Kit
• Ouroboros
• Everything Claude Code
• Oh My Codex
• Ralph Loop