AgentCraft: Claude 에이전트 팀의 코딩 작업을 Minecraft 스튜디오에서 지켜보고 병합하는 모드

9bow · 10월 6, 2026, 3:30오전

핵심 요약

AgentCraft는 Claude 에이전트 여러 개가 실제 git 저장소에서 계획, 구현, 리뷰를 나눠 맡는 과정을 Minecraft: Java Edition 안의 스튜디오 화면으로 보여주는 Fabric 모드와 오케스트레이터입니다.
리드 에이전트가 목표를 작업으로 나누고, 작업자 에이전트는 작업마다 별도의 git 워크트리에서 코드를 고치며, 변경 사항은 사용자가 게임 안의 리뷰 화면에서 Merge 를 눌러야만 내 브랜치에 들어갑니다.
에이전트의 git push 는 명령 필터뿐 아니라 git 설정 수준에서도 막혀 있고, 워크트리 밖 쓰기, 네트워크 접근, 파괴적인 명령은 게임 안의 권한 요청으로 넘어옵니다.
Windows 또는 macOS, Java 25, Node 22 이상, Minecraft: Java Edition 정품이 필요하고, 실제 에이전트를 실행하면 Claude API 사용량만큼 비용이 듭니다. 아직 개발용 클라이언트로만 실행되며, 저자는 한 사람이 한 대의 컴퓨터에서 써 본 단계라고 밝히고 있습니다.

AgentCraft 소개

코딩 에이전트를 여러 개 동시에 실행하면 사람이 보게 되는 것은 보통 터미널 창 여러 개에 흘러가는 텍스트입니다. 어느 에이전트가 어떤 파일을 읽고 있는지, 누가 막혀 있는지, 누가 내 판단을 기다리는지를 알려면 창을 하나씩 열어 로그를 거슬러 읽어야 합니다. 에이전트가 많아질수록 이 확인 작업이 늘어나고, 결과물을 내 브랜치에 들여도 되는지 판단하는 시점도 놓치기 쉽습니다. 이번에 소개하는 AgentCraft는 이 상황을 Minecraft 안의 사무실 공간으로 바꾸어, Claude 에이전트 팀이 일하는 모습을 걸어 다니며 확인하고 병합 여부를 직접 결정하게 하는 프로젝트입니다.

AgentCraft에서 사용자는 콘솔에 목표 하나를 입력합니다. 리드 에이전트가 저장소를 읽고 계획을 세워 작업 카드를 벽에 붙이면, 작업자 에이전트들이 자기 책상으로 걸어가 각자의 git 워크트리(worktree)에서 코드를 작성합니다. 책상 모니터에는 에이전트가 읽은 파일과 바꾼 줄이 실시간으로 표시되고, 사용자가 답해야 할 질문이 생기면 에이전트가 사용자에게 걸어와 질문을 띄웁니다. 작업이 끝나면 실제 diff를 리뷰 화면에서 확인하고, 사용자가 Merge 를 누르지 않으면 어떤 변경도 내 브랜치에 들어가지 않습니다.

AgentCraft는 GitHub 사용자 Blendi가 개인 계정으로 공개한 프로젝트이며, 저장소에 Mojang, Microsoft, Anthropic과 관계가 없다고 밝히고 있습니다. 구성은 크게 두 부분입니다: 게임 화면과 조작을 맡는 Java 기반 Fabric 모드, 그리고 에이전트 실행과 모든 상태를 맡는 Node 22, TypeScript 기반의 오케스트레이터인 Foreman입니다. Foreman은 Claude Agent SDK ( Anthropic이 소개하는 Claude Agent SDK로 에이전트 빌드하기 🤖)로 에이전트 세션을 만들고, 상태를 디스크에 저장해 두기 때문에 게임을 꺼도 에이전트는 계속 일합니다. 게임을 다시 켜면 스튜디오 화면이 그동안의 진행 상황을 따라잡습니다.

AgentCraft와 다른 멀티 에이전트 코딩 도구 비교

여러 코딩 에이전트를 병렬로 실행하고 결과를 검토하는 도구는 이미 여러 가지가 있습니다. 그중 사무실 화면에 에이전트를 아바타로 보여주는 Munder Difflin, 에이전트마다 워크트리를 나눠 주는 데스크톱 앱 Emdash와 비교하면 다음과 같습니다:

항목	AgentCraft	Munder Difflin	Emdash
화면	Minecraft: Java Edition 안의 3D 스튜디오 (Fabric 모드)	Electron 데스크톱 앱의 2D 사무실 화면	데스크톱 앱
사용하는 에이전트	Claude Agent SDK 기반 Claude 에이전트만	Claude Code, OpenAI Codex, Antigravity(Gemini) 등 기존 터미널 에이전트 CLI	Claude Code, Codex, OpenCode, Amp 등 여러 CLI
작업 분배	리드 에이전트가 의존 관계가 있는 작업 그래프를 만들고 리뷰까지 담당	사용자의 분신 역할을 하는 총괄 에이전트가 작업을 배분	사용자가 작업이나 이슈를 골라 에이전트에게 전달
격리와 병합	작업마다 워크트리, 사용자가 승인해야 병합, push 차단	메시지 전달 중심, 워크트리 격리는 선택	에이전트마다 워크트리와 브랜치, diff 검토 후 병합과 PR 생성

세 도구 모두 사람이 검토한 뒤에 결과를 받아들이는 흐름이 있습니다. 그중 AgentCraft는 Claude 한 종류로 범위를 좁힌 대신 리드 에이전트의 계획과 리뷰, 실패한 테스트의 재작업, 병합 충돌 해결까지 Foreman이 하나의 흐름으로 관리합니다. 반대로 Codex나 Gemini CLI 같은 다른 에이전트를 함께 쓰려면 AgentCraft가 아니라 다른 두 도구가 맞습니다. 원격 저장소에 push 하는 경로가 아예 없다는 점도 PR 생성까지 지원하는 Emdash와 다릅니다.

AgentCraft를 사용하면 좋을 사용자

AgentCraft는 Claude API(또는 Amazon Bedrock, Google Vertex AI, Microsoft Foundry) 계정을 가진 개발자 중, 여러 에이전트에게 한 저장소의 작업을 나눠 맡기면서 진행 상황을 한눈에 보고 싶은 경우에 맞습니다. 병합을 반드시 사람이 승인하고 push 가 구조적으로 막혀 있으므로, 아끼는 저장소에 에이전트를 붙여 보는 첫 실험으로도 부담이 적습니다. Minecraft를 이미 갖고 있다면 API 비용 없이 시뮬레이션 팀으로 화면과 흐름을 먼저 확인해 볼 수 있습니다.

반면 여러 사람이 같은 스튜디오를 함께 쓰려는 경우나 일반 Minecraft 런처에 설치하는 정식 모드가 필요한 경우에는 아직 맞지 않습니다. AgentCraft는 싱글플레이 전용이고 개발용 클라이언트로만 실행되기 때문입니다. 공식 실행 스크립트도 Windows와 macOS용만 있으며, macOS는 Apple Silicon에서만 테스트되어 Intel Mac이나 Linux에서는 직접 구성하고 확인해야 합니다. 팀 단위로 매일 쓰는 개발 환경을 찾는 사용자에게는 AgentCraft가 아직 적절한 선택지가 아닙니다. 저자도 개발자 한 명이 한 대의 컴퓨터에서 써 본 초기 프로젝트라고 밝히고 있으므로, 이를 감안해 살펴보시기 바랍니다.

AgentCraft에서 목표 하나가 처리되는 과정

AgentCraft의 팀은 리드 에이전트 한 명과 작업자 에이전트 다섯 명으로 구성됩니다. 리드인 Marlow는 계획, 작업 분배, 리뷰를 맡고, Juniper, Kit, Wren, Rowan, Tove가 코드를 작성합니다. 기본 설정에서는 리드가 Opus, 작업자가 Sonnet 모델을 쓰며, 작업자는 Juniper, Kit, Wren 세 명이 근무하고 동시에 최대 3명이 실행됩니다. 아래 6장의 화면은 목표 하나가 처리되는 순서이며, 시뮬레이션 백엔드의 데모 저장소에서 찍은 화면입니다:

목표 입력: ` 키로 콘솔을 열고 목표를 입력합니다. @juniper 처럼 이름을 붙이면 특정 에이전트에게 메시지를 보낼 수 있습니다.
계획: 리드 에이전트가 저장소를 읽기 전용으로 살펴본 뒤 목표를 의존 관계가 있는 작업들로 나눕니다. 작업은 작업 벽(Task Wall)에 붙고, 계획은 공유 메모리에 기록됩니다.
구현: 작업자는 agentcraft/<agent>/<task> 브랜치의 워크트리에서 코드를 고치고 테스트를 실행합니다. 앞선 작업이 끝나야 그 작업에 의존하는 작업이 시작됩니다.
질문: 사용자가 정해야 할 사항이 생기면 에이전트가 결정 연단(podium)으로 걸어오고 종이 울립니다. J 키로 질문, 권한 요청, 병합 결정을 오래된 순서대로 처리합니다.
리뷰와 병합: 작업이 끝날 때마다 저장소의 테스트 명령이 실행되고, 실패하면 작업자에게 한 번 되돌아갑니다. 리드 에이전트가 diff와 테스트 결과를 검토한 뒤 병합을 요청하면, 사용자는 Merge, Request changes, Reject 중 하나를 고릅니다.
공유 메모리: 리드의 계획과 결정, 저장소 규칙은 모든 에이전트가 읽는 마크다운 메모로 남고, 사용자도 라이브러리 화면에서 열어 볼 수 있습니다.

병렬로 진행한 작업끼리 충돌이 나면 해당 브랜치가 작업자에게 돌아가고, 작업자는 기준 브랜치를 자기 브랜치에 병합해 충돌을 해결한 뒤 다시 리뷰를 요청합니다. 저자는 이 처리 덕분에 같은 파일을 건드리는 작업도 순서대로 기다리지 않고 병렬로 계획할 수 있다고 설명합니다.

시뮬레이션 화면만 있는 것은 아닙니다. 저자는 샘플 저장소에서 실제 Claude 에이전트로 전체 과정을 게임 안에서만 진행했다고 밝히고 있습니다. 실행 중간에 게임을 재시작하고 Foreman을 내렸다가 다시 올렸지만 작업이 이어졌고, 기능 6개가 테스트를 통과한 채 저장소에 반영됐습니다. 아래는 그 실행에서 찍은 화면입니다:

AgentCraft의 구조: Minecraft 모드와 Foreman

AgentCraft는 화면을 그리는 모드와 일을 처리하는 Foreman을 분리해 두었습니다. 아래 그림은 저장소의 구조도를 옮긴 것으로, 왼쪽이 Minecraft (Fabric mod), 가운데가 Foreman (Node + TypeScript), 오른쪽이 Your git repo 이며 모드와 Foreman은 WebSocket, localhost only 로 연결됩니다:

Foreman은 작업과 의존 관계, 메시지, 공유 메모리, 결정 대기열, 워크트리를 모두 소유하고 디스크에 저장합니다. Claude 세션은 ID로 재개되므로 Foreman을 재시작하거나 비정상 종료돼도 중단된 작업이 이어집니다. 모드는 Foreman이 아는 상태를 그리고 사용자가 내린 결정을 돌려보내는 역할만 하므로, 게임이 꺼져도 작업은 사라지지 않습니다. 연결은 127.0.0.1 의 WebSocket(기본 포트 7878)만 받으며, Foreman은 브라우저에서 온 요청을 거부합니다.

에이전트가 Read, Grep, Glob 도구를 쓰면 라이브러리로, 파일을 고치면 책상으로, 테스트를 실행하면 테스트 벤치로 걸어가는 식으로 SDK 이벤트가 게임 속 위치와 동작에 연결됩니다. 멀리서는 상태 램프와 지붕 위 표시등으로 누가 일하고 누가 막혀 있는지 보이고, 가까이 가면 이름표와 카드, 모니터로 세부 내용을 확인할 수 있습니다.

별도로 시뮬레이션(sim) 백엔드도 제공합니다. 시뮬레이션 백엔드는 대본에 따라 움직이는 팀이 데모 저장소에서 실제 git 편집, 테스트, 병합을 수행하는 모드로, API를 전혀 호출하지 않습니다. 저자는 데모, 화면 품질 검사(QA, Quality Assurance), 개발에 이 백엔드를 쓰고 있습니다.

AgentCraft의 저장소 안전장치

AgentCraft는 실제로 아끼는 저장소에 붙이는 것을 전제로 설계되었고, 안전장치는 Foreman 문서에 자세히 정리되어 있습니다. 핵심은 다음 다섯 가지입니다:

항상 워크트리에서 작업: 작업자 에이전트는 작업마다 만들어진 워크트리에서만 코드를 고치고, 사용자의 체크아웃은 건드리지 않습니다. 리드 에이전트는 사용자의 체크아웃에서 계획을 세우므로 확인 없이 실행할 수 있는 것은 읽기 전용 명령뿐입니다.
병합은 사용자만: 병합 커밋은 작업 트리 밖에서 만들어진 뒤 fast-forward로 적용됩니다. 체크아웃에 커밋하지 않은 변경이 있으면 병합이 거부되고, 충돌이 나면 작업자에게 되돌아갑니다.
push 는 git 수준에서 차단: 에이전트가 실행하는 모든 프로세스에 GIT_ALLOW_PROTOCOL=agentcraft-none, protocol.allow=never 같은 환경 설정을 넣어 push, fetch, clone이 모두 실패하게 합니다. 테스트 스크립트나 git 훅 안에 숨은 push도 같은 이유로 실패합니다 (gitsafety.ts).
위험한 명령은 먼저 확인: 워크트리 안의 읽기와 편집은 허용되지만, 워크트리 밖 쓰기, curl 이나 npm install 같은 네트워크 접근, rm -r 이나 git reset --hard 같은 파괴적인 명령은 게임 안의 권한 요청이 됩니다. "Always allow" 를 고르면 그 허용이 어디까지 적용되는지가 요청 화면에 표시됩니다 (policy.ts).
작성자 구분: 에이전트의 커밋은 AgentCraft <Name> 이름으로 남고 서명되지 않으며, 사용자가 승인한 병합 커밋만 사용자의 git 이름으로 만들어집니다.

다만 저자는 이 장치가 샌드박스는 아니라고 명시합니다. 에이전트가 실행한 코드가 의도적으로 환경 변수를 지우고 git을 실행하는 경우까지 막지는 못하며, 권한 정책이 그런 명령을 발견하면 거부하는 방식으로 실수와 과도한 에이전트 동작을 막는 수준입니다.

AgentCraft 설치와 사용

AgentCraft를 실행하려면 Windows 10 또는 11, 또는 macOS 환경에 Java 25, Node 22 이상, git, 그리고 Minecraft: Java Edition 정품이 필요합니다. 실제 에이전트를 쓰려면 ANTHROPIC_API_KEY 를 설정하거나, Agent SDK가 지원하는 Amazon Bedrock(CLAUDE_CODE_USE_BEDROCK=1), Google Vertex AI(CLAUDE_CODE_USE_VERTEX=1), Microsoft Foundry(CLAUDE_CODE_USE_FOUNDRY=1) 중 하나의 자격 증명을 준비합니다.

Windows에서는 PowerShell 스크립트로 실행합니다:

git clone https://github.com/blendi-remade/agentcraft
cd agentcraft

tools\launch.ps1 -Backend sim                    # try it first: a simulated team, no API usage
tools\launch.ps1 -Repo C:\path\to\your\repo      # real agents on your repo
tools\stop.ps1                                   # stop everything launch.ps1 started

macOS에서는 brew install openjdk@25 로 Java 25를 설치한 뒤 Node 스크립트로 실행합니다. 이 스크립트는 시스템 Java 설정을 바꾸지 않고 해당 JDK를 골라 씁니다:

node tools/mac.mjs launch --backend sim                 # try the studio without API usage
node tools/mac.mjs stop --profile sim
node tools/mac.mjs launch --repo /path/to/your/repo --use-claude-login
node tools/mac.mjs stop

첫 실행에서는 npm 의존성을 설치하고 Gradle이 Minecraft와 Fabric을 내려받으므로 몇 분이 걸립니다. 이후에는 1분 안에 스튜디오에 들어갈 수 있고, 본부 건물은 처음 실행할 때 자동으로 지어집니다. 실행 옵션과 로그 위치는 tools/README.md에 정리되어 있습니다.

--use-claude-login(Windows는 -UseClaudeLogin) 옵션은 API 키 대신 내 컴퓨터의 claude CLI 로그인으로 에이전트를 실행합니다. Anthropic은 Agent SDK 문서에서 사전 승인 없이 서드파티 제품이 claude.ai 로그인을 제공하는 것을 허용하지 않는다고 밝히고 있습니다. 그래서 저자는 이 옵션을 기본으로 꺼 두었고, 자기 컴퓨터에서 직접 쓰는 개인 용도로만 의도했다고 설명합니다.

콘솔에서는 일반 텍스트를 입력하면 새 목표가 되고, 그 밖의 주요 명령은 다음과 같습니다:

명령	동작
`@name message`	특정 에이전트에게 메시지 보내기
`/answer [d4] <n or option> [text]`	열려 있는 결정에 답하기
`/diff [worktree or @agent]`	워크트리의 변경 사항 검토
`/status`	목표, 에이전트, 작업, 결정, 누적 비용 보기
`/pause @x`, `/resume @x`	작업을 유지한 채 에이전트 일시 정지와 재개
`/stop @x`, `/spawn @x [task]`	에이전트를 근무에서 빼거나 다시 투입
`/repo add <path>`, `/repos`	저장소 등록과 목록 보기

비용은 Anthropic이나 클라우드 제공자 계정에 토큰 단위로 청구되며, 저자는 작은 목표 하나에 몇 달러가 든다고 안내합니다. 비용을 줄이려면 모델과 추론 강도(effort), 작업자 수를 낮춰 실행합니다:

tools\launch.ps1 -Repo C:\path\to\repo -ForemanArgs '--model','sonnet','--effort','low','--workers','juniper,kit'

저자가 이 설정으로 샘플 저장소에서 측정한 결과, 작업 2개짜리 목표 3개(작업자가 해결한 병합 충돌 2건 포함)가 각각 2~10분 걸렸고 비용은 모두 합쳐 약 6달러였습니다. 시뮬레이션 백엔드는 무료입니다.

AgentCraft의 라이선스

AgentCraft는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다. 캐릭터 스킨, 블록 텍스처, UI 스프라이트 같은 그림도 assets-src/의 스크립트로 생성되어 같은 라이선스를 따릅니다.

단, Minecraft 자체는 포함되어 있지 않습니다. 개발 과정에서 Gradle이 Mojang에서 내려받으며, 실행하려면 각자 Minecraft: Java Edition을 구매해 갖고 있어야 합니다.

AgentCraft 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다.

이 글은 파이토치 한국 사용자 모임이 직접 정리한 글입니다. 새 글을 놓치지 않으시려면 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로 알림을 받으시고, 회원으로 가입하시면 주요 글들을 이메일로도 보내드립니다!

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~