Claude Code Game Studios 장단점과 적용법, 먼저 해 볼 것

Claude Code Game Studios 는 Claude Code 세션에 에이전트 49개와 슬래시 명령 74개, 훅과 경로별 규칙을 얹어 게임 스튜디오처럼 일하게 만드는 MIT 라이선스 템플릿이다. 기획부터 출시까지 이어진 절차와 위험 명령 차단을 얻는 대신 토큰 사용량이 늘고, 설정을 무겁게 하면 코드보다 문서가 먼저 쌓인다(저자 실험에서 standard 는 첫 코드 전에 문서 30개). 새 저장소에서 기본값 minimal 로 /start 부터 돌려 보고, 기존 게임 저장소에는 브랜치에서 /adopt 감사를 거친 뒤 들이는 편이 낫다.

01 설치하는 스킬이 아니라 복제해서 쓰는 저장소 템플릿이다

이 저장소를 소개한 유튜브 영상의 제목은 "AI 게임 개발팀 49명을 담은 스킬" 이다. 실제로는 스킬 하나나 플러그인이 아니라, git clone 해서 게임 저장소의 뼈대로 쓰는 템플릿이다. 루트에 CLAUDE.md 와 설정 파일 project.yaml 이 있고, .claude/ 아래에 에이전트·스킬·훅·규칙·문서가 있다. 그 옆에는 src/·design/·tests/·production/ 같은 게임 폴더가 놓인다. 이 글은 2026년 10월 19일에 나온 1.2 버전의 README 와 저장소 파일을 기준으로 한다.

README 가 밝힌 이유는 단순하다. 범용 대화 세션에는 구조가 없어서, 매직 넘버를 박아 넣거나 설계 문서를 건너뛰어도 말리는 쪽이 없고 QA 나 설계 리뷰도 일어나지 않는다. 그래서 디렉터·부서 리드·전문가로 이뤄진 스튜디오 조직을 에이전트로 옮기고, 결정은 끝까지 사용자가 내리게 했다.

GitHub 저장소 소개란에는 스킬이 72개로 적혀 있어 README 본문(74개)과 다르다. 이 글은 README 본문의 숫자를 따른다.

모두 Claude Code 가 원래 읽는 파일 형식이다. 공식 문서 기준으로 서브에이전트는 .claude/agents/ 에 둔 마크다운 파일(YAML 머리말과 시스템 프롬프트)이다. 스킬은 .claude/skills/<이름>/SKILL.md 가 /<이름> 명령이 되고, 훅은 .claude/settings.json 에 등록한다. 별도 서버나 확장 없이 저장소를 열고 claude 를 띄우면 그대로 읽힌다. 이 글은 템플릿의 구조·비용·적용 순서를 다루고, 이 템플릿으로 만든 게임의 완성도는 다루지 않는다.

02 디렉터에서 전문가로 일을 내리고, 파일을 쓰기 전에 사용자 승인을 받는다

에이전트는 세 층으로 나뉜다. 맨 위에 디렉터 셋(creative-director·technical-director·producer)이 있고, 그 아래 부서 리드 여덟(game-designer·lead-programmer·art-director·qa-lead 등)이 있다. 실제 작업은 맨 아래의 gameplay-programmer·level-designer·qa-tester 같은 전문가가 맡는다. 엔진 전문가는 Godot 4·Unity·Unreal Engine 5 별로 따로 있고, GDScript·셰이더·Blueprints 같은 하위 영역을 나눠 맡는다.

여기서 에이전트는 Claude Code 의 서브에이전트다. 공식 문서에 따르면 서브에이전트는 자기 컨텍스트 창에서 따로 정한 시스템 프롬프트·도구·권한으로 일하고, 메인 대화에는 최종 요약만 돌려준다. 머리말의 model 필드에는 opus·sonnet 같은 별칭을 쓰거나, 메인 대화의 모델을 그대로 쓰는 inherit 를 적을 수 있다. 이 템플릿은 디렉터 셋에 Opus 를, lead-programmer 와 전문가 15개에 Sonnet 을 지정했고, 나머지 30개는 세션 모델을 물려받는다. README 는 이 층 구분이 역할의 연차를 뜻할 뿐 요금제 구분은 아니라고 덧붙였다.

디렉터 에이전트 파일을 하나 열어 보면 역할이 권한으로 묶여 있다. 아래는 creative-director.md 머리말의 필드만 옮긴 것이다(설명 문장은 줄였다).

---
name: creative-director
description: ...  # 게임 정체성에 걸린 결정, 리드끼리 막혔을 때 부른다
tools: Read, Glob, Grep, Write, Edit, WebSearch
disallowedTools: Bash
model: opus
maxTurns: 30
memory: project
---

Bash 는 막혀 있다. 본문도 코드 작성·스프린트 일정·엔진 선택은 디렉터 몫이 아니라고 선을 긋고, 선택지 두세 개를 장단점과 함께 낸 뒤 하나를 권하라고 지시한다. 에이전트끼리의 관계는 README 가 정한 다섯 규칙을 따른다.

1. 수직 위임: 디렉터는 리드에게, 리드는 전문가에게 일을 넘긴다.
2. 수평 협의: 같은 층끼리 의견을 묻지만, 자기 영역 밖의 결정은 내리지 못한다.
3. 충돌 해결: 의견이 갈리면 공통 상위로 올린다. 설계는 creative-director, 기술은 technical-director 가 받는다.
4. 변경 전파: 여러 부서에 걸친 변경은 producer 가 조율한다.
5. 영역 경계: 명시적 위임 없이는 자기 영역 밖의 파일을 고치지 않는다.

사용자와는 다섯 단계 고리로 일한다. 에이전트가 먼저 묻고, 장단점을 붙인 선택지를 2~4개 낸다. 사용자가 고르면 초안을 보이고, 승인을 받은 뒤에야 파일을 쓴다. 이 고리를 얼마나 촘촘하게 돌릴지는 modes.automation 이 정한다.

autonomous 에서도 아무것도 묻지 않는 것은 아니다. automation_always_ask 의 기본값에 범위 변경·파일 삭제·스키마 변경이 들어 있고, 핫픽스·게이트 점검·출시 당일 패치·/setup-engine 은 이 설정과 상관없이 늘 협업 방식으로 돈다.

03 무게는 modes.rigor 하나로 고르고, 저자 실험은 가벼운 쪽을 가리킨다

project.yaml 의 modes.rigor 는 하위 설정 여섯 개를 한 번에 펼치는 손잡이다. 기본값은 minimal 이다.

여섯 값 가운데 하나를 project.yaml 에 직접 적으면 그 값이 rigor 보다 앞선다. 템플릿의 project.yaml 주석이 이 여섯 키를 미리 넣지 말라고 적어 둔 것도 그래서다. 넣는 순간 /start 가 정한 rigor 로는 그 항목을 바꿀 수 없다. 리뷰 방식과 팀 규모는 gitignore 대상인 project.local.yaml 에서 개인별로 덮을 수 있다. 시스템 하나만 다른 단계로 다루려면 project.yaml 맨 위의 workflow_overrides.system_overrides 를 쓰는데, 이 값은 단계를 올릴 때도 내릴 때도 쓸 수 있다. 테스트 증거가 빠졌을 때 막을지 경고만 할지는 testing.strict 로 정한다.

README 는 "게임을 만드나, 문서를 만드나" 라는 물음에 직접 잰 값으로 답한다. 저자는 같은 기획서 한 장으로 rigor 를 달리해 게임 넷을 만들고, 첫 게임 코드 전에 쓴 문서 수를 셌다.

빌드는 모두 실행됐고 테스트도 거쳤다. 블라인드 리뷰어 둘과 사람 플레이테스트는 standard 빌드를 꼴찌로 매겼다. 저자는 늘어난 문서가 "추적 가능성은 샀지만 더 나은 게임은 사지 못했다" 고 결론지었다.

이 근거는 무게를 낮춰 읽어야 한다. 저자가 직접 한 실험이고, 게임 넷 가운데 표에 나온 것은 두 수준뿐이며 full 은 빠졌다. 게임과 리뷰 기록도 저장소에 없다. 그러니 "무거운 설정이 게임을 낫게 한다는 근거는 없다" 정도로 받아들이는 편이 맞다. 1.1 버전(2026년 9월 23일)부터 기본값이 standard 에서 minimal 로 바뀌었다. 그 전에 만든 프로젝트를 올리면서 예전 동작을 지키려면 modes.rigor 를 standard 로 적어 두어야 한다.

가벼운 설정에서도 빠지지 않는 규칙이 하나 있다. 플레이어가 보는 화면을 바꾼 스토리는 누군가 게임을 띄워 눈으로 보고 production/qa/evidence/ 에 스크린샷을 남겨야 완료로 친다. 파싱 검사는 실행으로 치지 않는다. 테스트가 통과해도 화면 밖에 그려진 메뉴는 잡지 못한다는 이유에서, minimal 이 자동 테스트를 면제할 때도 이 확인은 남긴다.

04 위험한 명령은 권한 규칙이, 품질 검사는 훅이 맡는다

.claude/settings.json 은 두 겹으로 막는다. permissions.deny 에는 rm -rf 의 여러 변형과 git push --force·git reset --hard·git clean -f, sudo, chmod 777 이 들어 있다. .env 파일 읽기·편집과 Unreal 의 .uasset·.umap 편집도 막는다. 품질 검사는 여덟 개 이벤트에 걸린 훅 15개가 맡는다.

이렇게 나눈 것은 공식 문서의 권고와도 맞는다. 공식 훅 문서는 훅의 조건 필터가 최선 노력일 뿐이니, 반드시 허용하거나 막아야 할 것은 권한 시스템으로 다루라고 권한다. 실제로 쓸 때 걸리기 쉬운 조건은 넷이다.

• 프로젝트 루트(CLAUDE.md·project.yaml 이 있는 곳)에서 claude 를 띄워야 한다. README 는 하위 폴더에서 시작하면 훅·deny 규칙·먼저 묻는 권한이 빠진다고 경고한다.
• Python 3 이 없으면 project.yaml 을 읽지 못해 모든 설정이 아무 말 없이 기본값으로 돌아가고, 데이터 JSON 을 스테이징한 커밋은 막힌다.
• git deny 규칙은 git 뒤 어디에 있든 걸린다. 그래서 git commit -m "push + pull" 같은 커밋 메시지도 거부되는데, 문구를 바꾸면 지나간다.
• 훅은 저장소에 커밋된 셸 스크립트라 세션마다 자동으로 돈다. 남이 만든 템플릿이니 처음 띄우기 전에 .claude/hooks/ 를 읽어 보고, 띄운 뒤에는 /hooks(등록된 훅을 읽기 전용으로 보여 주는 명령)로 확인하는 편이 낫다.

05 장점은 절차와 안전장치, 단점은 토큰·문서·업그레이드 부담이다

비용은 README 가 다루지 않는다. 토큰 비용도 필요한 요금제도 적혀 있지 않아서, 공식 문서로 짚을 수 있는 지점만 정리한다. 공식 비용 문서는 세션 모델을 Opus 로 바꾸면 모델을 물려받는 서브에이전트에도 그대로 적용된다고 적었다. 이 템플릿에서 그 상속 쪽은 30개다. 서브에이전트는 메인 대화와 따로 자기 요청을 보내고, 그 요청도 사용량에 잡힌다.

컨텍스트도 늘어난다. 스킬 본문은 부를 때만 읽히지만 설명은 매 턴 컨텍스트에 실리고, 스킬 하나의 설명(description 과 when_to_use 합계)은 1,536자에서 잘린다. 서브에이전트 쪽은 기본 제공이 아닌 에이전트들의 설명 합계가 15,000토큰을 넘으면 Claude Code 가 시작할 때 경고한다. README 는 이 템플릿의 설명 합계를 밝히지 않았으니, 직접 띄워 /context 로 무엇이 자리를 차지하는지 보는 편이 확실하다. Pro·Max·Team·Enterprise 요금제라면 /usage 에서 최근 사용량 가운데 스킬과 서브에이전트가 차지한 비율도 볼 수 있다. 백그라운드 에이전트의 숨은 요청까지 재는 방법은 Claude Code agent_summary 비용, 평균 2%와 16.4%가 갈리는 이유와 재는 법에 정리했다.

플랫폼도 따져 볼 만하다. README 에 따르면 저자는 주로 Windows 10 과 Git Bash 에서 개발하고, 훅은 macOS·Linux 에서도 시험했다. 다만 데스크톱 알림 훅은 Windows 에서만 동작한다.

06 새 게임은 clone 뒤 /start, 기존 저장소는 브랜치에서 /adopt 부터

필요한 도구는 Git, Claude Code(네이티브 설치 권장, npm 으로 깔면 Node.js 22 이상), Python 3, Bash(Windows 는 Git for Windows)다. 훅 검증용 jq 도 권장한다. 새 게임이라면 템플릿을 그대로 복제한다.

git clone https://github.com/Donchitos/Claude-Code-Game-Studios.git my-game
cd my-game
claude

세션 안에서 /start 를 부르면 rigor 를 정해 project.yaml 에 modes.rigor 와 modes.automation 을 적는다. 엔진을 바로 정하거나 설정을 바꿀 때는 아래처럼 쓴다. --local 을 붙이면 팀이 함께 쓰는 project.yaml 이 아니라 개인 파일 project.local.yaml 에 적힌다.

/start
/setup-engine godot 4.7
/settings modes.rigor=standard
/settings --local modes.review_mode=solo

기존 게임 저장소라면 /adopt 가 출발점이다. /project-stage-detect 가 무엇이 있는지를 본다면, /adopt 는 이미 있는 설계 문서(GDD)·ADR(아키텍처 결정 기록)·스토리가 템플릿의 파이프라인에서 돌아갈 형식인지 감사한다. 범위는 full(기본)·gdds·adrs·stories·infra 가운데 고르고, 결과는 docs/adoption-plan-[날짜].md 하나로 나온다. 스킬 지침은 기존 문서를 다시 만들지 말고 빈 곳만 채우라고 정해 두었다.

그런데 /adopt 를 부르려면 먼저 .claude/ 가 저장소에 들어와 있어야 하고, README 에는 기존 저장소에 템플릿을 넣는 절차가 따로 없다. 가장 가까운 것은 UPGRADING.md 의 "공유 히스토리가 없는 저장소" 방식이다. 이 문서는 .claude/ 를 통째로 가져오라고 하고, 일부만 골라 복사하면 교차 참조가 깨진다고 경고한다. 되돌리기 쉽게 브랜치에서 해 보는 편이 낫다.

git log -- .claude   # 이미 .claude/ 를 손댄 기록이 있는지 먼저 본다
git switch -c try-ccgs
git remote add template https://github.com/Donchitos/Claude-Code-Game-Studios.git
git fetch template --tags
git checkout template/main -- .claude project.yaml
git diff --cached --stat

위 명령에서 project.yaml 은 저장소에 아직 그 파일이 없을 때만 함께 가져온다. 이미 있다면 체크아웃 목록에서 빼고 손으로 합친다. 저장소에 CLAUDE.md 가 없으면 같은 방법으로 가져오고, 있으면 덮지 말고 템플릿 쪽 내용을 손으로 합친다. UPGRADING.md 도 이미 있는 CLAUDE.md·project.yaml 은 체크아웃하지 말고 손으로 병합하라고 적었다. 브랜치에 커밋해 두면, 접을 때는 원래 브랜치로 돌아가 git branch -D try-ccgs 한 줄로 지울 수 있다.

올릴 때는 버전부터 확인한다. git describe --tags --abbrev=0 을 보거나 project.yaml 의 framework.version 을 보면 되는데, 뒤쪽 값은 업그레이드 뒤 늦게 따라올 수 있다. UPGRADING.md 기준으로 .claude/ 아래 템플릿 파일은 새것으로 바뀌고, 게임 코드·레지스트리와 .claude/ 에 직접 더한 파일은 그대로 남는다. 템플릿 파일을 고쳐 썼다면 체크아웃 뒤 git checkout HEAD -- <파일> 로 하나씩 되살릴 수 있다. 다만 되살린 파일은 새 릴리스의 변경을 놓치니, 조금 고친 파일은 새 판에 다시 적용하는 편이 낫다고 이 문서는 권한다. 1.2 버전은 post-compact.sh 를 없앴는데, settings.json 의 PostCompact 항목을 지우지 않으면 압축할 때마다 훅이 실패한다. 1.2 버전부터는 새 릴리스가 나오면 세션을 시작할 때 한 줄로 알려 준다. GitHub 조회는 하루 한 번까지이고, updates.check: false 로 끌 수 있다.

07 작은 팀이라면 새 저장소의 작은 프로토타입부터 해 볼 만하다

판단 기준은 되돌리기와 유지 부담이면 충분하다. 새 저장소나 브랜치에서 쓰는 한, 되돌리기는 지우는 것으로 끝난다. 유지 부담은 가볍지 않다. 1.1 버전은 2026년 9월 23일에 나왔고, 1.2 버전(10월 19일)까지 한 달이 안 되는 사이에 릴리스가 네 번 더 나왔다. 그중 한 패치의 릴리스 노트에는 거의 모든 스킬·훅·에이전트가 바뀌었다는 대목도 있다. 쓰기로 했다면 태그 하나에 고정하고, 올릴 때마다 UPGRADING.md 의 버전별 경고를 읽고 옮기는 편이 낫다.

먼저 해 볼 만한 것은 넷이다.

1. 빈 저장소에서 기본값 그대로 /start 를 부르고, /prototype 으로 한 화면짜리 프로토타입을 만든다. 첫 코드 전에 생긴 문서 수를 세면 README 실험과 견줘 볼 수 있다.
2. 한 세션이 끝나면 /context 와 /usage 로 스킬과 서브에이전트가 차지한 몫을 잰다.
3. 템플릿 전체를 쓰지 않더라도, 위험 명령 deny 목록과 "화면을 바꾼 작업은 실행 화면 캡처가 있어야 완료" 규칙은 자기 저장소로 옮겨 볼 만하다.
4. 스킬을 고친다면 /skill-test static <이름> 으로 구조 검사부터 돌린다. 이 검사는 템플릿 자체를 시험할 뿐, 게임을 시험하지 않는다.

deny 목록을 옮긴다면 시작은 아래 정도다. 원본은 rm·git clean 의 옵션 순서 변형과 PowerShell 판까지 130줄로 막으니, 이 다섯 줄로 모든 변형이 막히지는 않는다.

{
  "permissions": {
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)",
      "Read(**/.env*)",
      "Edit(**/.env*)"
    ]
  }
}

웹 게임이라면 기대치를 낮춰야 한다. README 가 다루는 엔진은 Godot·Unity·Unreal 셋이고, 엔진 에이전트 세트를 아예 고르지 않는 선택지도 있다. Phaser 같은 웹 엔진으로 만들면 엔진 전문가와 엔진별 테스트 명령은 쓸 데가 없고, 위계·절차·훅·QA 규칙만 남는다. 웹 엔진을 고르고 에이전트에게 엔진을 알려 주는 방법은 AI 로 게임 만들기: 웹 엔진 고르기부터 Steam 공개까지에서 다뤘다. 팀 리드라면 기존 게임 저장소에 바로 합치기보다, 새 프로토타입 저장소에서 문서량과 사용량을 확인한 뒤 합칠지 정하는 순서가 안전하다.

08 자주 묻는 질문

업그레이드하면 내가 고친 에이전트도 덮이나?

기본은 덮인다. 템플릿 파일은 새것으로 바뀌므로 고친 에이전트·스킬은 체크아웃 뒤 하나씩 되살리거나 새 판에 다시 적용해야 한다. .claude/ 에 따로 더한 파일은 지워지지 않으니, 처음부터 원본을 고치지 말고 새 파일로 더해 두면 업그레이드가 가볍다.

전투 시스템 하나만 다르게 관리할 수 있나?

예. 전체 rigor 는 그대로 두고 workflow_overrides.system_overrides 에 시스템 이름과 단계를 적으면 그 시스템만 다른 단계로 다룬다. 전체를 full 로 둔 채 덜 중요한 시스템만 가볍게 내리는 데도 쓸 수 있다.