멀티 리포지토리 마이크로서비스 변경은 조정의 문제입니다. 저는 이를 AI 에이전트 팀으로 해결했습니다.

RepoOrch에 대한 안내서 — 멀티 리포지토리 (multi-repo) 워크스페이스를 피어 투 피어 (peer-to-peer) 메시징과 엄격한 읽기 전용 (read-only) 안전 모델을 갖춘 AI 전문가들의 숙의 팀으로 변환하는 오픈 소스 Claude Code 플러그인입니다.

github.com/architonixlabs/RepoOrch · MIT 라이선스 · v0.3.0

마이크로서비스 조직에서 멀티 리포지토리 버그를 처리하는 솔직한 워크플로우는 다음과 같습니다: 세 개의 코드베이스를 열고, 눈이 흐릿해질 때까지 읽으며, 네 번째 코드베이스에서 계약 위반 (contract break)을 놓치지 않았기를 기도하는 것입니다.

이것은 코드의 문제가 아닙니다. 이것은 조정 (coordination) 문제입니다. 그리고 이것은 Claude Code의 새로운 Agent Teams 프리미티브 (primitive)가 해결하기 위해 만들어진 바로 그 형태의 문제입니다.

이 포스트에서 저는 다음 내용을 다룹니다:

왜 서브 에이전트 (subagents, 이전 프리미티브)가 멀티 리포지토리 변경 계획을 처리할 수 없는지
Agent Teams가 추가하는 것 — 구체적으로, 에이전트 간 피어 투 피어 메시징을 위한 메일박스 (mailbox) 추상화
멀티 리포지토리 워크스페이스를 숙의하는 AI 팀으로 바꾸기 위해 이 패턴을 사용하는 오픈 소스 플러그인인 RepoOrch를 어떻게 구축했는지
제안 전용 (propose-only) 안전 모델과 왜 이것이 문장이 아닌 플랫폼 레이어에서 강제되는지
지식 그래프 (knowledge graphs)가 대규모 워크스페이스에서 분류 (triage)당 토큰 비용을 어떻게 절감하는지

만약 당신이 단 하나의 마이크로서비스 변경을 위해 다섯 개의 탭을 열어두고 _"여기에는 더 나은 분업 방식이 있어야 해"_라고 생각한 적이 있다면, 이 글은 바로 그 문제를 위한 것입니다.

1. 문제의 형태

아래와 같은 워크스페이스를 상상해 보세요 — 지극히 평범한 마이크로서비스 레이아웃입니다:

my-project/
├── auth-service/
├── payments/
...

당신의 큐(queue)에 티켓이 도착합니다:

"인증 (auth) 리팩토링 이후 사용자들이 401 에러를 겪고 있습니다."

이 버그는 거의 확실하게 여러 리포지토리에 걸쳐 존재합니다. 아마도 auth-service가 JWT 클레임 (claim)의 형태를 변경했고, payments는 여전히 이전 형태를 기대하고 있을 수 있습니다. 혹은 notifications가 클레임을 제대로 검증하지 않아 조용히 이벤트를 누락시키고 있을 수도 있습니다. 이를 알 수 있는 유일하고 정직한 방법은 각 코드베이스를 읽고, 계약 (contract)을 추적하며, 무언가를 놓치지 않았기를 바라는 것뿐입니다.

이것은 교과서적인 에이전트형 AI (agentic AI) 활용 사례입니다. 단 한 가지 예외가 있다면, 에이전트들이 서로 **대화(talk to each other)**해야 한다는 점입니다. 그리고 최근까지도 그들은 그럴 수 없었습니다.

2. 서브에이전트 (subagents)가 이를 수행할 수 없는 이유

(Agent Teams 도입 전) Claude Code의 표준 에이전트 오케스트레이션 (agent-orchestration) 패턴은 다음과 같았습니다:

master agent
    ├─→ subagent A (auth-service 전문가)
    ├─→ subagent B (payments 전문가)
...

각 서브에이전트는 질문을 받고, 조사를 수행한 뒤, 마스터 (master)에게 보고합니다. 서브에이전트들은 서로 대화할 수 없습니다. 이들은 그래프 (graph)가 아닌 트리 (tree) 구조를 형성합니다.

"이 파일을 읽어봐" 또는 "스키마 (schema)를 요약해줘"와 같은 작업에는 문제가 없습니다. 하지만 두 전문가가 서로 _협상 (negotiate)_해야 하는 순간, 이 구조는 무너집니다.

401 버그를 해결하기 위해 실제로 일어나야 하는 과정을 생각해 보십시오:

인증 (auth) 전문가의 제안: "JWT의 sub 클레임 (claim)을 user_id에서 UUID로 변경하겠습니다."
결제 (payments) 전문가의 답변 필요 사항: "내 서비스가 sub 클레임의 형태에 의존하고 있는가?"

서브에이전트 트리 구조에서는 두 전문가 사이의 유일한 경로가 마스터를 거쳐야만 합니다. 따라서 마스터는 다음 과정을 수행해야 합니다:

인증 제안을 결제 전문가에게 질문으로 전달할 수 있을 만큼 깊이 이해하기
결제 전문가의 답변 받기
이를 다시 인증에 대한 제약 조건 (constraint)으로 변환하기
모든 리포지토리 간의 엣지 (edge)에 대해 이 과정을 반복하기

이는 확장성 (scale)이 없으며, 더 나쁜 점은 마스터를 자신이 실제로 갖추지 못한 조정자 (coordinator) 역할로 강제한다는 것입니다. 그 결과, 계획은 완벽해 보이지만 오래된 가정 (stale assumptions)이 내포된 계획이 만들어집니다.

3. Agent Teams: 메일박스 프리미티브 (mailbox primitive)

Claude Code 2.1.32는 Agent Teams를 도입했습니다. 핵심적인 차이점은 작지만 혁신적인 추가 사항 하나입니다. 바로 각 팀원이 메일박스 (mailbox)를 갖게 된다는 것이며, 팀원들은 서로에게 직접 메시지를 보낼 수 있습니다.

master agent
    ├─→ auth specialist  ──┐
    │                      │  직접적인 피어 메시지 (direct peer messages)
...

이제 실제로 일어나야 하는 대화가 일어날 수 있게 되었습니다:

auth → payments: "JWT sub 클레임(claim)을 user_id에서 UUID로 변경할 것을 제안합니다. 귀하의 서비스가 sub를 직접 읽고 있나요? 만약 그렇다면, 어떻게 파싱(parse)하고 있습니까?"

payments → auth: "네, 저희는 auth.middleware.ts:42에서 sub를 읽고 parseInt()를 호출합니다. 동일한 릴리스(release)에서 UUID 파싱으로 업데이트하지 않으면 귀하의 변경 사항으로 인해 저희 서비스가 중단될 것입니다."

그러한 심의(deliberation)가 실제로 신뢰할 수 있는 계획을 만들어냅니다. 마스터(master)가 계약(contract)을 중재할 만큼 똑똑할 필요는 없습니다. 전문가(specialists)들이 그 역할을 수행하기 때문입니다.

4. RepoOrch가 이를 통합하는 방법

RepoOrch는 멀티 리포지토리(multi-repo) 마이크로서비스 사례에 대해 이 패턴을 실행 가능하게 만드는 Claude Code 플러그인입니다. 설정은 명령어 하나로 완료됩니다:

/repo-orch-setup

설정 러너(setup runner)는 다음과 같이 동작합니다:

워크스페이스 루트(workspace root) 아래의 모든 git 리포지토리(repo)를 발견합니다.
각 리포지토리를 인덱싱(indexing)합니다 (언어, 프레임워크, 엔드포인트, 이벤트, 의존성).
리포지토리당 편집 가능한 컨텍스트(context) 문서를 작성하고, 사용자의 검토를 위해 일시 중지합니다. (이것이 가장 중요한 단계입니다. 컨텍스트 내의 owns 필드가 나중에 라우팅(routing)을 결정합니다.)
사용자의 확인이 있으면, 리포지토리당 하나의 전문가 에이전트(specialist agent)와 마스터가 라우팅에 사용할 registry.json을 생성합니다.

그 후, 어떤 티켓(ticket)이 들어오든 다음과 같이 실행할 수 있습니다:

/repo-orch-triage "최근 auth 리팩터링 이후 사용자들이 401 에러를 겪고 있습니다"

마스터는 레지스트리(registry)를 읽고 어떤 리포지토리가 연관되었을 가능성이 높은지 점수를 매긴 뒤, 관련 전문가들을 에이전트 팀(Agent Team)으로 생성합니다. 이들은 평결(VERDICT)을 내리고, 각자의 메일박스(mailbox)를 통해 리포지토리 간 계약(cross-repo contracts)에 대해 심의하며, 마스터는 다음과 같은 내용을 포함한 단일화된 순차적 변경 계획을 합성합니다:

리포지토리 간 의존성 순서 (어느 리포지토리의 변경이 먼저 반영되어야 하는지)
리포지토리별로 명시된 리스크(risks)
검증 힌트 (실행해야 할 테스트 / 엔드포인트)
수정된 파일 없음 — 이는 안전 모델(safety model)로 이어집니다.

근본 원인(root cause)을 알 수 없는 장애 상황을 위해서는 다음과 같은 적대적 변형(adversarial variant)이 있습니다:

/repo-orch-deliberate "결제(Payments)가 간헐적으로 실패함 — 근본 원인 알 수 없음"

이로 인해 팀은 전문가들이 첫 번째 그럴듯한 원인으로 너무 빨리 수렴하지 않고, 서로의 가설에 의문을 제기하도록 유도하는 모드로 전환됩니다.

5. 플랫폼 계층에서 강제되는 제안 전용 (Propose-only) 방식

프롬프트에는 "파일을 수정하지 마세요"라고 되어 있음에도 불구하고 에이전트가 파일을 수정해 버리는 AI 에이전트의 반복적인 실패 모드가 존재합니다. 자연어(Prose)는 보안 경계(Security boundary)가 아닙니다.

RepoOrch는 두 가지 계층에서 제안 전용(Propose-only) 방식을 강제합니다:

도구 제한 (Tool restriction). 모든 전문가 에이전트는 tools: Read, Grep, Glob, Bash와 함께 생성됩니다. 쓰기(Write), 편집(Edit), 생성(Create) 또는 삭제(Delete) 도구는 사용할 수 없습니다. 이는 프롬프트 지침이 아니라, 에이전트가 실제로 볼 수 있는 도구 목록(Tool inventory) 자체를 제한하는 것입니다.
PreToolUse 훅 (PreToolUse hook). 플랫폼 계층의 훅이 모든 Bash 호출을 가로채어 쓰기와 유사한 명령인 rm, mv, git commit, git push, sed -i, > 리다이렉션 등을 하드 블록(Hard-block)합니다. 악의적이거나 환각(Hallucination)에 의한 Bash 호출이라 할지라도 실행되기 전에 거부됩니다.

/repo-orch-triage 및 /repo-orch-deliberate 명령은 추가적으로 permissionMode: "plan" 설정을 가진 에이전트를 생성하므로, 생성 컨텍스트 자체가 읽기 및 위임(Read + Delegate) 전용이 됩니다.

README에 명시된 v0.2 보장 사항: 에이전트는 계획 문서(Plan document)를 생성합니다. 개발자가 이를 실행합니다.

6. 지식 그래프(Knowledge graphs) 및 토큰 절약

트리아지(Triage)를 수행하는 순진한 방식은 모든 전문가가 티켓이 발생할 때마다 자신의 리포지토리를 처음부터 다시 읽게 하는 것입니다. 이 방식도 작동은 하지만, 비용이 누적됩니다. 선택 사항인 /repo-orch-graph 명령은 리포지토리당 Claude 네이티브 지식 요약본을 구축합니다:

/repo-orch-graph    →  Claude가 각 리포지토리를 읽고 summary.json을 작성합니다.
     ↓                  (1회성 비용, API 키 불필요)
/repo-orch-triage   →  마스터(Master)가 summary.json을 약 600토큰 분량으로 사전 로드합니다.
...

이 전체 흐름은 Claude Code 세션 내부에서 실행됩니다. Python, API 키, 외부 서비스가 필요하지 않습니다. 요약본이 존재하지 않는 경우, 플러그인은 직접 파일 읽기 방식으로 자연스럽게 전환(Degrade gracefully)됩니다.

대규모 워크스페이스(Workspace)에서 이는 "비용이 많이 드는 느낌"과 "무료인 느낌" 사이의 차이를 만듭니다. 소규모 워크스페이스에서는 설정할 가치가 없으며, 플러그인을 통해 이를 건너뛸 수 있습니다.

7. CI를 위한 헤드리스 모드 (Headless mode)

Jira 티켓이나 GitHub 이슈가 생성될 때 자동으로 분류(Triage)가 이루어지기를 원하는 팀을 위해, RepoOrch는 Anthropic Agent SDK를 통해 헤드리스 엔트리 포인트(Headless entry point)를 노출합니다:

import { runTriage } from '.claude/plugins/repo-orchestrator/automation/repo-orch-triage_runner.mjs';

// GitHub/Jira 웹훅(Webhook) 핸들러 내에서:
...

이는 permissionMode: "plan" 모드로 실행되며, 대화형 흐름과 동일하게 읽기 전용 및 제안 전용(Read-only, propose-only) 제약 사항을 따릅니다. 출력물은 동일한 변경 계획(Change-plan) 문서이며, 소스 티켓에 댓글로 게시됩니다.

다음에 구축할 것들

v0.4 및 그 이후를 위해 제가 탐색 중인 몇 가지 방향은 다음과 같습니다:

신뢰도 가중치 계획 (Confidence-weighted plans). 집계 신뢰도 공식은 이미 skills/routing/SKILL.md에 존재합니다. 이를 더 눈에 띄게 노출하여 개발자들이 위험 요소를 단순히 심각도(Severity)가 아닌 불확실성(Uncertainty)에 따라 정렬할 수 있도록 할 것입니다.
그래프 인식 숙의 (Graph-aware deliberation). 현재 메일박스(Mailbox)는 완전히 연결되어 있습니다. 10개 이상의 리포지토리 워크스페이스의 경우, 실제 서비스 의존성 엣지(Service-dependency edges)를 따라 메일박스를 라우팅하면 숙의 오버헤드(Deliberation overhead)를 줄일 수 있습니다.
명시적 동의 프롬프트 뒤의 실행 모드 (An execute mode behind an explicit consent prompt). 여전히 기본값은 제안(Propose-by-default)이지만, 차이점 승인(Diff approval)과 함께 리포지토리별로 계획을 적용할 수 있는 보호된 경로를 제공할 것입니다.

사용해 보기

# 마켓플레이스 추가 (1회성)
/plugin marketplace add architonixlabs/RepoOrch

...

그 다음, 2개 이상의 git 리포지토리가 즉시 하위 디렉토리로 존재하는 모든 워크스페이스에서 /repo-orch-setup을 실행하세요.

소스, 이슈 및 토론: github.com/architonixlabs/RepoOrch

RepoOrch가 멀티 리포지토리 분류 작업을 단 한 시간이라도 줄여준다면, GitHub 스타(Star)는 제가 계속해서 개발을 이어갈 수 있게 하는 신호가 됩니다. 만약 사용 중 문제가 발생한다면 이슈를 등록해 주세요. 바로 응답하겠습니다. v0.3은 방금 10개의 보안 강화 패치를 배포했으며, v0.4는 여러분과 같은 피드백을 통해 형성되고 있습니다.