불편한 진실: 모델도, 병렬화도, 재시도도 아니다
많은 팀이 AI 코딩 품질을 올리기 위해 더 비싼 모델로 교체하거나, 에이전트를 병렬로 띄우거나, 실패 시 자동 재시도 루프를 붙인다. 직관적으로 맞아 보이는 접근이다. 그런데 52회 통제 실험 데이터는 정반대를 가리킨다.
UpGPT 팀이 공개한 벤치마크 리포트(dev.to)에 따르면, AI 코딩 품질에 가장 큰 영향을 미친 단일 변수는 AI가 시작하기 전에 작성하는 구조화된 명세서—CONTRACT.md—의 존재 여부였다. 같은 모델, 같은 코드베이스, 다른 문서 하나. 그것만으로 품질 점수는 5/10에서 9/10으로 뛰었고 비용은 54% 줄었다.
CONTRACT.md가 뭐길래
CONTRACT.md는 화려한 기술이 아니다. AI 워커가 작업을 시작하기 전에 읽는 단 하나의 마크다운 파일이다. 핵심은 네 가지 항목이다.
- Interfaces: 정확한 TypeScript 인터페이스 정의
- Database: 테이블명, 컬럼명, SQL 컨벤션
- Import paths: 타입과 클라이언트의 정확한 임포트 경로
- Non-goals: 이번 PR에서 구현하지 않는 것의 명시적 목록
이 네 가지가 있을 때와 없을 때의 차이가 2×2 팩토리얼 실험(20회 통제 실행)에서 명확하게 드러났다. CONTRACT.md가 없으면 AI 워커는 인터페이스를 추측하고, 임포트 경로를 탐색하고, 비목표 기능까지 구현하려 든다. 있으면 탐색을 멈추고 실행을 시작한다. 그 차이가 시간 68% 단축, 비용 65% 절감으로 나타났다.
생성 비용은 약 $0.15. 첫 실행에서 바로 회수된다.
직관과 다른 세 가지 함정
벤치마크가 부수적으로 뒤집은 가정들이 더 흥미롭다.
에이전트 팀(Agent Teams)은 비쌀 뿐 낫지 않다. Anthropic이 마케팅하는 네이티브 서브에이전트 구조는 실제로 비용이 73~124% 더 들었고 품질 향상은 없었다. 이유는 간단하다. 에이전트 각각이 전체 코드베이스 컨텍스트를 독립적으로 로드하기 때문이다. 80K 토큰짜리 컨텍스트를 세 에이전트가 각자 읽으면 캐시 소각 비용이 지배한다. Sequential + CONTRACT가 비용 면에서 항상 이긴다.
재시도 루프는 품질을 오히려 깎는다. 청화대 NLH 논문(2026년 3월)이 SWE-bench에서 자기진화 루프의 효과를 보고했지만, 코드 생성 태스크에서는 반대 결과가 나왔다. 모델은 부분 수정이 아니라 파일 전체를 재생성한다. 임포트 경로 하나를 고치려다 올바른 CRUD 엔드포인트와 테스트가 통째로 날아간다. 15번 재시도를 거쳐도 같은 패턴이 반복됐다. 품질은 9/10에서 6/10으로 하락, 비용은 2.1배 증가.
Opus 리뷰 패스는 CONTRACT가 좋으면 의미 없다. CONTRACT.md가 잘 작성된 상태에서 Sonnet은 이미 9.8/10을 찍는다. Opus가 전체 출력을 읽고 외과적 수정을 가해도 품질 변화가 없었다. 비용만 56% 추가됐다. 더 비싼 모델을 리뷰어로 붙이기 전에 브리프를 먼저 다듬어야 한다.
실전에서의 검증: Jira 티켓을 에이전트에 직접 던지면
dev.to에 공개된 또 다른 실전 사례는 이 원칙의 다른 구현 형태를 보여준다. GitHub Copilot 에이전트에 Jira 티켓 URL을 그대로 붙여넣으면 MCP를 통해 요구사항, 설명, 인수 조건(AC)을 구조화 데이터로 가져온다. 핵심은 여기서도 문서다.
.github/copilot_instructions.md는 에이전트의 행동 규칙을 정의하고, .github/workflows/copilot-setup-steps.yml은 어떤 도구를 쓰고 어떻게 검증할지를 명시한다. 에이전트는 이 두 파일을 읽고 코드를 쓰고, 테스트를 돌리고, 실패하면 오류 로그를 읽어 수정한다. 개발자는 스캐폴딩에 쓰던 시간의 50%를 아키텍처로 돌렸다고 보고한다.
Jira 티켓의 AC가 CONTRACT.md 역할을 하는 셈이다. 인수 조건이 불명확한 티켓은 에이전트에게 vague 프롬프트를 주는 것과 같다.
모델 진화가 가속될수록 명세서의 중요성은 커진다
한편 Kimi K2.6은 장기 구간 코딩과 에이전트형 작업에서 한 단계 올라선 성능을 보여준다. 4,000회 이상 도구 호출과 12시간 이상 연속 실행으로 Zig 추론 최적화에서 토큰 처리량을 약 15 tokens/sec에서 193 tokens/sec로 끌어올렸고, 8년 된 금융 매칭 엔진을 전면 개편해 처리량 133~185% 향상을 기록했다. SWE-Bench Verified 80.2, Terminal-Bench 2.0에서 66.7이라는 수치는 에이전트 실행 역량이 실질적으로 확장되고 있음을 보여준다.
그런데 바로 그렇기 때문에 명세서 구조가 더 중요해진다. 모델의 실행 역량이 늘어날수록, 명세서가 불명확할 때 에이전트가 '탐색'하며 소진하는 컨텍스트와 비용의 절대량도 커진다. 능력 있는 에이전트일수록 잘못된 방향으로 더 멀리 달려간다.
팀에 적용할 수 있는 실행 규칙
52회 벤치마크와 실전 사례가 수렴하는 지점을 팀 운영 규칙으로 정리하면 이렇다.
- 3개 이상 파일을 건드리는 모든 작업엔 CONTRACT 먼저. 인터페이스, DB 스키마, 임포트 경로, 비목표를 한 파일에 명시한다. 생성 비용 $0.15, 첫 실행에서 회수된다.
- Jira AC를 에이전트가 읽을 수 있는 구조로 작성한다. 자연어 서술보다 체크 가능한 인수 조건 목록이 에이전트에게 훨씬 직접적으로 작동한다.
- 재시도 루프를 자동화하지 않는다. 실패 시 CONTRACT를 개선하는 것이 루프를 도는 것보다 품질과 비용 양쪽에서 낫다.
- 에이전트 팀 병렬화는 규모 확장보다 맥락 격리 비용을 먼저 계산한다. 컨텍스트를 공유하지 않는 병렬화는 비용 폭발의 지름길이다.
- 모델 업그레이드 전에 브리프 품질을 먼저 올린다. Haiku + CONTRACT가 9.0/10을 찍는 상황에서 Opus를 붙이는 건 비용 낭비다.
시사점: AI-First 팀의 새로운 핵심 역량
이 데이터들이 팀 리드에게 던지는 질문은 명확하다. 우리 팀은 좋은 명세서를 쓸 수 있는가?
프롬프트 엔지니어링은 개인 기술이다. 명세서 설계는 팀 구조다. CONTRACT.md를 잘 쓰는 팀은 더 빠르고 저렴하게 더 나은 코드를 낸다. 이는 AI 도구 선택의 문제가 아니라 요구사항을 구조화하는 조직 역량의 문제다.
AI-First 팀 리빌딩에서 내가 이제 가장 먼저 보는 것은 코딩 속도가 아니다. 작업 시작 전에 인터페이스와 경계를 문서로 확정하는 훈련이 팀에 있는가—그 여부가 AI 도구의 ROI를 결정한다.