Claude Code 오케스트레이터로 토큰 비용 80% 줄이는 보일러플레이트 공개

Claude Code를 단순한 코드 보조 도구가 아니라 반복 실행되는 자동화 파이프라인 안에 넣으려는 시도가 나왔다. 개발자 Gojko Adzic이 공개한 'lights-on software factory' 보일러플레이트는 Claude Code 기반 개발 워크플로를 안전하게 돌리기 위한 출발점이다. Votito에서 실제로 운영한 구성을 바탕으로 정리했으며, 새 프로젝트에 바로 얹을 수 있는 뼈대이자 구조를 학습하기 위한 예제 성격을 함께 띠고 있다.

저장소가 제공하는 것은 크게 다섯 갈래다. 우선 호스트와 작업 디렉터리만 공유하는 샌드박스 컨테이너에서 Claude Code를 실행한다. Alpine과 Node.js, make, git 등으로 구성된 이미지를 make 타깃으로 빌드하고 띄우는 방식이라, 에이전트가 실행되는 환경과 개발자 환경이 분리된다.

두 번째는 결정론적 bash 명령 규제기다. 에이전트가 셸 명령을 실행할 때마다 깊이 들여다보고 프로젝트 규칙에 허용된 명령인지 자동으로 승인하거나 거부하며, 막힌 경우에는 대신 무엇을 해야 하는지 지시를 붙인다. 매번 사람이 승인 버튼을 누르는 피로를 줄이는 것이 목적이다. 여기에 더해 PostToolUse 훅이 Claude가 수정한 모든 JavaScript 파일에 린터를 돌려, 도메인 특화 규칙 위반을 사람 대신 기계가 잡아낸다. 반복적으로 같은 설계 피드백을 하게 될 때마다 그 규칙을 린터에 추가하라고 Claude에게 요청하는 식으로 규칙이 축적된다.

세 번째 축은 오케스트레이터다. 계획 단계에서 만들어진 플랜을 입력으로 삼아 멀티 에이전트 Claude 워크플로 스크립트를 결정론적으로 생성한다. 테스트와 게이트 구조를 스크립트에 미리 박아 넣고, 워크플로 조율이라는 기계적인 부분에서 추론 토큰이 소모되지 않게 만든다. 워크플로 생성 속도가 빨라질 뿐 아니라, 추론(LLM)에 맡기던 작업을 커맨드라인 도구로 옮기면서 토큰 지출이 크게 줄어든다는 설명이다.

효과를 보여주는 수치도 함께 제시됐다. Votito에서 이 구성을 운영했을 때, 오케스트레이터를 붙인 쪽이 맨몸의 Claude 워크플로를 돌렸을 때보다 토큰 소비가 약 80% 적었다고 한다. 전체 개요는 공개된 슬라이드 자료에서 확인할 수 있다.

이 저장소가 겨냥하는 문제는 두 가지다. 하나는 에이전트에게 권한을 얼마나 줄 것인가 하는 보안·통제 문제이고, 다른 하나는 에이전트를 반복 실행할수록 불어나는 토큰 비용과 사람의 개입 부담이다. 규제기와 린터 훅은 앞의 문제를, 워크플로 생성기는 뒤의 문제를 각각 결정론적인 장치로 흡수하려는 설계다.

실무적으로 눈여겨볼 지점은 '규칙을 사람이 아니라 저장소에 쌓는다'는 발상이다. 승인 요청이 올 때마다, 혹은 같은 코드 리뷰 지적을 반복할 때마다 그 내용을 규제기 규칙이나 린터 규칙으로 편입시키면, 같은 판단을 두 번 사람이 하지 않아도 된다. HTML이나 CSS 등 다른 파일 형식에 대한 커스텀 eslint 파서를 Claude에게 직접 구현시키라는 안내도 같은 맥락이다.

다만 이 저장소의 계획·구현 워크플로는 의도적으로 단순하게 유지된 예시다. 형식을 보여주고 오케스트레이터의 토대 역할을 하기 위한 것이므로, 실제 프로젝트에서는 각자의 명령이나 더 복잡한 규칙으로 대체하는 편이 낫다고 명시하고 있다. 80%라는 절감 수치 역시 Votito의 특정 셋업에서 나온 결과이지 모든 환경에 그대로 적용되는 값은 아니다.

구성 요소별 문서도 함께 제공된다. 컨테이너 설정은 CONTAINER.md, 명령 규제기는 REGULATOR.md, 린트 훅은 LINTER-HOOK.md, 오케스트레이터 내부는 ORCHESTRATOR.md, 사용자 흐름은 WORKFLOW.md에서 각각 다룬다. 처음 시작할 때는 GETTING-STARTED.md를 따라 컨테이너를 세팅하고 첫 변경을 실행해 보는 순서다.