[보고서] MAM 위임 도구의 역할(Role) 지정 옵션 누락 이슈 분석

본 문서는 멀티 에이전트 오케스트레이션 프레임워크(multi-agent-mux)의 핵심 CLI 도구인 multi-agent-mux-delegate-job에서 세션의 역할(Role)을 지정할 수 있는 옵션이 누락되어 발생하는 정합성 충돌 문제와 이에 대한 원인 분석 및 해결 방안을 정의합니다.

1. 문제가 발생한 정확한 상황 (Context)

프로젝트 개발을 오케스트레이션하는 과정에서 아래와 같은 에이전트 간 역할 분담을 적용하고자 했습니다.

개발 팀장 (Antigravity): 실제 저장소의 문서 수정 및 구현 진행 (Worker/Implementer)
리뷰 에이전트 (Claude): 문서 구조의 설계 및 계획안 수립 (Planner)

이 분담에 따라 Claude 세션(canary-projects-grpccanary-creator-claude)에 "문서 모듈화 계획 및 체크리스트 작성" 작업을 위임하기 위해 multi-agent-mux-delegate-job 도구로 비동기 작업을 요청했습니다.

그러나 자동 생성된 잡 지시서인 .mam/jobs/<job_id>/brief.md 파일의 메타데이터에 다음과 같이 구현자의 역할이 Worker로 강제 지정되어 나가는 상황이 발생했습니다:

# 📋 Brief: Job ed31b5fb Delegation

- **Job ID**: ed31b5fb
- **Target Agent**: claude (session: tmux:canary-projects-grpccanary-creator-claude)
- **Role**: Worker  <-- [이슈 발생 지점: Planner가 아닌 Worker로 강제 지정됨]
- **Timeout**: 3600 s (Idle: 120 s)

이는 프로젝트 협업 규칙(.agents/MULTI_AGENT_RULES.ko.md)에 명시된 **"에이전트 역할 범위 준수 원칙(Role Suitability Check)"**에 위배되며, claude가 문서 작성이 아닌 파일 직접 수정을 시도할 위험이 있는 정합성 모순을 유발합니다.

2. 문제 사유 (Root Cause)

이 문제의 근본적인 기술적 원인은 CLI 인수 파싱 로직 및 지시서(Brief) 생성 템플릿의 하드코딩에 있습니다.

CLI 옵션 설계 누락:
- multi-agent-mux-delegate-job submit 명령어의 헬프 스펙을 확인한 결과, --agent, --agent-session, --prompt 등의 인수는 정의되어 있으나, 작업의 논리적 성격을 조율하는 --role <role_name> 파라미터가 구현되어 있지 않습니다.
템플릿 내부의 상수 고정:
- API를 통해 비동기 잡이 수임될 때 생성되는 brief.md 파일과 잡 레지스트리 JSON의 생성기 로직 내부에 Role 값이 Worker 문자열 상수로 하드코딩되어 동작하고 있습니다. 이로 인해 어떤 에이전트에 어떤 종류의 명령을 위임하더라도 메타데이터상으로는 항상 Worker로 바인딩됩니다.

3. 문제 해결 방법 (Remediation & Workarounds)

3.1 단기적 우회 방법 (Workaround)

프레임워크 CLI 소스코드를 수정하기 어려운 제한적 상황에서는 프롬프트 페이로드(Prompt Payload) 하드닝 기법을 사용하여 에이전트의 오작동을 차단합니다.

해결 원리: brief.md의 메타데이터상 Role: Worker 지정을 덮어쓸 수 있도록, 프롬프트 문맥 내부에 **"너의 역할은 실제 문서를 수정하지 않고 계획만 수립하는 Planner이다. 절대 문서를 직접 수정하지 말라"**는 강력한 지시 제약(System-level Rule Override)을 포함하여 송신합니다.
효과: AI 에이전트는 메타데이터보다 프롬프트 지시어의 행위 제약을 우선 순위로 받아들이므로, 의도한 대로 설계서 및 계획안만 수립하는 Planner 동작을 정상 수행하게 됩니다.

3.2 근본적인 해결 방법 (Remediation)

프레임워크의 CLI 래퍼인 multi-agent-mux-delegate-job 파일의 파싱 로직 및 brief.md 빌더 로직을 다음과 같이 수정합니다.

1단계: CLI 인수 파서 수정 (`submit` 옵션 추가)

스크립트의 인수 파싱 영역에 --role 파라미터를 식별할 수 있는 변수 및 분기 로직을 선언합니다.

# 옵션 분석 루프 예시
while [[ $# -gt 0 ]]; do
  case $1 in
    --role)
      DELEGATE_ROLE="$2"
      shift 2
      ;;
    # ... 기존 옵션 파싱 ...
  esac
done

# 기본값 정의
DELEGATE_ROLE="${DELEGATE_ROLE:-Worker}"

2단계: `brief.md` 생성 템플릿 연동

잡 디렉토리 내에 brief.md를 기입하여 내보내는 빌더 영역(Python 혹은 쉘 스크립트 에코 영역)을 다음과 같이 동적 변수와 연결합니다.

- echo "- **Role**: Worker" >> "$BRIEF_PATH"
+ echo "- **Role**: ${DELEGATE_ROLE}" >> "$BRIEF_PATH"

3단계: 잡 레지스트리 JSON 메타데이터 갱신

동일하게 생성되는 .mam/jobs/<job_id>.json 파일 등의 메타데이터 생성 객체 내에 role: DELEGATE_ROLE 매핑 키를 추가하여, 타 모니터링 도구(예: reconcile.sh 및 status.sh)에서도 해당 에이전트의 잡 실행 역할을 정확하게 대시보드에 모니터링할 수 있도록 보완합니다.

5.0 KiB Raw Blame History