그때는 옳았던 설계가 부채가 된 이유: z-index 한 줄에서 시작한 기술부채

들어가며

안녕하세요. 노머스 프론트엔드팀 사봉석입니다.

프롬 서비스는 계속해서 확장하고 있습니다. 본 글은 저희 프론트엔드 팀이 서비스 확장 과정에서 겪은 이슈를 다룬 글입니다. 서비스 초기에 왜 그러한 설계를 했으며 어떤 한계점에 부딪혀 어떻게 개선하고 있는지 그 과정을 공유해 보겠습니다.

---

1. 그때는 정석적인 설계였습니다

화면 레이어 관리를 예로 들겠습니다. 팀에서 가장 자주 문제가 된 부분이고, 다른 영역에서 겪은 문제도 형태만 다른 같은 문제였습니다.

지금의 레이어 구조를 정한 시점의 서비스는 화면 수가 적었습니다. 화면 위에 뜨는 것은 바텀시트와 다이얼로그, 토스트 정도였고, 팀원들은 서로의 화면을 대부분 알고 있었습니다.

콘텐츠, 스택뷰, 모달로 레이어를 구분했습니다. 교과서적인 구조였고 그 시점에는 충분했습니다.

예외가 필요할 때는 z-index로 처리했습니다. 임시방편이 아니었습니다. 예외가 한두 개인 상황에서 오버레이 스택을 관리하는 시스템을 따로 만드는 것은 오버엔지니어링이라고 판단했습니다.

예외를 처리하는 방식이 사람마다 달라도 상관없었습니다. 전부 눈에 들어오는 양이었고, 서로 다르다는 사실을 알아볼 수 있었기 때문입니다.

---

2. 전제가 깨진 지점

서비스의 기능이 늘면서 예외도 늘었습니다.

모달 위에 떠야 하는 확인 다이얼로그, 그 위에 떠야 하는 토스트, 모달 안에서 열리는 드롭다운, 화면 전체를 덮는 미디어 뷰어, 요청이 끝날 때까지 아무것도 눌리면 안 되는 로딩 인디케이터. 하나씩 보면 전부 합당한 요구였고, 하나씩 들어올 때마다 z-index를 하나 더 얹는 것이 가장 작은 변경이었습니다.

문제는 예외가 늘었다는 것이 아닙니다.

개발자가 표현하려던 것은 “이것은 모달보다 위”라는 관계입니다. 그런데 코드에 남는 것은 숫자뿐입니다. 그 숫자가 왜 그 값인지는 정한 사람만 알고 있었습니다.

숫자만 보고는 관계를 알 수 없습니다.

z	무엇이 있나	코드에 적힌 형태
9999	전역 토스트	z-index: 9999 — 전역 CSS, 계산에서 빠져 있음
30	MoveTopButton	calc(modal + 20)
20	Loading, DropDown 딤	calc(modal + 10) — 같은 층, 순서는 DOM이 결정
16	DropDown 옵션 목록	calc(modal + 6)
15	QR 모달	calc(10 + stack-index)
14	Alert 모달	calc(10 + stack-index)
13	Alert 모달의 딤	calc(9 + stack-index)
11	StackViewModal, Menu, Purchase	calc(modal + 1)
10	바텀시트들	modalZIndex / var(--z-index-modal-z-index) / '10'
9	HeaderBar, 일반 모달	calc(modal - 1), calc(9 + 0)

정의된 값은 modalZIndex: 10 하나입니다. 나머지는 전부 거기서 몇 칸 떨어졌는지로 적혀 있습니다. 왜 6칸이고 왜 20칸인지는 코드에 없습니다.

관계를 코드에 적지 않으면 관계는 우연히 정해집니다. 굵게 표시한 두 줄을 보면 Alert 모달의 딤(13)이 바텀시트(10)보다 위입니다. 바텀시트가 떠 있는 상태에서 Alert가 열리면 바텀시트는 딤 뒤로 사라집니다. 두 컴포넌트를 잇는 코드는 한 줄도 없습니다. 같은 z-index 좌표계를 쓴다는 것 말고는 연결점이 없고, 그 좌표계는 어디에도 정의되어 있지 않습니다.

오버레이 밖에서도 마찬가지였습니다. 헤더 높이는 토큰으로 정의되어 있는데, “헤더 아래를 채운다”는 계산은 어떤 화면에서는 토큰을 빼는 식으로, 어떤 화면에서는 calc(100vh - 3.5rem)으로 적혀 있습니다. 한 파일 안에서 헤더는 토큰으로, 그 아래 컨테이너는 숫자로 적힌 곳도 있습니다. 헤더 높이를 한 번 바꾸면 앞쪽은 따라오고 뒤쪽은 어긋납니다.

하나씩 보면 전부 그 시점에 가장 빠르고 가장 작은 변경이었고, 리뷰에서 걸릴 이유도 없었습니다. 같은 요구가 서로 다른 코드가 된다는 것을 그때는 부채로 보지 않았기 때문입니다. 같은 층을 가리키는 코드가 이렇게 여러 형태로 남으면 새 예외를 넣는 사람은 어느 쪽을 따라야 할지 판단할 수 없습니다. 결국 가장 가까운 코드가 기준이 됩니다.

이 구조가 감당할 수 있는 예외의 수를 언제 넘어섰는지는 아무도 몰랐습니다. 테스트는 통과했고, 기능은 동작했습니다.

---

3. 코드에 적혀 있지 않으면 알 수 없습니다

이 구조의 한계는 처음 합류한 동료가 화면을 붙이면서 바로 드러났습니다. “이 위에 띄우려면 몇을 써야 하나요.” 이 질문에 코드로 답할 방법이 없었습니다. 아는 사람에게 물어보는 것이 가장 빨랐고, 물어볼 사람이 없으면 주변 코드에서 가장 큰 숫자보다 하나 큰 값을 넣었습니다. 그 값이 다른 화면의 무엇과 겹치는지는 확인할 방법이 없었습니다.

AI 코딩 도구를 쓰면서 같은 일이 훨씬 자주 일어났습니다. “이 위에 띄워달라”고 하면 주변에서 본 값보다 큰 숫자를 넣었습니다. 그것이 어떤 요소와 충돌하는지는 알 수 없었습니다. 코드 어디에도 적혀 있지 않기 때문입니다. 그리고 AI는 그 패턴을 학습해 다음에도 같은 코드를 반복했습니다.

처음에는 프롬프트를 보완할수록 요구사항대로 코드가 동작해서 AI 코드의 품질 문제라고 생각했습니다. 확인해 보니 아니었습니다. 문제는 AI가 기준으로 삼을 화면 간의 관계가 코드에 없다는 것이었습니다. 그래서 새 화면은 30분 만에 나왔는데 새로 띄운 오버레이가 기존 오버레이와 어떻게 겹치는지 확인하는 데는 반나절이 걸렸습니다.

표기 방식이 하나로 통일되어 있었다면 이 반복은 오히려 도움이 됐을 것입니다. 앞의 표처럼 같은 층을 가리키는 표기가 여러 갈래로 남아 있으면, 무엇이 지금의 규칙이고 무엇이 그때의 임시방편인지 구분할 수 없습니다. 정리하지 못한 예외가 새 코드의 기준이 되었습니다.

사람은 “이건 좀 지저분하지만 이유가 있다”를 기억으로 보완할 수 있었습니다. 하지만 그 기억이 없으면 코드에 적히지 않은 규칙은 알 수 없습니다. 새로 합류한 동료도, AI 도구도 같습니다.

이벤트를 위한 페이지가 많아지면서 특정 시기에만 발견되는 예외 케이스가 늘어났습니다. 팀에서 영향도 파악과 검증에 쓰는 시간이 눈에 띄게 늘어난 이유가 이것이었습니다. 규칙이 코드에 없으니 사람이 기억하는 엣지 케이스를 직접 눈으로 보는 것이 유일한 방법이었습니다.

---

4. 말로 전달하는 규칙은 유지되지 않습니다

처음에는 말로 막으려 했습니다. “이렇게 하지 마세요”의 반복입니다.

리뷰 코멘트로, 구두 공유로, AI 도구에 주는 프롬프트로 “z-index를 직접 쓰지 마세요”, “기존 컴포넌트를 먼저 찾아보세요” 같은 문장을 계속 늘렸습니다. 지시가 많아질수록 지켜지는 것과 지켜지지 않는 것을 구분할 수 없게 됐습니다.

세 가지 이유로 실패했습니다.

• 휘발됩니다. 매번 다시 말해야 하고, 말하지 않으면 사라집니다.
• 검증할 수 없습니다. 규칙이 지켜졌는지 확인할 방법이 없습니다.
• 충돌합니다. 규칙이 늘어날수록 서로 부딪히고, 결국 아무것도 지켜지지 않습니다.

당연한 결과였습니다. 말로 전달하는 규칙은 코드에 없는 맥락을 그때그때 임시로 채우는 것입니다. 코드에 규칙이 없으면 해결 방법은 매번 달라집니다.

---

5. 말이 아니라 시스템으로

기억 속 규칙을 코드로 옮겨야 하는 시점이 되었다고 판단했습니다. 매번 판단을 전달하는 대신 판단이 필요 없는 구조를 만드는 쪽으로 방향을 잡았습니다.

5-1. 선택지를 좁힙니다

같은 성격의 값이 한 곳에 모여 있지 않았습니다. 일부는 토큰에, 일부는 CSS에, 일부는 인라인 스타일에, 일부는 조건 분기 로직 안에 들어 있었습니다.

그래서 일원화의 첫 단계로 토큰화를 진행했습니다. 고를 수 있는 값이 적으면 틀릴 여지도 적습니다. 지시가 아니라 선택지를 줄이는 방식입니다.

다만 모든 케이스를 토큰으로 정의하지는 못했습니다. 정의된 것은 토큰을 통해서만 쓰이지만, 정의되지 않은 것은 여전히 CSS와 인라인과 로직 사이에 남아 있습니다.

절반만 좁혀진 선택지는 절반만 효과가 있습니다. 토큰이 있는 영역에서는 토큰이 쓰이고, 없는 영역에서는 주변 코드를 따라 하게 됩니다. 2장에서 말한 “가장 가까운 코드가 기준이 된다”가 그대로 남아 있는 자리입니다.

5-2. 문서, 사람이 읽는 데까지

지금은 기획서와 정책서, PR 디스크립션에 ‘왜 이렇게 만들었는지, 어떤 예외를 왜 허용했는지’를 남겨두고 있습니다.

4장의 구두 전달과 다른 점은 휘발되지 않는다는 것입니다. 나중에 맥락을 찾아볼 수 있습니다.

한계도 분명합니다. 문서와 PR만으로는 여러 스쿼드에서 동시다발적으로 발생하는 내용을 관리할 수 없었습니다. 결국 그 맥락은 코드가 아니라 코드 바깥에 남고 시간이 지나면 그것이 있다는 사실 자체를 잊게 됩니다.

사람이 찾아 읽어야 지켜지는 규칙은 결국 지켜지지 않습니다. 지금 저희가 온 곳은 기억을 문서로 옮긴 단계까지입니다. 그 문서를 기계가 검증하는 단계는 아직 남아 있습니다.

---

6. 마치며

z-index 뒤에 있던 관계, 그 값이 그 값인 이유, 끝내 하나로 모이지 못한 여러 갈래의 표기 방식. 전부 틀린 코드가 아닙니다. 서비스가 커지면서, 그때는 옳았던 설계가 부채가 된 것입니다. 그동안은 사람의 기억이 그 부분을 대신하고 있었습니다.

기억은 저장소에 남지 않습니다. 만든 사람이 팀을 옮기거나, 6개월이 지나거나, 코드를 읽는 주체가 사람이 아니면 그 규칙은 알 수 없습니다. 코드에 적히지 않은 것은 존재하지 않는 것이 됩니다.

무엇이 규칙이고 무엇이 예외인지, 이 값이 왜 이 값인지, 이 설계가 어디까지 감당하도록 만들어졌는지. 저희 팀의 과제는 그 판단을 코드가 들고 있게 만드는 일이고, 레이어 문제는 그중 한 사례입니다.

명시된 규칙의 수혜자는 처음 합류한 동료이고, 리뷰어이고, 6개월 뒤의 저입니다. AI 도구는 그 필요를 조금 더 일찍 알려줬을 뿐입니다.

접근 방법은 예전과 같습니다. 사람이 기억하던 규칙을 코드에 적어두는 것입니다.