여러 개발 플러그인을 하나의 에이전트로 통합하기: 1M 컨텍스트와 유지보수 비용

TL;DR
여러 Claude Code 플러그인으로 개인 개발 도구를 나눠 만들었는데 늘수록 관리·위임 오류로 번거로워졌습니다.
모델이 발전하고 메인 세션 컨텍스트가 1M 으로 커지자 나눠 둘 이유가 약해져 하나의 작업 비서(ops-agent)로 합쳤습니다. 이제 이슈를 시작한다 하나로 단순해졌습니다.

배경: AI에게 맡기려면 매번 같은 출발선이 필요하다

AI 에게 코드와 문서를 맡기면 반복 작업이 줄어듭니다. 문제는 같은 요청에도 매번 다르게 답하고, 어제 합의한 규칙을 오늘 잊는다는 점입니다. 매번 사람이 교정하면 그 교정이 다시 일이 됩니다. 그래서 일회성 프롬프트로 쓰는 대신, 판단과 규칙을 하네스에 심어 AI 가 매 세션 같은 원칙 위에서 시작하게 만들기로 했습니다.

필요가 생길 때마다 도구를 하나씩 만들었습니다. 각 판단은 그 시점엔 맞았습니다. 모델 컨텍스트가 넉넉하지 않던 때라 도구를 작게 나눠 필요할 때만 불러 쓰는 편이 합리적이었습니다. 범용 도구는 대외 공개를 염두에 두고 회사 내부 로직을 넣지 않았고, 멀티레포와 사내 연동은 각각 별도 플러그인으로 분리했습니다. 4개의 층이 생기게 되었습니다.

도구	역할
cross-verify	의사결정·설계·문서·구현 4축 교차 검증
flow	단일 레포 이슈 라이프사이클 (이슈 → spec → 구현 → 커밋 → PR)
org-flow	멀티레포 오케스트레이션 (spec·FE·BE 가 별도 레포)
toolkit	사내 도구·시스템 접근 (이슈 트래커·CI·내부 API 등)

org-flow (멀티레포 오케스트레이션)
  └─ flow (단일 레포 이슈 라이프사이클)
       └─ toolkit (사내 도구·시스템 접근)
            └─ provider (환경별 설정)

문제: 겹겹이 쌓을수록 에이전트가 놓친다

org-flow 가 flow 에 위임할 때마다 컨텍스트 전환이 생깁니다. 멀티레포 이슈를 시작하면 내부에서 flow 의 이슈 생성·시작을 호출하고 결과를 검증하고 워크트리 생성 같은 후속 작업을 이어갑니다. 위임 전 가드 설정, 위임 결과 검증, 실패 시 롤백을 LLM 에이전트가 순서대로 기억하고 실행해야 합니다. 층이 하나 늘 때마다 에이전트가 놓칠 수 있는 지점이 늘어납니다.

같은 기간 다른 배치 파이프라인 작업에서 같은 문제를 겪었습니다. 에이전트가 5단계를 수동으로 수행하다 캐시 미기록, 폴백 재삽입 같은 버그가 서너 번 반복됐습니다. 해법은 결정적 로직을 스크립트로 분리하고 불변식 검증을 스크립트에 내장해 에이전트의 개입 구간을 줄이는 데 있었습니다.

전환점: 모델이 발전하자 분리의 근거가 약해졌다

도구를 작게 나눈 근거는 필요할 때만 불러 쓴다였습니다. 모델 컨텍스트가 작은 경우 이 방식이 맞습니다. 그런데 모델이 세대를 거치며 발전하면서 전제가 흔들렸습니다. 체감상 가장 컸던 건 메인 세션이 한 번에 담는 컨텍스트가 1M 으로 늘어난 점입니다. 컨텍스트가 넉넉해지면서 하나의 에이전트가 이슈 플로우, 멀티레포, 검증, 규칙을 담아도 모자라지 않게 됐고 필요한 부분만 인덱스로 지연 로드하면 되는 구조가 된 것입니다.

다만 컨텍스트 하나로 단정하진 않습니다. 같은 기간 모델의 지시 이행·판단 품질도 함께 올라갔고 어느 요인이 결정적이었는지는 딱 잘라 말하기 어렵습니다. 정말 컨텍스트 때문인지는 다음 통합·분리 결정 때 다시 확인할 문제입니다. 분명한 건 방향입니다. 분리로 얻던 작게 유지의 이점은 줄고, 관리 포인트와 위임 오류라는 비용은 남았습니다. 그래서 판단을 다시 했습니다.

나눠 두는 대신, 하나로 합친다.

설계의 실체: 레포 수는 매니페스트가 알고, 도구가 처리한다

합치되, 레포 수처럼 바뀌는 정보는 코드가 아니라 데이터로 밀어냈습니다. org-flow 의 결정적 로직을 스크립트로 분리하고, flow 가 레포 수를 자동 감지해 단일·멀티를 투명하게 처리하도록 흡수했습니다.

이전 · 4층:  org-flow → flow → toolkit → provider
   │
   │ 통합
   ▼
이후 · 2층:  ops-agent(통합) → 사내 연동 어댑터

멀티레포 정보는 프로젝트 매니페스트 project.json 에 레포 수·역할·베이스 브랜치로 둡니다. 매니페스트가 없으면 단일 레포로 동작해 하위 호환을 유지하고, 새 프로젝트는 스킬 문서를 고치는 대신 매니페스트 십여 줄만 작성하면 됩니다.

이슈를 시작한다
  → flow 가 레포 수 자동 감지
  → 매니페스트로 관련 레포 결정
  → 워크트리 스크립트 (브랜치 생성·불변식 검증)
  → 작업 · AI 오케스트레이션
  → 커밋 스크립트 (원격 브랜치·불변식 검증)

결정적 작업은 스크립트로 옮기고, 각 스크립트에 불변식 검증을 내장했습니다. 브랜치나 원격 브랜치가 없으면 스크립트가 중단하므로, 에이전트는 호출하고 결과를 보고할 뿐입니다.

규칙도 세 시점(세션 시작, 편집·응답, 스킬 실행)에 자동으로 걸리게 두었습니다. 가령 표현 가드는 출력을 막는 대신 사전 주입과 사후 통지로 두어, 도구가 판단을 대체하지 않고 판단할 자리만 좁힙니다.

판단: 보조 도구에서 개인 개발 운영 에이전트로

하나로 합친 뒤 도구의 성격이 처음과 달라졌습니다. 처음엔 개발 편의를 돕는 보조 도구(DevEx)였는데, 이슈 플로우, 멀티레포 조정, 검증, 규칙 적용을 하나가 맡으면서 개인 개발을 운영하는 에이전트에 가까워졌습니다. 그래서 이름을 devex 에서 ops-agent 로 바꿨습니다. 단독 플러그인이던 교차 검증 도구도 이 안으로 들어와, 이제 별도 도구가 아니라 하나의 비서가 제공하는 검증 기능입니다. 이 도구는 회사 업무에도 쓰기 때문에 사내 연동은 별도(비공개) 플러그인으로 분리해, 퍼블릭 표면에 사내 정보가 섞이지 않도록 경계를 두었습니다.

지금 규모(1인 개발, 소수 프로젝트)에서는 매니페스트 + 스크립트 + 규칙 하네스로 충분하다고 판단했습니다. 과한 것을 미리 들이지 않았습니다. 정량 지표는 대부분 이슈를 병행하며 만든 것이라 측정이 끝나지 않았고, 검증되지 않은 수치는 적지 않았습니다. 다만 교차 검증 기능은 업무 레포 두 곳에서 타임존·페이지네이션 관련 이슈를 배포 전에 발견했습니다.

가장 큰 변화는 인지 모델입니다. 이슈가 멀티레포냐 단일 레포냐에 따라 org-flow 와 flow 를 구분해 쓰던 것이, 이슈를 시작한다 하나로 단일화됐습니다. 레포가 몇 개인지는 매니페스트가 알고, 도구가 처리합니다. 이 도구를 만들면서 분명해진 것은, AI 를 잘 쓰는 일이 모델을 다루는 일이 아니라 도구와 규칙의 아키텍처를 판단하는 일이라는 점입니다. 그리고 그 판단은 한 번으로 끝나지 않습니다. 처음엔 나누는 게 맞았고 지금은 합치는 게 맞았는데, 그 사이를 가른 건 모델이 발전한 것이고 그중 컨텍스트가 커진 영향이 컸습니다. 모델이 또 달라지면 분리와 통합을 다시 물어야 합니다. AI 는 그 판단을 실어 나르는 도구입니다.

매니페스트 스키마와 스크립트 등 구현 세부는 ops-agent 레포에 공개돼 있습니다.

---

이 글은 Claude와 함께 작업했습니다.