에이전트처럼 바라보기
클로드 코드 팀의 엔지니어 Thariq Shihipar의 Lessons from Building Claude Code: Seeing like an Agent에서 에이전트 개발에 대한 많은 단서를 얻을 수가 있다. 평소 에이전트를 이용하면서 궁금했던 점에 대해서 클로드 팀에서 어떻게 접근했는지 알 수 있는 좋은 글이라 생각하여 내용을 정리해본다.
Claude Code 팀이 실제로 에이전트 프로덕트를 만들면서 학습한 에이전트 도구 설계 원칙 관련해서 사고방식과 프레임워크 잘 정리된 것 같습니다.
이 글을 쓴 Thariq는 에이전트 도구를 설계할 때, 인간 엔지니어의 관점이 아니라 모델의 관점에서 모델이 가진 능력과 약점에 맞게 액션 스페이스(action space, 에이전트가 취할 수 있는 가능한 행동의 집합)를 구성해야 한다고 강조한다. 어려운 수학 문제를 풀때 종이 보다 계산기, 컴퓨터가 좋지만, 그만큼 잘 사용할 수 있는 능력이 필요하다는 비유를 들었다.
첫번째는 Elicitation이라 표현되는 모델이 필요한 정보를 이끌기 위한 질문 능력과 관련하여 AskUserQuestion라는 툴(tool)을 설계한 사례이다.
나도 평소에 궁금했던 점이 하나 있었는데, 에이전트 도구가 plan과 question을 같이 생성하는 경우가 있다는 것이다. 어떤 에이전트는 플랜을 세우기 전에 먼저 clarifying question을 던지기도 하지만, 어떤 경우에는 일단 플랜을 세운 다음에 그 뒤에 추가 질문을 한다. 그런데 이런 패턴에서는, 내가 추가 질문에 답을 했을 때 그 답변이 기존 플랜과 다른 방향의 접근을 요구하면, 에이전트가 플랜을 얼마나 잘 업데이트했는지가 잘 보장되지 않는 느낌이었다.
Thariq는 사용자의 답변이 기존 계획 내용과 충돌나는 경우에 대해서 AskUserQuestion tool 개발 사례를 설명한다. 그는 질문이 중요하다는 말보다 모델이 질문을 어떻게 구조화해서 사용자에게 보여줘야 답변 속도와 정보량이 올라가는지 설명을 한다. 그는 프롬프트 포맷을 건드리기 보다 아예 별도 tool로 분리한 것이 더 안정적이라고 설명한다.
클로드 코드의 첫번째 시도는 ExitPlanTool에 파라미터를 하나 추가해서 plan과 함께 question 리스트를 받도록 만들었다. 하지만 클로드는 계획을 세우는 일과 계획에 대한 질문을 만드는 일을 동시에 요구하는 것에 대해 혼란스러워 했다고 한다. 두번째 시도는 아웃풋 포맷을 변경하는 시도였다. 대괄호(brackets) 안에 여러 선택지를 넣은 불렛 포인트 질문 목록을 유저에게 보여주는 방식이었다. 하지만 이 방식 역시 일부 잘 동작했으나, 팀이 원하는 수준으로 품질을 보장하지 못했다고 한다(갑자기 문장을 추가하거나, 옵션을 빠뜨리거나, 아예 다른 포맷을 쓰는 경우 존재)
그래서 마지막 시도가 Claude가 언제든지 호출할 수 있는 AskUserQuestion tool을 만드는 쪽으로 방향성을 잡고, plan mode일때 이 tool을 적극적으로 사용하도록 프롬프트 설계를 했다고 한다. 결과는 성공적(안정적 동작, 스킬과 연계하는 등 여러 방식을 조합해서 사용)이었고, 중요한 점은 Claude가 이 tool을 호출하는 것을 좋아한다(seemed to like calling this tool)는 점이라고 한다. 이 표현이 어떤 의미인지 알겠는데, Thariq가 이를 어떻게 객관적으로 확인했는지는 솔직히 감이 잡히지 않는다.
두번째는 모델 능력 변화에 따라 tool을 재설계한 사례이다.
바이브 코딩을 초기에 경험한 분들은 taskmaster 같은 MCP 도구를 이용하여 todo 리스트를 활용한 사례를 많이 확인했을 것이다. 개인적으로 라이언 칼슨의 오픈소스 ai-dev-tasks를 참고를 많이 한 적이 있는데, 꽤 오래 전부터 라이언 칼슨도 https://github.com/snarktank/ai-dev-tasks/issues/60 이슈에서 더이상 to-do 기반의 태스크 매니지먼트가 모델 성능이 높아지면서 의미가 없어졌다고 표현했다. 그리고 관련 프롬프트를 오픈소스에서 제거했다.
클로드 코드 팀 역시 과거 todo list가 좋은 보조 장치였지만, 모델이 똑똑해지면서 이것이 오히려 제약이 되었다는 것을 관찰했다고 한다. 그래서 이 지점에서 TodoWrite를 Task tool로 전환하여 개별 모델의 self-management 도구에서 여러 에이전트 간 협업과 코디네이션을 위한 task 시스템으로 패러다인을 옮겼다고 설명한다. 예전에 잘 통했던 tool이 지금도 최선일 것이라는 가정을 지속적으로 검증해야한다는 것을 의미한다.
세번째는 검색 인터페이스 디자인이다. 기존이 RAG 기반으로 컨텍스트를 미리 선정해서 모델에게 전달하는 방식이었다면 이제는 모델이 스스로 검색하고 컨텍스트를 스스로 쌓도록 다시 설계했다는 사례이다.
클로드 코드는 초기에 RAG Vector DB를 이용해서 모델에게 관련 문서를 찾아서 컨텍스트를 넣는 패턴이었다. 이 방식은 속도가 바르지만 인덱싱/셋업이 필요하고 환경 변화에 취약하고, 무엇보다도 모델이 스스로 탐색하는 것이 아닌, 사람이 선택한 컨텍스트만 본다는 구조적 한계가 있었다. 그래서 클로드 코드 팀은 웹 검색은 Claude가 하는데 왜 코드 베이스 검색은 사람이 대신해야하지?라는 문제 인식으로 Grep tool을 제공해 Claude가 코드 파일을 직접 검색하고 스스로 필요한 컨텍스트를 구축하도록 개선했다. 클로드 팀은 모델이 똑똑해질수록, 적절한 검색 tool만 제공하면 자기 컨텍스트를 점점 더 잘 구성한다는 패턴을 관찰했다.
이후 클로드 코드 팀은 Agent Skills를 도입하면서 progressive disclosure 개념을 정의했다. Claude는 skill 마크다운 파일을 읽고, 그 안에 다른 파일 레퍼런스가 있으면 재귀적으로(recursively) 들어가며 필요한 정보만 점진적으로 발견하는 방식인 것이다(예: API 사용법, DB 쿼리 방식 등을 skill로 제공해서 모델이 탐색하면서 점점 넓은 컨텍스트를 확보하도록 설계).
이렇게 클로드 코드는 1년만에 컨텍스트 생성에 빈약하다가 이제 여러 레이어의 파일을 nested search하여 컨텍스트를 찾는 상태로 발전했다고 표현한다. 그리고 이 과정이 새로운 기능이 생길때마다 tool을 늘리는 것이 아니라 progressive disclosure를 활용해 문서 및 스킬 구조만 바구어 기능을 확장하는 패턴을 만들었다는 점이다. 이렇게 Claude code의 검색 인터페이스는 RAG → Grep → Agent Skills로 이어지는 진화를 통해, 모델에게 필요한 건 더 많은 툴이 아니란 점을 증명하였다. 이밖에 클로드의 다양한 사용법(예: MCP 추가방법)에 대해서 기존에 모델이 잘 응대하지 못했던 사례를 서브 에이전트로 대응한 내용도 흥미로웠다.
프로덕트 매니저 관점에서 생각해보면, 에이전트 설계할때 모델이 스스로 컨텍스트를 찾아서 구성할 수 있어야 하는데, 처음부터 모든 문서/정보를 넣지말고, 필요할때 skill 파일/문서 구조를 레이어 형식으로 설계해서 모델이 재귀적으로 탐색하여, 한 단계씩 열어가는 구조(progressive disclosure)는 생각해볼만할 것 같다. 예를 들면 가장 간단하게 튜토리얼 같은 것은 시스템 프롬프트에 다 넣거나 모든 문서 임베딩+RAG 방식 보다는 문서 구조를 점진적으로 탐색 가능하게 설계하고, 사용자가 해당 질문을 할때 별도 서브에이전트 플로우로 이용해서 메인 에이전트의 프롬프트를 간결하게 유지할 수 있을 것이다.
An Art, not a Science
Thariq는 마지막은 다음과 같이 마무리한다. 결국 사람이 또 다른 인텔리전스인 에이전트, 모델을 이해하기 위해 노력하고 집착하라는 것이다.
모델을 위한 tooling을 디자인하는 일은 과학만큼이나 예술이기도 합니다. 그리고 사용하는 모델, 에이전트의 목표 그리고 에이전트가 작동하는 환경에 크게 의존합니다. 자주 실험하고, 모델이 생성하는 아웃풋을 읽어보고 새로운 시도를 계속해 보세요. 그리고 “에이전트처럼 바라보기(see like an agent)”를 연습해 보세요.