Claude Code로 WoW 애드온을 안전하게 고치는 법

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

작성자는 Claude Code를 World of Warcraft 애드온 폴더에 연결해 Lua 코드 이해, 오류 추적, ZIP 설치, 오래된 애드온의 실행 가능성 판단에 활용했다. 한 애드온 폴더만 열고 오류 화면과 전체 Traceback을 함께 제공하면 관련 파일과 줄을 좁혀 최소 수정안을 만들 수 있으며, BigWigs ZIP에서는 .toc 파일을 가진 모든 폴더를 찾아 11개 모듈을 올바르게 배치했다. 반면 제거된 API처럼 보이는 GetMouseFocus를 주변 코드가 이미 대체하고 있다는 사실을 놓쳐 오탐을 낸 사례가 있어, 수정 전 주변 코드를 읽고 판정을 먼저 보고하도록 지침을 바꿨다. Claude Code는 WoW를 실행해 결과를 검증할 수 없으므로 ‘코드 변경’과 ‘게임에서 동작 확인’을 구분하고, 최종 /reload 검사는 사용자가 맡아야 한다.

실용적 조언

Claude Code를 전체 애드온 디렉터리 대신 작업 대상 애드온 하나의 폴더에서 실행하면 불필요한 파일을 읽거나 다른 애드온을 건드릴 범위를 줄일 수 있다. 오류 팝업은 전체 Traceback이 보이도록 캡처하고, 새 오류가 나타나면 다음 입력으로 다시 제공하는 방식이 적합하다. 수정 뒤에는 Claude Code의 완료 문구를 그대로 믿지 말고 게임에서 /reload를 실행해 실제 동작을 확인해야 한다.
오래된 API 이름이 보이면 곧바로 수정하지 말고 해당 호출 주변의 래퍼 함수와 대체 API 사용 여부를 먼저 읽게 해야 한다. Claude Code가 판정과 수정 작업을 한 번에 수행하지 않도록, 편집 전에 ‘오래된 API가 이미 처리됐는지’와 최종 판단을 문장으로 보고하게 만들면 오탐 수정 가능성을 낮출 수 있다. 결과 보고에는 ‘코드 변경’과 ‘게임에서 동작 확인’을 별도 상태로 남기는 편이 안전하다.
공통 안전 규칙은 AGENTS.md에 저장하고 Claude Code용 CLAUDE.md에서는 @AGENTS.md로 불러오면 같은 규칙을 여러 도구에 재사용할 수 있다. 대상 애드온 제한, WTF 폴더 금지, 첫 편집 전 백업, 최소 변경, 오류 은폐 금지, 필요한 게임 기능이 사라진 경우 중단을 기본 규칙으로 둘 수 있다. 특히 백업은 다른 규칙이 실패해도 원래 폴더로 되돌릴 수 있는 직접적인 복구 수단이다.

섹션별 상세

작성자는 Claude Code를 전체 AddOns 디렉터리가 아니라 애드온 하나의 폴더에 연결하고, Lua 오류 팝업과 Traceback을 입력으로 사용했다. Traceback에 포함된 애드온 경로, 파일명, 줄 번호가 관련 파일을 찾는 단서가 되고, Claude Code는 가장 작은 수정 후 사용자가 게임에서 /reload를 실행하는 짧은 피드백 루프를 따른다. 이 방식은 코드 변경과 실제 게임 동작을 빠르게 대조할 수 있을 때 신뢰할 만한 결과를 얻는다는 경험에 기반한다.

TomTom을 점검할 때 Claude Code는 .toc 파일과 Lua 파일을 읽고, 선언된 인터페이스 버전과 설치된 빌드 12.1.0.69497을 대조한 뒤 changelog까지 확인했다. 다만 파일을 읽은 사실만으로 실행 성공을 선언하지 않고, 게임 안에서 /way 50 50 test를 입력해 Lua 오류가 없는지 확인하도록 했다. 이 사례는 소스 파일 기반 판단과 런타임 검증을 서로 다른 단계로 유지한 경우다.

BigWigs ZIP 설치에서는 하나의 압축 파일에 들어 있는 11개 애드온 폴더를 테스트 디렉터리에 각각 배치하고 결과를 목록으로 남겼다. 처음 지침의 ‘애드온 폴더를 찾아라’라는 단수 표현은 11개 중 하나만 설치할 위험이 있었지만, .toc 파일을 포함한 모든 폴더를 찾도록 바꾸면서 구조가 다른 실제 압축 파일에도 대응했다. 작성자는 이 사례를 통해 프롬프트를 다시 읽는 것보다 실제 파일 구조를 대상으로 실행하는 편이 누락을 드러내는 데 효과적이라고 판단했다.

lua

local function GetMouseFocus() local objects = GetMouseFoci(); return objects and objects[1] end

Plumber가 제거된 API처럼 보이는 호출을 자체 함수로 감싼 사례이며, 주변 코드를 읽지 않으면 오탐으로 이어질 수 있다.

Plumber 검사에서는 게임 API에서 제거된 GetMouseFocus 호출을 발견하고 애드온이 깨졌다고 판단했지만, 실제 코드는 세 줄 떨어진 래퍼 함수에서 GetMouseFoci를 호출하고 있었다. 오래된 함수명이 있다는 사실만으로 결론을 내리면 정상 코드를 수정할 수 있으므로, 작성자는 주변 구현을 먼저 읽고 편집 전에 판정을 문장으로 보고하도록 규칙을 추가했다. Claude Code가 WoW 클라이언트를 실행할 수 없기 때문에 ‘code changed’와 ‘confirmed working in game’을 분리해서 출력하게 한 점도 같은 안전장치에 속한다.

text

@AGENTS.md

Claude Code가 자동으로 읽지 않는 AGENTS.md를 CLAUDE.md에서 불러오도록 만든 한 줄짜리 프로젝트 지침이다.

작성자는 AGENTS.md에 공통 규칙을 두고 CLAUDE.md에서 @AGENTS.md 한 줄로 불러오게 구성했다. 규칙은 대상 애드온만 수정하고 WTF 폴더는 건드리지 않으며, 첫 편집 전에 백업하고, 작동 중인 코드를 정리하지 않고, 오류를 숨기지 않으며, 애드온에 필요한 게임 기능이 사라졌다면 중단하고, 결과를 ‘working’이 아니라 ‘code changed’로 보고하도록 제한한다. 실행 전 잠금 장치는 아니지만, 백업 규칙은 다른 지침이 실패했을 때 복구 경로를 남긴다.

용어 해설

.toc 파일(.toc file): — .toc 파일은 World of Warcraft 애드온의 이름, 버전, 인터페이스 호환 정보와 불러올 Lua 파일 목록을 적는 매니페스트다. 애드온 구조와 게임 버전 호환성을 판단하는 출발점으로 쓰인다.
Traceback: — Traceback은 오류가 발생한 호출 경로를 파일명, 애드온 경로, 줄 번호와 함께 기록한 정보다. Claude Code는 이 위치 정보를 바탕으로 관련 파일을 찾고 수정 범위를 좁힌다.
정적 분석(Static Analysis): — 정적 분석은 프로그램을 실행하지 않고 소스 코드와 설정 파일을 읽어 API 호출, 파일 구조, 호환성 문제를 판단하는 방식이다. 실제 게임 안에서 수정 결과가 동작하는지는 별도로 검증해야 한다.
API 변경(API Change): — API 변경은 기존 애드온이 호출하던 게임 기능의 이름이나 동작이 바뀌는 상황이다. 오래된 함수명이 보여도 주변 코드가 대체 함수를 감싸고 있으면 실제 오류가 아닐 수 있다.