Claude Code 구축에서 배운 것: 에이전트처럼 보기 (Seeing like an Agent)
원문 출처: Thariq (@trq212) — X (구 Twitter), 2026년 2월 28일 공개
주제: 에이전트 설계, 툴 엔지니어링, Progressive Disclosure, AI 도구 진화
들어가며: 왜 에이전트처럼 봐야 하는가
AI 에이전트를 구축하는 일은 단순히 코드를 짜는 것과 다르다. 우리는 어떤 존재가 세상을 어떻게 인식하고, 어떤 도구를 통해 행동하며, 어떻게 목표를 달성하는지를 설계해야 한다. Anthropic의 Claude Code 팀이 실제 제품을 만들면서 터득한 교훈들은 바로 이 지점에서 출발한다. 팀을 이끈 Thariq(@trq212)는 수십 가지의 시행착오를 거치며 하나의 핵심 원칙에 도달했다. “에이전트처럼 보는 법(Seeing like an Agent)을 배워야 한다”는 것이다.
이 글은 그 경험을 바탕으로, 에이전트의 액션 공간(action space)을 어떻게 설계할 것인지, 도구는 어떻게 만들어야 하는지, 그리고 모델의 능력이 진화함에 따라 도구도 함께 진화해야 한다는 사실을 상세하게 풀어낸다.
1. 에이전트의 액션 공간 설계: 어려운 수학 문제를 푼다면?
에이전트 시스템을 만드는 가장 어려운 부분 중 하나는 에이전트가 실제로 할 수 있는 행동들의 집합, 즉 액션 공간(action space) 을 설계하는 것이다. Claude는 Tool Calling을 통해 행동하는데, Claude API에서는 bash, skills, 최근에는 코드 실행(code execution) 같은 다양한 기본 요소(primitive)로 도구를 구성할 수 있다.
그렇다면 어떤 도구를 줘야 할까? 도구가 하나면 충분할까, 아니면 50개가 필요할까?
Thariq는 이에 대해 아주 직관적인 사고 실험을 제안한다. 어려운 수학 문제를 풀어야 하는 상황을 상상해 보라. 당신이라면 어떤 도구를 원하겠는가?
- 종이와 연필만 있다면: 풀 수는 있지만, 복잡한 계산은 손으로 직접 해야 하므로 느리고 오류가 많다.
- 계산기가 있다면: 훨씬 나아지지만, 고급 기능을 사용하려면 그 사용법을 알아야 한다.
- 컴퓨터가 있다면: 가장 강력하고 빠른 옵션이다. 하지만 코드를 작성하고 실행하는 방법을 알아야 비로소 그 힘을 발휘할 수 있다.
이 비유가 에이전트 도구 설계의 핵심을 담고 있다. 도구는 에이전트 자신의 능력에 맞게 형성(shaped)되어야 한다. 너무 강력하지만 에이전트가 제대로 활용할 줄 모르는 도구는 아무 소용이 없고, 너무 단순한 도구는 에이전트의 잠재력을 가로막는다. 그리고 에이전트의 능력을 파악하려면 끊임없이 출력을 읽고, 실험하고, 주의를 기울여야 한다. 그것이 바로 “에이전트처럼 보는” 행위다.
2. AskUserQuestion 툴의 탄생: 소통 대역폭 높이기
문제의 시작: 질문이 왜 번거로울까
Claude는 텍스트로 질문을 던질 수 있다. 하지만 팀이 실제로 사용해보니, 그 질문에 답하는 것이 불필요하게 오래 걸린다는 사실을 발견했다. 사용자와 Claude 사이의 소통 마찰(friction)을 줄이고, 커뮤니케이션의 대역폭(bandwidth)을 높이려면 어떻게 해야 할까? 이 질문이 AskUserQuestion 툴 탄생의 출발점이었다.
1차 시도: ExitPlanTool 수정
가장 손쉬운 방법은 이미 존재하던 ExitPlanTool에 질문 배열(array of questions) 파라미터를 추가하는 것이었다. 구현은 쉬웠다. 그러나 문제가 생겼다. Claude에게 동시에 두 가지를 요청하게 된 것이다—계획(plan)을 세우면서 그 계획에 대한 질문들도 생성하라고. 만약 사용자의 답변이 계획과 충돌한다면? Claude가 ExitPlanTool을 두 번 호출해야 하나? 논리적 모순이 발생했고, 이 접근법은 폐기되었다.
2차 시도: 출력 포맷 수정
다음으로 팀은 Claude의 출력 지시(output instruction)를 변경하여, 질문을 담은 특수한 마크다운 포맷을 출력하게 했다. 예를 들어, 대괄호 안에 선택지를 담은 불릿 포인트 질문 목록을 출력하게 하고, 이를 파싱해서 UI로 보여주는 방식이었다. 이 방법은 가장 범용적인 변경이었고, Claude도 어느 정도 수행할 수 있었다. 하지만 보장이 없었다. Claude는 종종 추가 문장을 덧붙이거나, 선택지를 빠뜨리거나, 전혀 다른 포맷을 사용했다. 출력이 일관되지 않으면 파싱 로직도 불안정해진다.
3차 시도: 전용 AskUserQuestion 툴 생성
결국 팀은 Claude가 언제든지 호출할 수 있는 독립적인 툴을 만들었다. 특히 플랜 모드(plan mode) 에서 적극적으로 사용하도록 프롬프트되었다. 이 툴이 호출되면 모달(modal)이 화면에 표시되고, 사용자가 답변을 제출할 때까지 에이전트 루프는 멈춘다.
이 툴의 핵심 이점은 세 가지였다. 첫째, Claude에게 구조화된 출력을 요청할 수 있게 됐다. 둘째, 사용자에게 여러 선택지를 제시하도록 보장할 수 있었다. 셋째, Agent SDK에서 직접 호출하거나 skills에서 참조하는 방식으로 합성(compose)이 가능해졌다.
그리고 가장 중요한 발견: Claude가 이 툴 호출을 좋아했다. 아무리 잘 설계된 툴도 Claude가 그것을 어떻게 호출해야 할지 이해하지 못하면 무용지물이다. AskUserQuestion 툴은 Claude가 직관적으로 이해하고 활용한, 성공적인 도구 설계의 사례가 됐다.
다만 팀은 이것이 “최종 형태”라고 확신하지 않는다. 다음 사례에서 보듯, 한 모델에서 작동하는 것이 다른 모델에서는 최선이 아닐 수 있기 때문이다.
3. 모델 능력의 진화와 도구 설계의 재고: TodoWrite에서 Task Tool로
초기의 필요: TodoWrite 툴
Claude Code가 처음 출시됐을 때, 팀은 모델이 장기 작업을 수행하면서 자신이 해야 할 일을 잊어버린다는 문제를 발견했다. 이를 해결하기 위해 TodoWrite 툴을 도입했다. 이 툴은 작업 시작 시 할 일 목록을 작성하고, 모델이 작업을 완료함에 따라 하나씩 체크할 수 있게 해줬다. 사용자에게도 진행 상황이 표시됐다.
하지만 이것만으로도 부족했다. Claude는 여전히 자신의 목표를 잊어버리는 일이 잦았다. 이 문제를 해결하기 위해 팀은 5턴마다 시스템 리마인더를 삽입하여 Claude에게 현재 목표와 할 일 목록을 상기시켰다. 초기에는 이 방식이 효과적이었다.
능력 향상이 가져온 역설: 도구가 오히려 방해가 되다
그런데 모델이 발전하면서 상황이 역전됐다. 더 강력한 모델들은 리마인더 없이도 목표를 기억할 수 있게 됐고, 오히려 할 일 목록 리마인더가 모델을 경직시키는 부작용이 생겼다. Claude는 리마인더를 받으면 목록에 반드시 따라야 한다고 인식하여, 상황에 맞게 목록을 수정하거나 새로운 접근법을 취하는 것을 주저했다.
또한 Opus 4.5 모델이 서브에이전트(subagent) 활용 능력이 크게 향상되면서 새로운 문제가 등장했다. 여러 서브에이전트가 병렬로 작업할 때, 공유 할 일 목록을 어떻게 조율할 것인가? TodoWrite는 단일 에이전트를 위한 도구로 설계됐기에, 다중 에이전트 환경에 맞지 않았다.
Task Tool로의 전환
이 문제를 해결하기 위해 팀은 TodoWrite를 Task Tool로 교체했다. TodoWrite가 단일 모델이 ‘트랙을 벗어나지 않도록’ 유지하는 도구였다면, Task Tool은 에이전트들이 서로 소통하고 조율하는 도구로 설계됐다. Task는 의존성(dependencies)을 포함할 수 있고, 서브에이전트 간에 업데이트를 공유할 수 있으며, 모델이 상황에 따라 Task를 수정하거나 삭제할 수 있다.
이 사례는 에이전트 도구 설계에서 매우 중요한 교훈을 담고 있다. 모델의 능력이 향상되면, 과거에 필요했던 도구가 오히려 제약이 될 수 있다. 이것이 Thariq 팀이 기존 가정들을 지속적으로 재검토하는 이유이며, 비슷한 능력 프로파일을 가진 소수의 모델을 지원하는 것이 유리한 이유이기도 하다.
4. 검색 인터페이스의 설계: RAG에서 Grep으로, Grep에서 Progressive Disclosure로
1단계: RAG 벡터 데이터베이스
Claude Code가 처음 등장했을 때, 팀은 RAG(Retrieval-Augmented Generation) 벡터 데이터베이스를 사용하여 Claude에게 컨텍스트를 제공했다. RAG는 강력하고 빠르지만 몇 가지 근본적인 한계가 있었다. 인덱싱과 초기 설정이 필요했고, 다양한 환경에서 불안정할 수 있었다. 그리고 가장 중요한 문제: Claude가 스스로 컨텍스트를 탐색하는 것이 아니라, 컨텍스트가 주어지는(given) 구조였다. Claude는 수동적인 정보 수신자였다.
2단계: Grep 툴로의 전환
웹 검색이 가능한 Claude라면, 코드베이스도 스스로 검색할 수 있지 않을까? 팀은 Grep 툴을 Claude에게 제공했다. 이를 통해 Claude는 스스로 파일을 검색하고 필요한 컨텍스트를 직접 구축할 수 있게 됐다. Claude가 능동적인 컨텍스트 탐색자가 된 것이다. 이는 단순한 도구 교체가 아니라, 에이전트의 역할에 대한 철학적 전환이었다.
3단계: Agent Skills와 Progressive Disclosure의 형식화
팀이 Agent Skills를 도입하면서 Progressive Disclosure라는 개념을 공식화했다. Progressive Disclosure는 에이전트가 탐색을 통해 관련 컨텍스트를 점진적으로 발견할 수 있도록 하는 원칙이다.
구체적으로, Claude는 skill 파일을 읽고, 그 파일이 참조하는 다른 파일들을 재귀적으로 읽어나갈 수 있다. 예를 들어, 사용자가 수익(revenue)에 대해 물어보면:
- Claude가
SKILL.md를 읽는다. SKILL.md에서reference/finance.md를 참조하는 것을 발견한다.- Claude가
bash를 사용하여 해당 파일만 읽는다. sales.md나product.md는 필요하지 않으므로 컨텍스트에 로드되지 않는다.
이 파일시스템 기반 아키텍처가 Progressive Disclosure를 가능하게 한다. Claude는 각 작업에 필요한 컨텍스트만 선택적으로 로드하여 컨텍스트 오염(context pollution) 없이 집중력을 유지한다.
실제로 skills의 일반적인 용도 중 하나는 Claude에게 추가적인 검색 능력을 부여하는 것이다. API 사용법이나 데이터베이스 쿼리 방법을 담은 지침 파일이 대표적인 예다. Claude Code 출시 후 약 1년 동안, Claude는 스스로 컨텍스트를 구축하지 못하는 수준에서 여러 계층의 파일을 중첩 검색하여 정확히 필요한 컨텍스트를 찾는 수준으로 진화했다.
Progressive Disclosure는 이제 새로운 기능을 추가할 때 새로운 도구를 만들지 않아도 되는 표준 기법이 됐다.
5. Progressive Disclosure의 심화 적용: Claude Code Guide 서브에이전트
문제: Claude가 자기 자신을 모른다
Claude Code에는 현재 약 20개의 도구가 있다. 팀은 이 수를 최소화하기 위해 끊임없이 “이 도구가 정말 필요한가?”를 자문한다. 새로운 도구를 추가할 때의 기준이 높은 이유는 도구가 하나 추가될 때마다 모델이 고려해야 할 선택지가 하나 더 늘어나기 때문이다.
그런데 팀은 Claude가 Claude Code 자체에 대해 충분히 알지 못한다는 사실을 발견했다. “MCP를 어떻게 추가하나요?” 또는 “슬래시 커맨드가 뭔가요?” 같은 질문에 Claude가 제대로 답변하지 못했다. 어떻게 해결해야 할까?
1차 시도: 시스템 프롬프트에 직접 정보 포함
가장 명백한 해결책은 이 모든 정보를 시스템 프롬프트에 넣는 것이다. 하지만 이러면 컨텍스트 부패(context rot) 가 발생한다. 사용자가 Claude Code 사용법에 대해 묻는 빈도는 실제로 매우 낮다. 그런데 이 정보가 항상 컨텍스트에 있으면 Claude의 주요 임무인 코드 작성을 방해하고 토큰을 낭비한다.
2차 시도: 문서 링크 제공
팀은 Claude에게 공식 문서 링크를 주고, 필요할 때 로드하도록 했다. 이 방식은 Progressive Disclosure의 기본형이었다. 그러나 Claude가 맞는 답변 하나를 찾기 위해 과도하게 많은 검색 결과를 컨텍스트에 로드하는 문제가 있었다. 필요한 것은 답변 하나인데, Claude는 관련 문서 전체를 끌어들였다.
최종 해결책: Claude Code Guide 서브에이전트
팀은 Claude Code Guide 서브에이전트를 만들었다. Claude가 자기 자신에 대해 질문을 받으면, 이 서브에이전트를 호출하도록 프롬프트된다. 이 서브에이전트는 문서를 효율적으로 검색하는 방법과 무엇을 반환해야 하는지에 대한 광범위한 지침을 갖고 있다.
완벽한 해결책은 아니다. Claude가 자신의 설치/설정 방법을 묻는 질문에 여전히 혼란스러워할 때가 있다. 하지만 이전보다 훨씬 나아졌으며, 가장 중요한 것은 새로운 툴을 추가하지 않고 Claude의 액션 공간에 새로운 기능을 추가할 수 있었다는 점이다.
6. 핵심 원칙들: 에이전트처럼 보는 법
지금까지의 사례를 통해 Claude Code 팀이 발견한 핵심 원칙들을 정리하면 다음과 같다.
원칙 1: 도구는 모델의 능력에 맞게 형성되어야 한다
어려운 수학 문제 비유처럼, 종이가 필요한 사람에게 컴퓨터를 주면 오히려 혼란스럽다. 모델이 실제로 잘 활용할 수 있는 도구를 줘야 한다. 이를 위해서는 모델의 출력을 주의 깊게 읽고, 실험하고, 학습해야 한다.
원칙 2: 모델이 도구를 좋아하는지 확인하라
아무리 논리적으로 설계된 도구라도 Claude가 직관적으로 이해하고 사용하지 않으면 의미가 없다. AskUserQuestion 툴의 성공 요인 중 하나는 Claude가 이 툴을 호출하는 것을 “좋아했다”는 것이다. 이 감각은 수많은 출력을 읽고 패턴을 발견함으로써만 얻을 수 있다.
원칙 3: 과거의 가정을 지속적으로 재검토하라
TodoWrite가 필요했던 시절과 Task Tool이 필요한 시절은 다르다. 모델의 능력이 진화하면 도구도 함께 진화해야 한다. 한때 도움이 됐던 도구가 이제는 오히려 모델을 제약할 수 있다. 정기적으로 “이 도구가 지금도 여전히 필요한가?”를 물어야 한다.
원칙 4: 도구 추가의 문턱을 높게 유지하라
Claude Code는 약 20개의 도구를 운용하며, 팀은 이 숫자를 최소화하기 위해 끊임없이 노력한다. 도구가 하나 늘어날 때마다 모델이 고민해야 할 선택지가 하나 더 생기기 때문이다. 새 기능을 추가할 때는 먼저 Progressive Disclosure 등의 기법으로 도구 추가 없이 해결할 수 있는지 고민해야 한다.
원칙 5: Progressive Disclosure를 적극 활용하라
새로운 기능을 추가할 때마다 도구를 만들지 말고, 계층적 정보 공개 구조를 활용하라. 에이전트가 필요할 때 필요한 정보만 찾아서 로드하도록 하는 것이 컨텍스트 효율성과 모델 집중력 모두에 유리하다.
원칙 6: 이것은 과학이 아니라 예술이다
Thariq는 명확히 선언한다. “만약 당신이 이 가이드에서 도구를 어떻게 구축할지에 대한 엄격한 규칙을 찾고 있었다면, 아쉽게도 이 글은 그런 내용이 아니다.” 도구 설계는 사용하는 모델, 에이전트의 목표, 그리고 에이전트가 운영되는 환경에 따라 크게 달라진다. 자주 실험하고, 출력을 읽고, 새로운 것을 시도하라. 에이전트처럼 보라.
7. 한국 개발자들을 위한 시사점
이 글은 Anthropic의 내부 엔지니어링 경험에서 나온 것이지만, 그 원칙들은 한국의 엔터프라이즈 AI 도입 현장에도 직접 적용 가능하다.
레거시 시스템 통합 시: TodoWrite에서 Task Tool로의 전환처럼, 기존에 작동하던 방식이 시스템 규모가 커지거나 복잡해지면 오히려 병목이 될 수 있다. 정기적인 아키텍처 리뷰가 필요하다.
도구 설계 시: 도구의 스키마를 설계할 때는 Claude API의 구조화된 출력 기능을 최대한 활용하라. AskUserQuestion 툴처럼, 모델이 예측 가능하고 파싱 가능한 출력을 내도록 강제하는 것이 시스템 안정성을 높인다.
컨텍스트 관리: 한국의 금융, 의료, 공공 분야처럼 데이터 주권이 중요한 환경에서는 RAG보다 로컬 파일시스템 기반의 Progressive Disclosure가 더 적합할 수 있다. 외부 벡터 DB에 민감한 정보를 인덱싱하지 않아도 되기 때문이다.
멀티 에이전트 조율: Task Tool처럼 에이전트 간 의존성과 상태를 공유할 수 있는 조율 레이어를 설계하는 것이 복잡한 비즈니스 워크플로우 자동화의 핵심이다.
맺음말: 에이전트처럼 보는 것의 의미
“에이전트처럼 보는 것”은 단순히 AI의 관점에서 생각하는 것이 아니다. 그것은 모델의 출력을 끊임없이 관찰하고, 도구 설계의 가정을 검증하고, 모델 능력의 진화에 발맞춰 시스템을 재설계하는 지속적인 실천의 과정이다.
Claude Code 팀이 1년에 걸쳐 RAG에서 Grep으로, Grep에서 Progressive Disclosure로, TodoWrite에서 Task Tool로 진화시켜 온 과정은 단순한 기술적 변화가 아니라, 에이전트와 함께 성장하는 법을 배운 과정이었다. 이 교훈은 AI 도구를 구축하는 모든 이들에게 유효하다.
실험하라. 출력을 읽어라. 새로운 것을 시도하라. 에이전트처럼 보라.
작성일: 2026-02-28
원문: Thariq (@trq212) on X — “Lessons from Building Claude Code: Seeing like an Agent”
참고: Anthropic Claude API 공식 문서, Claude Code Skills 아키텍처, Agent Skills Deep Dive (Medium)