The Hon: Joseon — AI 에이전트 셋업 가이드

전제 문서: 팀 구성/역할 정의는 .claude/agents/ 참조 이 문서: 실제 환경 구축 및 실행 방법 순서: 위에서 아래로 따라가면 완성

---

목차

1. 사전 준비
2. Mac / Windows 셋업
3. Slack 워크스페이스 셋업
4. GitHub 리포지토리 셋업
5. MCP 서버 설정
6. Claude Code 에이전트 정의
7. Hooks 설정
8. Agent Teams 실행
9. Godot 프로젝트 초기화

---

1. 사전 준비

계정 (전부 무료)

서비스	플랜	용도
Claude	Max ($200/월, 5x) — 유일한 유료	Opus + Sonnet (Agent Teams 5 에이전트)
Slack	Free	에이전트 소통
GitHub	Free	Git + LFS
Tailscale	Free (개인)	Mac ↔ Win 연결

API 키

SLACK_BOT_TOKEN=xoxb-...          # Slack Bot (MCP — 채널별 메시지)
SLACK_WEBHOOK_URL=https://hooks... # Slack Incoming Webhook (#alerts 채널 고정)
GITHUB_TOKEN=ghp_...             # GitHub Personal Access Token

Claude API 키는 불필요. Claude Max 구독은 OAuth 인증으로 동작하며, Claude Code가 자동 처리.

---

2. Mac / Windows 셋업

도구 설치, 네트워크, GPU 파이프라인, 스케줄 태스크, WoL 등은 별도 문서로 분리됨.

환경	문서	역할
MacBook M3	mac-setup.md	지휘부 — Claude Code, MCP, 스케줄, WoL
Windows PC (RTX 5090)	windows-setup.md	GPU 공장 — ComfyUI, ACE-Step, jsfxr, Godot 빌드
ComfyUI 워크플로우	../comfyui_workflows/README.md	모델 목록, 워크플로우 JSON, 후처리, VRAM 스케줄링

→ 각 문서의 Phase 0 체크리스트를 전부 완료한 뒤 아래 §3부터 진행.

---

3. Slack 워크스페이스 셋업

1. 워크스페이스 생성

Slack Free 워크스페이스 생성 → "The Hon Joseon"

2. 채널 생성

#general, #dashboard
#agent-planner, #agent-artist, #agent-coder, #agent-composer, #agent-tester-pm
#output-art, #output-audio, #output-build, #output-docs
#alerts, #review-queue

3. Slack App (Bot) 생성

1. api.slack.com/apps → "Create New App"
2. Bot Token Scopes:
   • channels:read, channels:history
   • chat:write, chat:write.public
   • files:write, files:read
3. Install to Workspace → SLACK_BOT_TOKEN 복사
4. Incoming Webhook → SLACK_WEBHOOK_URL 복사

---

5. GitHub 리포지토리 셋업

1. 리포 생성

gh repo create the-hon-joseon --private
cd the-hon-joseon
git init

2. Git LFS 설정

git lfs install
git lfs track "*.png"
git lfs track "*.ogg"
git lfs track "*.wav"
git lfs track "*.mp3"
git lfs track "*.tres"
git lfs track "*.tscn"
git add .gitattributes
git commit -m "chore: configure git lfs for assets"

3. 브랜치 보호

git checkout -b dev
git push -u origin dev

GitHub Settings → Branches → Branch protection rules:

• Require pull request before merging
• Require status checks (GdUnit4)

4. 프로젝트 디렉토리 구조

the-hon-joseon/
├── project.godot
├── .gitattributes
├── .claude/
│   ├── settings.json
│   ├── agents/
│   │   ├── planner.md
│   │   ├── artist.md
│   │   ├── coder.md
│   │   ├── composer.md
│   │   └── tester-pm.md
│   ├── agent-memory/
│   │   ├── planner/
│   │   ├── artist/
│   │   ├── coder/
│   │   ├── composer/
│   │   └── tester-pm/
│   └── CLAUDE.md
├── .mcp.json
├── scripts/
│   ├── gdscript-lint.sh
│   ├── validate-art-output.sh
│   ├── validate-test-result.sh
│   ├── log-agent-start.sh
│   ├── log-agent-stop.sh
│   ├── check-remaining-tasks.sh
│   └── validate-task-output.sh
├── src/
├── res/
│   ├── sprites/
│   ├── audio/
│   │   ├── bgm/
│   │   └── sfx/
│   ├── data/
│   └── ui/
├── test/
└── docs/

---

6. MCP 서버 설정

프로젝트 루트에 .mcp.json 생성:

{
  "mcpServers": {
    "slack": {
      "type": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "$SLACK_BOT_TOKEN"
      }
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      }
    },
    "comfyui": {
      "type": "http",
      "url": "http://$WIN_PC_IP:8188/mcp"
    },
    "ace-step": {
      "type": "http",
      "url": "http://$WIN_PC_IP:8189/mcp"
    }
  }
}

Win PC GPU MCP: ComfyUI/ACE-Step에 MCP HTTP 래퍼가 필요합니다. 래퍼가 없으면 SSH 폴백을 사용합니다 (ssh $WIN_PC_USER@$WIN_PC_IP "python comfyui_runner.py ...").

확인:

cd the-hon-joseon
claude

---

7. Claude Code 에이전트 정의

에이전트 정의 파일은 .claude/agents/ 디렉토리에 위치. 직접 확인/수정할 것.

파일	모델	역할
.claude/CLAUDE.md	—	프로젝트 컨텍스트 (Lazy Loading 루트, 20줄 이내)
.claude/agents/planner.md	Opus	GDD 기반 기획 + 밸런스 설계
.claude/agents/artist.md	Sonnet	오방색 픽셀아트 생성 (ComfyUI)
.claude/agents/coder.md	Opus	Godot 시스템 구현 + 테스트
.claude/agents/composer.md	Sonnet	칩튠+국악 BGM/SFX (ACE-Step)
.claude/agents/tester-pm.md	Sonnet	QA+PM, Agent Team 리더

폴더별 CLAUDE.md (Lazy Loading):

• src/weapons/CLAUDE.md — 무기 시스템 컨벤션
• res/sprites/CLAUDE.md — 스프라이트 네이밍/팔레트 규칙

---

8. Hooks 설정

Hooks 전체 설정은 .claude/settings.json 파일에 정의. 직접 확인/수정할 것.

Hook	트리거	동작
GDScript 포매팅	Edit|Write (.gd 파일)	gdformat 자동 실행
git push 알림	Bash (git push 감지)	Slack Webhook 알림
에이전트 알림	Notification	Slack #alerts 전달
서브에이전트 로깅	SubagentStart/Stop	log-agent-start/stop.sh
팀원 유휴	TeammateIdle	check-remaining-tasks.sh
작업 완료 검증	TaskCompleted	validate-task-output.sh

---

9. Agent Teams 실행

Agent SDK(Python 오케스트레이터)는 불필요. Claude Code 네이티브 기능만으로 팀을 구성한다.

팀 시작

claude --agent tester-pm

> "Agent Team을 구성해. planner, artist, coder, composer를 팀원으로 생성하고,
>  Phase 1 작업을 분배해."

팀원과 직접 대화

# in-process 모드 (기본): Shift+Down → 팀원 순환 → 메시지 입력

# 분할 창 모드 (tmux 필요)
claude --agent tester-pm --teammate-mode tmux

단일 에이전트 실행 (팀 없이)

claude --agent planner
> "무기 진화 트리 설계해줘"

제약 사항 (실험적)

• 세션 재개 시 in-process 팀원 복원 불가 → 새 팀원 생성 필요
• 세션당 1팀만 가능
• 중첩 불가 (팀원이 팀을 만들 수 없음)
• 리더 고정 (이전 불가)

---

10. Godot 프로젝트 초기화

cd the-hon-joseon

mkdir -p src/{player,enemies,weapons,souls,equipment,systems,ui,hub}
mkdir -p res/{sprites/{characters,enemies,bosses,weapons,effects,ui,npcs},audio/{bgm,sfx},data,tilesets}
mkdir -p test

project.godot 핵심 설정

[display]
window/size/viewport_width=480
window/size/viewport_height=270
window/stretch/mode="viewport"
window/stretch/aspect="keep"

[rendering]
textures/canvas_textures/default_texture_filter=0  # Nearest (픽셀아트)

[physics]
common/physics_ticks_per_second=60

---

The Hon: Joseon 셋업 가이드. Mac/Windows 환경 셋업: mac-setup.md / windows-setup.md