mshumer/Claude-of-Duty 딥다이브
— AI 에이전트 함대가 한 개의 프롬프트로 만든 웹 브라우저 FPS 게임

1프로젝트 한 줄 요약

Claude of Duty는 웹 브라우저에서 바로 실행되는 1인칭 슈팅 게임이다. npm install 후 npm run dev만 하면 http://127.0.0.1:5173에서 돌아간다. 캔버스를 클릭하면 마우스가 잠기고(FPS 조작 시작), WASD로 이동·마우스로 조준·좌클릭 사격·우클릭 조준(ADS)·R 재장전·Shift 질주 같은 표준 FPS 조작을 지원한다.

기술적으로 요약하면 이렇다. 렌더링은 Three.js r180 + WebGL2 기반의 본격 HDR 파이프라인(그림자·앰비언트 오클루전·안티에일리어싱·블룸·톤매핑)을 직접 구현했고, 물리 엔진·오디오 합성·AI 적 캐릭터까지 전부 외부 라이브러리 없이 자작했다. 그리고 이 모든 걸 사람이 아니라 AI 에이전트 함대가 ARCHITECTURE.md라는 "계약서" 하나를 공유하며 병렬로 작성했다.

2왜 지금 주목받는가

이 레포의 가치는 "AI가 게임을 만들 수 있다"는 신기함을 넘어선다. README와 ARCHITECTURE.md에 담긴 협업 방법론과 정직한 실패 기록이 개발자 커뮤니티에서 화제가 됐다. 세 가지 이유가 있다.

① "단일 프롬프트 → 66k 줄"이라는 극단적 실험

prompt.md에 이 저장소를 만든 프롬프트 전문이 그대로 들어있다. 핵심은 "서브 에이전트를 펼쳐(fan out) 각자 하나씩 맡게 하고, 별도의 아주 혹독한 비평가 에이전트가 시각적으로 검사해 AAA 수준이 아니면 계속 반복(loop)하라"는 것. 즉 사람이 코드를 짜는 게 아니라, 에이전트들에게 역할을 나눠주고 서로 검증시키는 구조를 프롬프트 한 방으로 지시했다.

② "게임 코드"가 아니라 "하네스"가 진짜 주인공

README가 직접 "이 레포에서 흥미로운 부분은 게임이 아니라 하네스(harness)일 것"이라고 못 박는다. tools/ 폴더엔 헤드리스 Chromium으로 스크린샷을 찍고, 픽셀 단위로 비교해 회귀를 잡아내는 검증 도구 모음이 있다. AI가 화면을 "본다"고 착각하지 않게, 기계적으로 측정 가능한 게이트를 만든 것이 이 프로젝트의 진짜 엔지니어링이다.

③ 실패를 숨기지 않는 "정직한 평가" 문서

대부분의 화려한 AI 데모가 잘 된 장면만 보여주는 것과 달리, 이 레포는 어디서 실패했는지를 조목조목 적어뒀다. 11명의 적대적 비평가 에이전트가 매긴 점수는 10점 만점에 3.59 → 4.14 → 4.05 → 5.05로 올랐지만, 블라인드 A/B 테스트에서 모든 비평가가 매번 진짜 콜 오브 듀티 화면을 골라냈다. 손(손가락이 총을 제대로 못 쥠), 재질의 리얼함, 원거리 적 캐릭터, 간접광(GI) 근사, 프레임레이트 등 부족한 점을 구체적 수치와 함께 나열한다.

3기술 스택 전체 지도

이 프로젝트의 스택은 극단적으로 얇다. 게임이 실제로 돌 때 필요한 외부 라이브러리는 three 딱 하나다. 이것이 ARCHITECTURE.md의 "하드 룰(Hard rules)" 3번 — "새 npm 의존성 금지, three만, CDN·외부 이미지·HDRI·모델·오디오 파일 금지. 게임은 완전히 오프라인으로 돌아야 한다" — 때문이다.

렌더링 / 그래픽 (게임 화면을 그리는 층)

절차적 생성 (에셋을 코드로 만드는 층)

물리 / AI / 개발 도구

4아키텍처 심화 분석

이 게임의 아키텍처는 AI 에이전트 병렬 작업을 안전하게 만들기 위해 설계됐다. 핵심 아이디어는 "엔진(Engine)은 각 서브시스템이 무슨 일을 하는지 전혀 모르고, 오직 실행 순서만 지휘한다"는 것. 각 에이전트는 자기 디렉토리만 소유하고, 남의 모듈을 import하지 않는다. 필요하면 런타임에 ctx.get('fx')로 꺼내 쓴다. 이 규칙이 병렬 작업 중 서로의 코드를 망가뜨리지 않게 하는 열쇠다.

전체 시스템 구조도

핵심 설계 패턴 4가지

① 서브시스템 인터페이스 — 모두가 같은 모양

모든 서브시스템은 아래 뼈대를 따른다. 이 통일된 계약 덕에 엔진은 순서만 돌리면 된다.

export class MySystem {
  static id = 'mysystem';      // 고유 이름 — 남들이 나를 찾는 열쇠
  static deps = ['render'];    // 나보다 먼저 init 돼야 하는 것들

  async init(ctx) {}          // 리소스 생성 (await 가능)
  fixedUpdate(h, ctx) {}       // 120Hz 결정론적 게임플레이
  update(dt, ctx) {}           // 프레임당 1회
  lateUpdate(dt, ctx) {}       // 모든 update 후
  dispose() {}                 // 내가 만든 것 정리
}

② 결정론(Determinism) — Math.random() 금지

하드 룰 4번: "게임플레이나 비주얼에서 Math.random() 금지. ctx.rng를 써라." 왜? 캡처 재현성 때문이다. 같은 시드(seed)에서 항상 같은 결과가 나와야, 스크린샷 회귀 테스트가 "이 픽셀이 바뀌었다"를 신뢰할 수 있다. 엔진은 config.deterministic이면 고정 시드 0x5eed1234를 쓴다.

③ 제로 할당(Zero-allocation) 루프

하드 룰 5번: "프레임당 아무것도 새로 할당하지 마라." update() 안에서 new THREE.Vector3()를 만드는 건 버그로 취급한다. 벡터·행렬·배열은 init()에서 미리 만들어 재사용한다. 매 프레임 60번씩 객체를 새로 만들면 가비지 컬렉터가 돌며 프레임이 뚝뚝 끊기기(hitch) 때문이다.

④ 고정 스텝(Fixed timestep) + 보간

물리는 120Hz 고정 스텝(fixedUpdate)으로 돌아 프레임레이트와 무관하게 항상 같게 동작하고, 화면은 time.alpha(0~1)로 마지막 두 물리 스텝 사이를 보간(interpolate)해 부드럽게 그린다. 게임 물리의 정석 패턴이다.

렌더링에서 배우는 실전 교훈: "중앙값은 진짜 문제를 숨긴다"

5디렉토리 구조 해부

디렉토리 구조가 곧 작업 분담표다. ARCHITECTURE.md의 "소유권 지도(Ownership map)"가 각 폴더의 주인을 못 박아, 에이전트끼리 남의 영역을 건드리지 못하게 한다. 아래는 실제 소스 라인 수까지 집계한 것.

tools/ — 이 레포의 숨은 핵심

6학습 포인트 — 이 레포에서 배울 것

① AI 에이전트 오케스트레이션 설계

가장 값진 부분. 순차 단일 소유 vs 병렬 팬아웃의 실증 비교(§2 참고)는 AI로 큰 코드베이스를 만들려는 모든 사람에게 적용된다. 핵심 원리: "강하게 결합된 문제(coupled concern)는 한 에이전트가 순차로 맡아야 한다." 톤매핑·하늘·간접광처럼 서로 물린 문제를 여러 에이전트가 나누면 서로의 가정을 계속 깨뜨린다.

② 절차적 생성 (텍스처·오디오·지오메트리)

materials/는 노이즈 함수·Sobel 높이→법선 변환·시차 오클루전 매핑·삼중평면(triplanar) 투영으로 19종 표면을 만든다. audio/는 파형 합성·컨볼루션 리버브·HRTF 공간화로 소리를 만든다. 파일 없이 콘텐츠를 만드는 기법은 웹 게임·데모신(demoscene)·생성 예술에 직결된다.

③ 현대 실시간 렌더 파이프라인

HDR → MRT 프리패스(깊이/법선/속도) → GTAO → TAA(YCoCg 분산 클리핑) → 모션블러 → 블룸 → EV100 자동노출 → LUT → AgX. 이 후처리 체인 전체를 실제 코드로 읽을 수 있는 희귀한 오픈소스다. 게임 그래픽 프로그래밍 교재로 손색없다.

④ 결정론적 회귀 테스트 (스크린샷 게이트)

"AI가 만든 UI/그래픽이 안 망가졌는지"를 어떻게 자동으로 검증하는가에 대한 실전 답. 고정 시드 + 격리된 페이지 + 픽셀 diff 조합은 프론트엔드 비주얼 회귀 테스트에도 그대로 쓸 수 있다.

⑤ 성능 프로파일링 방법론

"중앙값이 아니라 분포(p50/p95/p99)를 보라", "정적 벤치마크가 아니라 실제 사용 시나리오를 재라"는 교훈은 웹·백엔드·모바일 모든 성능 최적화에 공통이다.

⑥ 라이브러리 없이 물리 엔진 만들기

BVH 브로드페이즈(29k 삼각형 → 22ms에 14k 노드, 레이캐스트당 0.25µs)·스윕 캡슐 캐릭터 컨트롤러·CCD 강체·PBD 래그돌·다층 탄환 관통을 자작. 충돌 검출·공간 분할의 정석 자료구조를 실제 구현으로 학습할 수 있다.

7하드웨어 / 시스템 요구사항

8직접 해볼 수 있는 실습 과제

🟢 입문 Lv.1

1. 실행하고 하드 룰 읽기. 레포를 클론해 npm install && npm run dev로 게임을 켜본다. 그다음 ARCHITECTURE.md의 "Hard rules" 7가지를 읽고, 각 규칙이 왜 AI 병렬 작업에 필요한지 한 줄씩 정리해본다.

2. 프리셋 바꿔보기. src/core/config.js에서 quality를 ultra→low로 바꿔 fps가 얼마나 오르는지, 화면이 어떻게 달라지는지 관찰한다.

🟡 중급 Lv.2

3. 스크린샷 하네스 돌려보기. node tools/capture.mjs로 한 장면을 캡처하고, baseline.mjs → imagediff.mjs 흐름을 실행해 "픽셀 게이트"가 어떻게 작동하는지 본다. 코드를 일부러 조금 바꿔 diff가 실패하게 만들어본다.

4. 새 텍스처 추가. materials/에서 기존 절차적 표면 하나(예: 벽돌)를 복제·변형해 새 재질을 만들고, world에 적용해본다.

🔴 고급 Lv.3

5. 새 서브시스템 만들기. ARCHITECTURE.md의 인터페이스를 따라 static id·init·update를 가진 새 시스템(예: 날씨 효과)을 추가하고, ctx.events로 기존 시스템과 연동한다. 남의 모듈을 import 없이.

6. 이 방법론을 내 프로젝트에 이식. 내가 만들려는 앱에 대해 ARCHITECTURE.md 스타일 계약서를 쓰고, AI 에이전트에게 "순차 단일 소유" 방식으로 서브시스템을 하나씩 맡겨본다.

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

• 레포: github.com/mshumer/Claude-of-Duty — 특히 prompt.md·ARCHITECTURE.md·README를 꼭 읽을 것
• Three.js 공식 문서: threejs.org/docs — 이 게임의 유일한 런타임 의존성
• LearnOpenGL: learnopengl.com — PBR·후처리·그림자 이론의 표준 교재(WebGL에도 적용)
• Fix Your Timestep!: Glenn Fiedler의 고정 스텝 루프 고전 아티클
• Web Audio API: MDN Web Audio — 이 레포의 절차적 사운드 합성 기반
• Vite: vitejs.dev — 개발 서버 & 번들러
• Playwright: playwright.dev — 헤드리스 캡처 하네스의 엔진