Claude Code를 활용한 다층 에이전트 시스템 구축 경험 공유

커뮤니티 반응

작성자의 체계적인 접근 방식에 대해 긍정적인 반응이며, 특히 에이전트에게 오케스트레이션을 맡기지 않는 결정에 공감하는 의견이 많다.

주요 논점

01찬성다수

에이전트를 순수 판단 역할로 한정하고 외부 로직으로 제어하는 것이 프로덕션 환경에서 훨씬 안정적이다.

합의점 vs 논쟁점

합의점

에이전트의 자율성에만 의존하면 비용이 급증하고 결과의 일관성이 떨어진다.
역할에 따른 권한 분리(RBAC)가 에이전트 시스템에서도 필수적이다.

논쟁점

여러 리포지토리에 걸친 복잡한 기능 구현 시 에이전트의 일관성이 저하되는 문제는 여전히 해결 과제로 남아 있다.

실용적 조언

에이전트가 코드를 커밋하기 전에 lint와 format을 강제하는 pre-commit hook을 설정하여 코드 품질을 강제하라.
모호한 티켓은 에이전트가 추측하게 두지 말고 즉시 차단(Blocker)으로 플래그를 지정하여 수동 개입을 유도하라.

섹션별 상세

에이전트의 역할을 오케스트레이션이 아닌 순수 판단(Judgment)으로 제한했다. Jira API 호출이나 Git 작업 같은 기계적인 업무는 Python 코드가 담당하고, Claude Code는 코드 작성이나 아키텍처 선택과 같은 판단이 필요한 시점에만 호출된다. 이러한 분리를 통해 에이전트가 도구 사용을 통해 직접 워크플로를 제어할 때 발생하는 속도 저하, 비용 증가, 비결정성 문제를 해결했다.

구현 에이전트와 리뷰 에이전트의 컨텍스트를 엄격히 분리하여 정확도를 높였다. 리뷰 에이전트는 수정 권한이 없는 읽기 전용 상태로 독립된 컨텍스트 윈도우에서 실행되며, 이를 통해 구현 에이전트가 스스로 인지하지 못하는 공유 코드의 동작 변경 사항을 효과적으로 포착했다. 권한 제어와 역할 분담이 에이전트 시스템의 안정성을 확보하는 핵심 요소임을 확인했다.

에이전트의 자율적인 코드 탐색 대신 사전에 조립된 구현 브리프(Brief)를 제공하는 방식을 채택했다. Python 오케스트레이터가 관련 문서 검색, 의존성 분석, 수용 기준 등을 30~50줄의 JSON 번들로 요약하여 전달함으로써 에이전트의 토큰 소비를 대폭 절감했다. 이는 에이전트가 직접 코드베이스를 탐색하며 낭비하는 리소스를 줄이고 작업의 집중도를 높이는 결과를 가져왔다.

지식 계층에 신뢰 등급(Verified, Inferred, Human-provided)을 도입하여 할루시네이션의 연쇄 작용을 방지했다. 에이전트가 과거에 추론한 내용을 무조건적인 사실로 받아들여 오류가 누적되는 현상을 막기 위해 각 정보의 출처와 신뢰도를 구분하여 관리했다. 이러한 계층화된 지식 관리는 세션 간의 연속성을 유지하면서도 데이터의 무결성을 확보하는 데 기여했다.

용어 해설

오케스트레이션(Orchestration): — 여러 시스템이나 워크플로를 자동화하고 관리하는 프로세스입니다. 이 글에서는 복잡한 티켓 처리 과정을 제어하기 위해 에이전트 대신 일반 Python 코드가 흐름을 제어하는 방식을 강조합니다.
컨텍스트 윈도우(Context Window): — LLM이 한 번에 처리할 수 있는 텍스트 데이터의 양입니다. 구현 에이전트와 리뷰 에이전트의 컨텍스트를 분리하여 서로 간섭을 줄이고 정확도를 높이는 전략으로 활용되었습니다.
할루시네이션(Hallucination): — AI 모델이 사실이 아닌 정보를 사실처럼 생성하는 현상입니다. 본문에서는 에이전트가 과거의 추론을 진실로 믿고 오류를 축적하는 문제를 방지하기 위해 지식 계층에 신뢰 등급을 도입했습니다.
서브에이전트(Subagent): — 특정 작업(예: 코드 리뷰)만을 수행하도록 권한과 역할이 제한된 보조 에이전트입니다. 권한 분리를 통해 구현 에이전트가 놓치는 오류를 잡아내는 역할을 수행합니다.

언급된 도구

Claude Code추천

코드 작성 및 판단을 위한 자율 코딩 에이전트 런타임

Jira중립

티켓 관리 및 작업 추적

언급된 리소스

문서AI-Assisted Product Engineering Full Writeup