Multi-agent 소유권 모델

추적: #245. 역할별 owner: #238 · #239 · #240 · #241 · #242 · #243 · #244

왜 필요한가

RAG 파이프라인은 단계별 (ingestion → 검색 → 계획 → 검증 → 답변 → eval) 로 나뉘지만, 허브 모듈 rag_core.py (~4,227 LOC) 가 검색·계획·검증·청킹·답변 조립을 한 파일에 집중하고 26개 파일이 이를 import. 14개 ADR 이 계약 (답변 스키마, 기준선 보존, eval 분리, 근거 경계) 을 고정. CLAUDE.md 는 “one PR, one concern” + stacked-PR 규율 요구.

여러 agent 가 병행 작업 시 3개 충돌 지점:

  1. 단일 파일 rag_core.py
  2. 답변 dict 스키마 (ADR 0003) — eval/, api/, demo/ 의 모든 소비자가 의존
  3. eval/config.yaml — naive_baseline preset 보존 의무 (ADR 0001)

해법: ADR 소유권 + 허브 lock-holder — ADR cluster 당 agent 1명, rag_core.py 변경은 단일 owner 경유.

원칙

  1. Start gate. 파일 소유권을 읽기 전에 먼저 overlap-preflight를 실행한다. Codex, Claude Code, 루트 checkout, .codex/worktrees/*, .claude/worktrees/*, 외부 git worktree는 모두 같은 coordination surface다. blocked면 시작하지 않고, warn이면 예상 변경 파일이 다른 세션의 dirty/diff 파일과 겹치지 않는다는 근거를 남긴다.
  2. ADR 소유권. agent 1명 = ADR 계약 1개 이상의 단독 저자. 해당 ADR 수정은 그 agent 의 PR 으로만
  3. 허브 lock holder. rag_core.py 는 Pipeline Core owner 만 수정. 다른 owner 는 hook, callback, run_rag_query public surface 경유
  4. Additive only. 신규 기능은 분석 변형 또는 확장 preset (ADR 0001/0011). 추출형 기준선은 절대 교체 금지
  5. Stacked PR. 의존 작업은 상위 PR 위로 rebase, gh pr create --base <upstream>. 독립 작업은 main 으로 직접

7개 소유권 역할

1. Pipeline Core — #238

  • 파일: rag_core.py (청킹 889–1100, 계획 1750–2025, 검색 2027–2320, 검증 2528–2750, 답변 조립 2749–2950 + 4155–4190)
  • ADR: 0001 (기준선), 0002 (메타데이터 우선), 0003 (답변 계약), 0004 (검증기·재시도), 0008 (근거 경계), 0010 (하이브리드 검색)
  • 금지: pipeline_cli_choices() 에서 naive_baseline 제거; run_rag_query 반환 dict 키 무단 변경; 답변 계약 변경 시 schema_version bump 누락

2. Ingestion — #239

3. Synthesis — #240

  • 파일: rag_synthesis.py; rag_core.py 안 synthesis 훅 1개 (Pipeline Core 경유)
  • ADR: 0011 (LLM synthesis additive)
  • 금지: claims/citations 를 LLM 에서 생성 (추출형 유지 — ADR 0003+0011). Synthesis 는 opt-in 유지, 기본 활성 금지

4. Evaluation — #241

5. Observability — #242

  • 파일: rag_observability.py; rag_core.py trace 훅 삽입점 (Pipeline Core 경유)
  • ADR: 0013 (pluggable observability)
  • 범위 예시: 신규 trace backend (Otel exporter, custom sink), redaction 정책, span enrichment

6. API & Demo — #243

  • 파일: api/main.py, app.py, demo/
  • ADR: 없음 — run_rag_query public surface 만 소비
  • 제약: run_rag_query 반환 dict 키만 사용. rag_core.py 내부 헬퍼 import 금지; 신규 인터페이스 필요 시 Pipeline Core owner 경유

7. Infra & CI — #244

충돌 해결 규칙

  • rag_core.py 동시 편집: Pipeline Core owner 가 단독 lock holder. 다른 owner 가 hook/public surface 로 안 되는 hub 변경 필요 시 Pipeline Core 경유 interface-change PR 먼저 → downstream PR 은 gh pr create --base 로 stack
  • 답변 dict 스키마 변경 (ADR 0003): 항상 standalone PR — ADR 수정 + schema_version bump + eval/api/demo 소비자 broadcast. feature 작업과 묶지 않음
  • eval/config.yaml: Evaluation owner 단독. 다른 owner 는 신규 분석 변형 preset 요청, 직접 편집 금지
  • docs/adr/ 파일: 해당 영역 owner 가 신규 ADR 작성. 기존 ADR 파일 삭제·이름변경 금지 — Status 블록에 Superseded 표시

시나리오 → owner 매핑

시나리오 owner 스태킹(Stacking)
신규 검색 backend (예: ColBERT) Pipeline Core + Evaluation Eval PR 이 Pipeline Core PR 위로 stack
신규 문서 포맷 (예: HWPX) Ingestion 독립(Standalone)
LLM-judge / RAGAS 메트릭 개선 Evaluation 독립(Standalone)
신규 데모 화면 또는 Colab 노트북 API & Demo 독립(Standalone)
신규 CI gate (예: schema_version assertion) Infra & CI 독립(Standalone)
답변 스키마 확장 Pipeline Core → API & Demo + Evaluation 소비자 PR 이 스키마 PR 위로 stack
신규 Otel exporter Observability 독립(Standalone)

검증

매 PR 전: make smoke + bash scripts/test.sh. load-bearing 파일 (rag_core.py, ingestion.py, visual_ingestion.py, eval/, api/main.py) 변경 시 real-data 영향을 검토한다 — private real-eval 은 maintainer 전용(ADR 0005 / CLAUDE.md ban-list 참조)이며, 동작 변경 PR 은 make real-eval-delta 로 델타를 측정해 PR §5 에 근거를 남기는 것을 권장한다(§5b 강제 게이트는 ADR 0084 로 폐지).

CI gate: pr-eval.yml, branch-and-issue-check.yml. 답변 계약 PR 은 추가로 schema_version 증가 + ADR 0003 갱신 확인.

참고