유니티 사화 리팩토링

문제

예시: AnimalMaskSkill 클래스의 코루틴 메서드 CoFirstAttack(…) 호출

문제 분석

상속 구조로 옮겨봐도 자식 클래스에 로직이 남지 않음

CharacterBaseState<EState, ECharacter> 추상 클래스를 두고, 상태마다 자식 클래스를 만들어 StateKey·AnimationName을 override하는 구조로 1차 시도

public abstract class CharacterBaseState<EState, ECharacter> where EState : Enum where ECharacter : Enum
{
    public abstract bool CanReenter { get; }
    public abstract EState StateKey { get; }
    public abstract ECharacter CharacterType { get; }
    protected abstract string AnimationName { get; }
    // ...
}

원인

• 자식 클래스가 override하는 것이 전부 값이고, 로직은 한 줄도 없음을 확인
• 상태마다 클래스 파일을 하나씩 만들며 얻는 것이 “상수 몇 개 선언할 자리”뿐 → 상속 대신 데이터로 정의하는 방향으로 전환

개선

상태는 데이터 에셋으로 정의하고, 실행은 StateRunner 하나가 담당

상태를 클래스가 아니라 ScriptableObject 에셋으로 정의

[CreateAssetMenu(fileName = "StateData", menuName = "Data/StateData")]
public class StateData : ScriptableObject
{
    [SerializeField] private PlayerStateType stateType;  // 상태 정체성. 자식 클래스 override 대신 인스펙터에서 지정
    [SerializeField] private bool isLooping;
    [SerializeField] private float cooldown;

    // 시간 구간형 — "언제부터 언제까지"
    [SerializeField] private IntervalDataEntry[] inputBlock;
    [SerializeField] private IntervalDataEntry[] inputBuffer;
    [SerializeField] private IntervalDataEntry[] superArmor;
    [SerializeField] private IntervalDataEntry[] invincible;
    [SerializeField] private IntervalDataEntry[] cameraLock;

    // 시점형 — "이 진행도에서 무엇을"
    [SerializeField] private SkillMoveDataEntry[] skillMove;
    [SerializeField] private SkillEffectDataEntry[] effect;
    [SerializeField] private HitboxDataEntry[] hitbox;
    [SerializeField] private AudioDataEntry[] audio;
    [SerializeField] private CameraShakeDataEntry[] cameraShake;
    [SerializeField] private CameraZoomDataEntry[] cameraZoom;
    [SerializeField] private FinishDataEntry[] finish;
    [SerializeField] private ObjectToggleDataEntry[] objectToggle;
}

이 데이터를 읽어 실행하는 클래스는 StateRunner 하나뿐, 상속 없음

// 역할: 상태를 관찰하고 무엇을 할지 신호(의도)를 보낸다.
public class StateRunner
{
    public void Enter()
    {
        _tracker.Begin();
        Animator.CrossFade(StateKey.ToString(), 0.1f, 0, 0f);
        RaiseEvent(0f);
    }

    public void Update()
    {
        _tracker.Update();
        RaiseEvent(_tracker.Progress);
    }
}

• StateRunner는 애니메이션 진행도(0~1) 만 추적하고, 데이터에 적힌 progress를 넘어설 때마다 해당 카테고리의 이벤트를 올림 — 초 단위가 아닌 진행도 기준이라 애니메이션 길이를 바꿔도 타이밍 비율 유지
• StateRunner는 무엇을 하라고 지시하지 않음 — “지금 히트박스 카테고리의 시점을 지났다”는 신호만 보내고, 실제 처리는 신호를 구독한 쪽이 담당

신호를 받는 쪽 — 이벤트 채널

상태를 아는 쪽과 상태에 반응하는 쪽을 채널로 분리

• PlayerStateEventChannel — 상태 진행 중 발생하는 이벤트(히트박스·이펙트·사운드·카메라)
• PlayerStateTriggerChannel — 상태 전이를 요청하는 신호
• PlayerCurrentStateChannel — 현재 상태를 읽기 전용으로 노출
• 발행 측(IPlayerStateEventRaiser)과 구독 측(IPlayerStateEventSubscriber) 인터페이스 분리, 구독자는 필요한 카테고리만 수신 → 새 연출 추가 시 상태 시스템 코드 수정 불필요

에디터 쪽 처리

• 데이터 항목이 여러 종류라 인스펙터가 복잡해질 수 있어, 커스텀 에디터로 필요한 항목만 노출되도록 처리
• 플레이 모드에서 SO progress를 실시간 수정해도 다음 진입부터 반영되도록 Enter()에서 UNITY_EDITOR 한정 이벤트 재정렬 적용 → 게임을 재시작하지 않고 타이밍 튜닝 가능

public void Enter()
{
#if UNITY_EDITOR
    // 에디터 플레이모드에서 SO progress를 런타임 수정하면 다음 진입부터 반영되도록 재정렬한다.
    SortEvents(_data);
    IsLooping = _data.IsLooping;
#endif
    // ...
}

결합 구조 실측

• before: 양방향 SerializeField 순환 참조 6쌍 확인(HumanMaskSkill↔PlayerSkillMove 등) — 양쪽 파일이 서로의 타입을 필드로 들고 있어 한쪽을 고치면 반대쪽도 매번 확인 필요
• after: 의존이 인터페이스·채널을 통해 한 방향으로만 흘러 순환 참조 0건
• before: 대부분이 씬에 붙어야만 존재하는 MonoBehaviour라 씬 없이는 읽기·검증이 어려움
• after: 상당수가 순수 C# 클래스·인터페이스라 코드만으로 계약 파악 가능

결과

한계 및 회고

회고

• 코드를 크게 안 고치고도 기능을 추가·변경할 수 있어야 한다는 선을 기준으로 설계. 디테일까지 전부 미리 설계하는 대신, “수정하기 쉽게 짜는 것”을 기본으로 두는 쪽을 선택
• SkillMove를 만들 때 “플레이어·몬스터·기믹 공용 시스템으로 키우자”는 계획이 나왔지만 취소. 지금 의도와 다른 설계를 미리 하는 것은 시간을 버리는 일이라고 판단

문제

싱글톤이 의존 해결 수단이었음

출시작은 CameraController·SaveManager·PlayerController·MaskChange 등 다수의 싱글톤 클래스로 시스템 간 참조를 연결. .instance 호출이 코드 곳곳에 흩어진 상태

• 어떤 클래스가 무엇에 의존하는지 선언부만 봐서는 알 수 없고, 메서드 본문의 .instance 호출을 전부 읽어야 파악 가능
• PlayerHumanMaskData처럼 수치 데이터 클래스까지 싱글톤이라 교체·테스트 불가능

문제 분석

초기화 순서를 실행 순서에 기대는 구조

싱글톤 초기화 순서가 Awake 실행 순서에 좌우됨. 레거시 MouseSettingUI에는 // TODO: TimelineHelper에서 savemanager 불러오는 문제 -> instance부터 하는건지라는 주석이 남아 있어, 문제는 인지했으나 해결하지 못한 상태로 확인

의존을 선언이 아니라 실행 순서로 관리하는 한, 클래스를 추가할 때마다 초기화 순서를 함께 신경 써야 하는 구조. “누가 무엇을 필요로 하는가”를 코드가 직접 말하게 하는 구조가 필요하다고 판단

개선

[Inject] 어트리뷰트 기반 주입 컨테이너를 직접 구현

외부 DI 프레임워크 대신 자체 컨테이너를 구현

동작 순서:

1. [RuntimeInitializeOnLoadMethod(AfterAssembliesLoaded)]로 어셈블리 로드 직후 1회만 타입과 [Inject] 필드 캐싱 — 런타임 리플렉션 재조회 없음
2. 씬 Awake에서 FindObjectsByType<MonoBehaviour>로 씬 객체 등록. 인터페이스·추상 타입도 키로 등록해 계약 타입으로 주입 가능
3. ScriptableObject는 씬 객체가 아니므로 IDataProvider를 통해서만 수집
4. 필드가 List<T>면 해당 타입 전부를, 단일 필드면 첫 번째를 주입

의존이 선언부에 드러남

after의 주입 필드는 49파일 161개. 타입별로 분류하면:

구체 타입 39개는 교체 대상이 아닌 것들 — 채널(HitChannel·AudioChannel), SO 데이터(EffectCatalog·AudioCatalog 등), 씬 컴포넌트 목록(List<CameraRole> 등), 외부 타입(InputActionAsset 등)

선택적 주입(Inject(true))은 90개로, “없어도 되는 의존”과 “필수 의존”을 구분해 표시. 없으면 필수는 LogError, 선택은 LogWarning을 남김

결과 및 회고

회고

• 같은 타입 구현체가 여럿이면 첫 번째만 주입되고 경고만 남는 한계
• 런타임에 생성되는 객체는 주입 대상 아님 — Awake 시점의 씬 객체만 스캔
• Script Execution Order를 -100으로 설정해야 동작하고, 부모 클래스 필드를 주입받으려면 private가 아닌 protected/public이어야 함. 둘 다 코드 주석에 명시

문제

폴더는 있었지만 경계는 없었음

출시작은 폴더 10개(Player·Enemy·Gimmick·UI·Manager·Camera·Object·Struct·Interface·Timeline)로 구성. 폴더는 분류일 뿐 경계가 아닌 상태

• namespace 선언이 거의 없어, 모든 타입이 전역 이름 공간에 위치해 이름 충돌을 파일명 규칙으로만 회피
• MenuUI(UI)가 MaskChange(Player)·CameraController(Camera)를 직접 참조하고, TimelineHelper(Player)가 MenuUI·MouseSettingUI(UI)를 참조하는 식으로 폴더를 넘나드는 참조가 흔함
• Interface 폴더에 인터페이스가 IDamageable·IEvent 둘뿐. 폴더는 만들었지만 계약 기반 설계는 자리잡지 못한 상태
• Manager 폴더는 SaveManager·SceneSwitcher·LanguageManager·TextManager·CoroutineManager 등 성격이 다른 전역 객체의 집합소 역할

문제 분석

경계 없는 참조가 반복될 수밖에 없었던 이유

폴더 구조는 “무엇을 어디에 둘지”만 정했을 뿐, “어디까지가 이 시스템의 책임이고 외부와 어떻게 연결되는지”는 문서화되지 않은 상태. 규칙이 없으니 새 코드를 쓸 때마다 각자 판단으로 참조를 만들었고, 그 결과가 폴더를 넘나드는 직접 참조와 전역 싱글톤. 구조를 코드로 먼저 짜면 이미 얽힌 뒤에야 경계가 보이므로, 순서를 뒤집어 규칙을 코드보다 먼저 확정하기로 판단

개선

폴더를 시스템으로 못 박고, 코드보다 규칙을 먼저 확정

코드를 쓰기 전에 역할·진입점·외부 연결·설계 규칙을 SystemUsageGuide 문서로 먼저 확정하도록 순서 변경

파일 대부분이 namespace Refactoring 아래로 정리. 시스템 간 연결은 인터페이스 또는 채널(AudioChannel·HitChannel·PlayerStateEventChannel·PlayerStateTriggerChannel·PlayerCurrentStateChannel) 5종을 통하고, 배선은 AttributeInjector가 씬 Awake에서 자동 처리

경계가 실제로 작동한 사례

• PlayerSystem이 카메라를 직접 조작하지 않음 — CameraSystem이 IPlayerStateEventSubscriber로 상태 이벤트를 구독해 흔들림·줌을 스스로 처리 (before는 PlayerCameraEffect가 플레이어 코드 안에 위치)
• CombatSystem은 DamageInfo/IDamageable만 정의, 공격자·피격자는 서로의 구체 타입을 모름
• UISystem은 게임 상태를 IGameStateController로만 조작 (before는 MenuUI가 Time.timeScale과 플레이어를 직접 조작)

결과 및 회고

회고

• EnemySystem과 PlatformSystem은 노출 인터페이스가 0개로, 아직 계약 없이 구체 타입으로 연결
• GimmickSystem도 시스템 크기 대비 계약이 적음. 둘 다 작업 범위 밖(Enemy·Gimmick 코드는 타인 작성)이라 다음 과제로 남김

문제

혼자 하는 리팩토링에는 반대하는 사람이 없음

출시작을 다시 짜기로 했을 때 가장 걱정한 것은 실력이 아니라 판단의 편향

• 자기가 짠 코드는 자기가 읽기 쉬움 — “읽기 쉬운가”를 스스로 판정 불가
• 리팩토링은 끝이 없어서, 어디서 멈출지 정해 주는 사람이 없으면 계속 고치게 되는 구조
• 팀 프로젝트에서는 리뷰어가 걸러 주던 것들이 1인 프로젝트에서는 전부 통과

AI를 쓰기로 한 이유가 여기 있음 — 코드를 빨리 뽑기 위해서가 아니라, 반대할 사람을 만들기 위해서

문제 분석

AI는 기본적으로 사용자 편을 듦

반대할 사람을 AI로 세우려 해도, AI는 기본적으로 사용자에게 동의하려는 경향. 그 상태로 붙이면 리뷰어가 아니라 들러리가 되는 구조. AI를 쓰기 전에 “동의하지 않아도 되는 조건”부터 규칙으로 못 박아야 한다고 판단. AI가 파일을 알아서 고치기 시작하면 설계 판단이 손을 떠나므로, 설계는 직접 하고 AI는 검사만 하도록 역할 분리 필요

개선

원칙 — 사용자 편을 들지 말 것

프로젝트 CLAUDE.md 최상단에 규칙 명시

- 사용자 편을 절대로 들지 말 것. 중립적이면서 기계적으로 근거에 의한 답변을 제시할 것.
- 파일 생성/삭제/변경은 진행하기 전 무조건 질문할 것.

동의 금지를 규칙의 첫 줄로 올리고, 평가 커맨드에도 엄격하고 진지하게, 중립적으로 판단한다를 반복 삽입. 두 번째 규칙(변경 전 질문)은 주도권을 지키기 위한 장치. 설계는 직접, AI는 검사와 근거 조사 담당

커맨드로 고정한 11가지

매번 프롬프트로 설명하면 기준이 흔들리므로, 반복되는 판정을 전부 슬래시 커맨드로 고정

평가 기준을 추상 원칙에서 떼어냈음

클래스 평가에서 SOLID 같은 원칙을 점수 항목으로 두지 않음 — 원칙 이름으로 판정하면 결국 해석 싸움이 되기 때문

좋은 코드의 기준: 읽기 쉽고 유지보수가 싼가. 그래서 추상 원칙(SOLID 등)을 점수 항목으로 두지 않고, “유지보수가 싼가”라는 결과만 본다.

대신 관찰 가능한 냄새로 축을 구성

1. 변경 파급 — 이거 하나 고치면 몇 군데가 깨지나 (본문의 new·Find·GetComponent·싱글톤 직접 호출, 깊은 체이닝, 같은 규칙 복붙)
2. 이해 비용 — 처음 보는 사람이 30초에 흐름을 따라가나 (인자 3개 초과, bool 플래그로 모드 가르기, 이름에 없는 사이드 이펙트)
3. 교체/삭제 용이 — 기능 하나 빼거나 갈아끼울 때 깔끔히 떨어지나 (새 종류마다 기존 switch에 분기 덧대기)
4. 과설계 없음 — 구현 1개뿐인 인터페이스, 호출 1곳뿐인 레이어, 안 올 확장의 선구현
5. 유니티 함정 — OnEnable 구독과 OnDisable 해제의 짝이 맞나 등

억지 평가는 금지 — 냄새가 안 보이면 그 행은 해당없음으로 표기. 지적할 것을 억지로 찾으면 리뷰가 노이즈가 되는 문제 방지

순서를 강제한 장치

커맨드끼리 선행 조건을 설정, 클래스 평가의 0번 절차로 배치

대상 파일이 속한 시스템, 그리고 그 파일이 참조하는 외부 시스템 중 Docs/SystemUsageGuide.md에서 상태: 미확정인 것이 하나라도 있으면 평가를 진행하지 않는다. 미확정 N개: <시스템명 나열>. system-evaluation으로 먼저 확정할 것.만 출력하고 멈춘다.

확정되지 않은 규칙으로 코드를 판정하면 그 판정이 오염되는 문제. 시스템 규칙 확정 → 클래스 평가 순서를 도구 차원에서 강제해, 순서를 건너뛰려 해도 커맨드가 멈추는 구조

근거와 추측을 분리

AI를 쓸 때 가장 위험한 것은 그럴듯한 추측을 근거처럼 받는 것. 조사 커맨드에 별도 규칙 적용

근거와 추측을 절대 섞지 않는다. (근거가 추측처럼, 추측이 근거처럼 보이면 안 된다) 근거가 없는 내용을 들고오면 폐기 대상이다. 빈손을 감추려 추측을 근거처럼 포장하지 말 것.

이 규칙으로 실제로 걸러진 사례 존재. 모바일 GPU 분석에서 Shader Variant 트래킹이 Terrain 셰이더를 못 잡는 문제를 확인했을 때, 원인을 추측으로 채우는 대신 “Unity의 알려진 한계로 확인, 이 부분은 미해결” 로 보고서에 기록. 빌드 용량 분석에서도 Play Asset Delivery를 검토한 뒤 “PAD가 나쁘다는 뜻이 아니라 이번 문제의 원인과 규모에 맞지 않았다”고 판단 근거를 분리해 기록

AI가 한 일과 직접 한 일

커밋 로그에도 이 경계가 남아 있음. AI 평가를 적용한 커밋에는 어떤 커맨드를 돌렸고 무엇이 바뀌었는지, 그리고 핵심 기능은 건드리지 않았다는 사실을 함께 기록

[DISystem] AttributeInjector.cs 평가 적용
- ai를 통한 설계 평가(code-convention, comment-convention, system-evaluation, code-evaluation)를
  적용하여 일부 주석 및 코드 수정됨(핵심 기능 수정 X)

규칙은 계속 다듬었음

처음부터 잘 돌아간 것은 아님. 커맨드 자체를 여러 번 수정

• 코드 평가 규칙 대폭 간소화 — 항목이 많으면 판정이 흐려지는 문제
• 더 단순하게 평가하기 위해 규칙 수정
• 규칙 단호하게 수정 — 애매한 표현을 남기면 AI가 사용자 편으로 기우는 문제
• 코드 평가 경각심 담긴 문장 추가

규칙을 만드는 것 자체가 설계 작업. 무엇을 나쁜 코드로 볼 것인지 문장으로 못 쓰면, 그 기준은 머릿속에도 없는 것이라는 판단

버린 기록

통제는 말로 되지만 폐기는 증거가 남음. 납득하지 못한 결과물은 남기지 않음

• 상속 + 제네릭 상태 구조 — 만들다 보니 제네릭에 플레이어 전용 타입이 들어가 플레이어 상태머신으로 고정돼 폐기
• Unity Localization + Addressable 패키지 — 도입 후 필요 없다고 판단해 제거, 자체 구현으로 전환
• 코드 설계 에이전트 — 만들었다가 재구현하고 결국 커맨드 방식으로 정리
• git-flow·PR 규칙 문서 — 실효가 없어 삭제
• 전면 자동화(코드 작성 → 평가 → 요약) — Pro 요금제 토큰이 곧바로 바닥나고 결과 만족도가 낮아 포기, 부분 자동화도 하지 않기로 함

결과 및 회고

회고

• 규칙을 문장으로 쓰는 과정에서 판단 기준이 정리됨. 이 문서화 습관은 SystemUsageGuide와 활동 일지로도 이어짐
• 처음부터 완성된 규칙은 없었음. 여러 번 고치고 단순화하며 다듬었고, 그 자체가 설계 작업