8.4 KiB
8.4 KiB
🛠️ Multi-Agent Mux 종합 개선 및 미해결 과제 백로그 (OPTIMIZATION.md)
- 최종 갱신일: 2026-08-05
- 통합 관리 대상: 기존
CODEBASE_REVIEW_REPORT.md(코드베이스 잔여 결함 16건) +OPTIMIZATION.md(오케스트레이션 최적화 과제 3건) - 총 추적 미해결 과제: 19건
📌 개요
본 문서는 Multi-Agent Mux (MAM) 프레임워크의 코드베이스 아키텍처 결함, 런타임 엣지케이스, 레거시 잔재 및 /multi-agent-mux-loop 오케스트레이션 최적화 과제를 단일 백로그로 통합 추적하기 위한 종합 관리 문서입니다.
1. 🔴 아키텍처 결함 (Architecture Flaws — 3건)
A-1: herdr 서버명 전역 고정 및 타 워크스페이스 세션 오등록
- 현상:
HERDR_SERVER_NAME이 워크스페이스별 파생값이 아닌multi-agent-mux라는 머신 전역 상수로 하드코딩되어 있습니다. - 파급 효과: 한 머신에서 다수의 MAM 워크스페이스 사용 시, 백그라운드 모니터(
reconcile.shdrift-B)가 다른 워크스페이스의 세션을 내.mam/agent-sessions.yaml레지스트리에 무단 등록하여 세션 오염을 발생시킵니다.
A-2: 공개 브로커 + HMAC 인증 Off + 와일드카드 전파
- 현상:
mqtt_common.py의 기본 브로커가 공개 서버(broker.hivemq.com), HMAC 무조건 True 반환으로 설정되어 있습니다. - 파급 효과: 외부에서 유입되는 malicious
error이벤트 수신 시reconcile.sh가 라이브 에이전트 pane을kill-session으로 강제 파괴하는 치명적 보안/안정성 위험이 존재합니다.
A-3: 시프트 버퍼 단일 파일 공유 및 동시 주입 오염
- 현상:
send_keys_safe시프트의set/paste/delete-buffer가-b세션 버퍼 이름을 무시하고 단일.mam/shim/tmp_buffer파일 하나만을 공유합니다. - 파급 효과: 다중 에이전트 동시 주입 시 대화 텍스트 교차 오염 및 무음 유실(t5 silent loss)이 발생합니다.
2. 🟠 엣지 케이스 및 런타임 버그 (Edge-case Bugs — 8건)
B-1: find_workspace_uuid tier-3 NameError로 영구 사망
lib.sh내 agy 대화 복원용 tier-3 경로가 미정의 변수(db_path,yaml_path) 및yamlimport 누락으로 항상NameError예외를 내고 삼켜져 agy 대화 복원이 거부됩니다.
B-3: command -v herdr 프리플라이트 무력화
create_session.sh의 프리플라이트 검사 시command -v herdr가lib.sh에 정의된 bash 함수(herdr())를 호명하여 실제 시스템herdr바이너리가 없어도 프리플라이트를 무조건 통과해버립니다.
B-4: 시프트 ls의 created=0 하드코딩으로 재개 가드 무력화
herdr ls서브커맨드 래퍼가 세션 생성시각을 상수0으로 리턴하여reconcile.shdrift-B 등록 시 epoch 0이 되어 오래된 대화 jsonl 배제 가드가 붕괴됩니다.
B-5: df --output GNU 전용 플래그 사용으로 macOS NFS 감지 실패
- macOS/BSD 환경에서
df --output구문 오류로 NFS 감지가 실패하고 "NFS 아님"으로 오판되어 SQLite WAL 포맷을 강행합니다.
B-6: 스킬 트리에 임시 파일 복사 및 유출
run_loop.sh::delegate_job_safe가 래퍼 스크립트를.agents/skills/...트리 내부에.tmp로 복사하여 버전 관리 트리를 오염시키고 rsync 배포 시 외부로 유출됩니다.
B-7: run_loop.sh 상대경로 cwd 의존 및 미추적 파일 누락
- 저장소 루트 밖에서
run_loop.sh구동 시wait_for_job이 3900초 무음 타임아웃을 발생시키며,git diff가 Creator가 새로 추가한 미추적 신규 파일을 리뷰어에게 누락합니다.
B-8: send_keys_safe agy 경로 검증 이탈
- agy 세션 주입 시 주입 실패 여부를 검증하지 않고 무조건
return 0을 남겨 실패 시에도 성공으로 보고됩니다.
B-9: LOGS_DIR import 시점 cwd 고정
mqtt_common.py모듈 로드 시점의 cwd로 감사 로그 경로가 1회 고정됩니다.
3. 🟡 오케스트레이션 최적화 과제 (Orchestration Optimizations — 3건)
O-1 (구 ISSUE-6): 타당하지 않은 리뷰 피드백 거부/반론 프로토콜 미지원
- 현상:
MULTI_AGENT_RULES.md1장 규약에는 "개발 팀장이 리뷰어의 타당하지 않은 피드백을 거부하고 명확한 이유를 회신할 수 있다"고 명시되어 있음. - 문제점:
run_loop.sh는 리뷰어의NOT PASS피드백 전체를 Creator에게 일방적으로 주입할 뿐, Creator가 특정 피드백을 거부하거나 반론을 제기하여 상호 조율하는 이의제기 채널이 코딩적으로 구현되어 있지 않음. - 해결 방안: Creator 교정 단계 프롬프트에 반론 작성 템플릿을 허용하고, 반론 발생 시 Planner/Reviewer에게 재검토를 요청하는 이의제기 브랜칭 로직 설계.
O-2 (구 ISSUE-7): 동일 워크스페이스 내 중복 루프 기동 방지 락 (Race-Free Lock)
- 현상: 동일 작업 트리에서 다수의
run_loop.sh스크립트가 병렬 기동될 경우 SQLite DB 갱신 경합 및 YAML 데이터 오염이 일어날 수 있음. - 문제점: 단순 PID 파일 존재 여부만 체크할 경우, PID Rollover(프로세스 ID 재사용) 또는
mkdir과 PID 기록 사이의 생성 창(Grace Window)에서 살아있는 락을 타 프로세스가 훔쳐가는 "락 도난(Live-lock theft)" 현상 발생. - 해결 방안:
- 락 소유자 레코드를 단순
PID에서PID + 시작시각(lstart) + 워크스페이스3중 구조로 결합하여 PID 재사용을 결정적으로 차단. mkdir직후 생성 창 유예 대기(Sleep Grace Period)를 부여하여 락 도난 방지.psCLI 부재 시 Fails-Open(락 무시) 대신 Fails-Safe(락 존중 + 경고) 로 전환하여 DB/YAML 오염 원천 방지.
- 락 소유자 레코드를 단순
O-3 (구 ISSUE-9): 조건부 오케스트레이션 위임 가드 (Invocation-Aware Scoped Guard)
- 현상: 오케스트레이터(Antigravity)가 평상시에는 Main Creator로서 코드 및 문서를 직접 집필해야 하지만,
/multi-agent-mux-loop슬래시 커맨드/스킬이 인보크된 상황에서도 이를 인지하지 못하고 에이전트들에게 위임하는 대신 직접 수정을 시도하는 지침 이탈 발생. - 해결 방안:
- 평상시 (일반 요청): 오케스트레이터가 Main Creator로서 소스 및 마크다운 파일 직접 작성/수정 도구(
write_to_file,replace_file_content)를 자유롭게 사용하여 단독 구현 수행. /multi-agent-mux-loop호출 시 (스킬 활성화 상태): 스킬 인터셉터 가드(Guardrail)가 작동하여 직접 수정 도구 호출을 거부(Interception)하고, **"슬래시 커맨드가 인보크되었으므로 직접 수정을 중단하고run_loop.sh를 실행하여 위임하십시오"**라는 에러를 반환해run_loop.sh자율 위임 실행을 코딩적으로 강제.
- 평상시 (일반 요청): 오케스트레이터가 Main Creator로서 소스 및 마크다운 파일 직접 작성/수정 도구(
4. ⚪ 레거시 잔재 및 죽은 코드 (Legacy Remnants — 5건)
C-1: Kanban 문서 29회 언급 vs 실제 구현 0건
- SKILL.md 파일들에 Kanban 지원 및 상태 파일 서술이 29회 언급되어 있으나 스크립트 구현은 0건입니다.
C-2: 미사용 .cache/ 상태 디렉터리 생성
reconcile.sh가.cache/multi-agent-mux-monitor디렉터리를mkdir만 하고 아무것도 읽거나 쓰지 않습니다.
C-3: 격리 스텁 4종 및 stop_session.sh 미사용 isolation 코드 잔존
provision_isolation등 4개 스텁 함수와stop_session.sh내.mam/agent_homes가드 코드가 호출자 0건인 채 잔존합니다.
C-4: 참조 0회 미사용 심볼 7종
_HERDR_SHIM_DIR_PATTERN,_REAL_HERDR_PATH,TERMINAL_STATUSES,ISOLATE,local_herdr등 7개 미사용 심볼이 잔존합니다.
C-6: stop_session.sh 도움말 문서 구버전 표기
- 스크립트 도움말에는
--mode soft|hard등이 서술되어 있으나 실제 옵션 파서는exit 2로 거부합니다.
5. 결론 및 향후 보완 로드맵
두 문서가 OPTIMIZATION.md 하나로 통합됨에 따라, 향후 코드베이스 개편 시 본 문서의 19가지 백로그 항목(아키텍처 3건, 엣지케이스 8건, 오케스트레이션 3건, 레거시 잔재 5건)을 일원화된 보완 로드맵으로 관리합니다.