DHH의 '규약은 토큰 효율'을 자체 프레임워크로 측정해 보기

서론

2026년 9월 23일 Rails World 기조연설에서 DHH는 "설정보다 규약이 토큰 효율에 연결된다"고 말했습니다.

하지만 Rails의 규약은 모델이 학습 데이터로 여러 번 본 것입니다. 모델이 잘 모르는 규약에서도 같은 말이 적용될 수 있을까요?

Guren은 필자가 개발하고 있는 Bun용 풀스택 프레임워크입니다. Hono, Drizzle, React 위에 Laravel 스타일의 규약을 얹었습니다. 아직 새로운 것이라 모델은 이 규약을 거의 모릅니다. 그래서 규약은 가이던스(ガイダンス: CLAUDE.md, 규칙, 스킬 등 에이전트용 설명 일체)로 알려주고 있습니다. 첫 번째 실험에서는 가이던스의 유무에 따라 에이전트의 작업 횟수가 달라지는 것을 소개했습니다.

본 기사에서는 다음 두 가지를 측정한 결과를 통해 이 질문에 답합니다.

• 모르는 규약을 알려줄 때 얼마나 비용이 드는가
• 알려준 규약을 에이전트가 실제로 사용하는가

1. 모르는 규약을 가르치는 비용

측정 방법

Guren은 Hono 위에 만들어진 프레임워크입니다. 따라서 규약이 없는 Hono 구성과 비교하여, 오직 규약을 알려주는 비용만을 추출할 수 있다고 생각했습니다.

framework-comparison 리포지토리에는 같은 사양의 작은 블로그가 여러 프레임워크로 구현되어 있습니다. 로그인, 게시물 작성, 댓글, 검증, 테스트까지 갖춘 앱입니다.

이 앱에 태그 기능을 추가하는 작업을 Guren과 Hono 구현에 맡겼습니다. DB 테이블 추가와 마이그레이션, React 폼과 표시, ?tag=로 필터링, 검증, 테스트까지 포함합니다. typecheck, 앱 테스트, 숨겨진 HTTP 스모크가 모두 통과하면 합격입니다.

Hono 구현은 Hono, Drizzle, React의 SPA를 수동으로 조합한 구성입니다. 기반 부품은 Guren과 같으므로 차이는 Guren의 규약뿐입니다.

규약 및 가이던스 예시

예를 들어, Guren 앱의 게시물 목록은 다음과 같이 작성합니다. 컨트롤러는 app/Http/Controllers에 두고, 쿼리는 validateQuery()로 검증합니다. 목록은 모델의 paginate()로 가져오고, @guren/core의 paginate()로 페이지 이동 링크를 붙인 후, Inertia 페이지로 전달합니다.

export default class PostController extends Controller {
async index() {
const { page } = this.validateQuery(ListPostsQuerySchema)
...
}

이 작성 방식은 가이던스 규칙 파일에서 알려줍니다. 예를 들어 페이지 이동에 대해서는 다음과 같이 적혀 있습니다.

For Inertia/HTTP pagination links wrap it with `paginate` from `@guren/core`:
`paginate(result, { path?, query?, fragment? })` — those three fields are `PaginatorOptions`.

가이던스가 없으면 에이전트는 이런 작성 방식을 타입 정의에서 찾아야 합니다. 실제로 가이던스 없는 3번 중 2번은 이 paginate() 사용법을 찾기 위해 타입 정의를 읽어 내려갔습니다.

결과

• 가이던스가 없으면 Guren이 가장 많은 턴을 사용했습니다. 함수가 어떤 패키지에 있는지 찾는 작업도 포함되었습니다.
• 가이던스를 넣자, 턴 수는 Hono와 같아졌습니다. 규약을 알려주니 헤매지 않고 작성할 수 있었습니다.
• 그럼에도 불구하고 비용은 Hono의 1.26~1.49배입니다.

차이는 어디에서 오는가

Sonnet 5.5의 로그를 기반으로 작업을 분류하고, Hono와의 차이가 어떤 작업에서 오는지 집계했습니다. 직접 측정한 값이 아니라, 분류 규칙에 근거한 추정치입니다.

⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

• 가이던스가 있는 경우, 차액은 모두 가이던스를 읽는 데서 발생했습니다. 구현 자체는 Hono보다 약간 저렴합니다.
• 가이던스는 에이전트가 모델을 호출할 때마다 다시 읽힙니다. 25.5k 토큰의 가이던스로 인해 한 번당 $0.17~$0.19가 소요되었습니다.
• 가이던스를 7.1k 토큰으로 줄이자 차이는 $0.135까지 줄었습니다.

참고로, 이 비교는 완성된 앱에 기능을 하나 추가하는 비용입니다. 프레임워크가 앱의 기반에서 담당하는 범위의 차이는 여기에 나타나지 않습니다.

2. 가르친 규약은 사용되는가

태스크

Guren으로 만든 블로그에 9개의 기능 티켓을 구현하게 했습니다. 티켓은 제품 오너(Product Owner)가 작성하는 요청문의 형태를 취하고 있습니다. 무엇을 만들지만 적었을 뿐, 사용할 API는 적지 않았습니다.

4가지 모델에 대해 가이던스 유/무를 각각 3회씩 테스트했습니다. 합격 조건은 채점용 숨겨진 테스트(총 84개)와 typecheck가 모두 통과하는 것입니다.

결과

| 모델 | 합격 (없음 → 있음) | 턴 | 비용 |
|---|---|
| Sonnet 5.5 | 26/27 → 27/27 | 37 → 29(-22%) | $0.57 → $0.61 |
| ... |

턴과 비용은 중앙값입니다.

• Opus, Fable, 가이던스가 있는 Sonnet은 9개 모두에 합격했습니다. 모델이 잘 모르는 프레임워크에서도 기능 단위의 구현을 해낼 수 있습니다.
• 가이던스를 추가하자 어떤 모델이나 턴 수가 11~27% 감소했습니다.
• 비용이 하락한 것은 세션이 긴 Opus와 Fable였습니다. Sonnet은 거의 변동이 없었고, Haiku는 증가했습니다.
• 합격률이 상승한 것은 Haiku뿐이었습니다(30%에서 44%).

프레임워크 기능을 사용했는가

합격한 181회의 경우 중, 티켓에 해당하는 Guren의 기능(첨부 파일, 속도 제한 등)을 사용하지 않고 같은 처리를 직접 구현한 것은 단 6회였습니다. 나머지 175회는 Guren의 기능을 사용했습니다.

• 이는 가이던스가 없는 경우에도 동일했습니다. 가이던스가 없어도 에이전트는 스스로 기능을 찾아 사용하고 있습니다.
• 1의 세부 내역을 보면, 가이던스가 줄이고 있는 것은 기능 탐색 노력(手間)이라고 생각됩니다. 그만큼 턴 수가 감소한 것입니다.

3. CLAUDE.md 작성 시 시사점

Guren에 국한되지 않고, 자신의 프로젝트의 규약을 에이전트에게 가르칠 때도 같은 말이 할 수 있을 것 같습니다.

• 가이던스는 호출할 때마다 다시 읽히는 고정비입니다. 양 자체가 비용이 되므로, 항상 로드하는 내용은 줄이는 것이 좋습니다.
• 가이던스의 효과는 턴 수에 나타납니다. 이번에는 세션이 긴 모델일수록 비용도 하락했습니다. 작업이 길수록 고정비를 회수하기 쉬운 것 같습니다.
• 상위 모델에서는 가이던스 유무로 합격 여부는 변하지 않았습니다. 차이가 나는 것은 노력(手数)과 비용입니다.
• 프레임워크 기능은 가이던스가 없어도 찾아 사용되었습니다. 가이던스에 작성해야 할 내용은 찾는 노력을 줄여주는 정보입니다.

4. 주의사항

• 러너는 헤드리스(headless) Claude Code만 사용했습니다.
• 시도는 각각 3회였습니다. 경향은 보이지만, 효과가 있다고 단정할 수 있는 수는 아닙니다.
• 티켓은 직접 만들었고, 사양을 세밀하게 정했습니다. 그만큼 실제 개발의 티켓보다 쉬워졌습니다.
• 1과 2는 러너의 세부 설정이 다릅니다. 비용 금액은 비교할 수 없습니다.
• Rails에서의 측정이 아니므로, Rails의 규약이 얼마나 효과적인지는 알 수 없습니다.

요약

이번 결과로 알 수 있는 것은, 규약이 토큰 효율로 이어지기 위해서는 모델이 그 규약을 알고 있어야 한다는 것입니다.
알지 못하는 규약은 가이드(guidance)를 통해 알려주면 에이전트가 사용합니다. 상위 모델은 9개의 기능 티켓 모두에 합격했으며, 구현된 대부분의 내용은 프레임워크 기능을 활용했습니다.
다만, 가이드를 제공하는 것 자체가 호출할 때마다 비용이 발생합니다. 기능을 하나 추가하는 데 드는 비용은 Hono의 1.26~1.49배였습니다.
가이드를 구체화할수록 그 차이는 작아집니다.

맺음말

Guren에는 앱의 기반이 되는 다음과 같은 기능들이 처음부터 갖춰져 있습니다.

• 프론트엔드와 서버를 연결하는 Inertia
• 페이지 props 및 라우트 타입 자동 생성
• 검증 에러를 폼으로 전달
• 인가(Policy)와 비동기 처리 작업(Job)
• 보안 헤더 등 안전을 위한 설정

이번에 비교한 Hono 구성에서는 이러한 기능들 중 상당 부분을 직접 작성하거나 간소화하여 처리해야 했습니다. 이번 측정에서도 에이전트는 Guren의 기능을 사용하여 9개의 티켓을 구현했습니다.

에이전트용 가이드(CLAUDE.md, 규칙, 스킬, hooks)를 포함하면 즉시 앱을 만들 수 있습니다. 꼭 사용해 보세요.

bunx create-guren-app my-app --agents claude

문서나 에이전트와 함께 앱을 만드는 코스는 Guren 공식 웹사이트에 있습니다.

토론