AI에게 내 게임을 플레이시키기: 에이전트용 텍스트 테스트 하네스 만들기

Who Should Read

유닛 테스트만으로는 실제 동작 검증이 어려워 Claude Code 같은 에이전트에게 앱을 직접 돌려 테스트시키고 싶은 개발자

Core Mechanics

• 브라우저 자동화 대신 텍스트 하네스
  • 브라우저 자동화 MCP는 화면 이동만 해도 스크린샷이 엄청나게 필요하다고 판단했다.
  • 게임이 텍스트 중심이고 턴제라서 Node.js 래퍼로 텍스트 렌더러와 합성 이벤트를 붙였다.
  • 게임 원본 파일은 수정하지 않았다.
• 상태를 텍스트로 뽑아 AI에게 준다
  • 플레이어·적·단서 패널을 전부 텍스트로 출력한다.
  • 길 찾기용으로 AI가 읽기 쉬운 컴팩트 맵도 따로 추가했다.
  • 에이전트는 서버 실행, 스냅샷 확인, 키 전송, 새 상태 읽기를 stateless HTTP 호출로 반복한다.
• 시나리오 fixture로 버그 재현
  • AI가 특정 상황을 만드는 최소 fixture를 직접 설계하게 했다.
  • 버그를 설명하면 재현하고, 코드를 고치고, 고친 뒤 다시 검증한다.
• 마일스톤마다 플레이테스트 시키기
  • 새 기능을 넣을 때마다 정상 경로와 여러 시나리오를 플레이테스트한 뒤 다음으로 넘어가게 지시했다.
  • 테스트 중 cage 상태가 풀리지 않는 버그를 AI가 스스로 찾아 고쳤다.
• 12분에 기능 5개 구현·검증
  • Claude Code(Sonnet 4.6, Pro 플랜)로 마일스톤 13의 특수 기능 5개를 약 12분, 약 120k 토큰에 끝냈다.
  • 단위 테스트는 204개가 통과한 상태였다.
• 사람 플레이는 여전히 필요하다
  • 사람이 직접 해 보니 버그와 '손맛' 문제가 여전히 나왔다.
  • 하지만 30분 안에 끝났고 목록으로 적어 AI에게 한 번에 고치게 했다.

Community Reactions

• 결정론적 게임이면 LLM 없이 시뮬레이션하라는 의견
  • 한 댓글은 렌더링과 로직을 분리하고 헤드리스로 수백만 판을 돌려 적 AI를 튜닝했다는 경험을 공유했다.
  • 같은 입력이면 같은 출력이라 리플레이도 가능하다고 했다.
• 실시간 게임은 상태 조회 API가 핵심이라는 경험
  • 물리 기반 실시간 게임은 브라우저 MCP로 테스트하기 어렵다는 댓글이 있었다.
  • 물리 엔진을 앞뒤로 스텝하는 API와 window.game API를 줬지만 '완벽히 동작한다'는 오판이 가끔 나왔다고 한다.
• E2E 웹 테스트에서 토큰을 10배 줄였다는 경험
  • 한 댓글은 raw DOM 대신 접근성 트리 ref(e1, e2...)를 쓰자 토큰 사용량이 약 10배 줄었다고 했다.
  • 코드 분석과 라이브 브라우저 스냅샷을 함께 줘야 테스트 품질이 크게 올랐다고 했다.
• 텍스트 방식의 한계를 지적하는 의견
  • 한 댓글은 텍스트 표현만으로 되는 게임은 일부뿐이라 픽셀과 OS 입력 기반으로 갔다고 했다.

How to Apply

• 앱 상태를 텍스트로 뱉는 엔드포인트 만들기
  • 오늘 기존 상태 객체를 사람이 읽는 텍스트로 바꾸는 GET /state 하나를 추가하라.
  • 원본 로직은 건드리지 말고 래퍼 서버에서 호출하라.
  • 에이전트가 curl만으로 읽을 수 있는지 확인하라.
• 입력 전송 엔드포인트와 fixture 로더 추가하기
  • /key?k=... 같은 입력 엔드포인트를 만들어 상태 변화를 확인하라.
  • 특정 상태를 바로 불러오는 fixture 로더를 붙여 버그 재현 시간을 줄여라.
• 마일스톤 지시문에 플레이테스트 의무 넣기
  • 기능마다 정상 경로와 엣지 케이스를 직접 돌려 확인한 뒤 다음으로 넘어가라고 지시하라.
  • 발견한 버그는 fixture로 재현시키고 수정 후 재검증하게 하라.
• 사람 테스트 결과는 모아서 한 번에 넘기기
  • AI 검증 후 30분 정도 직접 플레이하며 버그와 느낌 문제를 적어라.
  • 목록 전체를 AI에게 주고 수정과 검증을 한 번에 시켜라.

Try It

# Claude Code에 그대로 붙여넣기 (원문 방법을 프롬프트로 옮긴 것)

이 프로젝트에 에이전트용 플레이테스트 하네스를 만들어줘.

요구사항:
1. 기존 소스 파일은 수정하지 말고 별도 Node.js 래퍼 서버를 추가한다.
2. GET /state: 현재 {{앱/게임}} 상태를 사람이 읽는 텍스트로 반환한다.
3. GET /key?k=...: 입력 이벤트를 앱에 전달하고 새 상태 텍스트를 반환한다.
4. fixture 로더: 특정 시나리오 상태를 바로 불러올 수 있게 한다.

그다음 {{기능 이름}}을 구현하고, 하네스로 정상 경로와 엣지 케이스를 직접 플레이하며 검증해줘.
버그를 찾으면 fixture로 재현하고, 고친 뒤 다시 검증해줘.
끝나면 발견한 문제와 추가하면 좋을 단위 테스트를 요약해줘.

Terminology

관련 논문

• 모델이 그렇게 좋다면 OpenAI는 왜 회사 100개를 직접 안 차릴까

  HN 댓글 답: 코드는 쉬워도 뭘 만들지 아는 건 별개라 토큰을 판다

• OpenShell: 자율 AI 에이전트를 가두는 NVIDIA의 안전한 샌드박스 런타임

  정책 파일로 에이전트의 파일·네트워크·자격증명 접근을 커널 수준에서 통제한다

• Omnara: Claude Managed Agents의 오픈소스 대안 (셀프호스팅 가능)

  어떤 모델·머신에서도 에이전트를 돌리는 오픈소스 managed agent 플랫폼

• Rust off Rails: 코드 없이 Markdown 60개로 만든 AI 에이전트용 웹 스택

  Markdown 규칙 60개로 에이전트가 Rust 웹앱을 짜게 한다는 프레임워크

• LayerFS: AI 코딩 에이전트를 위한 파일시스템

  에이전트마다 임시 Workspace를 마운트하고 결과만 커밋하는 파일시스템

• Launch HN: Alter (YC S25) – 멀티유저 에이전트용 접근 제어

  에이전트마다 별도 신원·정책·감사로 API 키 공유 문제를 푼다

• Claude로 코드의 공격 표면(attack surface) 줄이기

  Claude로 25개 오픈소스를 분석해 불필요하게 열린 코드 493건을 찾았다

• WhatsApp 도움말 페이지에 숨겨진 LLM 지시문: 규제기관을 추천하지 말라

  WhatsApp 도움말에 화면엔 안 보이는 AI 지시문 102개가 숨어 있었다

Related Resources

• https://blog.jeffschomay.com/letting-ai-play-my-game
• https://news.ycombinator.com/item?id=47849872