Agent처럼 생각하기：Claude Code 팀의 도구 설계 철학

Thariq은 Anthropic 엔지니어이자 Claude Code의 핵심 개발자 중 한 명입니다. 2월 말 그는 X에 장문의 글을 게시하며, Claude Code를 구축하는 과정에서 겪은 agent 도구 설계에 관한 다섯 가지 실제 사례를 공유했습니다——이론적 프레임워크가 아니라, 현장에서 직접 부딪히며 얻은 경험입니다. 이 글은 351만 회 조회, 209개의 답글, 9,691개의 좋아요를 기록하며 수많은 고품질 논의를 이끌어냈습니다.

글 전체의 핵심 질문을 이끌어내기 위해, Thariq은 매우 적절한 비유를 사용합니다. 어려운 수학 문제를 풀 때, 어떤 도구가 필요할까요?

종이와 펜은 최소한의 구성——하지만 수작업 계산에 묶이게 됩니다. 계산기는 더 낫습니다——하지만 고급 기능 사용법을 알아야 합니다. 컴퓨터가 가장 강력합니다——하지만 코드를 작성할 줄 알아야 합니다.

도구의 선택은 사용자의 능력에 달려 있습니다. 프로그래밍을 모르는 사람에게 컴퓨터를 주는 것보다는 계산기를 주는 편이 낫습니다. 프로그래머에게 계산기를 주면 오히려 그의 능력을 제한하게 됩니다.

agent의 경우도 마찬가지입니다. 문제는 "어떤 도구가 가장 강력한가"가 아니라, "어떤 도구가 모델의 현재 능력에 가장 잘 맞는가"입니다. 이 글이 공유하는 것은, Claude Code 팀이 그 일치점을 찾아가는 과정에서 겪었던 시행착오입니다.

다음은 원문과 커뮤니티 토론에서 제가 정리한 네 가지 점진적 주제입니다.

---

적을수록 많다——도구 수에 관한 역발상

직관적으로는 도구가 많을수록 agent의 능력이 강해진다고 생각하기 쉽습니다. 하지만 Claude Code 팀의 경험은 정반대였습니다.

Claude Code가 현재 보유한 도구는 약 20개에 불과하며, 팀은 이 모든 도구가 실제로 필요한지 지속적으로 검토하고 있습니다. 새 도구를 추가하는 기준은 높습니다. 이는 모델이 고려해야 할 선택지를 하나 더 늘리는 것을 의미하기 때문입니다——도구가 늘어날수록, 모델이 의사결정을 내릴 때 "인지적 부담"이 커집니다.

이 발견은 커뮤니티에서 강한 공감을 불러일으켰습니다. leon.M은 자신의 실무 경험을 공유했습니다.

Apple의 CodeAct 연구는 이 관점에 정량적 근거를 제공합니다. 단일 코드 실행 프리미티브(code execution primitive)는 복잡한 태스크에서 방대한 전용 도구 세트보다 최대 20% 높은 성능을 보입니다. 적을수록, 실제로 더 많을 수 있습니다.

AskUserQuestion 도구의 세 차례 반복은 이 원칙을 가장 잘 보여주는 사례입니다. Claude Code 팀은 Claude가 사용자에게 질문하는 능력을 향상시키고 싶었습니다——Claude가 일반 텍스트로 질문할 수는 있었지만, 그 질문에 답하는 것이 번거롭게 느껴졌습니다. 마찰을 어떻게 줄일 수 있을까요?

첫 번째 시도: ExitPlanTool에 파라미터를 추가해, 계획을 출력하는 동시에 관련 질문들을 함께 내보내도록 했습니다. 결과——Claude가 혼란스러워했습니다. 계획과 그 계획에 대한 질문을 동시에 출력하도록 요구하면, 사용자의 답변이 계획과 충돌할 경우 어떻게 처리해야 할까요?

두 번째 시도: 출력 지침을 수정해 Claude가 특정 markdown 형식으로 질문하고, 프론트엔드에서 이를 파싱해 표시하도록 했습니다. 결과——불안정했습니다. Claude는 불필요한 문장을 추가하거나, 선택지를 빠뜨리거나, 전혀 다른 형식을 사용하는 경우가 있었습니다.

세 번째 시도: 독립적인 AskUserQuestion 도구를 만들었습니다. Claude는 언제든 이를 호출할 수 있으며, 호출하면 팝업 창에 질문이 표시되고 사용자가 답변할 때까지 agent 루프가 블로킹됩니다. 성공했습니다.

Thariq은 원문에서 흥미로운 문장을 남겼습니다.

Claude는 이 도구를 기꺼이 호출하는 것처럼 보였으며, 출력 결과도 좋다는 것을 확인했습니다. 아무리 잘 설계된 도구라도 Claude가 어떻게 호출하는지 이해하지 못한다면 작동하지 않습니다.

phuong은 예리하게 물었습니다. "'Claude가 이 도구를 기꺼이 호출하는 것처럼 보였다'는 문장이 여기서 가장 흥미롭고도 설명이 부족한 부분입니다. 모델이 도구에 대해 갖는 '선호도'를 어떻게 감지하셨나요——transcript를 읽는 방식으로요, 아니면 내부 호출 빈도 지표로요? 이 휴리스틱이 좀 더 구체화된다면, agent 도구 설계 방식이 완전히 달라질 것 같습니다."

이 질문은 끝내 답을 얻지 못했지만, 중요한 직관을 가리키고 있습니다. 도구 설계의 성공 기준은 "사람이 합리적이라고 느끼는가"가 아니라, "모델이 사용법을 이해하고, 실제로 사용하려 하는가"입니다.

Emeka는 엔터프라이즈 도구 개발의 관점에서 매우 직관적인 교훈을 덧붙였습니다. "예전에 agent용 도구를 만들 때 모든 입력과 출력을 통제하려 했는데, 모델이 그냥……우회해버렸습니다. 엔지니어링 공수를 아끼세요. 모델이 모호함을 처리할 수 있다고 신뢰하세요."

---

도구는 낡아진다——능력 향상 후의 족쇄 효과

"적을수록 많다"가 공간적 차원의 인식에 관한 것이라면, "도구는 낡아진다"는 시간적 차원의 교훈입니다.

한때 모델을 도왔던 도구가, 모델이 발전하면서 오히려 제약이 될 수 있습니다.

Claude Code 초기 출시 당시, 팀은 모델이 방향성을 유지하려면 할 일 목록이 필요하다는 것을 알았습니다——시작 시에 할 일을 기록하고, 작업이 완료되면 하나씩 체크해 나가는 방식이었습니다. 이를 위해 Claude에게 TodoWrite 도구를 제공했습니다. 그럼에도 Claude는 자신이 무엇을 해야 하는지 자주 잊었습니다.

팀의 대응은 5턴마다 시스템 알림을 삽입해 Claude에게 목표를 상기시키는 것이었습니다.

하지만 모델이 발전하면서 문제는 역전되었습니다. 모델은 할 일 목록 알림이 더 이상 필요 없었을 뿐만 아니라, 오히려 그 알림을 제약으로 느끼기 시작했습니다. 반복적으로 할 일 목록을 상기시키자, Claude는 목록을 유연하게 조정하는 것이 아니라 엄격하게 따라야 한다고 느끼게 되었습니다. 동시에, Opus 4.5는 서브 agent 활용 면에서 크게 향상되었지만, 서브 agent 간에 공유되는 할 일 목록을 어떻게 조율할 것인가라는 문제가 생겼습니다.

그래서 팀은 TodoWrite를 Task Tool로 교체했습니다. 두 도구의 차이는 본질적입니다. Todos의 역할은 모델이 궤도를 유지하도록 하는 것——마치 상사가 직원의 업무 목록을 감시하는 것과 같습니다. Tasks는 agent 간 소통을 지원하는 데 중점을 둡니다——팀의 협업 칸반 보드와 같습니다. Tasks는 의존 관계를 지원하고, 서브 agent 간에 업데이트를 공유하며, 모델이 이를 수정하거나 삭제할 수도 있습니다.

TodoWrite → 5턴마다 알림 → Task Tool, 이것은 세 번의 재설계입니다. 이전 설계가 "잘못되었기" 때문이 아니라, 모델이 이미 성장했기 때문입니다.

modi의 댓글이 이 현상을 정확하게 요약합니다.

이것은 흥미로운 논쟁도 불러일으켰습니다. Danny Cosson은 AskUserQuestion이 "실은 나쁜 설계"라고 생각합니다——Claude Code의 매우 우아한 텍스트 입력/텍스트 출력 모델을 특정 인터랙션 패턴에 억지로 끼워 맞춘 것이며, 실질적인 이점도 거의 없다는 주장입니다.

하지만 @Toong의 반론은 설득력이 있습니다. AskUserQuestion의 가치는 두 가지에 있습니다——주도권(모델에게 질문할 권한이 있다는 것을 명확히 전달하는 것)과 상태 관리(일반적인 텍스트 출력과 "사용자 개입을 기다리는" 블로킹 상태를 명확하게 구분하는 것).

같은 도구에 대해 완전히 다른 두 가지 평가가 존재합니다. 이것은 Thariq이 글 말미에서 말한 것을 정확히 증명합니다. 도구 설계는 과학이 아니라 예술입니다. 사용하는 모델, agent의 목표, 그리고 그것이 놓인 환경에 따라 달라집니다.

---

Agent 스스로 답을 찾게 하라——"제공"에서 "자율 탐색"으로

이 부분이 전체 글에서 제가 가장 실용적 가치가 높다고 생각하는 내용입니다.

Claude Code는 처음에 RAG 벡터 데이터베이스를 사용해 Claude에게 컨텍스트를 제공했습니다. RAG는 강력하고 빠르지만 두 가지 문제가 있었습니다. 하나는 인덱싱과 설정이 필요하며 환경에 따라 취약할 수 있다는 것, 다른 하나는 더 근본적인 문제——이 방식은 컨텍스트를 Claude에게 제공하는 것이지, Claude가 스스로 찾아가는 것이 아니라는 점입니다.

팀은 중요한 전환을 했습니다. Claude가 웹을 검색할 수 있다면, 코드베이스도 검색할 수 있지 않을까요? Claude에게 Grep 도구를 제공함으로써, Claude가 스스로 파일을 검색하고 컨텍스트를 구성하도록 했습니다.

Beacon의 댓글이 핵심을 찌릅니다.

1년이라는 시간 동안, Claude는 거의 자율적으로 컨텍스트를 구성하지 못하던 상태에서, 여러 레이어에 걸쳐 중첩 검색을 수행하며 필요한 컨텍스트를 정확히 찾아내는 수준으로 진화했습니다. 이 진화의 핵심은 Claude에게 더 많은 정보를 주는 것이 아니라, 더 나은 검색 능력을 주는 것이었습니다.

Claude Code에 Agent Skills가 도입되면서, 팀은 공식적으로 점진적 공개(Progressive Disclosure) 개념을 제시했습니다. agent가 탐색을 통해 관련 컨텍스트를 단계적으로 발견할 수 있도록 하는 방식입니다.

구체적인 구현은 우아합니다. Claude는 skill 파일을 읽을 수 있고, 그 파일들은 또 다른 파일을 참조할 수 있으며, 모델은 이를 재귀적으로 읽어나갈 수 있습니다. skill의 일반적인 용도는 Claude에게 더 많은 검색 능력을 추가하는 것입니다——예를 들어 API 사용법이나 데이터베이스 쿼리 방법에 관한 지침을 제공하는 것입니다.

Brian Wagner는 Claude Code의 사고방식과 완전히 일치하는 3계층 실천 사례를 공유했습니다.

SKILL.md는 간결하게 유지하고(약 100줄), 무거운 컨텍스트는 Claude가 필요할 때 발견하는 파일에 둡니다. 저는 이것을 3번째 레이어라고 부릅니다. 여러분은 점진적 공개라고 부르시는군요. 본질은 같습니다.

PrimeLine은 정량화된 3계층 시스템을 구축하기도 했습니다. JSON 설정(약 500 token) > 스키마 요약(약 300 token) > 전체 markdown(약 3K token). 컨텍스트 라우터가 태스크 키워드에 따라 어느 계층을 로드할지 결정합니다.

이 계층화 전략의 핵심 논리는 이것입니다. 컨텍스트는 유한한 자원이며, 한계 수익은 체감합니다. 모든 정보를 한꺼번에 agent에게 쏟아 넣으면 token을 낭비할 뿐만 아니라, 진정으로 중요한 정보가 희석됩니다. 필요에 따라 제공하고, agent 스스로 더 깊은 세부 사항이 필요한 시점을 판단하게 하는 것——이것이 확장 가능한 방식입니다.

Claude Code Guide 서브 agent는 점진적 공개의 또 다른 영리한 응용 사례입니다. 팀은 Claude가 Claude Code 자체를 사용하는 방법에 대해 충분히 알지 못한다는 것을 발견했습니다——MCP를 추가하는 방법이나 특정 슬래시 명령의 역할을 물어봐도 답하지 못했습니다.

모든 정보를 시스템 프롬프트에 집어넣을 수도 있었지만, 사용자가 이런 질문을 하는 경우는 드물기 때문에 컨텍스트 오염이 생기고, Claude Code의 주된 업무인 코드 작성에 방해가 될 것입니다.

먼저 Claude에게 문서 링크를 주고 스스로 검색하게 했습니다——가능하기는 했지만, Claude가 올바른 답을 찾기 위해 대량의 결과를 컨텍스트에 불러들이는 문제가 있었습니다. 최종 해결책은 전용 서브 agent를 구축하는 것이었습니다. Claude Code Guide입니다. 이 서브 agent는 상세한 검색 지침을 가지고 있으며, 문서를 효율적으로 검색하는 방법과 반환해야 할 내용을 파악하고 있습니다. 새로운 도구를 추가하지 않고도, Claude의 action space를 확장했습니다.

Lance Martin은 agent 설계 패턴에 관한 글에서 보완적인 시각을 제시했습니다. agent에게 수십 개의 도구를 정의하는 것보다, 컴퓨터를 주고 코드로 도구를 편성하게 하는 것을 고려하세요. Claude Code의 핵심 추상화는 CLI입니다——agent는 여러분의 컴퓨터 위에서 살며, bash와 파일 시스템이라는 기초 프리미티브를 통해 복잡한 태스크를 수행합니다. 소수의 원자적 도구(bash 도구 등)는 방대한 도구 세트보다 더 유연하고 token 효율이 높습니다.

---

모델 공감——Agent처럼 생각하기

앞서 살펴본 세 가지 주제——적을수록 많다, 도구는 낡아진다, agent 스스로 답을 찾게 하라——의 배경에는 공통된 메타 방법론이 있습니다. Thariq은 글 서두에서 이미 그것을 가리켰습니다. agent처럼 세상을 보라.

이것은 규칙의 집합이 아니라 하나의 사고방식입니다. David Zhang은 이것에 이름을 붙였습니다.

모델 공감(Model Empathy)——인간의 관점에서 "합리적인" 도구를 설계하는 것이 아니라, 모델의 관점에서 그것이 실제로 무엇을 보고 있는지, 어떻게 이해하는지, 어떻게 사용하는지를 생각하는 것입니다.

Terminally Drifting은 모든 agent 팀이 경험하는 동일한 교훈을 세 단계로 압축했습니다.

1. 인간을 위해 도구를 설계한다
2. 모델이 관리자 권한을 가진 라쿤처럼 도구를 사용한다
3. token 경제와 예측 가능한 부작용을 위해 재설계한다

"agent처럼 생각하기"가 바로 그 결정적인 돌파구입니다.

Vish는 자신의 전환점 경험을 공유했습니다. "우리는 계속해서 인간에게 합리적으로 느껴지는 도구 인터페이스를 구축해왔는데, agent가 왜 이상한 선택을 하는지 이해할 수 없었습니다. 한번 마음의 모델을 뒤집어서, 모델이 도구 정의 안에서 실제로 무엇을 보고 있는지를 생각하자, 모든 것이 달라졌습니다."

Emeka는 엔터프라이즈 도구 개발의 관점에서 같은 이야기를 했습니다. "기본값은 모두 인간의 멘탈 모델입니다——스키마, 필드명, 플로우, 모두 인간이 읽기 위해 최적화되어 있습니다. 하지만 agent에게 이것은 잘못된 프레임워크입니다."

"마음의 모델을 뒤집는다"는 것은 말로는 쉽지만, 실제로는 끊임없는 연습이 필요합니다. agent의 출력을 꼼꼼히 읽어야 합니다——무엇을 올바르게 했는지를 보는 것이 아니라, 왜 어떤 선택을 했는지, 어디서 망설였는지, 어디서 돌아갔는지를 보는 것입니다. 이러한 "이상한 행동"은 종종 모델의 버그가 아니라, 도구 설계의 버그입니다.

커뮤니티 토론에서는 몇 가지 생각해볼 만한 추가 시각도 등장했습니다.

OAIR은 맹점을 제기했습니다. 이 모든 도구 반복은 agent가 상태가 없다는 것을 전제로 합니다——각 세션은 처음부터 시작됩니다. 만약 가장 중요한 "도구"가 action space 안에 있는 것이 아니라, 이 코드베이스가 어떻게 작동하는지에 대한 영속적인 기억 속에 있다면 어떨까요? Claude Code는 이후 CLAUDE.md 파일과 memory 시스템으로 이 문제에 부분적으로 답했지만, 영속적 상태 관리는 여전히 agent 설계의 열린 과제로 남아 있습니다.

Clinker는 또 다른 설계 원칙을 제시했습니다. 원시 능력이 아니라 복구 가능성(recoverability)을 최적화하세요——명시적인 도구 사전 조건, 관찰 가능한 상태, 저비용 재시도는 빠르게 더 많은 도구를 추가하는 것보다 훨씬 효과적인 경우가 많습니다. 이것은 소프트웨어 엔지니어링에서 "오류 없는 시스템보다 결함 허용 시스템을 만들라"는 이념과 일맥상통합니다.

范式折叠의 정리가 가장 날카롭습니다.

Action space 설계는 본질적으로 권한 설계입니다——AI에게 어떤 권한을 주는지에 따라, 그것이 어떤 역할이 되는지가 결정됩니다. 팀 관리와 똑같습니다. 병목이 사람의 능력에 있다고 생각했는데, 실제로는 자신이 그은 권한 경계가 병목이었던 것입니다.

---

마치며

Thariq의 결론으로 돌아가겠습니다.

많이 실험하고, 출력을 읽고, 새로운 방법을 시도하세요. Agent처럼 관찰하세요.

Claude Code의 헤비 유저로서, 이 글을 읽고 가장 크게 느낀 것은 이것입니다. 겉으로 "자연스러워 보이는" 기능들 뒤에는, 수없이 많은 "이렇게는 안 되겠다, 다른 방법을 써보자"는 반복이 있었다는 것입니다. AskUserQuestion은 세 번을 시도했고, TodoWrite는 세 번을 재설계했으며, RAG는 Grep으로 대체되었습니다. 매번의 개선은 더 영리한 방안을 생각해냈기 때문이 아니라, 모델의 실제 행동을 꼼꼼히 관찰했기 때문입니다.

이 글의 부제는 "Seeing like an Agent"——agent처럼 세상을 보는 것입니다. 하지만 각도를 바꿔 생각해보면, 이것은 사실 모든 좋은 엔지니어링 실천의 본질이기도 합니다. 자신의 시각에서 시스템을 설계하는 것이 아니라, 사용자의 시각에서 설계하는 것. 다만 이번에는, 그 사용자가 AI 모델이라는 것이 다를 뿐입니다.

앞으로 agent를 구축하는 모든 개발자는, David Zhang이 말한 "모델 공감"을 익혀야 할 것입니다. 이것은 어떤 신비로운 능력이 아닙니다. 핵심은 세 가지입니다. 모델의 실제 행동을 관찰하고, 그 출력을 읽고, 본 것을 바탕으로 설계를 조정하는 것.

Agent처럼 관찰하세요.

---

더 읽어보기: