[핵심 메시지] 유출된 Claude Code의 구조적 패턴을 분석하여, AI 에이전트에게 126개의 모든 도구를 보여주는 대신 검색 기반(ToolSearch)으로 전환함으로써 토큰 낭비를 88% 줄이고 에이전트의 도구 선택 정확도와 다중 작업 능력을 대폭 향상시켰습니다.[전체 요약] 저자는 텔레그램 기반 AI 에이전트 ‘니콜(Nicole)’의 도구 관리 비효율성(126개 도구를 매번 LLM에 전체 노출)을 해결하기 위해, 유출된 Claude Code 53만 줄의 TypeScript 소스에서 도구 관리 패턴을 분석했습니다. 코드를 단순히 복사하는 대신, 니콜의 아키텍처에 부족한 6가지 핵심 도구(검증, 태스크 관리, 컨텍스트 검사, 워크플로, 도구 검색, 시스템 알림)를 도출하고 에이전트 팀을 활용해 병렬로 구현했습니다.
이 과정에서 LLM이 우회 호출되는 텔레그램 라우팅 문제와 토큰(Token: AI가 텍스트를 인식하고 처리하는 기본 데이터 조각) 계산 오차 문제를 겪었으나, 구조적 수정과 동적 비율 계산을 통해 해결했습니다. 결과적으로 프롬프트에 노출되는 도구 수를 16개로 줄여 컨텍스트 길이를 절반으로 단축시키고, 에이전트의 성능과 경제성을 동시에 확보했습니다.

[3가지 핵심 개념]
1. ToolSearch (도구 검색 아키텍처)
  - 에이전트에게 모든 가능한 행동(126개)을 한 번에 주입하지 않고, 필수 도구(Core 16개)만 기본 제공하는 설계입니다. 나머지 도구는 한국어 키워드 매칭을 통해 필요할 때만 검색하여 불러옵니다. 이 구조는 인지 과부하(잘못된 도구 선택)를 막고 토큰 비용을 급감시킵니다.
2. CtxInspect (동적 컨텍스트 보정기)
  - 한국어 텍스트가 영어보다 더 많은 토큰을 소모하는 현상을 교정하는 시스템입니다. 글자 수 기반의 단순 추정치와 실제 API가 반환한 사용량 간의 비율을 이동평균(과거 일정 기간의 데이터 평균을 지속해서 추적하는 방식)으로 계산하여, 매 턴마다 정확한 토큰 한도를 관리하고 초과 시 자동 요약을 수행합니다.
3. Task Management (의존성 기반 다중 태스크 추적)
  - 단일 세션에서 여러 작업을 동시에 수행할 때 에이전트가 기존 작업을 잊어버리는 문제를 해결하는 시스템입니다. 작업(Task)들을 파일 단위로 저장하고, ‘블록(blocks)’과 ‘대기(blockedBy)’ 상태를 명시하여 A작업이 끝나야만 B작업이 활성화되도록 논리적 흐름을 강제합니다.
[5분 실행 과제] 현재 당신이 AI(ChatGPT, Claude 등)에게 자주 사용하는 프롬프트나 지시문 목록을 열어보십시오. 한 번의 질문에 AI가 고려해야 할 조건이나 옵션이 5개를 초과한다면, 이를 “기본 지시”와 “추가 요청 시에만 고려할 지시” 두 가지로 분리하여 프롬프트를 다시 작성해 보십시오.
LLM의 인지적 한계와 아키텍처적 제약첫째, 126개의 도구를 16개로 줄인 ToolSearch의 성공은 LLM의 ‘어텐션(Attention) 메커니즘’의 한계를 정확히 공략한 결과입니다. 어텐션은 문장 내의 모든 단어(토큰)가 다른 모든 단어와 얼마나 연관되어 있는지 확률을 계산하는 방식입니다. 정보량이 많아질수록 연산량은 기하급수적으로 폭증하며, 특히 프롬프트 중간에 위치한 정보를 무시해 버리는 ‘중간 정보 누락(Lost in the Middle)’ 현상이 발생합니다. 126개의 도구를 한 번에 주입하는 것은 AI에게 건초 더미에서 바늘을 찾으라고 강요하는 것과 같으며, 이를 16개로 제한함으로써 어텐션 메커니즘이 핵심 논리에만 집중하도록 강제한 것입니다.
둘째, CtxInspect가 해결한 한국어 토큰 계산 오차는 AI가 텍스트를 인식하는 ‘BPE(Byte Pair Encoding)’ 방식의 구조적 불평등에서 기인합니다. BPE는 자주 등장하는 글자 조합을 하나의 토큰(텍스트 조각)으로 묶는 기술입니다. 영어는 1단어가 보통 1토큰으로 매핑되지만, 한국어는 형태소가 복잡하고 AI 학습 데이터에서 차지하는 비중이 작아 1음절이 2~3개의 토큰으로 잘게 쪼개집니다. 저자가 초기에 사용했던 ‘글자 수 / 2’라는 단순 공식은 언어 간의 BPE 처리 방식 차이를 무시한 잘못된 전제였으며, 이를 API의 실제 응답값으로 교정한 것은 기술적으로 매우 타당한 접근입니다.

결과적으로 이 두 도구의 결합은 단순히 프롬프트를 예쁘게 다듬는 ‘프롬프트 엔지니어링’을 넘어섰습니다. AI의 인지적(어텐션), 구조적(BPE) 한계를 인정하고, AI가 연산하기 가장 편안한 환경을 물리적으로 구축해 주는 ‘하네스(Harness, 제어 환경) 엔지니어링’의 정석을 보여줍니다.
검색의 경직성과 지연 지표의 함정첫째, ToolSearch가 채택한 하드코딩된 ‘키워드 매핑(Keyword Mapping, 특정 단어와 도구를 수동으로 짝지어두는 방식)’은 극도로 경직된 구조적 취약점을 가집니다. 사용자가 “네이버 메인 페이지 스크린샷 찍어줘”라고 명확히 말할 때는 작동하지만, “지금 보고 있는 화면 캡처해 놔”처럼 사전 정의된 키워드(“브라우저”, “스크린샷”)가 누락된 유의어를 사용할 경우 검색 엔진은 실패합니다. 126개의 도구를 LLM의 추론 능력에 맡기는 대신 단순 딕셔너리(사전) 검색으로 대체했기 때문에, 키워드가 일치하지 않으면 AI는 해당 도구의 존재조차 알지 못한 채 작업을 포기하게 되는 단일 장애점(Single Point of Failure)이 발생합니다.
둘째, CtxInspect의 핵심 로직인 ‘이동평균(Moving Average)’은 본질적으로 과거의 데이터로 미래를 예측하는 지연 지표(Lagging Indicator)입니다. 대화 초반에 일상적인 한국어 대화(비율 1.3)가 주를 이루다가 갑자기 복잡한 영문 코드 분석(비율 1.0에 근접)으로 대화의 성격이 급변한다고 가정해 보십시오. 이동평균은 과거의 높은 비율(1.3)을 한동안 유지하므로, 실제 토큰은 여유가 있음에도 불구하고 시스템이 ‘토큰 한도 초과’로 오판하여 멀쩡한 과거 대화 기록을 조기에 요약(삭제)해버리는 데이터 유실을 초래할 수 있습니다.

셋째, 이 아키텍처는 비용 절감(토큰 절약)을 위해 ‘자율 에이전트(Autonomous Agent)’의 본질을 훼손하는 모순을 안고 있습니다. 16개의 핵심 도구만 보여주고 나머지는 검색어에 의존하게 만들면, 에이전트는 예상치 못한 엣지 케이스(Edge Case, 극단적이거나 예외적인 상황)에 직면했을 때 창의적으로 도구를 조합할 기회를 원천 차단당합니다. 효율성을 얻은 대신, 개발자가 미리 그어놓은 좁은 경로 밖으로는 한 발짝도 나갈 수 없는 구조적 한계를 지닙니다.

저스틴) 다루는 문제에 따라 워크플로어의 서브플로어나 스텝을 정적으로 사람이 고정해 주거나 AI 에이전트가 동적으로 선택할 수 있게 하는 게 현실적일 수 있습니다. AI에이전트가 동적으로 선택할 때도 대상 스킬을 사람이 제한하거나 제한하지 않게도 할 수 있게 합니다.

만약 당신이 구축하는 AI 에이전트에 ToolSearch 아키텍처를 이식한다고 가정해 봅시다. 앞서 비판(Critique) 경로에서 지적했듯, 사용자가 사전에 없는 모호한 표현(예: “화면 캡쳐해줘” 대신 “지금 보이는 거 찰칵해줘”)을 입력하면 단순 키워드 검색은 실패합니다.

전체 126개 도구를 프롬프트에 다시 노출하는 방식(토큰 낭비)으로 회귀하지 않으면서도, AI가 유연하게 올바른 도구를 찾아내도록 만들려면 기존의 하드코딩된 ToolSearch 검색 로직을 어떻게 수정해야 할까요?

저스틴) 검색으로 바로 들어가지 말고, 의도 파악을 먼저 하고, 파악된 의도를 사용자의 표현과 결합해 수정된 것으로 ToolSearch 하도록 합니다.

“프롬프트 엔지니어링의 시대가 가고 하네스 엔지니어링의 시대가 왔다”고 강조한 이유는, AI를 다루는 방식이 근본적으로 변했기 때문입니다.

‘하네스(Harness)’는 원래 말이나 썰매개에게 씌우는 마구(가죽끈)나, 고공 작업자의 안전벨트를 뜻합니다. 지능은 뛰어나지만 환각(Hallucination)을 일으키거나 엉뚱한 결론으로 튀어버리기 쉬운 야생마 같은 LLM이, 수레(우리가 원하는 결과물)를 안전하고 정확하게 끌 수 있도록 LLM 주변에 구축하는 소프트웨어적 통제 환경과 시스템 아키텍처를 ‘하네스 엔지니어링’이라고 부릅니다.

구체적인 예를 들어보겠습니다. 프롬프트 엔지니어링이 AI에게 “126개 도구 중에서 실수하지 말고 가장 알맞은 걸 잘 골라봐”라고 ‘말(자연어)’로 지시하는 것이라면, 하네스 엔지니어링은 AI가 아예 딴짓을 하지 못하도록 양옆에 가드레일을 치고 필수 도구 16개만 쥐여주는 것(ToolSearch), 그리고 AI가 지치지 않도록 뇌 용량을 실시간으로 체크해서 과거 기억을 알아서 압축해 주는 것(CtxInspect)입니다. 즉, AI에게 무엇을 시킬지 고민하는 단계를 넘어, AI가 일할 수밖에 없는 물리적 환경을 코드로 짜는 것입니다.

하네스 설계 기저의 3가지 숨은 전제 (Hidden Assumptions)

전제 1: 자연어(프롬프트)는 완벽한 통제 수단이 아니다. 아무리 프롬프트를 정교하게 써도 확률 모델인 LLM은 반드시 실수한다. 100% 통제를 위해서는 결국 프로그래밍 언어(TypeScript 등)를 통한 시스템적 제어가 필수적이다.
전제 2: 모델의 지능보다 컨텍스트 관리가 성패를 가른다. 더 똑똑한 LLM(예: GPT-4)을 쓰는 것보다, 약간 덜 똑똑한 모델(GPT-5.4-mini)을 쓰더라도 그 모델이 처리해야 할 정보의 양(토큰)과 종류를 아키텍처 단에서 완벽하게 필터링해 주는 것이 비용 대비 성능이 압도적으로 높다.
전제 3: 자율성(Autonomy)은 제한될 때 더 극대화된다. 에이전트에게 무한한 자유도를 주면 길을 잃는다. ‘태스크 파일 기반의 의존성(블록/대기) 관리’처럼 엄격한 궤도를 만들어 주어야 비로소 다중 작업을 완료할 수 있다.

3. 비판적 질문 (Critical Question) 그렇다면 한 가지 치명적인 모순이 발생합니다.

질문: “결국 개발자가 모든 조건과 도구 검색 로직, 작업 순서(하네스)를 하드코딩으로 촘촘하게 통제해야 한다면, 처음부터 기존의 결정론적(규칙 기반) 소프트웨어를 짜는 것과 무엇이 다릅니까? 시스템이 견고해질수록 AI 에이전트 특유의 ‘창의적 문제 해결 능력(자율성)’은 소멸하는 것 아닐까요?”

저자가 가장 강조하고자 했던 핵심 메시지를 요약합니다.

[Core Message] AI 에이전트를 실무에서 제대로 작동하게 만드는 결정적 요인은 ‘프롬프트(명령어)의 정교함’이 아니라, AI가 실수할 수 없도록 물리적·구조적 제약을 가하는 ‘하네스(통제 환경) 아키텍처의 설계’에 있다.

[Full Summary] 저자는 53만 줄에 달하는 Claude Code 유출 소스를 분석하며 코드를 그대로 베끼는(Copy) 대신, 그들이 에이전트를 통제하는 ‘구조적 패턴’을 추출했습니다. 이전까지 저자의 에이전트 ‘니콜’은 126개의 도구를 한 번에 LLM에 주입하는 ‘프롬프트 의존적’ 방식을 썼으나, 이는 토큰 낭비와 환각(잘못된 도구 선택)을 초래했습니다. 저자는 유출 코드에서 영감을 얻어 도구 검색(ToolSearch), 동적 토큰 검사(CtxInspect), 태스크 의존성 관리 등의 6가지 제어 도구(하네스)를 이식했습니다. 그 결과, AI에게 주어지는 선택지를 16개로 물리적으로 제한함으로써 오히려 에이전트의 작업 정확도와 다중 작업 능력을 비약적으로 상승시키고 비용을 88% 절감했습니다.

[3 Key Concepts]

패턴의 이식 (Pattern vs. Copy): 유출된 코드의 가치는 특정 기능의 복사가 아니라, 대규모 도구를 어떻게 분류하고 LLM에 노출할 것인가(Core vs. Deferred)에 대한 아키텍처적 해답을 얻는 데 있었습니다.
인지적 과부하 통제 (Cognitive Load Control): AI에게 무한한 선택지(126개 도구)를 주는 것은 자유가 아니라 혼란입니다. 선택지를 16개로 제한하고 나머지는 검색 시스템(ToolSearch)에 맡김으로써 LLM의 추론 성능을 최적화했습니다.
하네스 엔지니어링 (Harness Engineering): AI의 지능에 기대어 “잘해봐”라고 말(프롬프트)로 지시하는 시대를 넘어, AI가 궤도를 이탈하지 못하도록 안전장치(검증, 파일 기반 작업 대기열, 토큰 한도 자동 계산)를 코드로 엮어내는 환경 구축 방법론입니다.

[5-Min Task] 현재 당신이 다루고 있거나 기획 중인 AI 시스템에서, AI의 판단력(프롬프트)에 전적으로 의존하고 있는 과정 한 가지를 식별하십시오. 그 과정을 AI의 선택이 아니라, ‘시스템적인 규칙(예: 특정 단어가 없으면 실행 불가, 2단계 완료 전 3단계 접근 불가)’으로 강제할 수 있는 방법을 1문장으로 설계해 보십시오.

저스틴) 계층적 분류 방식을 사용하는 것은 어떨까요?

계층적 분류 방식(Hierarchical Classification)을 도입하자는 제안은 인지적 과부하를 줄이는 매우 고전적이고 논리적인 접근입니다. 100개의 도구를 ‘파일’, ‘편집’, ‘이미지’ 등 5~6개의 상위 카테고리로 묶어서 1차적으로 보여주는 구조입니다.

이 방식을 AI 에이전트 환경에 적용했을 때의 강점과 한계는 다음과 같습니다.

강점 (토큰 절감): 126개를 전부 나열하는 것보다 AI가 한 번에 읽고 처리해야 할 정보량(컨텍스트 윈도우)을 극적으로 줄여주어, 집중력이 분산되는 현상을 막을 수 있습니다.
한계 (다중 턴 지연, Multi-turn Latency): 사람에게는 마우스 클릭 몇 번으로 끝나는 일이지만, AI 에이전트에게는 구조적 지연을 유발합니다. AI가 원하는 도구를 쓰려면 [1. 상위 카테고리 메뉴 요청] -> [2. 하위 도구 목록 확인] -> [3. 최종 도구 선택 및 실행]이라는 최소 3번의 생각-행동 사이클(API 왕복 호출)을 거쳐야 합니다. 이 과정에서 시간과 비용이 낭비됩니다.
반면 원문 저자가 채택한 ‘ToolSearch(검색)’ 방식은 16개의 핵심 도구만 평면에 늘어놓고, 나머지는 “브라우저 스크린샷” 같은 키워드로 검색 엔진에 던져 단 한 번의 호출로 숨겨진 도구를 바로 끄집어냅니다. 즉, 계층적 깊이를 파고드는 횟수를 줄여 AI가 더 빠르게 결론에 도달하도록 만든 ‘평면적(Flat) 검색 아키텍처’입니다.