From 738e4dc8d1cdd37aab3cb060d51229abf2dba751 Mon Sep 17 00:00:00 2001 From: Godopu Date: Sun, 21 Jun 2026 10:27:33 +0000 Subject: [PATCH] docs: add BOOTSTRAP.md project setup and onboarding guide --- BOOTSTRAP.md | 165 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 BOOTSTRAP.md diff --git a/BOOTSTRAP.md b/BOOTSTRAP.md new file mode 100644 index 0000000..4600d77 --- /dev/null +++ b/BOOTSTRAP.md @@ -0,0 +1,165 @@ +# BOOTSTRAP.md + +본 문서는 `advanced_multi_agent` 오케스트레이션 및 메시징 백플레인 워크플로우를 새로운 프로젝트에 도입하여 이식하고, 새로운 개발자/에이전트가 초기 가동을 시작할 때 수행해야 하는 환경 설정 및 구축 절차를 안내합니다. + +새로운 에이전트는 이 안내서에 기술된 절차를 순차적으로 실행하여 초기 환경을 안정적으로 설정할 수 있습니다. + +--- + +## 1. 프로젝트 구조 이해 (Scaffolding Overview) + +본 프로젝트를 새로운 환경에 복제(Clone)한 후, 핵심 구성 요소들의 위치와 역할을 먼저 파악해야 합니다. + +* `skills/`: 멀티 에이전트 구동 및 비동기 잡 처리를 수행하는 셸 스크립트 모음 + * `lib.sh`: 오케스트레이션의 핵심 셸 함수 및 가상환경(venv) 자동 연동 라이브러리 + * `tmux-agent-orchestrate-create/`: 격리된 tmux 에이전트 세션을 시작하는 스크립트 + * `tmux-agent-orchestrate-stop/`: 세션을 정상적으로 중지하고 상태를 업데이트하는 스크립트 + * `tmux-agent-orchestrate-resume/`: 중지된 에이전트 세션을 이전 대화 상태 그대로 복원하는 스크립트 + * `tmux-agent-orchestrate-status/`: 전체 에이전트 세션의 현재 구동 상태를 조회하는 스크립트 + * `tmux-agent-orchestrate-monitor/`: tmux 상태와 레지스트리 상태를 동기화하는 모니터 스크립트 + * `tmux-agent-orchestrate-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) 및 이벤트 발행 규약 정의 +* `MESSAGING.md`: 에이전트 간 주고받는 MQTT 메시지 와이어 스킴 가이드라인 + +--- + +## 2. 환경 설정 파일 생성 (.env) + +메시징 브로커 설정 및 실행 경로를 설정하기 위해 로컬 환경 설정 파일(`.env`)을 생성하고 수정해야 합니다. + +### 단계 2.1: 자동 생성 스크립트 실행 +프로젝트 루트에서 제공되는 환경 설정 템플릿 복사 스크립트를 실행합니다. + +```bash +# .env.example를 .env로 자동 복제 (이미 존재하면 덮어쓰지 않고 보호됨) +./scripts/generate-env.sh + +# 만약 강제로 덮어쓰고 백업을 생성하고 싶은 경우: +./scripts/generate-env.sh --force +``` + +### 단계 2.2: 환경 변수 수정 및 설정 +생성된 `.env` 파일을 열어 설정을 필요에 따라 구성합니다. + +> [!NOTE] +> `generate-env.sh`로 생성된 기본 `.env` 파일은 모든 환경 변수 항목이 주석 처리되어 있습니다. 주석 처리된 상태로 둘 경우 로컬 프로젝트 루트를 기준으로 한 상대 경로(`.hermes/` 등) 및 기본 공개 브로커 주소가 자동 지정되므로 그대로 사용하셔도 무방합니다. + +1. **MQTT Broker 설정 (`MQTT_BROKER`)**: + * 기본값은 HiveMQ 공개 브로커(`broker.hivemq.com`)로 잡혀 있으나, 보안 및 프라이버시가 중요한 프로덕션 작업 시에는 개인/사설 브로커 주소로 변경할 것을 강력히 권장합니다. +2. **인증 정보 (`MQTT_USERNAME`, `MQTT_PASSWORD`)**: + * 보안 브로커를 사용하는 경우 `replace_me`로 명시된 곳을 실제 브로커 계정 정보로 변경해 주십시오. +3. **경로 관련 변수 (선택 사항)**: + * 특정 빌드 시스템이나 호스트 폴더 구조에 맞추어 `AGENT_SESSIONS_YAML` 및 `DELEGATE_JOB_LOGS_DIR` 등의 경로 값을 절대 경로로 오버라이드해야 하는 경우에만 주석을 풀고 기입하십시오. + +> [!WARNING] +> **보안 모드 기본값 안내**: +> 시스템의 기본 설정은 **무인증 PoC 모드**입니다. 잡 등록 시 `auth_token`이 명시적으로 주입되지 않으면(또는 `null`인 경우) HMAC 서명 검증이 생략됩니다. +> 공개 브로커 사용 환경이나 실제 프로덕션 단계에서는 잡 등록 시 `auth_token`을 고유 난수값으로 생성 및 주입하여 HMAC 보안 서명을 활성화해야 합니다. (자세한 보안 규약은 [MESSAGING.md](./MESSAGING.md) 및 [AGENT.md](./AGENT.md)의 `2.3 보안 프로토콜` 섹션을 참조하십시오. 현재 CLI를 통한 자동 토큰 생성/주입 기능 지원은 향후 로드맵의 `FW-N6` 과제로 처리 예정입니다.) + +--- + +## 3. 의존성 및 가상환경 설정 (Venv Setup) + +오케스트레이션 및 MQTT 메시징을 구동하기 위한 Python 3 의존성을 설정합니다. + +### 단계 3.1: Python 가상환경 구축 +프로젝트 루트에서 `.venv` 가상환경을 생성하고 활성화합니다. + +```bash +# 가상환경 생성 +python3 -m venv .venv + +# 가상환경 활성화 +source .venv/bin/activate +``` + +### 단계 3.2: 의존성 패키지 설치 +`tmux-agent-orchestrate-delegate-job` 디렉터리에 기재된 `requirements.txt` 의존성 목록을 가상환경에 설치합니다. + +```bash +# 의존성 패키지(pyyaml, paho-mqtt 등) 설치 +pip install -r skills/tmux-agent-orchestrate-delegate-job/requirements.txt +``` + +--- + +## 4. 디렉터리 준비 및 보안 감시 가이드 + +에이전트 제어 상태 및 잡 기록을 위해 로컬 레지스트리 디렉터리가 정상적으로 생성되었는지 확인합니다. + +1. **필수 로컬 디렉터리 구조**: + * `.hermes/jobs/`: 등록된 비동기 잡의 세부 메타데이터가 파일 형태로 저장되는 디렉터리 + * `.hermes/delegate_job_logs/`: 에이전트가 발행하는 모든 백플레인 이벤트 흐름이 기록되는 audit log (`events.ndjson`) 보존 디렉터리 +2. **Git 커밋 제어 (.gitignore)**: + * 새 프로젝트 초기화 시 아래 파일들이 절대 리포지토리에 커밋되지 않도록 `.gitignore` 상태를 점검합니다. `!.env.example` 예외 처리가 유지되어야 템플릿이 보존됩니다: + ```text + .env + .env.* + !.env.example + .hermes/ + .venv/ + __pycache__/ + *.pyc + ``` + +--- + +## 5. 실행 환경 검증 및 부트스트랩 테스트 + +환경 구축이 오작동 없이 안전하게 완료되었는지 아래의 체크리스트를 실행해 검증합니다. + +> [!IMPORTANT] +> 아래의 모든 검증 명령은 반드시 **프로젝트 루트 디렉터리**(`.hermes/` 디렉터리가 직접 보이는 위치)에서 실행해야 합니다. 잡 레지스트리 디렉터리 기본 경로가 프로젝트 루트 하위의 `./.hermes/jobs` 상대 경로를 기준으로 탐색되기 때문입니다. + +### 검증 테스트 1: 잡 레지스트리 정상 구동 여부 +Python 스크립트 및 venv 라이브러리가 올바르게 로드되는지 확인하기 위해 잡 목록을 조회합니다. + +```bash +# 가상환경(.venv) 파이썬 인터프리터를 사용하여 실행 +.venv/bin/python3 skills/tmux-agent-orchestrate-delegate-job/scripts/registry.py list +``` +* **출력 기대 결과**: 에러 메시지 없이 빈 JSON 배열 `[]` 또는 현재 등록된 pending/running 잡 목록이 성공적으로 출력되어야 합니다. + +### 검증 테스트 2: MQTT 연결 브로커 핸드셰이크 테스트 +브로커와의 송수신 통신망 상태를 확인하고, 이벤트 생명주기 및 멱등성이 온전히 작동하는지 실측 검증합니다. + +```bash +# 1. 테스트용 임시 잡 등록 및 발급된 8자리 Hex 잡 ID 획득 +JID=$(.venv/bin/python3 skills/tmux-agent-orchestrate-delegate-job/scripts/registry.py register \ + --agent "test-agent" \ + --prompt "Bootstrap check command" \ + --timeout 120) +echo "Generated Job ID: $JID" + +# 2. 획득한 잡 ID에 대해 백그라운드 이벤트 구독기(Subscriber) 구동 +.venv/bin/python3 skills/tmux-agent-orchestrate-delegate-job/scripts/job_subscriber.py --job "$JID" & + +# 3. 구독자의 MQTT Broker 소켓 연결 및 수신부 초기화 완료를 보장하기 위해 2초 대기 +sleep 2 + +# 4. 테스트 시작 이벤트 발행 (Subscribe-before-Publish 원칙 준수) +.venv/bin/python3 skills/tmux-agent-orchestrate-delegate-job/scripts/publish_event.py \ + --job "$JID" \ + --event started \ + --detail "Bootstrap MQTT verification connection check" + +# 5. 이벤트 수신이 터미널(stdout) 및 .hermes/delegate_job_logs/events.ndjson 로그 파일에 정상 기록되는지 확인 + +# 6. 검증 완료 후 백그라운드 프로세스 종료 및 테스트 잡 레코드 수동 정리 +kill %1 +rm -f ".hermes/jobs/$JID.json" ".hermes/jobs/$JID.lock" +``` + +--- + +## 6. 에이전트 온보딩 가이드 (New Agent Onboarding) + +본 환경 구축을 무사히 마쳤다면, 협업하는 에이전트는 즉시 프로젝트 루트에 있는 **[AGENT.md](./AGENT.md)** 문서를 읽어야 합니다. + +해당 문서에는 에이전트가 각 역할(PM, Worker, Reviewer)로 구동될 때 지켜야 할 **수술적 변경 규칙, 교차 검증 통과 규약, Tmux 뷰포트 유실 방지를 위한 스냅샷 패턴** 등이 서술되어 있어 안정적인 멀티 에이전트 워크플로우에 즉시 기여할 수 있도록 돕습니다.