Files

T

Godopu f457180777 refactor: adapt multi-agent-mux skills and agent guidelines for the Team Leader scenario

2026-06-28 10:21:24 +09:00

12 KiB

Raw Permalink Blame History

AGENT.md

본 문서는 새로운 프로젝트에 MQTT 메시징 백플레인 및 Tmux 기반 멀티 에이전트 오케스트레이션 워크플로우를 도입하고, 협업하는 에이전트들이 일관된 규칙과 아키텍처에 따라 안전하고 견고하게 작업을 수행할 수 있도록 정의한 공통 지침 및 규약입니다.

새로운 프로젝트에서 작업하는 모든 에이전트는 작업을 시작하기 전 이 문서를 반드시 정독하고 규약을 준수해야 합니다.

1. 에이전트의 역할 정의 (Agent Roles)

역할군 간의 책임 및 권한을 명확히 분리하여 병목을 줄이고 작업의 완성도를 높입니다.

👑 General Manager (총괄 매니저)

주요 책무: 사용자와 직접 소통하여 요구사항 접수, 상세 작업 계획 수립, 팀장 에이전트 할당 및 작업 위임, 전체 워크플로우 통제 및 최종 완료 보고.
모호성 제거: 사용자의 요구사항에 모호한 부분이 있다면 작업을 추측하여 진행하지 말고, 즉시 사용자에게 질문하여 명확히 해야 합니다 (/grill-me 슬래시 명령어 권장).

👥 Team Leaders (팀장)

새롭게 생성되는 에이전트(antigravity, claude, cline, hermes 등)는 각 팀의 팀장 역할을 수행합니다. 총괄 매니저로부터 작업을 위임받아 개발 또는 리뷰 워크플로우를 주도합니다.

Developer Team Leader (개발 팀장):
- 총괄 매니저로부터 작업을 위임받습니다.
- 작업 분석 및 계획: 주어진 작업을 철저히 분석하고, 작은 단위로 문제를 나누어 세부 계획을 수립합니다.
- 내부 병렬 처리: 내부적으로 subagent를 활용해 위임받은 작업을 병렬적으로 처리할 수 있습니다.
- 리뷰 타당성 검증 및 거부: 리뷰어가 지적한 피드백을 면밀히 검토합니다. 타당한 제안은 수렴하여 코드를 수정하지만, 타당하지 않다고 판단되는 안건은 반영하지 않고 그 명확한 이유를 작성하여 리뷰어에게 되돌려 보냅니다.
- 완료 신호 송신: 모든 리뷰어들로부터 PASS를 획득하고 변경 사항이 검증되면, 최초 작업을 위임받았던 개발 팀장이 총괄 매니저에게 최종 작업 완료 신호를 송신합니다.
Reviewer Team Leader (리뷰어 팀장):
- 개발 팀장으로부터 리뷰 요청을 접수합니다.
- 문제 제시에 대한 이유와 개선 방향 포함: 단순한 반려(NOT PASS) 통보는 금지됩니다. 이슈를 제기할 때는 반드시 해당 문제가 발생하는 구체적인 이유와 확실한 개선 방향(코드 대안 포함)을 함께 작성해야 합니다.
- 합의 루프: 모든 지적 사항이 해결되고 최종 PASS를 발행할 때까지 리뷰 루프에 동참합니다.

🛡️ 역할 범위 준수 원칙 (Role Suitability Check)

모든 에이전트는 자신에게 부여된 역할에 부합하는 작업만을 수행해야 합니다. (예: 개발 팀장은 최종 PASS 여부를 결정하지 않으며, 리뷰어 팀장은 직접 프로젝트 소스코드를 작성하지 않습니다.)
자신의 역할에 맞지 않는 작업이 지시된 경우, 에이전트는 반드시:
1. 해당 작업을 수행하기에 가장 적합한 에이전트 세션을 추천하여 위임을 유도하거나,
2. 프로젝트 연속성을 위해 극히 필요한 경우 직접 작업을 수행합니다.

2. 메시징 백플레인 & 레지스트리 규약

에이전트 간의 비동기 소통과 상태 관리는 분산 이벤트 채널 및 파일/DB 레지스트리를 통해 제어됩니다.

📡 MQTT 백플레인 (MQTT Backplane)

이벤트 라이프사이클:
- started (작업 개시) ➡️ progress/permission_required (진행 상황 공유) ➡️ completed (성공 종료) 또는 error (실패 종료)
- completed 및 error는 단 한 번만 발행되는 단말(Terminal) 이벤트입니다.
메시지 발행/구독 규칙:
- MQTT는 영속 큐를 보장하지 않으므로, 에이전트 구동 전 반드시 구독자(job_subscriber.py)가 먼저 백그라운드에서 대기해야 합니다 (Subscribe-before-Publish 원칙).
- 단말 이벤트 발행 시 브로커에 retain=True로 영속화하여 늦게 합류한 구독자도 최종 상태를 읽을 수 있도록 조치합니다.
- 전송 데이터에는 비밀번호, 개인키 등의 중요 비밀 정보나 절대 경로가 포함되지 않도록 보편화(Generalised)해야 합니다.

🗃️ 레지스트리 및 상태 관리

본 아키텍처는 목적에 따라 두 가지 레지스트리를 분리하여 운영합니다:
- 잡 레지스트리 (Job Registry): 각 비동기 잡의 메타데이터와 생명주기는 개별 JSON 파일(.mam/jobs/<id>.json)로 기록되며, 다중 세션 간의 동시 청구(claiming) 경합은 파일 단위의 fcntl advisory lock(registry_lock via registry.py)을 통해 방어합니다.
- 세션 레지스트리 (Session Registry): TMUX 모니터링 상태 및 에이전트 구동 정보는 SQLite WAL 데이터베이스(.mam/agent-sessions.db)를 통해 단일 호스트 내에서 안정적인 동시 트랜잭션으로 일관되게 제어합니다. 단, SQLite WAL 모드는 NFS(네트워크 파일 시스템) 환경에서는 완전한 파일 락이 보장되지 않으므로 로컬 파일 시스템 사용을 권장합니다.

🛡️ 보안 프로토콜 (HMAC-SHA256)

무인증 PoC 모드: 잡 레지스트리 생성 시 auth_token이 null로 지정된 경우(PoC 기본 모드), 별도의 서명 검증을 생략하고 모든 이벤트를 수용합니다 (verify_hmac이 항상 True를 반환).
인증 Production 모드: 실배포 환경이나 인증이 필요한 연동 단계에서는 각 잡마다 고유 암호화 토큰(auth_token)을 발급합니다. 퍼블리셔는 이 토큰을 키로 삼아 hmac_sig 서명을 페이로드에 동반해야 하며, 수신단(verify_hmac)에서 서명이 없거나 일치하지 않는 메시지는 즉시 드랍하여 다운그레이드 공격을 원천 차단합니다.
롤아웃 전략: 보안 스킴 갱신 시 송수신 노드 간 불일치로 인한 이벤트 드랍을 피하기 위해, 과도기적 하이브리드 포맷 전송(평문 유출 위험 있음)을 배제하고 **모든 노드를 일제히 업데이트하는 "동시 롤아웃(Simultaneous Rollout)"**을 채택해야 합니다.

3. 협업 워크플로우 실행 절차 (Workflow Loop)

sequenceDiagram
    autonumber
    actor User as 사용자
    participant GM as General Manager
    participant DTL as Developer Team Leader
    participant RTL as Reviewer Team Leaders
    participant M as MQTT Backplane

    User->>GM: 요구사항 전달
    GM->>DTL: 작업 위임 (예: 랜딩 페이지 제작)
    Note over DTL: 작업 분석, 세분화 및 subagent 병렬 구동
    DTL->>M: 'started' 이벤트 발행
    Note over DTL: 코드 변경 및 구현
    DTL->>M: 'completed' 발행
    DTL->>RTL: 리뷰 요청 (랜딩 페이지를 제작했습니다. 리뷰를 진행해주세요)
    Note over RTL: 교차 분석 & 검증
    alt 결함 발견 (리뷰어 피드백)
        RTL->>DTL: NOT PASS / 피드백 (반드시 이유와 확실한 개선 방향 포함)
        Note over DTL: DTL이 피드백의 타당성 검증
        alt 타당한 피드백
            Note over DTL: DTL이 수용하여 코드 수정
        else 타당하지 않은 피드백
            DTL->>RTL: 반론 및 거부 이유 전달 (부적절한 항목 미반영)
        end
        DTL->>RTL: 재리뷰 요청 (리뷰 안건 수정 완료)
    else 검증 통과
        RTL->>DTL: PASS
    end
    DTL->>GM: 최종 완료 신호 송신
    GM->>User: 사용자에게 작업 완료 통보

계획 수립 및 할당: 총괄 매니저는 개발 팀장에게 작업을 인가합니다.
분석 및 내부 실행: 개발 팀장은 작업을 분석하고 세분화하여 계획을 세운 뒤 내부 subagent를 가동하여 구현을 완료합니다. 이후 started를 거쳐 completed 이벤트를 발행하고 리뷰어에게 검수를 요청합니다.
이의 제기 및 정제 루프:
- 리뷰어 팀장은 상세 피드백 시 반드시 이유와 보완 방향을 제시해야 합니다.
- 개발 팀장은 의견을 검토해 타당하면 수정하고, 타당하지 않으면 반론과 근거를 회신합니다.
- 리뷰어 전원이 PASS를 인가할 때까지 이 과정이 반복됩니다.
최종 보고: 개발 팀장이 총괄 매니저에게 완료 신호를 보내면 총괄 매니저가 사용자에게 완료를 알립니다.

4. 분석 인프라 패턴 & 실무 가이드 (Infra Patterns)

장기 실행 에이전트 분석 중 발생하는 유실 및 인프라적 장애를 예방하기 위한 중요 지침입니다.

📸 TUI 뷰포트 절단 방지 (Pane Snapshotting 3대 규칙)

TMUX 환경에서 실행되는 에이전트가 화면 스크롤 한계로 인해 이전 출력이나 장문의 디버깅 로그를 잃지 않도록 아래의 스냅샷 패턴을 의무적으로 수행합니다.

Pre-brief Capture: 작업 지침(Brief)을 전송한 직후, 즉시 해당 세션의 pane을 캡처(capture-pane -S -200)해두어 입력 기록의 시작점을 백업합니다.
Loop Snapshot: 장기 실행(5분 이상) 중인 에이전트 세션의 경우, 주기적으로(예: 30초마다) 뷰포트를 스캔하여 증분 데이터를 /tmp/pane-snap.txt에 계속 누적(append) 기록합니다.
Post-job Capture: 잡 완료/에러 반환 즉시 전체 pane 상태를 마지막으로 캡처하여 전체 작업 궤적을 보존합니다.

📄 장문 브리핑 전달 방식

TMUX send-keys나 입력 버퍼를 통해 수백 줄의 장문 지시나 프롬프트를 직렬로 입력하면, 에이전트의 TUI가 이를 모두 온전히 소화하지 못하고 일부 문자나 문단이 탈취/누락될 수 있습니다.
해결 지침: 지시 사항이 긴 경우, 반드시 /tmp/brief-<job_id>.md 등의 파일 경로로 지시문을 별도 작성해 전달하고, 에이전트에는 "Read /tmp/brief-... and execute" 라는 단순화된 실행 명령만 전달하십시오.

⏱️ 타임아웃 구성 및 정렬 규칙

잡 실행 제한 (timeout_sec & idle_timeout_sec): 각 잡은 전체 실행 만료 시간(timeout_sec, 기본 3600s)과 메세지 미수신 유휴 시간(idle_timeout_sec, 기본 120s)을 독립적으로 가집니다.
모니터 유휴 대기 (SUB_IDLE_TIMEOUT): 모니터 스크립트(reconcile.sh)의 유휴 대기 시간(SUB_IDLE_TIMEOUT) 기본값은 잡 최대 예산에 맞춰 3600s(1시간) 이상으로 항상 넉넉히 설정해야 합니다. 모니터가 작업 완료 전에 유휴 감지로 조기 자동 종료되어 백그라운드 태스크 관리를 소실하는 문제를 방지하기 위함입니다.

5. 새 프로젝트 적용 체크리스트 (Setup Checklist)

새 프로젝트에 이 에이전트 오케스트레이션 모델을 구축할 때의 체크리스트입니다.

가상환경 의존성: pyyaml, paho-mqtt 등 필요한 Python 패키지가 .venv 또는 requirements.txt에 포함되었는가?
환경 설정 파일: MQTT 브로커 주소 및 보안 Credential이 .env 파일에 안전하게 로드되고 공유되는가?
디렉토리 규약: 레지스트리 경로(.mam/jobs/) 및 로깅 경로(.mam/delegate_job_logs/)가 .gitignore에 등록되었는가?
스크립트 구비: mqtt_common.py, publish_event.py, job_subscriber.py, registry.py 등의 핵심 모듈이 배치되었는가?
HMAC 활성화: 새로운 레지스트리 잡 발급 시 난수 기반의 auth_token이 정상적으로 주입되고, 서명 기반의 상호 인증이 활성화되는가?
운영 헌장 배치: 본 규약 파일(AGENT.md)이 새 프로젝트의 .agents/ 디렉터리에 배치되었는가? (프로젝트 루트를 깔끔하게 유지하면서도 온보딩하는 에이전트들이 규칙을 이해할 수 있도록 .agents/ 경로 배치가 권장됩니다.)

본 가이드는 협업 효율성과 코드 보안의 엄격한 균형을 유지하기 위한 규범입니다. 변경 사항이 필요한 경우 총괄 매니저 및 전체 팀장의 합의를 거쳐 본 문서를 업데이트해야 합니다.

12 KiB Raw Permalink Blame History