코딩 스타일 가이드(ESLint)를 나중에 안 것

큰 회사들이 코딩 스타일 가이드를 괜히 두는 게 아니었습니다. 처음엔 “혼자 짜는데 무슨 스타일 가이드냐” 싶었습니다. 그런데 AI와 함께 짜다 보니, 일관된 규칙이 없으면 코드가 매번 조금씩 다른 모양으로 자란다는 걸 알게 됐습니다. 린트 규칙은 취향 문제가 아니라, 세션마다 기억을 잃는 AI에게 강제되는 공통 약속이었습니다. 이 글은 그걸 왜 늦게 깨달았고, 늦게 켜는 게 왜 그렇게 비싼지를 풀어 씁니다.

린트가 뭔가요 — 자동으로 잔소리하는 도구

용어부터 짚겠습니다. **린트(lint)**는 사람이 일일이 보지 않아도, 코드를 자동으로 훑으며 “이건 규칙에 안 맞아”라고 잡아 주는 도구입니다. 자바스크립트·타입스크립트 세계에서 가장 널리 쓰이는 게 ESLint입니다.

용어: 린트(lint) / ESLint

코드를 자동으로 검사해 스타일·문법·위험 패턴을 잡아 주는 도구입니다. 사람이 코드 리뷰에서 매번 지적할 법한 것들(“이 변수 안 써요”, “이 줄 너무 길어요”, “이 함수 너무 커요”)을 기계가 대신, 매번, 똑같이 잡아 줍니다.

용어: 코딩 스타일 가이드

“우리 코드는 이런 모양으로 쓴다”는 합의된 약속입니다. 구글 같은 큰 조직은 언어별로 두꺼운 스타일 가이드를 두고, 그 약속의 상당 부분을 ESLint 같은 도구로 자동 강제합니다. 사람의 기억이 아니라 도구가 약속을 지키게 하는 것입니다.

그러니까 스타일 가이드가 “약속”이라면, 린트는 그 약속을 자동으로 집행하는 “심판”입니다. 큰 회사가 둘 다 두는 이유는 단순합니다 — 사람이 많을수록 약속을 기억으로만 지키게 하면 반드시 새기 때문입니다.

”혼자인데 스타일 가이드가 왜 필요해”

혼자 개발할 땐 이 필요를 잘 못 느낍니다. 내 머릿속 규칙대로 짜면 되니까요. 저도 처음엔 그렇게 생각했습니다. 그런데 두 가지가 이 생각을 정면으로 뒤집었습니다.

• 나는 한 사람이 아닙니다 — 세션이 바뀌면 AI는 이전의 약속을 잊습니다. 한 세션의 “나”와 다른 세션의 “나”가 미묘하게 다른 스타일로 짭니다. 혼자 같지만, 실제론 매번 새 사람과 일하는 셈입니다.
• AI는 일관성의 근거가 없으면 표류합니다 — 명시적 규칙이 없으면, AI는 그때그때 가장 그럴듯한 모양으로 코드를 만듭니다. 그 결과 같은 프로젝트 안에서 패턴이 제각각이 됩니다.

왼쪽: 공통 규칙이 없으면 매 세션이 다른 방향으로 흩어집니다. 오른쪽: 린트 규칙 하나가 모든 세션을 같은 약속으로 끌어당깁니다. AI 협업에선 "매 세션이 새 사람"이라, 이 수렴 장치가 더 절실합니다.

구글 같은 큰 조직이 엄격한 스타일 가이드를 두는 이유가 바로 이거였습니다. 사람이 많을수록 “각자의 취향”이 쌓이면 코드가 누더기가 됩니다. 그런데 AI 협업은 사실상 “매 세션이 새 사람”이라, 그 효과가 더 빨리, 더 크게 나타납니다. 일관성은 미관이 아니라 읽고 고치는 비용의 문제입니다.

늦게 켜면 못 켠다 — 늦은 도입의 진짜 함정

여기서 가장 아픈 교훈이 나옵니다. 스타일 규칙을 나중에 도입하면, 그 순간 기존 코드 전체가 한꺼번에 빨갛게 터집니다.

“나중에 켜자”가 “영영 못 켜자”가 되는 경로

코드가 수만 줄 쌓인 뒤에 린트를 켜면, 수백 개의 위반이 동시에 쏟아집니다. 그걸 다 고칠 엄두가 안 나서 결국 규칙을 못 켜거나, 켜도 경고를 무시하게 됩니다. 무시되는 규칙은 없는 규칙과 같습니다. 그래서 0줄짜리 프로젝트에 규칙을 거는 건 공짜지만, 다 자란 코드에 거는 건 거의 불가능에 가깝습니다.

뒤늦게 도입 — 두 번에 걸쳐

SL.AIMS도 결국 이 함정에 그대로 걸렸고, 뒤늦게 두 번에 나눠 린트를 들였습니다.

1. 1차 — 백엔드 0-warning (2026-05-03) ESLint와 타입스크립트용 플러그인을 백엔드에 설치하고, 쏟아진 경고를 전부 0이 될 때까지 정리했습니다. “경고가 0이다”라는 상태를 한번 만들어 둬야, 이후 새 경고가 곧바로 눈에 띕니다. 깨끗한 바닥을 먼저 만든 셈입니다.
2. 2차 — 거버넌스 규칙 + 프론트 확장 (2026-06-05) 백엔드에 거버넌스 성격의 규칙을 추가하고, 그때까지 빠져 있던 프론트엔드(portal)에도 린트를 설치·설정했습니다. 커밋 이력에 “ESLint 거버넌스 규칙 도입”으로 그 시점이 남아 있습니다.

용어: 0-warning(제로 워닝)

“경고가 단 하나도 없는 상태”를 기준선으로 삼는 정책입니다. 경고를 1개라도 허용하면 곧 10개, 100개가 되어 아무도 안 봅니다. 0을 유지하면 새로 생긴 경고 1개가 즉시 도드라져 그 자리에서 처리됩니다.

시점	대상	한 일
2026-05-03	백엔드	ESLint 설치 + 경고 전부 정리(0-warning 바닥 만들기)
2026-06-05	백엔드 + 프론트	거버넌스 규칙 추가 + 프론트(portal)에 린트 설치·설정

모든 규칙을 “절대 기준”으로 켤 수는 없다

도입하면서 또 하나 미묘한 깨달음이 있었습니다. 린트 규칙 전부를 “절대 기준”으로 켤 수는 없다는 것입니다.

예를 들어 “파일은 300줄을 넘기면 안 된다”(max-lines) 같은 규칙은, 이미 1,000줄짜리 파일이 수십 개인 프로젝트에선 켜는 순간 전부 터집니다. 위 §“늦게 켜면 못 켠다”의 함정 그대로입니다. 그래서 이런 크기 규칙은 절대 기준 대신, **“지금보다 나빠지지만 마라”**는 점진적(ratchet) 방식으로 바꿔 적용해야 했습니다.

규칙 성격	예	레거시 위에서 켤 수 있나
절대 기준	”안 쓰는 변수 금지”, “== 대신 ===”	대체로 OK — 위반이 적고 기계가 고쳐 줌
절대 기준(크기류)	“파일 300줄 초과 금지”	✗ 켜는 순간 수백 개 터짐 → 못 켬
점진(ratchet)	“지금 크기보다 더 커지면 차단”	✓ 오늘 당장 켤 수 있음

즉 같은 “파일 크기”를 다루더라도, 절대 기준으로 들이밀면 못 켜지만 점진 방식이면 켜집니다. 이 ratchet 이야기는 다음 글로 이어집니다. → 파일·함수 크기 ratchet 게이트

린트는 AI에게 주는 “공통 언어”

린트 규칙을 켜 두면, AI가 코드를 짤 때마다 그 규칙이 자동으로 방향을 잡아 줍니다. 사람이 매번 “이 스타일로 해줘”라고 말할 필요가 없습니다. 규칙이 곧 합의된 약속이고, 세션이 바뀌어도 그 약속은 파일에 남아 작동합니다. 사람이라면 코드 리뷰에서 잡을 일을, 린트가 매 커밋마다 똑같이 잡아 줍니다. 이게 AI 협업에서 린트가 특히 값진 이유입니다 — 잊지 않는 리뷰어를 하나 고용한 셈입니다.

처음부터 했어야 할 일

프로젝트 첫날, 코드 한 줄 쓰기 전에 린트부터 켰어야 했습니다. 0줄짜리 프로젝트에 규칙을 거는 건 공짜고, 그때 켜 두면 코드는 처음부터 그 규칙에 맞춰 자랍니다. 수만 줄이 쌓인 뒤에 거는 건 — 봤듯이 — 거의 불가능에 가깝습니다. 스타일 가이드는 “여유가 생기면 할 일”이 아니라 “시작 조건”입니다.

교훈

코딩 스타일 가이드(린트)는 혼자여도, 아니 AI와 함께라면 더더욱 필요합니다. ① 세션마다 약속을 잊는 AI에게 린트는 세션을 넘나드는 공통 약속이자 잊지 않는 리뷰어입니다. ② 규칙은 첫날에 켜십시오 — 코드가 쌓인 뒤엔 위반이 폭주해 못 켭니다(“나중에”가 “영영”이 됩니다). ③ 일부 규칙(특히 크기류)은 절대 기준이 아니라 “악화 금지”의 점진(ratchet) 방식으로 적용해야 레거시 위에서도 켤 수 있습니다.

---

이 글은 SL.AIMS를 만들며 겪은 현장 회고 중 하나입니다. 전체 그림은 〈사례연구: SL.AIMS〉에 있고, 크기 규칙을 레거시 위에서도 켜는 ratchet 게이트 이야기로 이어집니다.