AI 브라우저 저장소 디버깅 루프

AI가 프런트엔드 기능을 빠르게 붙일 때 자주 놓치는 영역이 브라우저 저장소입니다. 화면은 분명 새로 배포됐는데 어떤 사용자는 예전 권한 화면을 보고, 어떤 사용자는 결제 완료 후에도 온보딩 배너가 사라지지 않고, 어떤 사용자는 로그아웃 뒤 새로고침하면 다시 로그인된 것처럼 보입니다. 서버 코드와 API 응답만 보면 정상이라 더 혼란스럽습니다. 원인은 localStorage, sessionStorage, 쿠키, IndexedDB, Service Worker 캐시, 탭 사이 동기화, 기능 플래그 캐시 같은 브라우저 상태가 서로 다른 생명주기로 남아 있기 때문인 경우가 많습니다.

초보자는 브라우저 저장소를 “웹사이트가 내 브라우저에 잠깐 맡겨 두는 작은 상태 창고”로 이해하면 됩니다. 실무자는 여기서 한 단계 더 들어가야 합니다. 어떤 값은 탭을 닫으면 사라져야 하고, 어떤 값은 로그인 사용자가 바뀌면 즉시 지워져야 하며, 어떤 값은 배포 버전이 바뀌면 무효화되어야 합니다. AI에게 “상태가 이상한 버그를 고쳐 줘”라고만 지시하면 캐시 삭제 버튼 하나를 만들거나, 모든 저장소를 무작정 비우는 위험한 코드를 제안할 수 있습니다. VIBE 코딩에서는 저장소별 책임, 만료 조건, 마이그레이션 규칙, 테스트 계정 재현 절차, 승인 기준을 묶은 브라우저 저장소 상태 디버깅 루프가 필요합니다.

핵심 결론

브라우저 저장소 상태 디버깅의 핵심은 “저장된 값을 다 지운다”가 아니라 “어떤 값이 언제 유효한지 계약으로 만든다”입니다. 로그인 세션, 사용자 설정, 임시 폼, 기능 플래그, 결제/권한 상태, 튜토리얼 진행률, 오프라인 큐는 모두 같은 저장소에 넣어도 되는 값이 아닙니다. 각 상태에는 소유자, 저장 위치, 만료 조건, 사용자 변경 시 처리, 배포 버전 변경 시 처리, 실패 시 복구 방법이 있어야 합니다.

AI 작업의 성공 기준도 바뀌어야 합니다. 단순히 “새로고침 후 화면이 유지된다”가 아니라 “다른 계정으로 전환해도 상태가 섞이지 않는다”, “권한이 회수되면 저장소 값이 남아도 서버 진실이 우선한다”, “배포 후 오래된 스키마가 안전하게 폐기된다”, “로그아웃 후 뒤로가기를 눌러도 보호 화면이 보이지 않는다”, “브라우저 콘솔과 public HTML에 내부 식별자나 민감한 설정명이 보이지 않는다”까지 확인해야 합니다.

좋은 루프는 네 가지 문장으로 요약됩니다. 첫째, 브라우저 저장소는 캐시일 뿐 권한의 최종 근거가 아니다. 둘째, 저장소 키와 값에는 버전과 범위가 있어야 한다. 셋째, 재현은 새 브라우저와 더러운 브라우저를 모두 포함해야 한다. 넷째, AI에게는 삭제보다 상태 전이와 검증을 먼저 요구해야 한다.

왜 중요한가

브라우저 상태 버그는 서버 로그만으로 잘 보이지 않는다

서버는 정상 응답을 줬는데 사용자는 오래된 화면을 봅니다. API는 최신 권한을 내려줬는데 프런트엔드가 localStorage의 이전 역할 값을 먼저 읽습니다. 결제는 성공했는데 IndexedDB에 남은 온보딩 상태가 결제 전 화면을 다시 띄웁니다. 이런 문제는 서버 로그만 보면 “정상 200”으로 보일 수 있습니다. 브라우저 안에 남은 상태가 진짜 장애 원인이라면 서버 중심 디버깅은 계속 헛돌게 됩니다.

AI 에이전트는 보통 코드 저장소와 테스트 결과를 중심으로 판단합니다. 하지만 브라우저 저장소는 사용자의 과거 행동, 오래된 배포, 탭 동시성, 모바일 브라우저 정책, 확장 프로그램, 네트워크 끊김의 영향을 받습니다. 그래서 AI에게는 “현재 코드만 보고 고쳐라”가 아니라 “오래된 저장소가 남은 사용자까지 가정해라”는 지시가 필요합니다.

저장소가 권한처럼 쓰이면 보안과 신뢰가 동시에 깨진다

가장 위험한 패턴은 브라우저 저장소 값을 권한의 근거처럼 쓰는 것입니다. 예를 들어 isAdmin 같은 플래그를 브라우저에 저장하고 그 값으로 중요한 버튼을 보여주거나 숨기는 방식은, UI 표시만이 아니라 사용자 신뢰에도 영향을 줍니다. 서버 검증이 따로 있더라도 public 화면에 잘못된 버튼이 보이면 사용자는 서비스가 불안하다고 느낍니다. 반대로 결제 완료나 구독 상태가 저장소에 늦게 반영되면 정당한 사용자가 기능을 못 쓰는 문제가 생깁니다.

브라우저 저장소는 편의와 성능을 위한 보조 계층이어야 합니다. 권한, 결제, 소유권, 공개/비공개 상태 같은 결정은 서버 진실을 우선해야 합니다. 프런트엔드는 저장소 값을 사용하더라도 “임시 표시”와 “최종 판단”을 분리해야 합니다.

AI가 만든 빠른 패치는 사용자별 재현성을 더 나쁘게 만들 수 있다

저장소 버그를 빨리 고치려다 모든 키를 삭제하는 코드를 넣으면 다른 기능의 사용자 설정, 오프라인 임시 작업, 접근성 선호, 작성 중 폼 데이터까지 사라질 수 있습니다. 특정 버그는 사라져도 사용자 경험은 더 나빠집니다. 반대로 새로운 키 이름으로 우회하면 과거 키가 계속 남아 다음 배포에서 다시 충돌합니다. AI가 제안한 임시 패치가 누적되면 브라우저 저장소는 아무도 책임지지 않는 쓰레기장이 됩니다.

실제 작업 순서

1단계: 증상을 저장소 관점으로 다시 적는다

먼저 버그 설명을 “화면이 이상하다”에서 “어떤 저장소 상태가 어떤 화면 판단에 영향을 주는가”로 바꿉니다. 예를 들어 “로그아웃 후에도 대시보드가 보인다”는 다음처럼 쪼갭니다.

• 로그아웃 요청은 서버에서 성공하는가.
• 로그아웃 직후 쿠키와 세션성 상태가 의도대로 제거되는가.
• 탭을 새로고침하면 서버의 인증 상태를 다시 확인하는가.
• 뒤로가기 캐시나 Service Worker가 보호 화면 HTML을 재사용하지 않는가.
• localStorage에 남은 사용자 요약이 보호 화면을 먼저 렌더링하지 않는가.

이렇게 바꾸면 AI에게 줄 입력이 선명해집니다. “로그아웃 버그 수정”이 아니라 “로그아웃 이후 브라우저 저장소, 탭 캐시, 서버 인증 확인 순서를 검증하라”가 됩니다.

2단계: 저장소 인벤토리를 만든다

현재 기능이 쓰는 저장소를 표로 정리합니다. 키 이름을 전부 공개 문서에 적을 필요는 없지만, 개발 내부에서는 다음 항목이 필요합니다.

이 표가 없으면 AI는 저장 위치를 마음대로 고릅니다. 편의상 localStorage를 쓰고, 만료 조건 없이 영구 상태를 남기며, 사용자 전환을 고려하지 않습니다.

3단계: 키 설계에 범위와 버전을 넣는다

좋은 저장소 키는 충돌을 피하고 폐기하기 쉽습니다. 기능명, 데이터 종류, 스키마 버전, 사용자 범위가 분리되어야 합니다. 예를 들어 전역 테마와 계정별 온보딩 상태를 같은 규칙으로 다루면 안 됩니다. 전역 선호는 사용자 전환에도 유지될 수 있지만, 권한과 작업 초안은 사용자 범위를 가져야 합니다.

버전도 중요합니다. 저장된 값의 모양이 바뀌었는데 이전 값을 그대로 읽으면 undefined 처리, 잘못된 분기, 화면 깜빡임, 무한 로딩이 생길 수 있습니다. 배포 시점에 값을 전부 지우는 대신 “이전 버전이면 안전 기본값으로 복구하고 새 구조로 저장한다”는 마이그레이션을 둡니다. 마이그레이션이 어려운 상태는 명시적으로 폐기합니다.

4단계: 서버 진실 재확인 지점을 정한다

브라우저 저장소는 빠른 첫 화면을 만들 수 있지만, 중요한 상태는 서버 재확인이 필요합니다. 페이지 진입, 탭 포커스 복귀, 결제 완료 콜백, 권한 변경 이벤트, 로그아웃, 사용자 전환, 배포 버전 변경 시점에는 저장소보다 서버 응답이 우선해야 합니다. 저장소 값은 “이전 추정”으로 표시할 수 있지만, 확정 UI는 서버 확인 뒤에 보여야 합니다.

여기서 초보자가 자주 하는 실수는 로딩 화면이 싫어서 저장소 값을 바로 확정값처럼 보여주는 것입니다. 전문가급 구현은 다릅니다. 저장소 값을 읽더라도 상태를 unknown, cached, verified, expired, conflict처럼 나누고, 중요한 버튼은 verified 이후에만 활성화합니다.

5단계: 더러운 브라우저 테스트를 만든다

새 시크릿 창에서만 테스트하면 저장소 버그를 못 잡습니다. 의도적으로 더러운 브라우저 상태를 만들어야 합니다.

• 이전 버전 키가 남아 있는 상태.
• 다른 계정의 사용자 범위 값이 남은 상태.
• 기능 플래그 캐시가 오래된 상태.
• 제출 직전 폼 초안이 남은 상태.
• 로그아웃 직후 뒤로가기를 누른 상태.
• 여러 탭이 같은 저장소를 동시에 수정한 상태.
• 모바일 브라우저에서 탭이 백그라운드로 갔다가 돌아온 상태.

자동화 테스트가 가능하면 각 상태를 fixture로 만들고, 어렵다면 최소한 브라우저 수동 스모크 체크리스트에 넣습니다. 중요한 것은 “깨끗한 환경에서 한 번 성공”이 아니라 “오래된 환경에서도 안전하게 회복”입니다.

6단계: 관측 신호를 남기되 원문 값은 남기지 않는다

저장소 디버깅에는 로그가 필요하지만, 값 자체를 찍으면 안 됩니다. 대신 이벤트 이름, 키 그룹, 스키마 버전, 상태 전이, 폐기 사유, 복구 결과, 소요 시간, 브라우저 종류 정도를 기록합니다. 예를 들어 “온보딩 상태 v1 폐기 후 v2 기본값 생성” 같은 신호는 유용하지만, 저장된 원문 JSON 전체는 위험합니다. public 화면, 브라우저 콘솔, 알림 메시지에도 내부 키 이름이나 민감한 설정명이 노출되지 않아야 합니다.

상황별 예시

예시 1: 로그아웃 뒤 보호 화면이 잠깐 보이는 문제

증상은 사용자가 로그아웃했는데 뒤로가기를 누르면 대시보드가 순간적으로 보이는 것입니다. 흔한 원인은 이전 화면 HTML, 메모리 상태, localStorage 사용자 요약, 브라우저 뒤로가기 캐시가 섞이는 것입니다. 작업 순서는 다음과 같습니다.

1. 로그아웃 성공 후 인증 쿠키와 메모리 사용자 상태를 즉시 폐기한다.
2. 보호 페이지 진입 시 저장소 사용자 요약만으로 본문을 렌더링하지 않는다.
3. 서버 인증 확인 전에는 민감한 데이터 대신 중립적인 확인 화면을 둔다.
4. 뒤로가기 복귀 시 인증 상태를 다시 확인한다.
5. 로그아웃 직후 뒤로가기와 새로고침 테스트를 자동/수동 체크에 넣는다.

승인 기준은 단순합니다. 로그아웃 이후 어떤 새로고침과 뒤로가기에서도 보호 데이터가 보이면 안 됩니다. 잠깐 보이는 것도 실패입니다. 서버가 인증 실패를 돌려준 뒤 리다이렉트되는 정도로는 부족합니다. 첫 렌더부터 안전해야 합니다.

예시 2: 결제 완료 후에도 무료 사용자 화면이 남는 문제

결제 완료는 서버에서 성공했지만 브라우저가 이전 구독 상태를 캐시해 무료 화면을 계속 보여줄 수 있습니다. 이때 모든 저장소를 비우면 튜토리얼, 테마, 작성 중 초안까지 영향을 줍니다. 더 나은 방법은 결제 성공 콜백과 계정 상태 갱신 이벤트에서 구독 관련 캐시만 무효화하고, 서버에서 최신 구독 상태를 다시 읽은 뒤 확정 UI를 보여주는 것입니다.

검증은 세 가지 사용자로 나눕니다. 첫째, 처음 결제하는 사용자. 둘째, 결제 실패 후 다시 성공한 사용자. 셋째, 다른 탭에서 결제를 완료한 사용자. 특히 세 번째는 탭 간 동기화가 없으면 한 탭은 유료, 다른 탭은 무료처럼 보일 수 있습니다. 탭 간 메시지나 포커스 복귀 재조회가 필요한 이유입니다.

예시 3: 기능 플래그가 배포 후에도 예전 UI를 고정하는 문제

AI가 A/B 테스트나 점진 배포를 도울 때 기능 플래그 값을 브라우저에 오래 저장하는 경우가 있습니다. 짧은 실험에는 편하지만, 배포가 끝났는데도 일부 사용자가 예전 UI를 보는 원인이 됩니다. 기능 플래그 캐시는 짧은 만료 시간, 배포 버전, 서버 재확인 조건이 있어야 합니다. 플래그가 “안전 장치”인지 “실험 분기”인지도 분리해야 합니다. 안전 장치는 오래 남아도 되지만 실험 분기는 종료 시 제거되어야 합니다.

예시 4: 작성 중 폼 초안이 다른 사용자에게 보이는 문제

공유 PC나 팀 계정 전환 환경에서는 작성 중 임시 폼이 다른 사용자에게 보일 수 있습니다. 초안 저장은 편리하지만 사용자 범위가 없으면 위험합니다. 초안은 계정 범위, 문서 범위, 만료 시간, 제출 후 삭제 조건을 가져야 합니다. 로그아웃이나 사용자 전환 시에는 현재 사용자가 소유한 초안만 보이도록 해야 하며, 소유자를 확인할 수 없는 초안은 안전하게 숨겨야 합니다.

실패 모드

실패 모드 1: 모든 저장소 삭제로 버그를 덮는다

가장 쉬운 패치는 전체 저장소 삭제입니다. 하지만 이것은 사용자 설정, 접근성 옵션, 오프라인 초안, 튜토리얼 진행률까지 지울 수 있습니다. 버그 하나를 고치고 여러 UX 회귀를 만드는 방식입니다. 삭제가 필요하다면 키 그룹과 조건을 좁혀야 합니다. “구독 캐시 v1만 폐기”, “현재 사용자 범위의 임시 권한 요약만 삭제”처럼 구체적이어야 합니다.

실패 모드 2: 저장소 값을 서버 권한처럼 믿는다

브라우저에 저장된 역할, 구독, 소유권 값으로 중요한 결정을 내리면 안 됩니다. 저장소 값은 오래될 수 있고, 사용자가 바꿀 수 있고, 다른 계정의 흔적일 수 있습니다. UI 힌트로 쓰더라도 서버 확인 전에는 중요한 액션을 비활성화하거나 중립 상태를 보여야 합니다.

실패 모드 3: 스키마 버전 없이 영구 저장한다

처음에는 작은 문자열 하나였던 값이 나중에는 객체가 되고, 다시 배열이나 중첩 구조가 됩니다. 버전이 없으면 이전 값이 새 코드에서 예외를 만들거나 잘못된 기본값으로 해석됩니다. 모든 장기 저장 값에는 스키마 버전과 복구 경로가 필요합니다.

실패 모드 4: 깨끗한 브라우저만 테스트한다

개발자는 새 브라우저나 초기화된 프로필로 자주 테스트합니다. 실제 사용자는 몇 달치 저장소, 오래된 탭, 모바일 백그라운드 상태, 확장 프로그램, 느린 네트워크를 가지고 있습니다. 저장소 버그는 더러운 환경에서 나타납니다. 테스트도 더러워야 합니다.

실패 모드 5: 디버깅 편의를 위해 원문 값을 콘솔에 찍는다

문제를 찾겠다고 저장소 원문, 사용자 객체, 요청 응답 전체를 브라우저 콘솔에 출력하면 public 노출 위험이 생깁니다. 디버깅 로그도 허용 목록 신호로 제한해야 합니다. 키 이름, 값 길이, 버전, 폐기 사유처럼 안전한 정보만 남깁니다.

검증 체크리스트

• 저장소 인벤토리에 상태 종류, 저장 위치, 소유 기능, 만료 조건, 사용자 변경 처리, 서버 진실 우선 여부가 적혀 있는가.
• 권한, 결제, 소유권, 공개 상태는 브라우저 저장소만으로 확정하지 않는가.
• 장기 저장 값에 스키마 버전과 마이그레이션 또는 폐기 규칙이 있는가.
• 로그아웃, 사용자 전환, 계정 삭제, 권한 회수, 결제 상태 변경에서 관련 저장소가 좁은 범위로 정리되는가.
• 배포 버전 변경 후 오래된 키가 안전하게 무효화되는가.
• 여러 탭에서 같은 사용자가 상태를 바꿀 때 다른 탭도 갱신되는가.
• 더러운 브라우저 fixture 또는 수동 스모크 절차가 있는가.
• 브라우저 콘솔에 사용자 원문, 내부 설정명, 외부 서비스 인증값, 긴 식별자 원문이 남지 않는가.
• public HTML에 관리자용 문구나 내부 워크플로우 라벨이 보이지 않는가.
• 새 시크릿 창, 오래된 저장소가 있는 창, 모바일 브라우저 복귀 상황을 모두 확인했는가.

AI에게 줄 지시 예시

아래 지시는 그대로 붙여 넣기보다 현재 기능명과 상태명을 바꿔 쓰는 템플릿입니다. 핵심은 AI에게 “삭제”보다 “계약과 검증”을 요구하는 것입니다.

브라우저 저장소 상태 버그를 고쳐라. 먼저 localStorage, sessionStorage, 쿠키, IndexedDB, Service Worker 캐시 중 이 기능이 실제로 읽고 쓰는 위치를 인벤토리로 정리하라. 권한·결제·소유권 판단은 서버 응답이 최종 진실이며, 브라우저 저장소 값만으로 확정 UI를 활성화하지 마라. 장기 저장 값에는 스키마 버전과 만료 조건을 두고, 사용자 전환·로그아웃·배포 버전 변경 시 좁은 범위로 폐기하라. 전체 저장소 삭제로 해결하지 마라. 더러운 브라우저 상태, 여러 탭, 뒤로가기, 모바일 복귀 상황을 테스트하라. 브라우저 콘솔에는 원문 사용자 데이터나 인증 관련 값이 남지 않게 하라. 변경 뒤에는 실패 모드와 승인 기준을 결과에 적어라.

리뷰 지시는 더 짧게 줄 수 있습니다.

이 변경이 브라우저 저장소를 권한의 최종 근거로 쓰지 않는지, 오래된 저장소에서 안전하게 회복되는지, 여러 탭과 사용자 전환에서 상태가 섞이지 않는지, 콘솔에 민감한 값이 남지 않는지 확인해라. 전체 삭제로 회피한 부분이 있으면 더 좁은 무효화로 바꿔라.

테스트 지시는 다음처럼 분리합니다.

깨끗한 브라우저 성공 경로뿐 아니라 이전 버전 저장소, 다른 사용자 범위 값, 오래된 기능 플래그, 로그아웃 후 뒤로가기, 결제 완료 후 다른 탭 갱신, 모바일 탭 복귀를 포함한 검증 목록을 만들어라. 자동화가 어려운 항목은 수동 스모크 절차와 승인 기준으로 남겨라.

중단/승인 기준

즉시 중단해야 하는 경우

• 저장소 값만으로 권한, 결제, 소유권, 공개 상태가 확정되는 코드가 발견된 경우.
• 로그아웃 뒤 뒤로가기나 새로고침에서 보호 데이터가 한 프레임이라도 보이는 경우.
• 사용자 전환 후 이전 사용자의 초안, 이름, 구독 상태, 기능 플래그가 섞이는 경우.
• 전체 저장소 삭제 외에는 설명 가능한 복구 전략이 없는 경우.
• 브라우저 콘솔이나 public HTML에 원문 사용자 데이터, 내부 설정명, 외부 서비스 인증값이 보이는 경우.
• 오래된 스키마 값을 읽을 때 예외, 무한 로딩, 잘못된 기본 권한이 발생하는 경우.

이 중 하나라도 나오면 “부분 성공”으로 배포하지 않습니다. 범위를 줄여서라도 먼저 위험 상태를 제거해야 합니다.

승인할 수 있는 경우

• 저장소별 책임과 만료 조건이 문서 또는 코드 주석으로 확인된다.
• 권한·결제·소유권은 서버 재확인 뒤 확정 UI가 활성화된다.
• 오래된 저장소, 여러 탭, 사용자 전환, 로그아웃 뒤로가기, 모바일 복귀 테스트가 통과한다.
• 필요한 무효화가 좁은 키 그룹으로 제한되어 다른 사용자 설정을 지우지 않는다.
• 브라우저 콘솔과 public HTML 차단어 스캔이 깨끗하다.
• 실패 모드와 롤백 방법이 작업 결과에 남아 다음 AI 작업자가 같은 실수를 반복하지 않는다.

다음 단계

브라우저 저장소 루프를 처음 도입한다면 로그인/로그아웃, 결제/구독, 기능 플래그 중 하나를 고르세요. 세 영역을 동시에 고치려 하면 저장소 인벤토리만 커지고 검증이 흐려집니다. 가장 사용자 피해가 큰 흐름 하나에서 저장소 계약, 더러운 브라우저 테스트, 서버 진실 재확인, 콘솔 안전 스캔을 끝까지 만든 뒤 다른 흐름으로 복제하는 편이 안전합니다.

팀 단위로 운영한다면 PR 템플릿이나 AI 작업 지시서에 “브라우저 저장소 영향” 항목을 추가하세요. 새 키를 만들 때마다 저장 위치, 만료 조건, 사용자 범위, 서버 진실 우선 여부를 적게 하면 저장소 부채가 눈에 보입니다. 특히 AI 에이전트에게 프런트엔드 상태 수정을 맡길 때 이 항목이 없으면, 에이전트는 가장 빠른 저장소를 골라 기능을 통과시키는 방향으로 움직입니다.

마지막으로, 저장소 디버깅은 배포 스모크와 연결되어야 합니다. 새 버전이 올라간 뒤 대표 사용자를 시크릿 창과 오래된 브라우저 프로필로 각각 확인하고, 보호 화면, 결제 화면, 기능 플래그 화면, 작성 중 폼을 살펴봅니다. 문제를 찾기 위한 기록은 남기되 원문 값은 남기지 않습니다. 이 습관이 쌓이면 AI가 만든 빠른 프런트엔드 변경도 실제 사용자 브라우저에서 예측 가능하게 움직입니다.