Claude code agents orchestra 업데이트

내가 작업한 오픈소스 중에서 가장 많은 Star를 받은 프로젝트가 있는데, 바로 claude-code-agents-orchestra이다.

이 프로젝트는 기존 Claude Code Agent의 Subagent 기능을 활용해 여러 에이전트가 팀을 이루고, Claude가 적절한 팀을 찾아 작업을 할당하도록 돕는 도구이다. 최근 새롭게 추가된 Skills 기능을 이 프로젝트에 어떻게 접목할지 리서치하던 중, Vercel 블로그에서 매우 흥미로운 글을 발견했다.

바로 Jude Gao님이 작성한 AGENTS.md outperforms skills in our agent evals라는 포스트다.

AGENTS.md와 Skills 비교 실험

이 글은 AI 코딩 에이전트에게 프레임워크(Next.js) 관련 지식을 제공할 때 어떤 컨텍스트 전달 방식이 가장 효과적인지 실험한 결과를 다룬다.

컨텍스트 제공 방식 (Configuration)	통과율 (Pass Rate)	기준 대비 (vs Baseline)
기본 (Baseline - no docs)	53%	-
스킬 (Skill - default behavior)	53%	+0p
명확한 스킬 사용 지시 (Skill with explicit instructions)	79%	+26p
AGENTS.md 인덱스 명시 (AGENTS.md docs index)	100%	+47p

실험 결과에서 알 수 있듯, 능동적으로 도구를 호출하도록 유도하는 Skills 방식보다 AGENTS.md를 통해 정적(수동적)으로 컨텍스트 지도를 만들어 제공하는 방식이 압도적으로 효과적이었다.

프로젝트 개선 아이디어

이 대목에서 큰 힌트를 얻었다. 현재 내 프로젝트의 핵심인 Subagent를 호출하는 기능 역시 Skills와 동일한 ‘능동적 도구 호출’ 방식이다.

Vercel의 실험 결과처럼 수동적 컨텍스트 제공이 유리하다면, Subagent의 역할과 호출 방법 역시 CLAUDE.md (또는 AGENTS.md)를 통해 정적인 인덱스로 제공하는 것이 훨씬 뛰어난 성능을 보일 것이라는 가설을 세우게 되었다.

해당 블로그에서 제안한 효율적인 인덱싱 방식은 아래와 같다.

[Next.js Docs Index]|root: ./.next-docs
|IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning
|01-app/01-getting-started:{01-installation.mdx,02-project-structure.mdx,...}
|01-app/02-building-your-application/01-routing:{01-defining-routes.mdx,...}

마무리 및 향후 계획

위 구조를 참고하여 Subagent 관리 방식을 개편하는 PR을 작성해 두었다.

다만, 현재 사용 중인 Codex의 구독 기간이 남아있어 당장 테스트하기는 어렵다. 향후 Claude Code를 다시 사용하게 되는 시점에 직접 테스트해 본 뒤 병합할 예정이다.

클로드 넘 비싸…