Claude Code 팀이 도구를 3번 갈아엎고 배운 Tool 설계 원칙 4가지

도구를 줄였더니 AI가 더 잘했습니다. 에이전트를 만들 때 가장 자연스러운 본능은 “기능이 부족하면 도구를 하나 더 주자”입니다. Anthropic 팀이 Claude Code를 1년간 만들면서 발견한 건 그 반대였습니다. 도구가 하나 늘 때마다 AI가 “이걸 불러야 하나 말아야 하나” 고민하는 비용이 같이 늘어나거든요.

에이전트를 직접 만들면서 똑같은 함정에 빠졌기에 이 글이 뼈 아팠습니다. Claude Code 팀 개발자 Thariq이 도구를 더하고 빼고 다시 설계한 과정을 순서대로 추렸습니다.

도구 하나에 두 역할을 넣으면 AI가 멈춥니다

Claude Code 팀이 맨 처음 부딪힌 문제였습니다. 사용자에게 질문하는 기능이 필요했는데 “계획 세우기” 도구에 질문 기능을 같이 넣었습니다. 구현은 빨랐지만 AI가 계획을 짜면서 동시에 질문을 만들다 보니, 사용자 답변이 계획과 충돌하면 스스로 판단을 못 했습니다.

두 번째 시도는 마크다운 포맷으로 질문을 출력하게 하는 것이었는데 AI가 형식을 제멋대로 바꿔버렸습니다. 세 번째에서야 질문 전용 도구 AskUserQuestion을 따로 분리했고, 그때 안정적으로 작동하기 시작했습니다. 도구 하나에 역할 하나. 단순한 원칙인데 직접 부딪혀봐야 체감이 됩니다.

• 계획+질문 합체 — AI가 같은 도구를 두 번 호출하는 오류
• 마크다운 포맷 출력 — AI가 문장을 덧붙이거나 형식 무시
• 전용 도구 분리 — 구조화된 응답이 비로소 안정적으로 출력
• 설계가 아무리 좋아도 AI가 부르고 싶어하지 않으면 의미 없음

잘 작동하던 도구가 어느 날 족쇄가 됩니다

도구를 잘 분리해서 만들었다고 끝이 아닙니다. 이걸 ‘도구 유통기한(tool decay)‘이라고 부르고 싶습니다. 한때 필수였던 도구가 모델 업그레이드 이후 오히려 발목을 잡는 현상이거든요.

초기 Claude Code에는 할 일 목록 도구가 있었고, 5턴마다 “지금 할 일 잊지 마세요”라고 시스템 알림까지 보냈습니다. 모델이 좋아진 뒤에는 이 알림이 역효과를 냈습니다. AI가 목록을 수정해야 할 상황에서도 원래 계획을 고집했습니다. Opus 4.5에서 서브에이전트 협업이 가능해졌을 때는 기존 Todo 구조로 에이전트 간 작업 공유 자체가 안 됐습니다.

결국 Task Tool로 전면 교체했습니다.

• TodoWrite에서 Task Tool로 교체 — 에이전트 간 의존성 공유 가능
• “이 도구가 아직 유효한가?” 주기적 점검이 새 도구 추가만큼 중요
• 지원 모델 수를 적게 유지해야 판단 속도가 빨라짐
• 도구 개수보다 모델 능력에 맞는 도구 형태가 우선

AI한테 맥락을 떠먹여 주면 오히려 못합니다

도구를 더하고 빼는 과정을 거치면서 Claude Code 팀이 발견한 더 근본적인 패턴이 있습니다. AI한테 정보를 넣어주는 것보다 직접 찾게 하는 게 낫다는 것입니다.

처음에는 RAG 벡터 데이터베이스로 맥락을 미리 넣어줬습니다. 빠르고 강력했지만 환경마다 인덱싱이 깨졌고, AI가 “받은 정보”에만 기대는 문제가 있었습니다. Grep 도구를 줘서 코드베이스를 직접 검색하게 바꿨더니 맥락 품질이 올라갔습니다. 여기에 Skills 파일을 더해서 AI가 파일 안에 참조된 다른 파일을 재귀적으로 탐색하는 구조를 만들었습니다.

이걸 **단계적 맥락 발견(progressive disclosure)**이라고 부릅니다. 정보를 한꺼번에 주는 게 아니라 AI가 필요한 것을 스스로 찾아가는 방식입니다.

• RAG — 환경 의존성 높고 AI가 수동적으로 맥락 소비
• Grep + Skills — AI가 여러 층의 파일을 능동적으로 탐색
• 1년 만에 “맥락을 못 만드는 AI”에서 “스스로 찾는 AI”로 변화
• 도구 추가 없이 Skills 파일만으로 기능 확장 가능

도구를 추가하지 않고도 AI가 할 수 있는 일을 늘리는 법

이 단계적 맥락 발견 패턴이 빛을 발한 사례가 하나 더 있습니다. Claude Code 사용법을 물어봐도 답을 못 하는 문제가 있었습니다. 시스템 프롬프트에 사용법을 전부 넣을 수도 있었지만, 그 질문은 가끔만 나옵니다. 자주 안 쓰는 정보가 맥락 범위를 상시 차지하면 코드 작성이라는 본업 성능이 떨어집니다. 이걸 **맥락 잡음(context rot)**이라고 부릅니다.

해결책은 전용 서브에이전트였습니다. 사용법 질문이 들어올 때만 가이드 에이전트가 문서를 검색해서 답만 돌려주는 구조로 바꿨습니다. 도구 수는 그대로인데 AI가 할 수 있는 일은 늘어난 것입니다.

• 시스템 프롬프트에 모든 정보 — 맥락 잡음으로 코드 품질 하락
• 문서 링크만 제공 — AI가 결과를 너무 많이 맥락에 올림
• 전용 서브에이전트 + 검색 지침 — 필요한 답만 깔끔하게 반환
• 도구를 더하는 대신 구조를 바꿔서 해결한 사례

정답 공식은 없습니다

도구를 더하고 빼고 다시 설계하는 이 과정에 정답 공식은 없습니다. 모델이 바뀌면 도구도 바뀌어야 하고, 어제 맞았던 구조가 내일은 병목이 될 수 있습니다.

Anthropic 팀이 1년간 반복한 한 가지가 있습니다. AI 출력을 읽고, 실험하고, 다시 고치는 것. 결국 에이전트를 잘 만드는 사람은 AI 입장에서 볼 줄 아는 사람입니다.