Files

T

Godopu c68852b8e3 docs: add FUTURE_WORKS.md — 3-agent deep analysis results (FW-01~FW-16)

2026-06-21 06:15:08 +00:00

20 KiB

Raw Blame History

FUTURE_WORKS.md

목적: advanced_multi_agent 프로젝트의 향후 작업 후보를 추적한다. 출처: 2026-06-21 3개 코딩 에이전트 병렬 분석 (agy-existing, agy-new, claude-existing) brief: /tmp/deep-analysis-brief.md (12개 항목)

0. 메타데이터

항목	값
분석 일시	2026-06-21 (Sun) 03:52 ~ 05:48 KST
brief 커밋	`50b2b20 refactor(skills): rename tmux-agent-orchestrate-delete -> stop (step 1)` 직후
워크스페이스	`/home/godopu16/PuKi/laa/canary_projects/advanced_multi_agent`
분석 도구	tmux `-L multi-agent-canary` 격리 서버 위 3개 세션
모델	agy-existing: Gemini 3.5 Flash (High) · agy-new: Gemini 3.1 Pro (High) · claude-existing: Claude Opus 4.8
분석 wall-clock	agy-existing ~6min · agy-new ~5min · claude-existing ~4min (3m 51s reported)
본문 추출 범위	10~12번 항목만(개선점 + 기술부채). 1~9번(프로젝트 목표/스킬 분석)은 pane scrollout으로 미수복.

추출 상태 보고

| agy-existing | 마지막 응답 캡처 성공 (10·11·12번, 102줄) | | ✅ agy-new | 풀 보고서 보존 — /tmp/agy-new-final-report.txt (215줄, A~~D 1~~12번 + 종료선 전부) | | ⚠️ claude-existing | 초기 응답 단편(38줄, ##12) 캡처 → subagent가 재요청으로 풀 보고서 회수 — /tmp/claude-existing-report-reprint.md (129줄, 1~12번 전부) |

→ 본 문서는 agy-new의 풀 보고서를 SSOT(Single Source of Truth)로 사용하고, claude 재출력 보고서를 §6(3-way 합의 보강)에 cross-validate. 1~9번 영역은 §4(agy-new 보고서 발췌)에 보존됨.

1. 합의된 개선점 (3개 에이전트 교차 검증)

각 항목의 인용 수는 3개 에이전트 중 몇 명이 지적했는지를 나타낸다.

🔴 FW-01. MQTT subscriber 자동 재연결 부재 (3/3 합의)

출처: agy-existing(개선점 2, 우선순위 높음), agy-new(개선점 2), claude-existing(간접 — ack 빈도 안정성)
문제: job_subscriber.py 메인 루프가 일시적 네트워크 단절 시 즉시 종료. 에이전트가 오케스트레이터로부터 고아(orphaned) 상태가 됨.
영향 범위: skills/tmux-agent-orchestrate-delegate-job/scripts/job_subscriber.py
해결 방안:
- paho-mqtt의 on_disconnect 콜백 + 지수 백오프(exponential backoff)
- 재접속 성공 시 --expect-retention 옵션으로 retained terminal 이벤트 즉시 조회
작업량: 소 (Small)
근거 파일: skills/tmux-agent-orchestrate-delegate-job/scripts/job_subscriber.py:165-174 (on_connect/connect)

🔴 FW-02. NFS/네트워크 파일시스템 환경에서 flock 락 취약 (3/3 합의)

출처: agy-existing(개선점 1, 우선순위 높음), agy-new(개선점 2, "구조 확장성")
문제: atomic_dump_yaml의 동시성 잠금이 로컬 fcntl.flock에 의존. NFS/NAS 환경에서 락 무시 → 레지스트리 손상 위험.
영향 범위: skills/lib.sh의 atomic_dump_yaml, skills/tmux-agent-orchestrate-delegate-job/scripts/registry.py:55의 timeout_sec: int = 600 인접 영역
해결 방안:
- 단기: 락 파일 명시적 에러 핸들링 + 사용자 경고
- 장기: SQLite WAL(Write-Ahead Logging)로 마이그레이션
작업량: 중 (Medium) — 단순 패치가 아닌 데이터 레이어 교체 검토
근거 파일: skills/lib.sh (atomic_dump_yaml)

🟡 FW-03. delete/stop 명칭 잔재 + 산문/주석 drift (2/3 합의 + 1/3 [추측])

출처: agy-new(##12, "잔재된 단어의 찌꺼기"), claude-existing(##12, "이름/의미 불일치", [추측])
문제: 50b2b20에서 tmux-agent-orchestrate-delete → stop rename 완료했으나:
- Messaging_System_REPORT.md 본문에 terminate/delete 용어 잔존
- skills/tmux-agent-orchestrate-create/SKILL.md:25 주석에 create/resume/delete/status/monitor 옛 이름 잔존 가능 ([추측])
- 옵션 명세(--purge-conversation, --mode soft|hard)는 delete 시맨틱 유지
영향 범위: 보고서 + SKILL.md 주석 + 옵션 시맨틱
해결 방안:
- grep -rn -E '(delete|terminate|terminated|kill)' --include='*.md' skills/ 일괄 점검
- 산문에서 옛 의미 단어를 모두 stop으로 치환 (단, --purge-conversation은 의도적 단어로 보존 — 사용자 확인 필요)
- Step 2 작업의 일부로 흡수 가능
작업량: 소 (Small)
근거 파일: Messaging_System_REPORT.md, skills/tmux-agent-orchestrate-create/SKILL.md:25

🟡 FW-04. 환경변수 오버라이드 경로 분절화 (2/3 합의)

출처: agy-new(##12, "암시적 환경변수 오버라이드 분절화")
문제: 래퍼 셸 스크립트는 .env를 보고, mqtt_common.py는 OS 환경변수를 직접 조회. export 누락 시 로드 경로 불일치 버그.
영향 범위: 래퍼 셸 스크립트 전체 + skills/tmux-agent-orchestrate-delegate-job/scripts/mqtt_common.py
해결 방안:
- 진입점(예: delegate-job submit)에서 .env를 강제 로드하는 단일 함수 도입
- 또는 mqtt_common.py에서도 dotenv 패턴 사용 (python-dotenv 의존성 추가)
작업량: 소 (Small) ~ 중 (Medium)
근거 파일: skills/tmux-agent-orchestrate-delegate-job/scripts/mqtt_common.py

🟡 FW-05. Public Broker 환경에서 auth_token 평문 노출 (1/3 합의, 1/3 강조)

출처: agy-new(개선점 3, 우선순위 높음, 보안)
문제: PoC(HiveMQ 공용 브로커) 환경에서 auth_token이 평문 전달 → 도청·이벤트 인젝션 위험.
영향 범위: publish_event.py, job_subscriber.py
해결 방안: HMAC-SHA256 서명 도입 (토큰 자체는 평문, 이벤트 페이로드에 서명 첨부)
작업량: 중 (Medium)
근거 파일: skills/tmux-agent-orchestrate-delegate-job/scripts/registry.py:55 (auth_token 정의), Messaging_System_REPORT.md §1.1(PoC 보안 위험)

🟡 FW-06. 에이전트 초기 기동 에러 MQTT 전파 결함 (1/3 합의)

출처: agy-existing(개선점 3, 우선순위 보통)
문제: 에이전트 쉘 기동 시 syntax error·패키지 부재 등 즉각적 예외가 MQTT error 채널로 안 가서 오케스트레이터가 timeout(exit 2)까지 대기.
영향 범위: delegate-job submit의 에이전트 부트스트랩 셸
해결 방안: 셸 진입 시 trap ... ERR + publish_event.py --event error 강제 발행하는 부트스트랩 래퍼.
작업량: 중 (Medium)
근거 파일: skills/tmux-agent-orchestrate-delegate-job/SKILL.md

🟢 FW-07. lib.sh `_resolve_real_tmux_path`의 하드코딩 경로 (1/3 합의)

출처: agy-existing(##12 #1)
문제: _resolve_real_tmux_path 함수 안에 /multi-agent-tmux-shim/, /skills/.bin 경로 문자열 하드코딩.
영향 범위: skills/lib.sh:32 부근
해결 방안: 상수 정의로 추출 + 동적 감지.
작업량: 소 (Small)
근거 파일: skills/lib.sh

🟢 FW-08. `_delegate_py_bin` 매 호출마다 디스크 검색 (1/3 합의)

출처: agy-existing(##12 #3)
문제: .venv/bin/python을 매 호출마다 상위 경로 디스크 검색 → 불필요한 I/O.
영향 범위: skills/lib.sh의 _delegate_py_bin
해결 방안: 환경변수(AGENT_PYTHON_BIN)로 캐싱.
작업량: 소 (Small)
근거 파일: skills/lib.sh

🟢 FW-09. YAML 비정형 status 코멘트 혼재 (1/3 합의, [추측])

출처: agy-existing(##12 #2, [추측])
문제: last_visible_status에 auto-registered 같은 임의 코멘트 → 파서 혼란 가능 ([추측]).
영향 범위: 모니터 스크립트 status 갱신 경로
해결 방안: 상태 코드 enum 정의 + 코멘트는 별도 필드(last_visible_note).
작업량: 소 (Small)
근거 파일: 모니터 SKILL.md

🟢 FW-10. 상태값/문서 표류 (1/3 합의, [추측])

출처: claude-existing(##12, [추측])
문제: 코드 검증셋(lib.sh:217)은 running/terminated/archived/stopped 4종. Messaging_System_REPORT.md:168-179의 잡 상태머신은 pending/running/completed/error/cancelled 5종. 두 도메인이 섞여 문서 표류 가능 ([추측]).
영향 범위: 도큐먼트 + lib.sh status enum
해결 방안: 두 도메인(세션 상태 vs 잡 상태)을 명시적으로 분리하고 glossary 섹션 추가.
작업량: 소 (Small)
근거 파일: lib.sh:217, Messaging_System_REPORT.md:168-179

🟢 FW-11. 인터프리터 분리 부채 (1/3 합의, [추측])

출처: claude-existing(##12, [추측])
문제: .venv는 paho-mqtt만, 시스템 python3는 yaml만 → monitor --subscribe는 venv, YAML 쓰기는 시스템 python 위임 ([추측]). 단일 인터프리터에 둘 다 설치하면 단순화 가능 ([추측]).
영향 범위: requirements.txt 또는 셋업 스크립트
해결 방안: 의존성 통합 + 둘 다 포함하는 단일 venv 강제.
작업량: 소 (Small)
근거 파일: .venv/, 시스템 python3 의존성

🟡 FW-13. stop SKILL.md frontmatter description이 delete 시절 문구 그대로 (1/3 합의, 매우 시급)

출처: claude-existing(11-1, 우선순위 높음 · 작업량 소 · 문서신뢰)
문제: skills/tmux-agent-orchestrate-stop/SKILL.md의 description이 여전히 "Terminate … mark it terminated … Does NOT delete on-disk" 식의 옛 문구. 본문 16회 "terminated" 잔존.
영향: LLM 라우팅 정확도(description으로 스킬 선택) + 사용자 혼란.
해결 방안: Step 2와 함께 description + 산문을 stopped 중심으로 재작성.
작업량: 소 (Small)
근거 파일: skills/tmux-agent-orchestrate-stop/SKILL.md frontmatter + 본문

🟡 FW-14. REPORT.md 미커밋 rename으로 작업 트리 더러움 (1/3 합의)

출처: claude-existing(11-2, 우선순위 높음 · 작업량 중 · 미완결상태)
문제: git status = D REPORT.md + ?? Messaging_System_REPORT.md. rename이 git mv가 아니라 단순 mv였음. 권위 문서가 모호.
영향: 협업/리뷰 혼란, "어느 게 사양서?"
해결 방안: git mv Messaging_System_REPORT.md REPORT.md && git commit 또는 명시적 삭제.
작업량: 소 (Small)
근거 파일: 작업 트리 상태

🟡 FW-15. monitor `--subscribe`의 wildcard MQTT 구독 + 자동 kill (1/3 합의, 보안)

출처: claude-existing(11-3)
문제: 기본값이 평문 공용 브로커(MQTT_BROKER=broker.hivemq.com:1883) + 평문 bearer 토큰. monitor --subscribe가 wildcard 구독 + 자동 kill까지 함 (과거 리뷰 식별).
영향: 공용 브로커 사용 시 이벤트 스푸핑 / 세션 원격 종료 가능.
해결 방안: HMAC 서명 + TLS 강제. monitor subscribe의 자동 kill은 화이트리스트 기반 매칭.
작업량: 중 (Medium)
근거 파일: Messaging_System_REPORT.md:310-311, 323-326

🟢 FW-16. 세션 상태(YAML)와 잡 상태(registry) 도메인 혼동 (1/3 합의, [추측])

출처: claude-existing(12)
문제: 코드 검증셋(lib.sh:217)은 running/terminated/archived/stopped. Messaging_System_REPORT.md:168-179의 잡 상태머신은 pending/running/completed/error/cancelled. 두 도메인이 다르다는 것을 문서가 명확히 구분 안 함.
영향: 운영 시 혼동, API/스킬 옵션 시맨틱 일관성 저하.
해결 방안: 도큐먼트 glossary 섹션 추가 + 두 도메인 명시적 분리.
작업량: 소 (Small)
근거 파일: lib.sh:217, Messaging_System_REPORT.md:168-179

2. 합의된 강점 (3개 에이전트 공통)

강점	출처	근거 파일
원자적 YAML 레지스트리(flock + validate + os.replace)	agy-existing(10-1)	`skills/lib.sh`
tmux shim 소켓 격리 (PATH prepend)	agy-existing(10-2)	`skills/lib.sh` (`TMUX_SERVER_NAME`)
3-Tier UUID Resolution (`find_workspace_uuid`)	agy-existing(10-3)	`skills/lib.sh`
워크플로우 A→B→C→D 통합 (squashed from delegate-job)	git log `0eb1d94`	`.git` 히스토리

(1~9번 항목 미수복으로 3-way 합의 강점 리스트는 불완전 — 추후 보강 필요)

3. 작업 우선순위 매트릭스

우선순위	항목	합의	작업량
🔴 매우 시급	FW-13 (stop SKILL frontmatter 잔존)	1/3 (claude, 강하게 강조)	소
🔴 높음 + 다수 합의	FW-01 (subscriber 재연결)	3/3	소
🔴 높음 + 다수 합의	FW-02 (flock NFS 취약)	3/3	중~대
🔴 높음 + 단독 합의	FW-05 (auth_token 평문)	1/3 (강조)	중
🟡 보통	FW-03 (delete 잔재)	2/3	소
🟡 보통	FW-04 (env 분절)	2/3	소~중
🟡 보통	FW-06 (초기 에러 전파)	1/3	중
🟡 보통	FW-14 (REPORT.md 미커밋 rename)	1/3	소
🟡 보통	FW-15 (monitor subscribe + 자동 kill)	1/3	중
🟢 낮음	FW-07 ~ FW-12, FW-16	1/3	소

권장 첫 스프린트 (소~중 작업량, 합의도/시급성 높은 것부터):

FW-14 REPORT.md rename 정규화 (git mv) — 즉시 가능, 작업 트리 클린업
FW-12 미커밋 잔재 정리 (test-sessions.yaml.bak 등) — 즉시 가능
FW-13 stop SKILL.md frontmatter/산문 재작성 — Step 2의 일부
FW-01 subscriber 재연결 — 작업량 작고 합의도 3/3
FW-05 auth_token HMAC 서명 — 보안, 합의 강조

**claude-only 신규 인사이트 (FW-13~16)**는 Step 2 작업(옵션 시맨틱 재정립) 시작 시 함께 흡수 권장. 특히 **FW-13(stop SKILL.md description 잔존)**은 즉시 처리 가능하고 라우팅 정확도에 직결.

4. agy-new 풀 보고서 발췌 (1~9번 영역 보강)

출처: /tmp/agy-new-final-report.txt (215줄) 캡처 시점: 2026-06-21 05:50 (첫 subagent가 추출, agy-new pane 응답이 종료되기 직전)

A. 프로젝트의 최종 목표 (Goal / Vision)

1. 달성하려는 사용자 시나리오

단일 tmux 환경 위에서 다수 자율 에이전트(Claude Code, Antigravity CLI 등)에게 병렬로 복잡한 장기 작업을 위임(Delegate) + 비동기 관찰(Fire-and-observe). 사용자는 터미널을 점유당하지 않고, 격리 서버에서 에이전트가 알아서 일하도록 한 뒤 작업 완료나 권한 필요 시 MQTT 이벤트 스트림으로 알림. (근거: skills/tmux-agent-orchestrate-delegate-job/SKILL.md:3-4)

2. 6개 스킬의 워크플로우 시퀀스

create — 빈 tmux 격리 세션 생성·등록
delegate-job — 프롬프트 위임 + MQTT 구독기 시작
monitor / status — 30초 주기 reconcile 또는 단발 조회
stop — 우아 종료(--capture-id 옵션으로 ID 보존)
resume — 디스크의 대화 ID로 컨텍스트 복원 (근거: 각 SKILL.md Companion skills, delegate-job Workflow)

3. 연구실/표준화 연구 연결성 [추측 포함]

QUIC/IoT 기반 멀티 에이전트 표준화 연구의 최소 기능 검증(Canary PoC). MQTT 단방향 이벤트 스트리밍 모델(Event-driven state machine)이 분산 에이전트들의 잡 라이프사이클 통합 관제에 적합한지 가설 검증.

4. 권위 있는 "사양서" 문서

아키텍처/시스템 사양: Messaging_System_REPORT.md (MQTT 브로커, 와이어 스키마, ACL, 보안)
에이전트 로컬 실행/세션 관리 사양: 6개 SKILL.md
상태 SSOT: .hermes/agent-sessions.yaml

B. 개발 내용 심층 분석

5. Messaging_System_REPORT.md 분석

와이어 스키마: schema_version=1, seq(단조 증가), job_id(8-hex), event ∈ {started,progress,permission_required,completed,error}, timestamp(ISO-8601 UTC), detail, data
잡 상태 머신: pending → running → completed|error(터미널, retain=True) → cancelled
ACL: 구독자(Hermes)=read, 에이전트=write, 토픽 python/mqtt/jobs/+/events
PoC vs Prod:
- PoC: broker.hivemq.com:1883, 인증/TLS 없음 — 도청·스푸핑 위험
- Prod: 자체 호스팅 Mosquitto/EMQX, :8883 TLS 1.3, username/password + persistence true — 코드 변경 없이 .env만으로 전환
알려진 한계: NFS fcntl 붕괴 → SQLite WAL, 토큰 평문 → HMAC, 구독자 끊김 → Auto-Reconnect

6. 6개 스킬 역할/입출력/의존성

create: tmux 격리 + YAML 등록
resume: 디스크 UUID로 tmux 부활
stop: tmux 종료 + YAML 갱신 (이력 보존)
status: 스냅샷 (drift 감지)
monitor: Kanban 워커 30초 reconcile
delegate-job: 비동기 위임 + MQTT 이벤트 관찰
agent-sessions.yaml: fcntl.flock + os.replace로 동시성 훼손 방지
tmux 격리: TMUX_SERVER_NAME 또는 -L 플래그, 글로벌 kill-server 보호

7. 환경변수 통합 제어

.env + generate-env.sh로 시스템 기본값 오버라이드
경로: AGENT_SESSIONS_YAML, CLAUDE_PROJECT_DIR, LOCAL_BIN
통신: TMUX_SERVER_NAME, MQTT_BROKER, MQTT_USERNAME, MQTT_TLS, MQTT_CA_CERTS
로컬 워크스페이스 세팅과 MQTT 클라우드 세팅 분리 → 잡별 주입 + 프로덕션 전환 무코드

8. `cd9eec1` 커밋 의미 (절대경로 → 상대경로/Env)

문제: 개발자 홈(/home/godopu16/PuKi/...) 하드코딩 → 다른 환경/CI 복사 시 즉시 고장
해결: BASH_SOURCE 기반 워크스페이스 동적 추론 + ${VAR:-default} env override
흔적: .env.example 기본값 패턴, lib.sh 동적 경로 파싱

9. `50b2b20` 커밋 의미 (rename `delete` → `stop`)

문제 의식: delete라는 명칭이 "영구 삭제/복구 불가" 오해 유발
실제 의도: tmux 컨테이너 우아 종료 + resume 가능 (대화 이력 보존)
Step 1: 디렉터리명/식별자만 rename (이미 커밋됨)
예상 Step 2:
- 옵션 직관성 재정립: --purge-conversation(진짜 삭제)과 --mode soft|hard 재정의 또는 폐기
- 하위 호환 코드 제거
- 산문/주석의 옛 명칭 잔재 정리

C. 코드/구조 품질 진단 (agy-new 평가)

10. 잘 된 점 Top 3

무결성 보장 동시성 모델 — fcntl 락 + 임시파일 os.replace 패턴으로 YAML/JSON 파손 방지
비침투 무중단 아키텍처 — PoC→Prod 전환 시 .env/Registry JSON만으로 설정 오버라이드
사용자 환경 격리 — TMUX_SERVER_NAME 소켓으로 사용자 터미널과 완전 분리

11. 시급 개선점 Top 3 (agy-new 발췌)

fcntl NFS 환경 붕괴 (구조 확장성, 작업량: 大) → SQLite WAL 전면 교체
Public Broker 평문 토큰 (보안, 우선순위 高) → HMAC-SHA256 서명 도입
Subscriber 재연결 부재 → Auto-Reconnect + 지수 백오프

D. 기술 부채 후보 (agy-new 발췌)

옛 명칭 잔재 (delete/terminate)
stopped 상태 추가로 인한 reconcile.sh Skip-set 비대화
.env(셸)와 OS env(python) 분기 — export 누락 시 버그

(agy-new 풀 본문은 /tmp/agy-new-final-report.txt 참조)

5. 분석 인프라 개선 권고 (다음 라운드 시)

근본 원인: pane TUI의 자체적인 위쪽 truncate + subagent의 pane 추출 시점 차이로 1~5번이 사라짐. 이번 차이점: agy-new는 첫 subagent가 brief 직후 빠르게 캡처해 215줄 풀 보고서를 보존함. agy-existing/claude-existing은 캡처 시점이 늦어 12번 단편만 남음.

다음 분석 시 권장 패턴:

brief 직후 capture-pane -S -200 즉시 캡처 → 누적 백업
응답 진행 중 30초마다 >> /tmp/pane-snap.txt 누적
"분석 종료" 직후에도 한 번 더 전체 캡처 (출력이 안정될 때까지)

6. 변경 이력

날짜	변경
2026-06-21	초기 작성 — 3개 에이전트 분석 결과를 3-way 합의 매트릭스로 정리
2026-06-21	§4 갱신 — `/tmp/agy-new-final-report.txt`(215줄)로 1~9번 영역 보강. SSOT를 agy-new로 확정. §5(분석 인프라 개선) 추가.
2026-06-21	§1·§3 갱신 — claude 재출력 보고서(`/tmp/claude-existing-report-reprint.md`) 기반 FW-13~16 신규 항목 추가. 우선순위 매트릭스에 FW-13(매우 시급) 포함. 권장 첫 스프린트 갱신.

20 KiB Raw Blame History