docs: update DRAFT_PLAN.md with problem definitions & gRPC justification, move agent rules to .agents/

2026-07-06 09:53:36 +09:00
parent 403793cbb9
commit ee9ae41195
29 changed files with 1294 additions and 2139 deletions
@@ -10,30 +10,50 @@

 본 프로젝트를 새로운 환경에 복제(Clone)한 후, 핵심 구성 요소들의 위치와 역할을 먼저 파악해야 합니다.

-*   `.agents/skills/`: 멀티 에이전트 구동 및 비동기 잡 처리를 수행하는 셸 스크립트 모음
-    *   `lib.sh`: 오케스트레이션의 핵심 셸 함수 및 가상환경(venv) 자동 연동 라이브러리
-    *   `multi-agent-mux-create/`: 격리된 tmux 에이전트 세션을 시작하는 스크립트
-    *   `multi-agent-mux-stop/`: 세션을 정상적으로 중지하고 상태를 업데이트하는 스크립트
-    *   `multi-agent-mux-resume/`: 중지된 에이전트 세션을 이전 대화 상태 그대로 복원하는 스크립트
-    *   `multi-agent-mux-status/`: 전체 에이전트 세션의 현재 구동 상태를 조회하는 스크립트
-    *   `multi-agent-mux-monitor/`: tmux 상태와 레지스트리 상태를 동기화하는 모니터 스크립트
-    *   `multi-agent-mux-delegate-job/`: 비동기 잡 분할 실행 모듈
-        *   `requirements.txt`: Python 의존성 목록 (paho-mqtt, pyyaml)
-        *   `scripts/`: 핵심 비즈니스 로직을 구동하는 Python 스크립트 디렉터리
-            *   `registry.py`: 잡의 등록, 클레임 및 원자적 파일 락 제어 (CLI 지원)
-            *   `job_subscriber.py`: 백그라운드 이벤트 구독기 및 오디팅 로그 생성기
-            *   `publish_event.py`: 실행 상태 및 에러 트랩 시 이벤트 퍼블리셔
-            *   `mqtt_common.py`: 공통 MQTT 브로커 연결 유틸리티
-*   `AGENT.md`: 에이전트 간의 역할 분담(PM, Worker, Reviewer) 및 이벤트 발행 규약 정의
+*   `.agents/`: 오케스트레이션 및 에이전트 커스텀 스킬 디렉터리
+    *   `AGENT.md`: 에이전트 간의 역할 분담(PM, Worker, Reviewer) 및 이벤트 발행 규약 정의
+    *   `AGENT.ko.md`: 에이전트 간의 역할 분담(PM, Worker, Reviewer) 및 이벤트 발행 규약 정의 (한국어)
+    *   `skills/`: 멀티 에이전트 구동 및 비동기 잡 처리를 수행하는 셸 스크립트 모음
+        *   `lib.sh`: 오케스트레이션의 핵심 셸 함수 및 가상환경(venv) 자동 연동 라이브러리
+        *   `multi-agent-mux-create/`: 격리된 tmux 에이전트 세션을 시작하는 스크립트
+        *   `multi-agent-mux-stop/`: 세션을 정상적으로 중지하고 상태를 업데이트하는 스크립트
+        *   `multi-agent-mux-resume/`: 중지된 에이전트 세션을 이전 대화 상태 그대로 복원하는 스크립트
+        *   `multi-agent-mux-status/`: 전체 에이전트 세션의 현재 구동 상태를 조회하는 스크립트
+        *   `multi-agent-mux-monitor/`: tmux 상태와 레지스트리 상태를 동기화하는 모니터 스크립트
+        *   `multi-agent-mux-delegate-job/`: 비동기 잡 분할 실행 모듈
+            *   `requirements.txt`: Python 의존성 목록 (paho-mqtt, pyyaml)
+            *   `scripts/`: 핵심 비즈니스 로직을 구동하는 Python 스크립트 디렉터리
+                *   `registry.py`: 잡의 등록, 클레임 및 원자적 파일 락 제어 (CLI 지원)
+                *   `job_subscriber.py`: 백그라운드 이벤트 구독기 및 오디팅 로그 생성기
+                *   `publish_event.py`: 실행 상태 및 에러 트랩 시 이벤트 퍼블리셔
+                *   `mqtt_common.py`: 공통 MQTT 브로커 연결 유틸리티
 *   `MESSAGING.md`: 에이전트 간 주고받는 MQTT 메시지 와이어 스킴 가이드라인

 ---

-## 2. 환경 설정 파일 생성 (.env)
+## 2. 워크스페이스 프로비저닝 (단계 0 — 참고용)
+
+에이전트가 이 안내서를 읽기 전에 워크스페이스 설치가 선행되어야 합니다. 이 단계는 이미 개발자(사람)가 설치기를 통해 수행 완료한 상태입니다. 에이전트가 환경 검증 작업을 수행할 때 파일들이 어떤 경로로 복사되고 설치되었는지에 대한 기초 사실(Reference)을 제공하기 위해 여기에 기록해 둡니다.
+
+### 단계 0.1: 설치 스크립트 실행 (이미 기수행됨)
+인스톨러를 통해 워크스페이스를 기동하기 위해 사람이 다음 명령을 구동하였습니다:
+
+```bash
+curl -fsSL https://git.godopu.com/tmpl/multi-agent-mux/raw/branch/main/deploy/install.sh | bash
+```
+
+인스톨러는 시스템 의존성 유효성을 검증하고 리포지토리를 불러와 오케스트레이션을 위한 `.agents/` 스켈레톤 및 관련 문서 파일(본 `BOOTSTRAP.ko.md` 포함)을 복사하고 `.env` 및 `.venv` 가상환경 설정을 자동으로 수행했습니다.
+
+> [!NOTE]
+> **검증 전용 경고**: 본 가이드를 읽고 있는 AI 에이전트는 인스톨러 스크립트를 스스로 **다시 실행해서는 안 됩니다.** 즉시 환경 변수 설정 및 검증 테스트 단계로 넘어가십시오.
+
+---
+
+## 3. 환경 설정 파일 생성 (.env)

 메시징 브로커 설정 및 실행 경로를 설정하기 위해 로컬 환경 설정 파일(`.env`)을 생성하고 수정해야 합니다.

-### 단계 2.1: 자동 생성 스크립트 실행
+### 단계 3.1: 자동 생성 스크립트 실행
 프로젝트 루트에서 제공되는 환경 설정 템플릿 복사 스크립트를 실행합니다.

 ```bash
@@ -44,7 +64,7 @@
 ./scripts/generate-env.sh --force
 ```

-### 단계 2.2: 환경 변수 수정 및 설정
+### 단계 3.2: 환경 변수 수정 및 설정
 생성된 `.env` 파일을 열어 설정을 필요에 따라 구성합니다.

 > [!NOTE]
@@ -60,15 +80,15 @@
 > [!WARNING]
 > **보안 모드 기본값 안내**:
 > 시스템의 기본 설정은 **무인증 PoC 모드**입니다. 잡 등록 시 `auth_token`이 명시적으로 주입되지 않으면(또는 `null`인 경우) HMAC 서명 검증이 생략됩니다.
-> 공개 브로커 사용 환경이나 실제 프로덕션 단계에서는 잡 등록 시 `auth_token`을 고유 난수값으로 생성 및 주입하여 HMAC 보안 서명을 활성화해야 합니다. (자세한 보안 규약은 [MESSAGING.md](./MESSAGING.md) 및 [AGENT.ko.md](./AGENT.ko.md)의 `2.3 보안 프로토콜` 섹션을 참조하십시오. 현재 CLI를 통한 자동 토큰 생성/주입 기능 지원은 향후 로드맵의 `FW-N6` 과제로 처리 예정입니다.)
+> 공개 브로커 사용 환경이나 실제 프로덕션 단계에서는 잡 등록 시 `auth_token`을 고유 난수값으로 생성 및 주입하여 HMAC 보안 서명을 활성화해야 합니다. (자세한 보안 규약은 [MESSAGING.md](./MESSAGING.md) 및 [AGENT.ko.md](.agents/AGENT.ko.md)의 `2.3 보안 프로토콜` 섹션을 참조하십시오. 현재 CLI를 통한 자동 토큰 생성/주입 기능 지원은 향후 로드맵의 `FW-N6` 과제로 처리 예정입니다.)

 ---

-## 3. 의존성 및 가상환경 설정 (Venv Setup)
+## 4. 의존성 및 가상환경 설정 (Venv Setup)

 오케스트레이션 및 MQTT 메시징을 구동하기 위한 Python 3 의존성을 설정합니다.

-### 단계 3.1: Python 가상환경 구축
+### 단계 4.1: Python 가상환경 구축
 프로젝트 루트에서 `.venv` 가상환경을 생성하고 활성화합니다.

 ```bash
@@ -79,7 +99,7 @@ python3 -m venv .venv
 source .venv/bin/activate
 ```

-### 단계 3.2: 의존성 패키지 설치
+### 단계 4.2: 의존성 패키지 설치
 `multi-agent-mux-delegate-job` 디렉터리에 기재된 `requirements.txt` 의존성 목록을 가상환경에 설치합니다.

 ```bash
@@ -89,7 +109,7 @@ pip install -r .agents/skills/multi-agent-mux-delegate-job/requirements.txt

 ---

-## 4. 디렉터리 준비 및 보안 감시 가이드
+## 5. 디렉터리 준비 및 보안 감시 가이드

 에이전트 제어 상태 및 잡 기록을 위해 로컬 레지스트리 디렉터리가 정상적으로 생성되었는지 확인합니다.

@@ -110,7 +130,7 @@ pip install -r .agents/skills/multi-agent-mux-delegate-job/requirements.txt

 ---

-## 5. 실행 환경 검증 및 부트스트랩 테스트
+## 6. 실행 환경 검증 및 부트스트랩 테스트

 환경 구축이 오작동 없이 안전하게 완료되었는지 아래의 체크리스트를 실행해 검증합니다.

@@ -158,8 +178,8 @@ rm -f ".mam/jobs/$JID.json" ".mam/jobs/$JID.lock"

 ---

-## 6. 에이전트 온보딩 가이드 (New Agent Onboarding)
+## 7. 에이전트 온보딩 가이드 (New Agent Onboarding)

-본 환경 구축을 무사히 마쳤다면, 협업하는 에이전트는 즉시 프로젝트 루트에 있는 **[AGENT.ko.md](./AGENT.ko.md)** 문서를 읽어야 합니다.
+본 환경 구축을 무사히 마쳤다면, 협업하는 에이전트는 즉시 .agents/ 디렉터리에 있는 **[AGENT.ko.md](.agents/AGENT.ko.md)** 문서를 읽어야 합니다.

 해당 문서에는 에이전트가 각 역할(PM, Worker, Reviewer)로 구동될 때 지켜야 할 **수술적 변경 규칙, 교차 검증 통과 규약, Tmux 뷰포트 유실 방지를 위한 스냅샷 패턴** 등이 서술되어 있어 안정적인 멀티 에이전트 워크플로우에 즉시 기여할 수 있도록 돕습니다.