Claude Code 멀티 에이전트 안전 운용

여러 AI 에이전트를 동시에 가동할 때 무엇이 망가지는가. 800시간의 경험에서.

왜 멀티 에이전트가 필요한가

Claude Code는 한 세션에서 하나의 태스크만 다룰 수 있다. 코드를 작성하면서 테스트를 돌리고, 문서도 갱신하는 작업을 한 세션으로 처리하면 컨텍스트가 부풀어 토큰 효율이 악화된다.

해결책은 역할 분리다. 구현 에이전트, 리뷰 에이전트, 테스트 에이전트로 나누어 각자 전문 영역에 집중한다.

전체 방침 결정, 우선순위 부여, 품질 판단

코드 구현, 테스트 실행, 문서 갱신. tmux로 동시 가동

모든 에이전트에 공통된 안전 제약. rm -rf 방지, 시크릿 유출 방지, 토큰 제한

멀티 에이전트는 사고 위험이 단일 운용의 2~3배가 된다. 각 에이전트가 독립적으로 동작하기 때문에 한 에이전트가 변경한 파일을 다른 에이전트가 덮어쓰는 사례가 발생한다.

최소한 필요한 안전 설정:

npx @gaebalai/cc-guard --shield

이 명령어로 8개의 기본 hook이 일괄 설치된다. 멀티 에이전트 환경에서는 모든 에이전트가 같은 hook을 공유한다 (~/.claude/settings.json은 공통).

tmux의 각 페인에서 Claude Code를 기동. 왼쪽 페인에서 구현, 오른쪽 페인에서 테스트. send-keys로 태스크를 투입.

특정 디렉터리에 파일이 추가되면 자동으로 Claude Code에 태스크를 투입. inotifywait로 감시.

Claude Code 내장 Agent tool로 병렬 실행. 메인 세션의 컨텍스트를 오염시키지 않고 조사·분석을 수행.

멀티 에이전트 협조는 아직 발전 도중이다. 다음과 같은 문제가 일상적으로 발생한다:

멀티 에이전트에 앞서, 먼저 단일 운용의 안전 설정을 다져두자.