pattern: autoplay-bot-blamed-for-balance

source: manual

adapter: rhythm-battle

task_label: stat-injection-fix

error_message: rhythm-battle autoplay 봇이 패배하는 이유를 봇 로직 버그로 의심했으나, 실제로는 기본 밸런스 문제 (baseDamage 낮음, bossHP 높음). 봇은 정상 작동 중.

resolution: 봇 코드 조사 → 정상 확인 (노트 인식/타이밍 정확) → 밸런스 수치 확인 → baseDamage/bossHP 조정으로 해결

trigger_condition: autoplay 테스트 실패 시 봇 로직을 먼저 의심하고, 실제로는 데이터/밸런스가 원인인 경우

resolution_pattern: 1) 봇 로직 간단 검증 (노트 인식, 입력 타이밍 정상?) 2) 밸런스 수치 확인 (승리 가능한 데미지인가?) 3) 봇 수정은 최후 수단 4) 데이터 먼저, 코드 나중 원칙

applicable_when:
autoplay 봇 존재
테스트 실패
로직/데이터 경계가 불명확
밸런스 조정 가능한 게임

not_applicable_when:
봇 코드에 명백한 에러 로그
봇이 아예 실행 안됨
밸런스 수정 불가능 (고정 설계)

status: active

notes: stat-injection-fix-report.md에서 발견. rhythm-battle 봇 조사 후 로직 정상 확인, 밸런스 문제로 판명. 일반적 패턴: 실패 → 코드 의심보다 데이터 먼저 확인.


pattern: standalone-mode-early-exit-no-callback

adapter: adapter-bridge

task_label: bridge-fix

error_message: adapter-bridge.js가 standalone 모드에서 if (!isIframe) return; early exit하여 onComplete 콜백 미등록 → Playwright 직접 URL 접근 시 BattleResult 미수신

resolution: standalone 모드에서도 onComplete 등록, window.__lastBattleResult 노출. early return 전에 핸들러 등록 또는 standalone 분기 추가.

trigger_condition: iframe 체크 후 early return하는 구조에서, standalone 모드 실행 시 필수 핸들러 미등록

resolution_pattern: 1) early return 전에 필수 핸들러 등록 2) 또는 standalone 모드 분기 추가 (if (!isIframe) { /* standalone 핸들러 */ return; }) 3) iframe 여부와 무관하게 핸들러는 등록, postMessage 전송만 조건부

applicable_when:
postMessage 기반 통신
iframe/standalone 양쪽 지원 필요
테스트 환경이 standalone URL 직접 접근
early return 패턴 사용

not_applicable_when:
iframe 전용 설계 (standalone 지원 불필요)
postMessage 미사용
early return 없음

status: excluded

exclude_reason: 이미 bridge-fix-report에서 수정 완료. standalone 모드 핸들러 등록 추가됨 (2026-03-15). 현재 시스템에서 더 이상 발생 안 함.

notes: bridge-fix-report.md에서 발견. 수정 완료되었으나 교훈으로 기록. 향후 유사 구조 설계 시 참고용.


pattern: adapter-integration-repetitive-manual

error_message: 7개 어댑터에 adapter-bridge.js 스크립트 태그 추가 작업 반복 (각 15-30분 × 7 = 2-4시간 소요)

resolution: 체크리스트 작성, 각 어댑터 HTML 수동 편집. 향후 공통 스크립트 자동 주입 방안 검토.

trigger_condition: 공통 모듈(bridge, shim, hints-common 등) 업데이트 시, 각 어댑터에 수동 통합 필요

resolution_pattern: 1) 공통 스크립트를 shared/ 경로에 두고 전 어댑터가 참조 (CDN 방식) 2) 또는 빌드 스크립트로 자동 주입 3) 어댑터 템플릿 HTML 생성기 (adapter-template.html) 4) 최소: 체크리스트 + 자동 검증 스크립트

applicable_when:
다수 어댑터 존재 (5개+)
공통 인프라 변경 빈도 높음
수동 통합 시간 비용 큼 (1시간+)

not_applicable_when:
어댑터 3개 이하
공통 인프라 변경 드묾 (1회성)
각 어댑터 구조가 너무 달라 자동화 불가능

notes: balance-v3-action-items.md에서 발견. 7개 어댑터 반복 작업 필요. 자동화 미구현 상태.


pattern: stat-params-ignored-hardcoded-level

adapter: multi-adapter

error_message: 전 어댑터에서 쿼리 파라미터 (pHP, pATK, eHP 등) 파싱하지만 실제 게임 로직에 미반영. enemyLevel=1 하드코딩 유지.

resolution: 각 어댑터의 CONFIG/CHARACTER_STATS 초기화 시점에 URL 파라미터 값 주입 코드 추가. 파싱 후 console.log로 적용 확인.

trigger_condition: URL 파라미터 파싱 코드 존재하나, 파싱된 값을 게임 초기화 시 실제 변수에 대입하지 않음

resolution_pattern: 1) 파싱 후 반드시 적용 검증 단계 추가 (console.log로 CONFIG/CHARACTER_STATS 확인) 2) 파싱과 적용을 한 함수에서 처리 (parseAndApplyStats) 3) E2E 테스트에서 스탯 반영 확인 (난이도별 승률 차이)

applicable_when:
다단계 데이터 흐름 (파싱 → 정제 → 적용)
서브에이전트가 파싱만 구현
적용 누락 가능성 높음

not_applicable_when:
파싱과 적용이 한 줄 (직접 대입)
단순 구조
적용 누락 불가능

notes: balance-v4-report.md에서 발견. 전 어댑터 공통 문제. 일부 수정됨 (stat-injection-fix-report), 하지만 새 어댑터에서 재발 가능.


adapter: auto-battle

error_message: Easy 난이도에서 패배, Hard 난이도에서 승리 발생 (난이도 역전 현상)

resolution: 스탯 파라미터를 게임 로직에 정상 반영 후 해결. 난이도별 결과 분포 확인 (Easy>Equal>Hard 순 승률).

trigger_condition: 난이도 파라미터 전달되나 게임 로직에 미반영, 승패가 RNG나 고정 밸런스에만 의존

resolution_pattern: 1) 난이도 파라미터를 실제 게임 변수(enemyHP, enemyATK)에 매핑 2) 난이도별 결과 분포 확인 (Easy>Equal>Hard 순 승률 예상) 3) 역전 발견 시 매핑 누락 의심 4) 자동 테스트로 난이도 곡선 검증

applicable_when:
다난이도 게임
파라미터 전달 구조 존재
자동 테스트로 역전 감지 가능

not_applicable_when:
단일 난이도
난이도가 의도적으로 역전 (hard가 쉬운 설계)
테스트 불가능

notes: balance-v4-report.md에서 발견. auto-battle에서 Easy 패배, Hard 승리. 원인: enemyLevel=1 고정 (스탯 미반영).


pattern: stat-scaling-ui-only-judge-ignored

adapter: visual-novel

task_label: hints-expansion-review

error_message: atkToPersuasion, defToResilience 등 스탯 스케일링이 UI 레이어(onChoice 함수)에만 적용, __JUDGE__.applyTurn 순수 함수는 스탯 무시 → 시뮬레이션 vs 실제 불일치

resolution: 스탯 연동을 applyTurn 순수 함수 내부로 이동. UI와 순수 함수 모두 같은 스탯 적용 로직 사용.

trigger_condition: UI 레이어와 순수 함수(__JUDGE__) 분리 구조에서, 스탯 스케일링이 UI만 적용되고 순수 함수는 고정 공식 사용

resolution_pattern: 1) 순수 함수에 스탯 파라미터 추가 (__JUDGE__.applyTurn(state, choice, stats)) 2) UI와 순수 함수 모두 같은 스탯 적용 로직 사용 3) E2E 테스트에서 시뮬레이션 vs 실제 결과 비교

applicable_when:
UI/비즈니스 로직 분리
__JUDGE__ 같은 순수 함수 존재
시뮬레이션 기능 제공 (flat 상관 검증 필요)

not_applicable_when:
UI와 로직 미분리
순수 함수 없음
시뮬레이션 불필요

notes: hints-expansion-review-2026-03-19.md에서 발견. visual-novel 스탯 연동 재작업 필요 권고됨. flat 상관 문제 (UI와 순수 함수 불일치).


error_message: 9종 어댑터 모두 atmosphere 기능 독자 구현 (~80% 코드 유사도, 총 8000줄 중복 추정)

resolution: shared/hints-common.js로 공통 모듈 추출 권장 (30% 코드 감축 가능). applyAtmosphere, checkTurnLimit 등 공통 함수 제공.

trigger_condition: 여러 어댑터에서 동일 기능(atmosphere, turnLimit 체크 등) 구현 시, 각각 독자 구현 (코드 유사도 70%+)

resolution_pattern: 1) 공통 함수를 shared/ 모듈로 추출 (applyAtmosphere, checkTurnLimit, parseCommonHints) 2) 각 어댑터는 import하여 사용 3) 중복 코드 제거, 단일 소스 유지

applicable_when:
3개 이상 어댑터가 같은 기능 구현
코드 유사도 높음 (70%+)
공통 모듈 추출 가능

not_applicable_when:
어댑터마다 구현 완전히 다름
공통 추출 불가능 (UI 구조 차이 등)
중복 코드 양 적음 (1000줄 미만)

notes: hints-expansion-review-2026-03-19.md에서 발견. atmosphere 구현 3가지 방식 존재하지만 모두 유사. shared 모듈 미구현 상태.


error_message: hints 변형 E2E 테스트 부재 → 회귀 테스트 불가, hints 변경 시 영향 미확인

resolution: 각 어댑터마다 최소 3종 hints 변형 테스트 케이스 작성 (정상/경계/비정상), __JUDGE__.simulate() 기반 자동 검증, CI 통합.

trigger_condition: 새 기능 추가 (hints, 스탯 등) 후, E2E 테스트 작성 없이 완료 선언

resolution_pattern: 1) 기능별 E2E 테스트 최소 3건 작성 (정상/경계/비정상) 2) CI에서 자동 실행 3) 스크린샷 비교 또는 시뮬레이션 결과 비교 4) 회귀 테스트 자동화

applicable_when:
자동 테스트 가능한 기능
회귀 리스크 높음
E2E 인프라 존재 (Playwright 등)

not_applicable_when:
수동 테스트만 가능
일회성 기능
회귀 리스크 낮음

notes: hints-expansion-review-2026-03-19.md에서 발견. E2E 테스트 증거 부재, 자동 회귀 테스트 인프라 미구축.