하드코딩이 너무 많았던 것

“승인됨”, “반려”, “대기” — 이런 상태값을 코드 곳곳에 글자 그대로 박아 넣었습니다. 처음엔 편했습니다. 그런데 그 한 줄 한 줄이 나중에 수백 개의 수정 지점이 되어 돌아왔습니다. 하드코딩은 빌린 줄도 모르고 빌린 빚이었고, 갚는 데만 4월부터 6월까지 걸렸습니다. 이 글은 “그 작은 글자 하나가 왜 그렇게 비쌌는지”를, 모르는 분도 따라올 수 있게 처음부터 풀어 쓴 기록입니다.

”하드코딩”이 정확히 뭔가요

먼저 용어부터 짚겠습니다. 개발자들이 말하는 **하드코딩(hard-coding)**은 “변할 수 있는 값을 코드 안에 글자 그대로 못 박아 넣는 것”입니다. 못 박았다는 비유 그대로입니다 — 한번 박으면 빼기 어렵고, 같은 못을 여러 군데 박으면 뺄 때 전부 찾아다녀야 합니다.

용어: 하드코딩

상태·종류·라벨처럼 나중에 바뀔 수 있는 값을, 한 곳에서 관리하지 않고 코드 여기저기에 직접 적어 넣는 것입니다. 예: 문서가 승인됐는지 판단하는 자리마다 'APPROVED'라는 글자를 손으로 적어 넣는 것.

구체적인 장면은 이렇습니다. 전자결재 문서에는 상태가 있습니다 — 작성중, 상신됨, 결재중, 승인, 반려 같은 것들. 이 상태를 다루는 코드를 짤 때, 저는 그냥 'APPROVED', 'REJECTED' 같은 글자를 그 자리에 직접 적었습니다. 화면에 “승인됨”이라고 띄울 때도 그 한글을 그 자리에 박았습니다. 이렇게 하면 당장은 빠릅니다. 별도 테이블을 설계할 필요도, 어딘가에서 값을 불러올 필요도 없으니까요.

왜 처음엔 다들 이렇게 하나

하드코딩은 게으름이 아닙니다. 오히려 가장 자연스러운 첫 선택입니다. 문서 하나의 상태를 화면에 보여주는 코드를 처음 짤 때, “승인됨”이라고 바로 적는 것보다 빠른 길은 없습니다. 테이블을 설계하고, 코드값 규칙을 정하고, 라벨을 불러오는 구조를 만드는 건 — 그 순간엔 과해 보입니다.

문제는 그 “한 번”이 절대 한 번으로 끝나지 않는다는 점입니다. 같은 상태값이 백엔드에도, 프론트엔드 화면에도, 모바일 앱에도, 그리고 그 각각의 안에서도 수십 군데에 흩어져 박힙니다. 결재 목록에서 한 번, 상세 화면에서 한 번, 통계에서 한 번, 알림 문구에서 한 번… 그렇게 하나의 개념(“승인”)이 수십 개의 복제본으로 번집니다.

왼쪽: 같은 "승인" 개념이 6군데에 다른 표기로 복제된 상태. 오른쪽: 코드값·영문·한글 라벨을 한 테이블에서만 정의하고, 모든 곳이 그것을 참조하는 상태. 고칠 곳이 여섯 개에서 하나로 줄어듭니다.

무엇이 위험한가 — tsc도 테스트도 못 잡는 버그

복제 자체가 왜 위험할까요. 핵심은 **“한 곳에서 표기를 살짝 다르게 적으면 조용히 어긋난다”**는 데 있습니다. 누군가(사람이든 AI든) 한 자리에서는 'APPROVED'라고 적고, 다른 자리에서는 'Approved'라고 적으면, 두 글자는 컴퓨터에겐 완전히 다른 값입니다.

가장 무서운 종류의 버그

이런 오타는 컴파일러(tsc)도 단위 테스트도 잡지 못합니다. 둘 다 “글자가 문법에 맞는가”만 보지, “그게 올바른 상태값인가”는 모르기 때문입니다. 코드는 멀쩡히 빌드되고, 테스트는 초록불이 켜집니다. 그런데 실제로는 라벨이 안 뜨거나, 더 나쁘게는 분기 로직이 조용히 어긋나 승인된 문서가 미승인으로 취급되는 식의 사고가 납니다. 화면 한 군데가 깨지는 건 차라리 다행입니다 — 로직이 어긋나면 데이터가 틀어집니다.

그리고 AI와 협업하면 이 복제가 더 빨리 번집니다. AI는 눈앞 맥락에 있는 패턴을 그대로 따라 적기 때문입니다. 한 파일에서 'APPROVED'를 본 AI는 다음 파일에서도 망설임 없이 그 글자를 또 박습니다. 멈춰서 “이거 어디서 한 번에 관리해야 하는 거 아닌가?”라고 물을 직관이, 명시적 규칙이 없으면 작동하지 않습니다.

부채에는 이자가 붙는다 — 비용의 변화

하드코딩은 기술 부채의 교과서적 예입니다. 빌릴 땐 공짜처럼 보이지만, 갚을 땐 이자가 붙습니다. 같은 “상태값 하나 바꾸기” 작업의 비용이 시간에 따라 이렇게 변합니다.

시점	그 값이 박힌 곳	”상태 하나 추가/변경” 비용
초기 (코드 1주차)	한 곳	1분 — 그 자리만 고치면 됨
몇 주 후	대여섯 곳	전부 찾아 똑같이 고치기, 한 곳 빠뜨릴 위험
몇 달 후	백엔드·프론트·모바일 수십 곳	”어디에 다 박혔지?”부터 추적, 누락 시 silent 버그
이관 시점	프로젝트 전역	전수 조사 + 마이그레이션 + 검증, 수 개월 작업

맨 아랫줄이 실제로 SL.AIMS가 치른 대가입니다. 처음에 30분이면 설계했을 구조를, 몇 달에 걸쳐 갚았습니다. “나중에 정리하자”가 만든 빚의 전형적인 모습입니다.

대장정 — enum에서 공통코드로

결국 “하드코딩 0”을 원칙으로 세우고, 모든 분류값을 코드에서 데이터로 옮기는 대대적인 이관을 시작했습니다. 출발점에서 두 가지 후보가 있었습니다.

용어: enum(이넘)

프로그래밍 언어가 제공하는 “정해진 값들의 묶음”입니다. 하드코딩보다는 낫습니다(오타를 일부 막아 줍니다). 하지만 새 값을 추가하려면 코드를 고쳐 다시 배포해야 하고, 한글·영문 라벨이나 도메인(영역) 구분을 담지 못합니다.

용어: 공통코드 + SSOT

상태·유형 같은 값을 숫자 코드값("01", "02"…)으로 저장하고, 그 코드의 한글·영문 라벨과 소속 영역을 코드 그룹 테이블 한 곳에서만 정의하는 방식입니다. SSOT(Single Source of Truth, 단일 진실 출처)는 “정답이 오직 한 군데에만 있다”는 원칙입니다.

SL.AIMS는 두 번째를 택했습니다. 핵심 설계는 이렇습니다: 상태·유형을 숫자 코드값으로 저장하고, 코드값 + 영문 라벨 + 한글 라벨 + 소속 도메인을 코드 그룹 테이블에서만 정의합니다. 그리고 백엔드와 프론트는 이 단일 출처에서 생성된 상수를 공유합니다 — 손으로 베껴 적는 게 아니라.

• 코드 추가에 더 이상 배포가 필요 없습니다 — 새 상태가 필요하면 데이터로 한 줄 추가하면 됩니다.
• 라벨이 어긋날 일이 없습니다 — 한글/영문을 한 곳에서만 관리하니까요.
• 도메인이 격리됩니다 — 근태의 “01”과 연차의 “01”이 각자 다른 영역에 속해 서로 충돌하지 않습니다.

세 방식을 한눈에 비교하면 왜 공통코드가 답이었는지 분명해집니다.

방식	오타로 어긋남	새 값 추가	한/영 라벨·도메인
하드코딩(글자 직접)	쉽게 어긋남	곳곳을 손수 수정	담을 곳 없음
enum	일부 방지	코드 고쳐 재배포	담지 못함
공통코드 + SSOT	출처가 하나라 안 어긋남	데이터로 한 줄	한 곳에서 관리

이관은 이렇게 단계로 흘러갔습니다 (실제 순서)

1. W1 — 작업유형부터 가장 기초가 되는 분류값(WorkType 등)을 숫자 코드로 옮기고, 코드를 조회하는 공통 인프라를 먼저 깔았습니다.
2. W2 — 자재·생산·AI·HR·결재 모듈을 차례로 돌며 흩어진 enum을 숫자 코드로 전환했습니다. AI 계층 분류값 7종도 이때 함께 이관됐습니다.
3. W3 — 문서 상태전이 전자결재의 문서 상태(DRAFT·SUBMITTED·APPROVED…)와 단계 상태를 숫자 코드로 옮기고, 상태가 바뀔 때 허용된 전이인지 검증하는 단일 권위를 세웠습니다.
4. Tier B — 화면 소비처 9개 화면에서 하드코딩된 enum을 걷어내고 DB 조회로 바꿔, 2026-05-31에 배포·검증까지 마쳤습니다.

이관에도 함정이 있었다 — 빚을 갚을 때도 이자가 붙는다

글자 라벨을 숫자 코드로 바꾸는 마이그레이션 자체가 또 다른 지뢰밭이었습니다. 운영 중인 DB에 숨어 있던 제약 조건(CHECK)이 새 숫자값을 거부하거나, 타입 변환 단계를 빠뜨리면 데이터가 조용히 안 바뀌는 일이 있었습니다(겉으론 성공한 것처럼 보이는데 실제 갱신은 0건). 그래서 “제약을 먼저 제거하고, 변환 캐스트를 명시하고, 변환 후 실제 값을 눈으로 확인한다”는 배포 런북을 따로 만들어야 했습니다. 하드코딩을 박는 건 1분이었지만, 빼는 건 이렇게 절차가 필요했습니다.

처음부터 했어야 할 일

이 모든 건 프로젝트 첫날, 분류값 설계 30분이면 피할 수 있었습니다. “상태·유형·구분은 코드에 글자로 적지 않는다 — 처음부터 데이터(공통코드)로 둔다.” 이 규칙 하나만 첫날에 정했다면, 몇 달짜리 이관 대장정은 통째로 없었을 것입니다.

덧붙여, 이 하드코딩 문제는 혼자 동떨어진 게 아닙니다. 흩어진 중복 값들은 그대로 코드 양을 불리고, 그 불어난 코드는 AI가 읽어야 할 토큰을 늘리고 컨텍스트를 채워 환각을 부릅니다. 하드코딩·비대화·토큰 폭증은 한 뿌리에서 자란 가지입니다.

교훈

하드코딩은 “빠른 길”이 아니라 “복제된 빚”입니다. ① 상태·유형 같은 분류값은 처음부터 단일 출처(공통코드) 테이블로 둡니다 — enum도 차선책일 뿐, 라벨과 도메인을 담지 못합니다. ② 백엔드·프론트·모바일이 같은 출처에서 생성된 상수를 공유하게 합니다(손으로 베끼지 않습니다). ③ 한 번 흩어진 하드코딩을 되돌리는 비용은 처음 설계 비용의 수십 배이고, 되돌릴 때도 이자(마이그레이션 함정)가 붙습니다 — 지금 박지 않는 게 가장 쌉니다.

---

이 글은 SL.AIMS를 만들며 겪은 현장 회고 중 하나입니다. 전체 그림은 〈사례연구: SL.AIMS〉에 있고, 같은 뿌리에서 자란 코드 비대화 이야기와 토큰 폭증 이야기로 이어집니다.