개발 메모장

squash merge가 release마다 cherry-pick이 충돌하는 이유

Kir93 — Mon, 22 Jun 2026 18:40:20 +0900

1. 도입부 (Why This Matters)

릴리즈 브랜치를 만들 때마다 같은 일이 반복된다. 분명 일상 통합 브랜치에서는 깨끗하게 머지됐던 변경인데, 릴리즈 브랜치에 모으려고 cherry-pick을 돌리면 매번 1~3건씩 충돌이 난다. -x, -m, -X theirs 같은 옵션을 바꿔봐도, 전략(recursive/ort)을 바꿔봐도 결과는 비슷하다. 손으로 풀고, 다음 릴리즈에서 또 푼다.

이 글의 결론을 먼저 말하면 이렇다. cherry-pick을 튜닝하는 건 헛수고다. 충돌의 범인은 cherry-pick이 아니라, 그 한참 앞에서 일어난 squash 머지다. squash가 git이 3-way 머지의 기준점으로 쓰는 공통 조상(merge base)을 지워버리기 때문에, cherry-pick은 "이미 적용된 변경"을 알아보지 못하고 매번 충돌을 만든다.

이 글에서는 (1) squash가 공통 조상을 어떻게 파괴하는지 git 동작 수준에서 풀고, (2) merge --no-ff 직접 머지로 전환해 릴리즈 생성 충돌을 0으로 만든 방법과 검증 결과를 다룬다. 읽는 데 약 8분.

git의 머지·cherry-pick 동작은 안정적이지만, 본문 설명·수치는 2026년 6월 기준이다. 동작이 헷갈리면 git merge-base, git patch-id 문서로 직접 확인하길 권한다.

2. 핵심 개념 (What & Why)

git의 머지는 3-way merge다. 비유하자면, 두 사람이 같은 문서를 각자 고쳐 왔을 때 이를 합치는 일이다. 이때 원본이 있으면 "A는 3 문단을, B는 7 문단을 고쳤구나" 하고 각자의 변경을 분리해 합칠 수 있다. 원본이 없으면 두 결과물을 글자 단위로 비교하는 수밖에 없고, 조금만 겹쳐도 "둘 중 뭐가 맞아?"라며 충돌이 난다.

여기서 원본에 해당하는 것이 merge base(공통 조상) 다. 두 브랜치가 갈라지기 직전의 공통 커밋이며, git merge와 git cherry-pick 모두 이 기준점을 잡아 "양쪽이 각각 무엇을 바꿨는가"를 계산한다. 좋은 공통 조상이 있으면 겹치는 변경도 자동으로 풀리고, 공통 조상이 어긋나면 충돌이 난다.

세 가지 머지 방식을 한 줄씩 정의하면:

merge --no-ff: 머지 커밋을 새로 만들어 양쪽 부모를 모두 기록한다. 히스토리 그래프(조상 관계)가 그대로 보존된다.
squash merge: feature의 커밋 여러 개를 단일 커밋으로 압축해 대상 브랜치에 얹는다. 이 커밋은 원본 커밋들과의 조상 링크가 없다.
cherry-pick: 특정 커밋의 "부모와의 차이(diff)"를 현재 브랜치에 패치처럼 다시 적용한다. 실제로는 그 커밋의 부모를 base로 삼는 3-way 머지다.

핵심은, 이 세 가지가 merge base를 각각 다르게 다룬다는 점이다. 그리고 그 차이가 릴리즈 충돌의 발생 여부를 가른다.

3. 동작 원리 (How It Works)

3-1. squash가 공통 조상을 지운다

스쿼시 + cherry-pick 릴리즈: 조상 링크가 끊겨 공통 조상을 못 찾고 충돌하는 구조

그림 1. feature를 squash로 통합하면 단일 커밋 S가 생기는데, S는 f1·f2·f3와의 조상 관계가 끊겨 있다. 릴리즈 브랜치에 그 변경을 넣으려면 S를 cherry-pick 할 수밖에 없고, 이때 공통 조상이 어긋나 충돌이 난다.

feature 브랜치의 커밋 f1·f2·f3를 squash로 통합 브랜치에 머지하면 단일 커밋 S가 생긴다. 그런데 S의 부모는 통합 브랜치의 직전 커밋 하나뿐이다. f1·f2·f3와 S 사이에는 git이 추적할 수 있는 조상 관계가 존재하지 않는다. 원본 feature 브랜치의 커밋들은 영구 히스토리 그래프에서 사라지고, 압축된 S 하나만 남는다.

이제 릴리즈 브랜치를 main에서 잘라낸 뒤 그 변경을 넣는다고 해보자. feature 브랜치를 직접 머지하려 해도, 릴리즈와 feature의 공통 조상은 main인데 정작 그 변경은 S에만 있다. 결국 S를 cherry-pick 하는 길밖에 없다.

그리고 cherry-pick S는 S의 부모를 base로 삼는 3-way 머지다. 문제는 S의 부모(통합 브랜치 tip)에는 릴리즈 브랜치에는 없는 다른 squash 변경들이 섞여 있다는 것이다. base와 릴리즈의 맥락이 어긋나 있으니, 논리적으로는 "그 feature 변경만"인데도 주변 콘텍스트 불일치로 충돌이 난다. 게다가 git이 "이 변경은 이미 적용됐다"를 인식하는 수단(조상 추적, patch-id)이 squash로 깨져 있어, 같은 변경이 다른 경로로 들어와도 중복으로 보지 못하고 다시 적용하려다 또 충돌한다.

3-2. `merge --no-ff`는 공통 조상을 살린다

merge --no-ff 직접 머지: 공통 조상 main이 살아 있어 자동 3-way로 해소되는 구조

그림 2. feature와 릴리즈 모두 main에서 갈라져 공통 조상이 main으로 살아 있다. merge --no-ff는 두 부모를 가진 머지 커밋 M을 만들고, git은 main을 merge base로 잡아 겹치는 변경까지 자동으로 풀어낸다.

해법은 squash와 cherry-pick을 둘 다 버리는 것이다. 모든 feature 브랜치를 main에서 자르고, 릴리즈 브랜치도 main에서 자른다. 그러면 둘의 공통 조상은 항상 main 이다.

릴리즈 브랜치에 feature를 merge --no-ff로 직접 머지하면, 두 부모(릴리즈 tip + f3)를 가진 머지 커밋 M이 생긴다. 이제 git은 main을 merge base로 잡아 정상 3-way 머지를 수행한다. 양쪽이 같은 곳을 건드렸더라도 "둘 다 공통 조상 대비 같은 변경을 했네"를 인식하므로 겹치는 변경까지 자동으로 병합된다. 덤으로 커밋이 압축되지 않아 히스토리가 100% 보존된다(추적성).

요약하면, cherry-pick이 아니라 "원본 feature 브랜치를 그대로 머지" 하는 것이 핵심이다. 원본을 머지해야 공통 조상이 살고, 공통 조상이 살아야 3-way가 충돌을 자동으로 해소한다.

4. 실무 적용 (Practical Examples)

❌ 안티패턴 (Anti-Pattern): squash + cherry-pick 릴리즈

# 통합 브랜치: PR을 squash로 머지 → 커밋 압축, 조상 링크 끊김
git checkout develop
git merge --squash feature/awesome
git commit -m "feat: awesome"

# 릴리즈: main에서 자른 뒤 squash 커밋을 cherry-pick
git switch -c release/x main
git cherry-pick <squash커밋>     # ⚡ 매 릴리즈 1~3건 충돌

# 안 통하는 처방들 — 근본 원인(끊긴 조상)을 못 고친다
git cherry-pick -X theirs <squash커밋>
git cherry-pick -m 1 <squash머지커밋>

왜 문제인가: cherry-pick은 squash 커밋의 부모를 base로 삼는데, 그 base에는 릴리즈에 없는 변경이 섞여 있어 3-way 기준점이 어긋난다. -m, -x, -X theirs 같은 옵션은 충돌을 회피할 뿐 원인인 "끊긴 조상"을 복원하지 못한다.

✅ 권장 패턴 (Good Practice): main 기반 + `merge --no-ff` 직접 머지

# 모든 feature는 main에서 자른다 (공통 조상 = main)
git switch -c feature/awesome main
# ... 작업, 일상 통합용 PR은 develop으로 ...

# 릴리즈: main에서 자른 뒤, 포함할 feature 브랜치를 직접 --no-ff 머지
git switch -c release/x main
git merge --no-ff feature/awesome     # 공통 조상 main → 자동 3-way
git merge --no-ff feature/another

왜 되는가: 릴리즈와 각 feature의 공통 조상이 main으로 살아 있어, git이 정상 3-way 머지로 겹침을 자동 해소한다. squash 커밋을 패치로 재적용하는 게 아니라 원본 브랜치를 그대로 머지하는 것이 차이의 전부다.

실행 결과 (한 레포의 측정 사례)

한 프로덕션 프론트엔드 레포에서 전략을 전환한 뒤, 릴리즈 한 건(약 9개 PR 규모)을 생성해 측정한 결과다.

포함 대상 9건 전부 자동 머지 성공, 수동 개입 0.
자동 충돌 해소 2건(package.json, 자동 생성된 타입 선언 .d.ts 파일) — git 3-way가 스스로 처리.
커밋 약 100개 전부 보존(squash였다면 9개로 압축됐을 분량).
릴리즈 생성 충돌 1~3건 → 0건, 생성 체감 시간 약 5분 → 약 30초.

위 수치는 특정 레포·릴리즈 1건 기준의 측정치이며, 코드베이스 규모와 변경 분포에 따라 달라질 수 있다.

5. 장단점 및 고려사항

장점	단점
✓ 릴리즈 생성 충돌 대부분 자동 해소(공통 조상 보존)	✗ 머지 커밋이 늘어 히스토리 그래프가 복잡해 보임
✓ 커밋 히스토리·추적성 100% 보존	✗ feature 브랜치를 릴리즈 시점까지 보존해야 함
✓ cherry-pick 옵션 튜닝이 필요 없음	✗ "main은 모든 분기의 깨끗한 베이스" 불변식을 유지해야 함
✓ PR→develop, feature→release, release→main에 동일 전략 일관 적용	✗ 단일 trunk + squash가 더 잘 맞는 팀에는 과할 수 있음

도입 체크리스트:

main을 모든 feature/release 분기의 공통 베이스로 고정한다.
모든 머지를 --no-ff 일반 머지로 통일한다(squash·rebase·cherry-pick 배제).
feature 브랜치는 릴리즈에 포함될 때까지 살려두고, 릴리즈 완료 자동화에서 일괄 삭제한다.
릴리즈 완료 후 main을 통합 브랜치로 동기화해 "통합 브랜치 = main + 진행 중 PR" 상태를 유지한다.
히스토리 가독성은 git log --first-parent로 보완한다(머지 커밋만 따라 1차 흐름만 보기).

흔한 함정: "squash가 히스토리를 깔끔하게 해 준다"는 통념이다. 단일 trunk 모델에서는 맞는 말일 수 있지만, 릴리즈를 cherry-pick으로 조립하는 구조라면 그 깔끔함의 청구서가 매 릴리즈 충돌로 돌아온다. 전략은 팀의 릴리즈 방식과 함께 골라야 한다.

6. 결론 및 다음 단계 (Conclusion)

핵심 3줄 요약:

릴리즈 cherry-pick 충돌의 근본 원인은 cherry-pick이 아니라, 그 앞단의 squash가 공통 조상(merge base)을 지운 것이다.
main 기반 + merge --no-ff 직접 머지로 공통 조상을 살리면, 3-way 머지가 겹치는 변경까지 자동으로 해소한다.
머지 전략 자체를 바꾸지 않으면 cherry-pick 옵션 튜닝은 부질없다.

프런트엔드 AX 설계기 0편 — 레거시 3개와 차세대 FE를 위한 워크플로우 설계기

Kir93 — Fri, 19 Jun 2026 19:26:40 +0900

1. 도입부 (Why This Matters)

React 15에 묶인 레거시 프로젝트 3개와, Next.js 기반 차세대 프로젝트들을 한 사람이 동시에 굴리는 상황을 떠올려 보자. 프로젝트마다 컨벤션이 다르고, 빌드 함정이 다르고, "여기서는 이렇게 하면 안 된다"는 암묵지가 다르다. 컨텍스트 스위칭 비용만으로도 하루가 샌다.

여기에 AI를 얹으면 처음엔 빨라진 것 같다. 그런데 곧 다른 종류의 비용이 보인다. 채팅창에 그때그때 프롬프트를 복붙 하니 결과가 매번 다르고, AI가 건드리면 안 되는 곳을 건드려도 막을 경계가 없고, 잘 된 흐름을 재현할 수도 팀에 넘길 수도 없다. 산발적 사용의 한계는 속도가 아니라 운영 가능성에서 드러난다.

이 글은 그 한계를 마주한 FE 한 명이 4개월에 걸쳐 AI 워크플로를 "설계"로 끌어올린 기록의 입구다. 이 글을 읽고 나면 (1) 왜 팁 모음이 아니라 설계가 필요한지, (2) 그 설계가 어떤 4개의 축으로 묶이는지, (3) 11편 중 어디부터 읽으면 되는지를 얻는다. 예상 소요: 약 8분.

2. 핵심 개념 (What & Why)

먼저 신생 용어 두 개를 한 줄로 정의하고 넘어가자. 둘 다 아직 자리 잡는 중인 말이라 용어 자체에 무게를 싣지는 않는다.

바이브 코딩(vibe coding): AI 에이전트와 함께 코드를 만드는 개발 방식. 즉 개발 과정에 AI가 들어온 것.
AX(Agent Experience): 에이전트를 위해, 에이전트와 함께 쓰도록 인터페이스를 설계하는 일. 즉 제품 표면에 AI가 들어온 것.

비유하자면 AI에게 일을 맡기는 것은 유능하지만 처음 온 신입에게 일을 맡기는 것과 같다. 신입에게 우리는 무엇을 하는가? 건드려도 되는 것과 안 되는 것을 정하고(권한), 결과를 검수하고(게이트), 신뢰가 쌓이면 재량을 늘리고(자율성), 온보딩 문서를 정비한다(운영). AI도 정확히 같은 네 가지가 필요하다. 산발적 프롬프트에는 이 넷이 전부 빠져 있다.

여기서 중요한 연결고리 하나. 이건 FE의 본업에서 벗어난 일이 아니다. FE의 본질은 "사람과 시스템 사이의 인터페이스를 설계·구현하는 craft"다. 그 인터페이스의 양 끝에 이제 사람만이 아니라 AI가 들어온다 — 우리가 AI와 함께 만들고(바이브 코딩), AI를 위해 만들기(AX) 때문이다. AI 워크플로를 설계한다는 것은 개발자와 에이전트 사이의 인터페이스를 설계한다는 뜻이고, 그건 영역이 넓어진 FE의 일이다. 표면이 사람이든 에이전트든, 인터페이스를 잘 만드는 craft는 하나다.

그래서 이 시리즈는 "Claude Code 팁 모음"이 아니다. 팁은 개별 기교지만, 여기서 다루는 건 팀 단위 운영을 전제로 한 권한·검증·자율성·운영의 설계다.

3. 동작 원리 (How It Works)

설계는 크게 4-layer 책임 분리라는 뼈대 위에서, 4개의 축으로 펼쳐진다.

프론트엔드 AX 설계기 — 시리즈 지도

뼈대: 4-layer 책임 분리

산발적 사용이 위험한 핵심 이유는 "권한"과 "재사용"과 "실행"이 한 덩어리로 뭉쳐 있다는 데 있다. 이걸 네 겹으로 가른다.

Public command — 사람이 부르는 진입점. 이름·인자·게이트만 책임진다. 권한 게이트가 여기 있다.
Internal skill — 여러 커맨드가 공유하는 재사용 계약. 단, skill 자체는 권한 경계가 아니다. (이 명제가 1편의 주제다.)
Shared docs — 권한 경계 매트릭스 같은 공유 가이드. 결정의 근거를 한 곳에 모은다.
Agent — 권한 분리 실행. tool scope로 "이 작업은 읽기 전용 도구만" 같은 식으로 권한을 분배한다.

권한은 skill에 숨기는 게 아니라 public command의 게이트 · 명시적 사용자 확인 · agent의 tool scope 세 곳으로 분배된다. 이 원칙 하나가 나머지 설계 전체의 토대다.

4개의 축

권한 경계 — AI가 무엇을 건드릴 수 있나. (1편 skill≠경계, 2편 agent 기본 OFF, 8편 자율 모드 경계, 9편 외부 도구(MCP) 경계)
검증 게이트 — 결과를 어떻게 믿나. (4편 Claude 분석·Codex 비평의 교차 검증, 5편 writer/evaluator 분리, 6편 게이트 보정·철회·earn-back, 7편 AI 변조·CI-gaming 탐지)
라이프사이클 — 계획과 구현을 어떻게 잇나. (3편 양방향 spec lifecycle)
운영 결정 — 무엇을 계속 유지·폐기하나. (10편 모델 선택 운영, 11편 운영 루프 회고)

각 편은 독립된 "결정 + 측정" 아크라서, 어느 편부터 읽어도 성립한다. 0편(이 글)은 그 전체 지도와 "왜 설계가 필요했나"를 담는 입구다.

4. 실무 적용 (Practical Examples)

축적된 규모를 먼저 정직하게 밝히면, 약 4개월간 200+ 커밋, 공개 커맨드 13개·내부 skill family 10개·에이전트 6개로 수렴했고, 정식 릴리스 흐름(CHANGELOG·semver·릴리스 노트·공지)으로 v0.1.0부터 v0.6.1까지 운영했다. 이 숫자는 생산성 배수가 아니라 들인 노력과 범위를 가리킨다. "AI로 N배 빨라졌다" 류 주장은 측정 조건 없이는 하지 않는다.

✅ 권장 패턴 (Good Practice)

책임을 4-layer로 가르고, 진입점은 게이트를 명시한다.

<!-- commands/ship.md — public command: 이름·인자·게이트만 책임진다 -->
---
description: 변경분을 검증하고 릴리스한다
argument-hint: [patch|minor|major]
---
1. 검증 게이트: 테스트·린트·타입체크 통과 확인 (실패 시 즉시 중단)
2. 사용자 확인: 버전 범프 내용을 명시하고 명시적 승인을 대기
3. 실행: 승인 시에만 release 에이전트에 위임 (해당 agent는 제한된 tool scope)

# 디렉터리도 책임별로 갈라 둔다
commands/   # public  : 사람이 부르는 진입점 + 게이트
skills/     # internal: 재사용 계약 (권한 경계 아님)
agents/     # 실행    : tool scope로 권한 분리
docs/guides/# shared  : 권한 경계 매트릭스 등 결정의 근거

핵심은 세 가지다. 게이트가 진입점에 보이게 있고(2단계 전 1단계가 막는다), 위험한 실행은 명시적 승인 뒤로 미루며, 실행 권한은 agent의 tool scope로 좁힌다.

❌ 안티패턴 (Anti-Pattern)

# 모든 규칙·권한·예외가 한 파일에 뒤섞임
~/.claude/CLAUDE.md   # 수천 줄, 무엇이 무엇을 막는지 추적 불가
# 실행: 매번 채팅창에 긴 프롬프트를 복붙, 사람마다 표현이 다름

무엇이 문제인가? 권한 경계가 어디에도 명시되지 않아 AI가 무엇이든 건드릴 수 있고, 같은 작업도 사람·시점마다 결과가 달라 재현이 안 되며, 잘 된 흐름을 팀에 넘기거나 회귀를 추적할 수 없다. 빨라 보이지만 운영이 불가능하다.

실행 결과

권장 패턴에서 /ship minor를 부르면, 테스트가 깨진 순간 1단계에서 멈춘다. 통과하면 "minor 범프: 0.6.1 → 0.7.0" 같은 내용을 보여주고 사람의 승인을 기다린다. 승인 후에야 tool scope가 제한된 에이전트가 릴리스를 수행한다. 같은 명령은 누가 부르든 같은 게이트를 통과하므로 재현 가능하고, 그대로 팀에 공유된다.

5. 장단점 및 고려사항

장점	단점
✓ 권한 사고를 게이트·승인·scope로 구조적으로 차단	✗ 초기 설계·정비 비용이 든다 (산발적 사용보다 느린 출발)
✓ 재현 가능 — 같은 명령은 같은 결과 게이트를 통과	✗ 도구 스펙 변화에 맞춰 지속 유지보수 필요
✓ 팀 공유·온보딩이 명령 한 줄로 가능	✗ 과설계 위험 — 1인·소규모엔 무거울 수 있음
✓ 회귀·변조를 검증 게이트로 조기 포착	✗ 측정 없이 "효과"를 주장하면 hype가 된다

도입 체크리스트(작게 시작):

가장 위험한 작업 하나(예: 릴리스·마이그레이션)부터 게이트 + 명시 승인으로 감싼다.
권한이 "어디서" 분배되는지 한 장의 표(권한 경계 매트릭스)로 적는다.
자주 쓰는 흐름 1~2개만 public command로 고정해 재현성을 확보한다.
효과는 측정 조건과 함께만 기록한다(예: "이 코퍼스 기준 토큰 N% 절감(추정)").

흔한 함정: skill에 권한을 숨겨두고 "경계를 세웠다"라고 착각하는 것. skill은 재사용 계약일뿐 권한 경계가 아니다(→ 1편).

6. 결론 및 다음 단계

핵심 3줄 요약:

산발적 AI 사용의 한계는 속도가 아니라 운영 가능성(권한·재현·공유)에서 드러난다.
해법은 팁이 아니라 설계 — 4-layer 책임 분리 위에 권한·검증·라이프사이클·운영 4개 축을 얹는다.
이건 곁다리가 아니라 개발자와 에이전트 사이 인터페이스를 만드는, 넓어진 FE의 본업이다.

안 만든 것이 규율이다 — 절제로 끌고 간 토이 프로젝트 회고 (Scrooge 5편)

Kir93 — Tue, 16 Jun 2026 17:53:09 +0900

scrooge

1. 도입부 — 토이 프로젝트가 망하는 진짜 이유

개인 프로젝트는 보통 기능 부족으로 망하지 않는다. 하고 싶은 게 너무 많아서 망한다. "이왕 만드는 김에 이것도", "나중에 필요할 테니 미리", "더 일반적으로 추상화해두면" — 이런 충동이 쌓이면, 정작 핵심은 미완인 채로 곁가지에 짓눌려 프로젝트가 무거워진다. 혼자 쓰는 도구일수록 이 제동장치가 없다. 리뷰어도, 데드라인도, 말려줄 동료도 없으니까.

scrooge는 약 2주, 57개 커밋으로 v0.6.1까지 굴러간 작은 도구다(2026-05-25 첫 커밋 ~ 06-02). 이 회고에서 말하고 싶은 건 그동안 만든 기능 목록이 아니다 — 그건 0~4화에서 충분히 다뤘다. 대신 "안 만든 것"이 어떻게 이 도구를 가볍게 유지했는가를 말하려 한다.

이 글에서 당신이 얻어갈 것은, 토이 프로젝트에 적용할 수 있는 "절제의 규율(discipline of restraint)" 몇 가지와, 그 규율이 실제로 무엇을 막았는지에 대한 구체적 사례다. 추상적 다짐이 아니라, "이 규칙이 없었다면 만들었을 것"의 목록이다.

2. 핵심 개념 — 규율은 "막은 것"으로 측정된다

좋은 working rule의 효과는 눈에 잘 안 띈다. 막은 것은 존재하지 않으므로 보이지 않기 때문이다. 쓰지 않을 추상을 안 만들었다면, 그 안 만든 추상은 코드베이스 어디에도 없어서 "내가 뭘 아꼈는지"조차 잊는다. 그래서 절제의 규율은 의식적으로 기록해야 그 가치를 알 수 있다.

이 글의 척추는 하나의 원칙이다.

speculative 금지 — 미래의 Task는 스캐폴딩일 뿐, 미리 만들지 않는다.

"나중에 필요할 것 같아서" 미리 짓는 코드를 금지하는 규칙이다. 그리고 이 원칙은 혼자 굴러가지 않는다. simplicity first(가장 단순한 해법부터), surgical changes(필요한 곳만 최소 변경), verification gate(완료 전 검증 통과 강제)가 함께 절제의 망을 짠다. 이들은 CLAUDE.md의 Working rules에 명문화돼 있다.

3. 동작 원리 — 각 규칙이 막은 것

규칙을 "지킨 미덕"이 아니라 "막은 사고"로 뒤집어 보면 그 값어치가 드러난다.

working rule이 실제로 막은 것: speculative 금지·simplicity first·surgical changes·verification gate가 각각 차단한 부채

speculative 금지 → 안 쓸 추상·죽은 코드를 막았다.
scrooge를 만들다 보면 "압축 규칙을 플러그인 시스템으로 일반화하면 어떨까", "dial을 임의 단계로 확장 가능하게 미리 설계하면" 같은 유혹이 온다. 전부 지금은 안 쓰는 기능이다. speculative 금지는 이걸 "필요해지면 그때"로 미뤘다. 결과적으로 코드베이스에 쓰이지 않는 추상 레이어와 죽은 코드가 쌓이지 않았다. 미래를 위한 스캐폴딩은 대부분 그 미래가 안 와서 부채로만 남는다.

simplicity first → 과설계를 막았다.
4화에서 본 단일 전역 상태 파일(~/.claude/.scrooge-active)이 좋은 예다. 프로젝트별·세션별 상태 키를 두는 "더 일반적인" 설계가 가능했지만, simplicity first는 "지금 필요한 가장 단순한 것"을 골랐다. 전역이라는 한계는 4화에서 솔직히 적었지만, 그 단순함이 상태 관리 코드를 한 군데로 모아줬다. 필요해지기 전에 일반화하지 않는다가 핵심이다.

surgical changes → 곁다리 리팩터의 회귀 위험을 막았다.
기능 하나를 고치다 보면 "이 김에 주변도 정리하자"는 충동이 온다. surgical changes는 변경을 필요한 곳에 국한했다. 곁다리 리팩터는 리뷰하기 어려운 큰 diff를 만들고, 본 작업과 무관한 회귀를 끌어들인다. 작은 변경은 되돌리기도 쉽다.

verification gate → 불일치와 "됐겠지" 머지를 막았다.
scrooge의 registry는 language × dial → rule path 1:1 계약이다(0화). 규칙 파일을 옮기거나 이름을 바꾸면 같은 변경에서 registry도 동기화해야 한다. verification gate는 이 동기화를 사람의 기억이 아니라 완료 전 검증에 맡겼다. "아마 맞겠지" 하고 머지했다가 registry와 실제 파일이 어긋나는 사고를 구조적으로 막은 것이다.

4. 실무 적용 — 절제를 규칙으로 박기

이 시리즈에서 "코드 예제" 자리는 working rule 문서가 채운다. 토이 프로젝트에도 그대로 옮길 수 있는 형태다.

✅ Good Practice — working rule을 명문화하고 "안 만들 것"을 적기

# CLAUDE.md — Working rules (발췌, 개념적 표현)

## 절제 원칙
- speculative 금지: "나중에 필요할 것 같아서"는 만들 이유가 아니다.
  미래 Task는 스캐폴딩으로만 남기고 코드로 짓지 않는다.
- simplicity first: 지금 필요한 가장 단순한 해법부터. 일반화는 두 번째
  사용 사례가 실제로 등장하면 그때.
- surgical changes: 변경은 필요한 곳에 국한. "이 김에"를 금지.
- verification gate: 완료 전 검증을 통과해야 머지. registry-rule 1:1
  동기화는 검증 항목에 포함.

## (선택) "안 만들기로 한 것" 로그
- 압축 규칙의 범용 플러그인화 → 보류 (사용 사례 1개뿐)
- dial 임의 단계 확장 → 보류 (lite/full로 충분)

핵심은 마지막 섹션이다. "안 만들기로 한 것"을 명시적으로 적으면, 막은 것이 비로소 보인다. 같은 충동이 또 올 때 "이미 보류하기로 했지"로 빠르게 처리된다.

❌ Anti-Pattern — "이왕 만드는 김에"의 누적

# 규칙 없는 토이 프로젝트의 전형
- "이왕이면 플러그인 시스템으로" → 안 쓰는 추상
- "나중을 위해 설정 레이어 미리" → 죽은 코드
- "이 김에 주변 리팩터" → 큰 diff, 회귀 위험
- "혼자 쓰는데 검증은 무슨" → registry-rule 불일치 방치

왜 문제인가. 각각은 "더 좋게 만들려는" 선의지만, 누적되면 핵심을 곁가지가 짓누른다. 혼자 쓰는 도구라 제동장치가 없으니 더 빨리 무거워진다. 그리고 이 부채는 "기능"처럼 보여서 줄이기도 어렵다 — 만든 걸 지우는 건 안 만드는 것보다 늘 힘들다.

실행 결과 — 절제가 남긴 궤적

약 2주·57커밋·v0.6.1이라는 작은 궤적은 규모로 인상적인 숫자가 아니다. 이 숫자의 의미는 반대다 — 이 기간 동안 쌓이지 않은 부채가 이 도구를 계속 손볼 만하게(maintainable) 유지했다는 것이다. dogfooding도 같은 결이다. 압축 도구를 만들며 그 도구로 압축한 문서를 쓰는(자기 도구를 자기가 먹는) 습관은, "안 쓰는 기능"을 일찍 발견하게 해줘 speculative를 자연히 억제했다. (registry 확장성과 dogfooding의 자세한 이야기는 0화에서 다뤘으니 여기선 콜백만.)

5. 장단점 및 고려사항

장점	단점·비용
✓ 부채가 안 쌓여 도구가 계속 손볼 만함	✗ "나중에 필요했던" 걸 그때 만드는 비용 발생
✓ 작은 변경이라 리뷰·롤백이 쉬움	✗ 큰 그림 리팩터를 미루다 한꺼번에 몰릴 수 있음
✓ "안 만들 것" 로그가 같은 고민을 재활용	✗ 규율을 기록·유지하는 약간의 오버헤드

실무 팁 — 토이 프로젝트 절제 체크리스트

"나중에 필요할 것 같아서"는 만들 이유가 아니다. 두 번째 사용 사례가 실제로 올 때까지 미룬다(speculative 금지).
가장 단순한 해법부터 시작한다. 일반화는 단순함이 한계에 부딪힌 뒤에.
변경을 필요한 곳에 국한한다. "이 김에"가 떠오르면 별도 작업으로 적어두고 지금은 안 한다.
혼자 써도 검증 게이트를 둔다. 계약(registry 같은)이 있으면 그 동기화를 사람 기억이 아니라 검증에 맡긴다.
"안 만들기로 한 것"을 기록한다. 막은 것은 보이지 않으므로, 적어야 그 가치를 안다.

핵심 3줄 요약

토이 프로젝트는 기능 부족이 아니라 "이왕이면"의 누적으로 무거워진다. 품질은 무엇을 만들었나가 아니라 무엇을 안 만들었나로 갈린다.
speculative 금지·simplicity first·surgical changes·verification gate는 각각 죽은 코드·과설계·회귀 위험·계약 불일치를 막았다 — 규율은 막은 것으로 측정된다.
막은 것은 보이지 않으므로 "안 만들기로 한 것"을 기록해야 그 가치가 드러난다.

시리즈를 마치며

이 시리즈는 "출력을 다루는 일도 인터페이스 craft"라는 한 줄을 따라왔다. scrooge는 LLM 출력의 표현·register·포맷을 설계하는 도구였고, 그건 FE가 오래 잘해온 presentation layer가 에이전트 표면으로 넓어진 것일 뿐이다. 접근성으로서의 압축(0화), 측정 우선(1화), 안전성 계약(2화), 비자명한 디버깅(3화), 멀티 호스트 이식(4화), 그리고 절제(5화) — 표면이 사람이든 에이전트든, 결과물이든 그걸 만드는 과정이든, 잘 만드는 craft는 결국 하나다.

저장소는 github.com/Kir93/scrooge-mode에 공개돼 있고, 이슈·PR·새 언어 rule 기여 모두 환영한다.

켰는데 왜 안 먹지 — 하나의 모드를 Claude Code와 Codex 두 호스트에 (Scrooge 4편)

Kir93 — Mon, 15 Jun 2026 17:50:00 +0900

scrooge

1. 도입부 — "같은 기능"이 호스트마다 다른 표면을 갖는다

압축 모드 하나를 Claude Code에서 잘 돌렸다고 하자. 이걸 Codex에도 태우려 한다. 기능은 "똑같다" — 사용자 입력에 압축 지시를 끼워 LLM이 짧게 답하게 만든다. 그런데 막상 옮기려 보면, 두 호스트가 개입하는 메커니즘 자체가 다르다. 같은 기능인데 표면이 갈린다.

여기에 더 음험한 문제가 겹친다. "scrooge가 켜졌다"는 말이 실은 세 가지 다른 의미로 쓰이고 있었다는 점이다. 설치됐다는 뜻인지, 지금 활성이라는 뜻인지, 이 세션에만 거는 지시라는 뜻인지. 이 셋을 섞으면 "분명 켰는데 왜 안 먹지" 같은 혼란이 반드시 생긴다.

이 글에서 당신이 얻어갈 것은 두 가지다. 하나는 같은 기능을 다른 hook 메커니즘에 이식하는 패턴, 다른 하나는 "설치 범위 ≠ 활성 상태 ≠ 세션 지시"라는 세 개념을 분리하는 멘탈 모델과, 그걸 어겼을 때 생기는 구체적 함정이다. 워크플로 글인 만큼 멱등성·가드레일·검증을 특히 강조한다.

2. 핵심 개념 — 섞이기 쉬운 세 가지

용어 1줄 정의 — hook: 에이전트의 동작 흐름 중간에 끼어들어 입력·출력을 가로채거나 변형하는 확장 지점. scrooge는 hook으로 사용자 입력에 압축 지시를 주입한다.

scrooge를 멀티 호스트로 옮기며 가장 중요했던 통찰은, "scrooge 켜짐"을 세 층으로 분리한 것이다.

설치 범위·활성 상태·세션 지시 3개념 분리와, 단일 전역 상태 파일이 만드는 함정

설치 범위(install scope): hook이 어디에 설치됐는가. user-level(전역)에 깔렸는가, 특정 위치에만 깔렸는가. → 핵심: 설치됐다고 켜진 게 아니다.
활성 상태(active state): 지금 켜져 있는가. scrooge는 이걸 단일 전역 파일 ~/.claude/.scrooge-active 하나로 표현한다. 파일이 있으면 켜짐, 없으면 꺼짐.
세션 지시(session instruction): 이 세션에만 거는 일회성 지시. 전역 상태를 건드리지 않고 현재 대화에만 압축을 적용하는 경로.

이 셋은 서로 독립이다. 설치돼 있어도 비활성일 수 있고, 전역은 꺼져 있는데 한 세션만 켤 수도 있다. 이 독립성을 인지하지 못하면 디버깅이 미궁에 빠진다.

3. 동작 원리 — 다른 메커니즘, 같은 기능

호스트별로 갈리는 hook 표면

같은 압축 모드인데 두 호스트의 개입 방식이 다르다.

Claude Code: UserPromptSubmit hook으로 사용자 입력 제출 시점에 개입하고, 가시 출력으로 압축 지시를 드러낸다.
Codex: hook intercept로 흐름을 가로채는 방식. 같은 목적이지만 경로가 다르다.

핵심은 "기능 명세는 하나, 호스트 어댑터는 둘"로 본 것이다. 압축 모드라는 추상은 공유하되, 각 호스트의 hook 메커니즘에 맞는 어댑터를 따로 둔다. FE에서 같은 컴포넌트를 다른 렌더 타깃에 태우는 것과 같은 구조다 — 로직은 공유, 어댑터는 분리.

활성 상태는 왜 "전역 파일 하나"인가, 그리고 그 함정

활성 상태를 단일 전역 파일(~/.claude/.scrooge-active)로 둔 건 의도적 단순화다. 상태 관리 코드는 이 파일을 가리키는 getStatePath() 한 군데로 모인다(hooks/scrooge-config.js의 해당 로직). 프로젝트별·세션별 키가 없으니 구현이 단순하고, "지금 켜졌나?"의 답이 항상 명확하다.

대가는 켜고 끄기가 전역이라는 점이다. 그리고 여기서 이 글의 핵심 함정이 나온다.

텍스트 명령 /scrooge는 전역 상태 파일을 켜고 끈다 → 모든 세션에 영향.
반면 skill 단독 호출은 그 세션에만 적용되고 전역 상태는 건드리지 않는다.

즉 "scrooge를 켜는" 두 경로가 서로 다른 층을 건드린다. 사용자가 한 세션에서 skill로 켜고 "켰다"고 믿은 뒤 다른 세션을 열면, 전역 상태는 여전히 꺼져 있어 "어, 껐는데 왜 안 먹지(혹은 켰는데 왜 안 먹지)"가 된다. 이건 버그가 아니라 세 개념(②와 ③)을 섞었을 때 필연적으로 생기는 혼란이다. 그래서 이 함정을 코드 주석이나 버그가 아니라 설계 문서/멘탈 모델 레벨에서 명시하는 게 중요하다(이 동작이 왜 전역인지 코드로 추적한 작업이 한 세션에 기록돼 있다).

멱등한 설치기 — 재설치해도 같은 결과

멀티 호스트 + 전역 상태는 설치/재설치를 까다롭게 만든다. 이전 버전의 hook 블록이 설정 파일에 남아 중첩되거나(중첩 레거시 hook), 더는 안 쓰는 상태가 남는(stale state) 문제다. scrooge 설치기는 이걸 멱등(idempotent)하게 처리한다 — 몇 번을 재설치해도 결과가 같도록, 설치 전에 중첩 레거시 hook 블록과 stale state를 청소한다. 설치가 멱등하지 않으면, 재설치할 때마다 hook이 쌓여 같은 입력에 압축 지시가 두 번 끼는 식의 부작용이 난다.

4. 실무 적용 — 멀티 호스트 어댑터 + 멱등 설치

이 시리즈에서 "코드 예제" 자리는 hook 설정·설치기 구조가 채운다.

✅ Good Practice — 어댑터 분리 + 멱등 설치 + 상태 단일화

// 1) 활성 상태는 단일 전역 파일 한 군데로 (getStatePath 하나)
function getStatePath() {
  return path.join(os.homedir(), ".claude", ".scrooge-active");
}
const isActive = () => fs.existsSync(getStatePath());

// 2) 호스트별 어댑터 분리 — 기능 명세는 공유, 메커니즘만 다름
const adapters = {
  "claude-code": injectViaUserPromptSubmitHook,  // 가시 출력
  "codex":       injectViaHookIntercept,         // intercept
};

// 3) 멱등 설치: 항상 "청소 → 설치" 순서
function install(host) {
  removeNestedLegacyHooks(host);   // 중첩 레거시 hook 제거
  clearStaleState(host);           // stale state 청소
  adapters[host].register();       // 그다음 설치 → 몇 번 돌려도 같은 결과
}

핵심은 (a) 상태가 한 군데(getStatePath)로 모이고, (b) 호스트 차이는 어댑터로 격리되며, (c) 설치가 항상 "청소 먼저"라 멱등하다는 점이다.

❌ Anti-Pattern — 세 개념을 섞고, 설치가 비멱등

// 잘못된 설계
function enableScrooge() {
  // 설치하면서 동시에 켜고, 세션 지시랑도 안 구분
  appendHookBlock(config);           // ← 재설치마다 블록이 쌓임 (비멱등)
  // 활성 상태를 세션마다 따로? 전역으로? 기준 없음
  // skill 호출과 /scrooge가 같은 걸 켠다고 가정 ← 실제론 다른 층
}

왜 문제인가. appendHookBlock은 재설치할 때마다 hook을 누적시켜 압축 지시가 중복 주입된다(비멱등). 그리고 "설치=활성=세션"을 한 함수에 뭉치면, skill로 켠 것과 /scrooge로 켠 것이 같다고 착각하게 만들어 3화에서 본 종류의 "재현 안 되는" 혼란을 낳는다.

실행 결과 — 분리가 사주는 것

세 개념을 분리하고 설치를 멱등하게 만들면, "왜 안 먹지"의 답이 명확해진다. 설치는 됐는데 전역이 꺼졌나(②)? 이 세션만 skill로 켠 거였나(③)? 를 각각 확인하면 된다. 그리고 재설치를 몇 번 하든 hook이 한 벌만 남으므로, 압축 지시 중복 같은 부작용이 구조적으로 사라진다.

5. 장단점 및 고려사항

장점	단점·비용
✓ 호스트가 늘어도 어댑터만 추가하면 됨 (로직 공유)	✗ 어댑터 레이어라는 추상 비용이 선행
✓ 단일 전역 상태 파일로 "켜졌나?"가 항상 명확	✗ 켜고 끄기가 전역 — 프로젝트별 분리 불가
✓ 멱등 설치로 재설치 부작용(중복 hook) 차단	✗ "청소 먼저" 로직을 호스트별로 유지해야 함

실무 팁 — 멀티 호스트 툴링 체크리스트

"켜짐"을 세 층으로 분리한다: 설치 범위 / 활성 상태 / 세션 지시. 한 단어로 뭉치지 않는다.
기능 명세와 호스트 어댑터를 분리한다. 호스트가 늘 때 건드리는 건 어댑터뿐이어야 한다.
활성 상태의 단위를 명시적으로 정한다. 전역이면 "전역임"을 문서에 박고, /scrooge와 skill 단독 호출의 차이를 사용자에게 분명히 알린다.
설치를 멱등하게: 항상 "청소(중첩 레거시 hook·stale state) → 설치" 순서. 재설치가 결과를 바꾸면 안 된다.
검증 게이트를 둔다. 설치 후 "hook이 한 벌만 등록됐는가 / 상태 파일 경로가 단일한가"를 자동 확인한다.

핵심 3줄 요약

같은 압축 모드라도 호스트마다 hook 메커니즘이 다르다(Claude=UserPromptSubmit+가시 출력, Codex=hook intercept). 기능은 공유, 어댑터는 분리로 푼다.
"scrooge 켜짐"은 설치 범위 ≠ 활성 상태 ≠ 세션 지시 세 개념이며, 섞으면 "켰는데 왜 안 먹지" 혼란이 난다. 특히 /scrooge(전역)와 skill 단독 호출(세션 한정)이 다른 층을 건드린다.
멀티 호스트 + 전역 상태에서는 멱등 설치(청소 먼저)가 필수다.

저장소는 github.com/Kir93/scrooge-mode에 공개돼 있고, 이슈·PR·새 언어 rule 기여 모두 환영한다.

재현 안 되는 버그의 정답은 버그가 아니었다 — 비자명한 디버깅 기록 (Scrooge 3편)

Kir93 — Sun, 14 Jun 2026 17:46:17 +0900

scrooge

1. 도입부 — 가장 비싼 버그는 "버그가 아닌 버그"다

디버깅의 교과서적 함정은 존재하지 않는 버그를 쫓는 것이다. 코드 어딘가가 틀렸다고 확신한 채로 가설을 세우고 검증하고 또 세우는데, 알고 보니 코드는 멀쩡했고 내 전제가 틀렸던 경우다.

scrooge를 굴리며 만난 두 버그가 정확히 이 결을 가졌다. 하나는 "무응답"으로 보였지만 사실 정상 동작이었고, 다른 하나는 "압축 때문"으로 보였지만 압축은 원인이 아니었다. 둘 다 표면 증상이 엉뚱한 범인을 가리키고 있었다.

이 글에서 당신이 얻어갈 것은 두 가지다. 하나는 가설을 체계적으로 배제해 "버그 아님"에 도달하는 절차, 다른 하나는 여러 원인이 겹친 현상에서 "진짜 원인"과 "가중 요인"을 분리하는 분석법이다. 둘 다 에이전트 툴링처럼 비결정적이고 여러 레이어가 얽힌 시스템에서 특히 쓸모 있다.

2. 핵심 개념 — 표면 증상과 root cause의 거리

에이전트 플러그인은 여러 레이어가 포개진 시스템이다. 마켓플레이스/배포 레이어, 호스트(Claude Code 등)의 hook 레이어, 플러그인의 command·skill 레이어, 그 아래 모델의 생성 레이어. 증상은 맨 위에서 보이지만 원인은 어느 층에든 있을 수 있다.

그래서 이런 시스템의 디버깅은 "코드를 읽어 버그를 찾는다"보다 "가능한 원인 레이어를 하나씩 배제해 범위를 좁힌다"에 가깝다. 의학의 감별 진단(differential diagnosis)과 같은 구조다. 그리고 그 배제 과정의 끝에서 가끔, "모든 레이어가 정상이다 = 버그가 아니다"라는 결론을 만난다.

용어 1줄 정의 — drift: 의도한 출력 양식에서 모델 출력이 조금씩 벗어나는 현상. 여기서는 한국어 출력에 한자(漢字)가 새어 나오는 "한자 drift"를 가리킨다.

3. 동작 원리 ① — "무응답"의 4겹 오진

/scrooge-stats(절감 통계를 보여주는 명령)가 아무 응답도 내지 않는 증상이 보고됐다. 분명 버그처럼 보였다. 하지만 결정적 단서가 하나 있었다 — 재현이 일정하지 않았다. 이 "재현 안 됨"이야말로 첫 번째 힌트였다. 확정적 버그라면 같은 조건에서 항상 재현돼야 하니까.

가설을 세우고 하나씩 배제해 나갔다.

가설 ① 플러그인 마켓플레이스 캐시 vs 로컬 repo 버전 차이.
가장 흔한 용의자. 마켓플레이스에 캐시 된 플러그인 버전과 로컬에서 개발 중인 repo 버전이 달라, 옛 코드가 도는 상황. → 배제. 버전을 맞춰 확인했지만 증상이 그대로였고, 무엇보다 "재현 안 됨"이 버전 불일치로는 설명되지 않았다.

가설 ② hook intercept가 입력을 가로채 먹어버림.
scrooge는 hook으로 동작에 개입한다. hook이 stats 호출을 가로채 응답을 삼켰을 수 있다. → 배제. hook intercept 경로를 시뮬레이션해 입력이 어디로 흐르는지 추적했지만, 여기서 응답이 사라지는 게 아니었다.

가설 ③ command와 skill의 이름 충돌(disable-model-invocation).
같은 이름의 command와 skill이 서로를 가리는(shadow) 관계가 있었다(이 그림자 관계는 메모리에도 기록돼 있다). 이게 stats 호출을 잘못된 대상으로 보냈을 수 있다. → 배제. shadow 관계는 실재했지만, 무응답의 직접 원인은 아니었다.

root cause ④ 측정할 대화가 없는 "0 턴 새 세션".
세 가설을 배제하고 나서야 전제를 의심했다. stats는 대화의 토큰을 집계해 절감률을 보여주는 명령이다. 그런데 호출된 시점이 막 시작한 0 턴짜리 새 세션 — 즉 집계할 대화 자체가 없는 상황이었다. stats는 정확히 동작하고 있었다. 셀 게 없으니 보여줄 것도 없었던 것이다. 무응답은 버그가 아니라, "측정 대상 없음"이 무응답처럼 보인 UX 문제였다.

핵심 교훈은 그림 맨 아래에 있다 — "재현 안 되는 버그"의 정답이 "버그 아님"일 수 있다. 그리고 가설을 하나씩 배제하는 과정 자체가, 결국 틀린 건 코드가 아니라 내 전제였음을 드러내 준다.

4. 동작 원리 ② — 한자 drift: 원인과 가중 요인 분리

두 번째 버그는 분류가 까다로웠다. 한국어 출력에 한자가 섞여 나오는 한자 drift다(2화의 정합성 가드가 막으려는 바로 그 현상). 가장 쉬운 결론은 "압축이 한국어를 한자로 치환해서"였다. 압축 강도를 올리면 더 자주 보였으니까. 하지만 이 결론은 틀렸다 — 정확히는, 인과의 방향을 착각한 결론이었다.

현상을 세 원인으로 분해했다.

① CJK 토크나이저 공유: 많은 모델이 한·중·일 문자를 같은 토큰 공간에서 다룬다. 한국어 한자어와 그에 대응하는 한자(漢字) 토큰이 토큰 공간상 가깝다.
② 의미벡터 근접: 한자어(예: 한글로 쓴 단어)와 그 한자 표기는 의미 공간에서도 가깝다. 모델 입장에서 둘은 "거의 같은 뜻"이라, 치환이 일어나기 쉬운 토양이 깔려 있다.
③ 샘플링 무작위성: 디코딩은 확률 분포에서 토큰을 뽑는 과정이라, 가끔 한자 토큰이 뽑힌다. 비결정성 그 자체다.

이 셋이 겹쳐 한자 drift가 생긴다. 그렇다면 압축은? 압축은 원인이 아니라 가중 요인(aggravator)이다. 압축 압력이 출력을 짧고 밀도 높게 몰면 한자 치환이 더 자주 유발되는 건 맞다. 하지만 압축을 꺼도 위 세 원인은 그대로 남으므로 drift가 0이 되지 않는다. 만약 "압축이 원인"이라 결론 냈다면, 압축을 약화하는 헛된 처방으로 갔을 것이다 — 토큰만 손해 보고 drift는 안 사라지는.

이 분리가 실무적으로 중요한 이유는 처방이 달라지기 때문이다. 원인이 모델 레벨(토크나이저·샘플링)에 있으므로, 올바른 대응은 압축을 줄이는 게 아니라 출력 레벨의 정합성 가드(2화의 한글 전용 제약)로 drift를 잡는 것이다. 원인과 가중 요인을 섞었다면 이 처방에 도달하지 못한다.

5. 장단점 및 고려사항 — 이런 디버깅에서 배운 것

잘한 점 (Good)	빠지기 쉬운 함정 (Anti-Pattern)
✓ "재현 안 됨"을 단서로 읽고 전제를 의심함	✗ "분명 버그다"라는 전제를 끝까지 안 놓음
✓ 가설을 레이어별로 하나씩 배제 (감별 진단)	✗ 첫 그럴듯한 가설(캐시 차이)에 매달림
✓ 원인 vs 가중 요인을 분리 (압축은 가중 요인)	✗ 상관(압축↑→drift↑)을 인과로 단정
✓ 원인 레이어에 맞는 처방(정합성 가드)	✗ 가중 요인을 줄이는 헛된 처방(압축 약화)

실무 팁 — 비 자명한 버그 체크리스트

"재현이 일정한가?"를 가장 먼저 묻는다. 비일관적 재현은 종종 "버그 아님" 또는 "전제 오류"의 신호다.
가능한 원인을 레이어로 나열하고 하나씩 배제한다. 배제 과정 자체가 기록이 되고, 나중에 같은 증상이 오면 재사용된다.
세 가설을 배제했다면 전제를 의심한다. "셀 게 있긴 한가?"처럼, 코드가 아니라 입력 조건을 본다.
상관과 인과를 구분한다. "X를 올리면 Y가 는다"는 X가 Y의 원인이라는 증거가 아니다. X를 꺼도 Y가 남는지 확인한다.
원인 레이어에 처방을 건다. 모델 레벨 원인은 출력 가드로, 설정 레벨 원인은 설정으로. 레이어를 잘못짚으면 처방이 헛돈다.

핵심 3줄 요약

"재현 안 되는 버그"의 정답은 "버그 아님"일 수 있다. /scrooge-stats 무응답은 세 가설을 배제한 끝에 "측정할 대화가 없는 0 턴 새 세션"이라는 전제 오류로 판명됐다.
한자 drift의 진짜 원인은 CJK 토크나이저 공유·의미벡터 근접·샘플링 무작위성이며, 압축은 원인이 아니라 가중 요인이다.
디버깅의 핵심은 상관을 인과로 착각하지 않고, 원인이 사는 레이어에 처방을 거는 것이다.

저장소는 github.com/Kir93/scrooge-mode에 공개돼 있고, 이슈·PR·새 언어 rule 기여 모두 환영한다.

안 깎는 것이 실력이다 — 압축 도구가 거부해야 할 출력 (Scrooge 2편)

Kir93 — Sat, 13 Jun 2026 17:42:38 +0900

scrooge

1. 도입부 — 압축 도구의 진짜 위험은 "덜 압축"이 아니다

압축 도구를 만들 때 본능적으로 좇는 목표는 "최대한 깎기"다. 그런데 출력 압축에는 일반적인 성능 최적화에 없는 위험이 하나 있다. 너무 잘 깎으면 사람이 다친다.

예를 들어 LLM이 이런 출력을 내야 하는 상황을 생각해 보자. "이 명령은 데이터베이스를 복구 불가능하게 삭제합니다. 실행 전 백업을 확인하세요." 압축 규칙이 이걸 "DB 삭제 주의"로 깎았다고 하자. 토큰은 줄었다. 하지만 복구 불가능이라는 사실과 백업 확인이라는 행동 지시가 사라졌다. 사용자가 이 경고를 가볍게 보고 명령을 실행하면, 줄인 토큰 몇 개가 데이터 전체와 맞바꿔진다.

그래서 잘 만든 압축 도구의 핵심 설계는 "어떻게 더 깎을까"가 아니라 "무엇을 절대 깎지 않을까"다. 이 글에서 당신이 얻어갈 것은, 출력 도구에 "거부 영역"을 계약처럼 박는 방법과 그 경계를 어디에 긋는지에 대한 구체적 기준이다.

2. 핵심 개념 — register, 그리고 "압축하지 않는다"는 약속

용어 1줄 정의 — register: 언어학에서 상황에 맞는 말투·격식 수준을 뜻한다. 여기서는 "출력이 띠어야 할 표현 양식" 정도로 읽으면 된다. 압축된 register, 격식 있는 register, 안전을 위한 normal prose register 등.

scrooge에는 safety register라는 컨벤션이 있다(CLAUDE.md에 명문화). 골자는 한 줄이다.

특정 종류의 출력은, 압축 강도(dial)가 아무리 공격적이어도 normal prose로 유지한다.

즉 압축 도구이면서도 "여기는 압축 안 함"을 규칙으로 선언해 둔 것이다. 이건 도구의 약점이 아니라, 도구가 신뢰받을 수 있는 근거다.

"안전성 계약"이라는 프레임

여기서 이 글의 핵심 프레임이 나온다. 무엇을 압축하지 않을지를 정하는 일은 단순한 예외 처리가 아니라 계약(contract)이다. 사용자는 scrooge를 켤 때 암묵적으로 이렇게 믿는다. *"토큰은 아껴주되, 내가 다칠 수 있는 정보는 온전히 보여주겠지."* 안전 register는 그 믿음을 코드와 규칙으로 보증하는 명문 조항이다. 계약이 깨지면 — 즉 압축이 안전 정보를 깎으면 — 도구는 "토큰 아끼는 도구"가 아니라 "위험한 도구"가 된다.

3. 동작 원리 — 경계를 어디에 긋는가

핵심은 압축 대상과 안전 register를 명확히 분리하는 것이다. dial이 올라가면 전자는 점점 더 깎이지만, 후자는 어느 강도에서도 normal prose를 유지한다.

압축 강도가 올라가도 안전 register

안전 register에 들어가는 것 (압축 제외)

세 부류가 명시적으로 "안 깎는" 영역이다.

보안 경고: credential 노출 위험, 위험한 명령, 권한 상승 같은 경고. 압축돼 흐려지면 사용자가 위험을 과소평가한다.
되돌릴 수 없는 동작: 삭제·덮어쓰기·배포처럼 한 번 하면 못 무르는 행위에 대한 안내. 복구 불가능성과 선행 확인 절차가 압축으로 증발하면 안 된다.
모호하면 위험한 다단계 절차: 순서가 틀리면 사고가 나는 절차. 압축이 단계를 뭉치거나 생략하면 명료성(auto-clarity)이 깨진다.

관통하는 기준은 하나다. "압축이 명료성을 깎았을 때, 사람이 잘못 행동할 수 있는 출력인가?" 그렇다면 안전 register다. 여기서 auto-clarity가 압축률보다 항상 우선한다는 우선순위가 register 레벨에 박힌다.

한자 가드 — "압축 규칙"이 아니라 "정합성 가드"

scrooge에는 한국어 출력에서 한자(漢字)가 새어 나오는 것을 막는 규칙이 있다. 흥미로운 분류 결정은 이걸 압축 규칙이 아니라 정합성(correctness) 가드로 처리한 점이다.

왜 이 구분이 중요한가. 한자 leakage 가드를 "압축 규칙"으로 분류하면, 압축 강도를 낮추면 가드도 느슨해질 수 있다는 잘못된 함의가 생긴다. 하지만 한글 출력에 한자가 섞이는 건 압축 강도와 무관하게 틀린 출력이다. 그래서 이건 압축 다이얼에 종속되는 규칙이 아니라, 모든 dial에서 똑같이 지켜야 할 정합성 조건으로 박았다.

그리고 여기서 의도적이고 명시적인 비대칭이 하나 있다. 한자 가드는 ko의 every dial(lite·full 모두)에 적용하되, en에는 의도적으로 넣지 않았다(이 결정을 정리한 세션에서 en은 N/A로 명시). 한자 leakage는 CJK(한·중·일) 토크나이저를 공유하는 환경에서 한국어 같은 언어에 나타나는 CJK 한정 실패 모드라, 영어 출력에는 해당하지 않기 때문이다. 중요한 건 이 예외를 "그냥 안 넣음"으로 흘리지 않고 — bilingual parity(두 언어 동등 대우)의 예외임을 명시적으로 플래그 했다는 점이다. parity는 기본 원칙이되, 깨야 할 땐 왜 깨는지를 기록으로 남긴다.

4. 실무 적용 — 거부 영역을 규칙으로 박기

이 시리즈에서 "코드 예제" 자리는 register 정책과 가드 규칙이 채운다.

✅ Good Practice — 안전 register를 dial과 분리해 선언

# rules/ko/full.md (발췌, 개념적 표현)

## 압축 정책 (dial: full — 공격적)
- 인사·맥락 복창·완곡어법 제거
- 부연은 핵심만, 산문은 압축 표현으로

## 안전 register (압축 제외 — 모든 dial 공통)
다음은 압축 강도와 무관하게 normal prose로 유지한다:
- 보안 경고(credential·위험 명령·권한)
- 되돌릴 수 없는 동작(삭제/덮어쓰기/배포)의 위험성과 선행 확인
- 순서가 틀리면 위험한 다단계 절차

## 정합성 가드 (압축 규칙 아님 — 모든 dial 공통)
- 한국어 출력은 한글 전용. 한자(漢字) leakage 금지.
#   ※ 이 가드는 ko 전용. en은 CJK 한정 실패라 N/A (parity 예외, 의도적).

핵심은 "안전 register"와 "정합성 가드"가 압축 정책과 다른 섹션에, 모든 dial 공통으로 적혀 있다는 점이다. dial을 바꿔도 이 두 섹션은 그대로다 — 그게 계약이라는 증거다.

❌ Anti-Pattern — 안전 정보를 압축 대상에 섞기

# 잘못된 규칙
## 압축 정책 (dial: full)
- 모든 출력을 최대한 짧게. 경고·주의도 한 줄로 요약.   # ← 위험
- 절차는 단계 합쳐서 압축.                              # ← 모호해지면 사고
- 한자 써도 됨 (토큰 효율 좋음).                         # ← 정합성 위반

왜 문제인가. 안전 정보를 압축 대상에 함께 두면, 압축 강도를 올릴 때마다 안전성이 함께 깎인다. "경고도 한 줄로"는 복구 불가능 같은 결정적 단어를 날리고, "단계 합쳐서"는 순서 의존 절차를 망가뜨린다. "한자 써도 됨"은 토큰은 줄지만 한국어 독자에게 읽기 비용을 떠넘긴다(0화의 접근성 프레임과 정면충돌). 셋 다 토큰 몇 개와 사용자의 안전·이해를 맞바꾸는 거래다.

실행 결과 — 계약이 있을 때의 동작

안전 register가 박혀 있으면, dial을 full로 올려도 보안 경고는 온전한 문장으로 나온다. 사용자는 "압축 모드인데도 위험 정보는 또렷하다"는 일관성을 경험하고, 그게 도구를 신뢰하는 근거가 된다. 반대로 정합성 가드 덕에 한국어 출력에 한자가 새지 않으므로, ko 사용자는 압축의 이득을 읽기 비용 증가 없이 온전히 가져간다.

5. 장단점 및 고려사항

장점	단점·비용
✓ 압축 강도와 무관하게 안전성이 보장됨 (신뢰의 근거)	✗ 절감률 수치는 안전 register만큼 낮아짐 (덜 화려한 숫자)
✓ 정합성/안전과 압축을 분리해 규칙이 명료해짐	✗ "무엇이 안전 register인가"의 경계 판단에 지속적 노력 필요
✓ parity 예외를 기록으로 남겨 결정이 추적 가능	✗ 예외(en N/A 등)가 늘면 규칙 일관성 관리 부담

실무 팁 — 거부 영역 설계 체크리스트

"압축이 명료성을 깎으면 사람이 잘못 행동하나?"를 단일 기준으로 삼는다. 그렇다면 안전 register.
안전 register는 압축 정책과 다른 섹션에 둔다. 같은 섹션에 두면 dial을 따라 함께 깎일 위험이 구조적으로 생긴다.
"틀린 출력"과 "덜 압축된 출력"을 구분한다. 한자 leakage처럼 틀림에 해당하는 건 압축 규칙이 아니라 정합성 가드로 분류해 모든 dial에 건다.
parity를 깰 땐 이유를 기록한다. "그냥 안 넣음"이 아니라 "CJK 한정 실패라 en은 N/A"처럼 명시적 플래그를 남긴다.

핵심 3줄 요약

압축 도구의 진짜 설계 난제는 "어떻게 더 깎을까"가 아니라 "무엇을 절대 안 깎을까"이며, 이건 사용자와의 안전성 계약이다.
보안 경고·되돌릴 수 없는 동작·모호한 다단계 절차는 모든 dial에서 normal prose로 유지하고, auto-clarity를 압축률보다 우선한다.
한자 leakage처럼 틀림에 해당하는 건 압축 규칙이 아니라 정합성 가드로 분류하며, parity를 깰 땐 그 예외를 기록으로 명시한다.

저장소는 github.com/Kir93/scrooge-mode에 공개돼 있고, 이슈·PR·새 언어 rule 기여 모두 환영한다.

측정하지 않으면 압축이 아니다 — 출력 압축 도구의 효과를 재는 법 (Scrooge 1편)

Kir93 — Fri, 12 Jun 2026 15:53:40 +0900

scrooge

1. 도입부 — "더 압축하자"가 위험한 이유

압축 도구를 며칠 굴리다 보면 자연스러운 다음 생각이 떠오른다. *"영문 출력을 좀 더 깎을 수 있지 않을까?"* 규칙을 한두 줄 더 공격적으로 쓰면 토큰이 더 줄 것 같다.

이 충동은 합리적으로 보이지만, 실은 방향을 모르는 최적화다. 더 깎았을 때 토큰이 정말 줄어드는지, 줄어든다면 얼마나 줄어드는지, 그 대가로 무엇이 깨지는지 — 이걸 모르는 채로 규칙만 더 공격적으로 쓰는 건 도박이다. 압축 도구에서 "규칙을 더 공격적으로"는 곧 출력의 명료성(auto-clarity)과 안전 register를 깎는 쪽으로 압력을 주는 일이기 때문이다. 이득은 불확실한데 위험은 확실하다.

그래서 scrooge 개발 중 "더 압축하자"는 plan을 의도적으로 보류했다. 먼저 한 일은 압축이 아니라 측정이었다. 이 글에서 당신이 얻어갈 것은, 프롬프트·출력처럼 "정확한 수치를 매기기 애매한" 대상의 효과를 어떻게 재현 가능한 벤치마크로 환원하는가에 대한 구체적 방법이다.

2. 핵심 개념 — 프롬프트형 도구는 왜 측정이 어려운가

일반 코드 최적화와 다른 점

함수 하나를 최적화했다면 측정은 명확하다. 같은 입력에 실행 시간을 재서 before/after를 비교하면 된다. 결정론적이고, 단위가 분명하다.

LLM 출력 압축은 그렇지 않다. 두 가지가 측정을 흐린다.

비결정성: 같은 프롬프트라도 출력이 매번 다르다. 한 번 재서 "30% 줄었다"라고 말하면 그건 그날 그 샘플의 우연일 수 있다.
단위의 모호함: "압축됐다"를 무엇으로 잴 것인가? 글자 수? 토큰 수? 토큰이 곧 비용이므로 토큰 수가 정답이지만, 그러려면 baseline이 명확히 정의돼 있어야 한다.

핵심 통찰: baseline 없는 % 는 의미가 없다

"50% 절감"이라는 말이 성립하려면 무엇 대비 50%인지가 고정돼야 한다. scrooge가 택한 baseline은 압축을 전혀 걸지 않은 normal(일반) 출력이다. 그리고 그 사이에 약하게 압축한 terse를 두고, 본 제품인 scrooge× {언어} × {강도} 출력들을 같은 입력에 대해 나란히 생성한다.

용어 1줄 정의 — 코퍼스(corpus): 여기서는 "같은 입력 프롬프트 묶음 + 그걸 각 모드로 돌린 출력 묶음"을 뜻한다. 측정의 기준 표본 집합이다.

이렇게 하면 "scrooge ko full이 normal 대비 얼마나 줄었나"가 같은 입력 위에서 계산되는, 비교 가능한 수치가 된다.

3. 동작 원리 — 코퍼스로 ground truth 만들기

측정의 뼈대는 단순하다. 하나의 입력을 여러 출력 모드로 돌리고, 토큰 수를 집계해 baseline과 비교한다.

절감률 측정 코퍼스

세 가지 설계 포인트가 이 측정을 "그럴듯한 숫자"가 아니라 "재현 가능한 ground truth"로 만든다.

① 입력에 verbose-prone edge를 일부러 넣는다.
압축 도구의 진짜 실력은 "원래 짧은 답"이 아니라 "가만 두면 장황해지는 답"에서 드러난다. 그래서 코퍼스 입력에 장황해지기 쉬운 엣지 프롬프트를 의도적으로 포함한다. 평균적인 입력만 재면 도구가 가장 일하는 구간을 놓친다.

② baseline·terse·scrooge를 한 표본 위에 나란히 둔다.
normal / terse / scrooge× {ko, en} × {lite, full} 조합을 같은 입력으로 생성한다. normal은 절감의 기준점(0%), terse는 "단순 간결 지시"만으로 얼마나 줄어드는지의 대조군, scrooge 계열은 본 제품의 실측치다. terse라는 중간 대조군이 중요한 이유는, "규칙 묶음 없이 그냥 짧게 써"만 해도 얻는 절감과 scrooge 규칙이 추가로 사주는 절감을 분리해 보여주기 때문이다. 이게 없으면 scrooge의 공을 과대평가하게 된다.

③ 측정 결과는 커밋하지 않는다(gitignore).
코퍼스 입력과 리포트 도구는 저장소에 두되, 산출된 절감 수치 자체는 gitignore 했다. 이유는 정직성이다. 절감률은 모델·시점·샘플링에 따라 달라지는 값이라, 한 번 잰 숫자를 저장소에 박아두면 "고정된 사실"처럼 오해된다. 대신 도구를 저장소에 두고 재현은 "다시 측정"으로 하게 만든다. README가 절감 %를 단정하지 않고 "추정(estimated)"으로 표기하는 태도와 같은 결의 결정이다.

4. 실무 적용 — 측정 파이프라인 만들기

이 시리즈에서 "코드 예제" 자리는 설정·구조·측정 코퍼스가 채운다. 1화의 예시는 절감률 측정 파이프라인의 골격이다.

✅ Good Practice — baseline을 고정하고 재현 가능하게 측정

# 1) 코퍼스: 입력 + 모드 매트릭스 (장황해지기 쉬운 입력 포함)
inputs = load("benchmark/inputs/")        # verbose-prone edge 포함
modes  = ["normal", "terse",
          "scrooge:ko:lite", "scrooge:ko:full",
          "scrooge:en:lite", "scrooge:en:full"]

# 2) 같은 입력을 모든 모드로 생성하고 토큰 수 집계
for inp in inputs:
    for m in modes:
        out = generate(inp, mode=m)
        record(inp.id, m, count_tokens(out))   # 글자수 아님 — 토큰수

# 3) baseline(normal) 대비 절감률 산출
#    절감률 = (normal_tokens - mode_tokens) / normal_tokens
report = reduction_vs_baseline(baseline="normal")

# 4) 산출된 수치는 gitignore — 도구만 저장소에, 재현은 "다시 측정"으로

핵심은 (a) baseline이 코드에 명시돼 있고, (b) 토큰 수로 재며, (c) 같은 입력 위에서 모드를 비교하고, (d) 결과를 박제하지 않는다는 네 가지다.

❌ Anti-Pattern — 인상으로 절감률을 말하기

# 흔한 실수
# - 출력 두어 개 눈으로 보고 "한 절반 줄었네" → 표본 1~2개, 비결정성 무시
# - 글자 수로 비교 → 비용 단위(토큰)와 어긋남
# - baseline 없이 "scrooge는 60% 절감" → 무엇 대비 60%인지 불명
# - 측정해보지도 않고 규칙부터 더 공격적으로 → auto-clarity·안전 register만 깎임

왜 문제인가. 이렇게 나온 "60%"는 반증 불가능한 마케팅 문구다. 누가 "정말?"이라고 물으면 재현할 방법이 없다. 그리고 측정 없이 규칙부터 공격적으로 바꾸면, 줄어든 토큰의 이득보다 깨진 명료성·안전성의 손해가 클 수 있는데 그걸 알 길조차 없다.

실행 결과 — 측정이 사주는 것

측정 파이프라인을 갖추면 두 가지가 생긴다. 첫째, "scrooge ko full은 normal 대비 약 N% 절감(추정, 이 코퍼스·이 모델 기준)"처럼 조건이 붙은 정직한 수치를 말할 수 있다. 둘째 — 그리고 이게 더 중요한데 — "여기를 더 압축하면 토큰은 X만큼 더 줄지만 명료성 체크가 깨진다"는 트레이드오프가 눈에 보인다. 측정은 자랑할 숫자를 주는 게 아니라, 어디를 건드리면 안 되는지를 알려주는 지도를 준다.

5. 장단점 및 고려사항

장점	단점·비용
✓ 절감 주장이 재현 가능한 근거를 갖는다	✗ 코퍼스·리포트 도구를 먼저 만드는 선투자가 필요
✓ "더 압축" 결정의 트레이드오프가 가시화된다	✗ 비결정성 탓에 표본을 충분히 모아야 신뢰구간이 좁아짐
✓ terse 대조군이 도구의 순효과를 분리해준다	✗ 모델·시점이 바뀌면 수치도 바뀌어 재측정이 필요

실무 팁 — 측정 도입 체크리스트

baseline을 코드에 명시한다. "무엇 대비"가 함수 시그니처에 드러나야 한다.
글자 수가 아니라 토큰 수로 잰다. 비용 단위와 측정 단위를 일치시킨다.
장황해지기 쉬운 입력을 코퍼스에 일부러 넣는다. 평균 입력만으로는 도구의 일하는 구간을 못 본다.
순효과 대조군(terse)을 둔다. "그냥 짧게 써"와 도구의 차이를 분리한다.
수치를 박제하지 않는다. 도구를 커밋하고 결과는 gitignore. 발표할 땐 "추정 + 측정 조건"을 함께 적는다.

핵심 3줄 요약

프롬프트·출력 도구의 효과는 비결정성과 단위 모호함 때문에 측정이 어렵지만, 같은 입력 + 고정 baseline + 토큰 수 집계로 재현 가능하게 만들 수 있다.
terse 같은 중간 대조군이 도구의 순효과를 분리하고, 산출 수치는 gitignore + "추정" 표기로 정직하게 다룬다.
측정의 진짜 가치는 자랑할 숫자가 아니라, "더 압축해도 되는 곳과 건드리면 안 되는 곳"의 지도다.

저장소는 github.com/Kir93/scrooge-mode에 공개돼 있고, 이슈·PR·새 언어 rule 기여 모두 환영한다.

토큰은 돈이다 — 한국어를 위한 LLM 출력 압축 도구 (Scrooge 0편)

Kir93 — Wed, 10 Jun 2026 13:30:27 +0900

scrooge

1. 도입부 — 왜 이 이야기가 중요한가

LLM에게 길게 답하지 말라고 시켜본 적 있을 것이다. "간결하게", "불릿으로", "200자 이내로". 이게 단순한 취향 문제가 아닌 이유는, 출력 토큰이 곧 비용이자 지연시간이기 때문이다. 같은 정보를 절반의 토큰으로 전달할 수 있다면, 그건 API 청구서와 응답 속도에 직접 꽂히는 최적화다.

그래서 "LLM 출력을 압축하자"는 도구들이 등장했다. 그런데 이들을 들여다보다가 한 가지가 걸렸다. 압축의 상당 부분이 영어의 약어 관습, 심하면 한문(Classical Chinese)식 함축에 기대고 있었다. 토큰을 줄이는 영리한 트릭이지만, 그 트릭을 읽어내려면 독자가 그 언어 문화의 소양을 갖고 있어야 한다. 압축된 출력이 누군가에게는 더 읽기 어려워진다는 뜻이다.

이 글은 그 지점에서 출발해 만든 도구 scrooge(구두쇠, github.com/Kir93/scrooge-mode)의 0화다. 시리즈 전체는 "토큰은 돈이다 — KO-first LLM 출력 압축 도구 scrooge 만들기"이고, 0화부터 5화까지 총 6편으로 이어진다. 이 글에서 당신이 얻어갈 것은 두 가지다.

재정의 하나: 출력 압축을 "영리한 압축 트릭"이 아니라 "accessibility(접근성) 문제"로 보면 설계가 어떻게 달라지는가.
결정 하나: 다국어(i18n)를 나중에 "지원 추가"하는 대신 첫 커밋부터 아키텍처에 깔면 무엇이 쉬워지는가.

scrooge는 공개 저장소(github.com/Kir93/scrooge-mode)다. 다만 이 글에서는 특정 커밋 해시를 인용하지 않는다 — 해시는 리팩터링되면 깨지고 독자가 따라갈 대상도 아니기 때문이다. 대신 "초기 커밋 단계에서 무엇이 이미 결정되어 있었는가"라는 사실만 근거로 쓴다.

2. 핵심 개념 — "압축"을 다시 정의하기

출력 압축이란

LLM의 답변은 기본적으로 장황하다. 인사하고, 맥락을 복창하고, 친절한 부연을 단다. 출력 압축은 이 장황함을 규칙으로 깎아 같은 의미를 더 적은 토큰으로 만드는 일이다. scrooge의 경우, 사용자가 압축 강도(dial)를 고르면 그에 맞는 규칙 묶음(rule)을 LLM에게 시스템 지시로 주입하는 방식으로 동작한다.

영감의 출처는 분명히 밝혀둔다. scrooge는 caveman(github.com/JuliusBrussee/caveman, MIT, © Julius Brussee)에서 "출력을 압축한다"는 개념을 빌렸다. caveman은 단순한 "짧게 말하기 팁"이 아니라, 여러 에이전트에서 동작하는 출력 압축 도구로 자신을 설명하며 lite·full·ultra·wenyan(classical Chinese) 같은 모드를 제공한다. scrooge는 코드나 규칙 문구를 그대로 가져온 게 아니라(verbatim copy 아님), 개념만 참고해 i18n-first로 독립 재구현했다. 차이는 뒤에서 설명한다.

"압축 트릭"과 "접근성"은 다른 문제다

여기서 이 시리즈를 관통하는 첫 번째 프레임이 나온다.

기존 도구의 암묵 전제는 대략 이렇다. *"독자는 영어 약어와 함축적 표현을 무리 없이 읽는다."* 영어권 사용자에겐 합리적이다. 하지만 한국어로 일하는 사람에게 영어식으로 압축된 출력은 토큰은 줄었지만 인지 비용은 오히려 올라간 결과물일 수 있다. 압축의 이득이 독자의 모국어 바깥에서 새는 것이다.

그래서 scrooge의 출발점은 *"어떻게 더 압축할까"가 아니라 *"누구의 토큰을, 누구가 읽을 수 있게 줄이는가"였다. 압축률을 높이는 기술 문제가 아니라, **자기 언어로 토큰을 절약할 수 있게 하는 접근성 문제로 재정의한 것이다. 이름이 "구두쇠(scrooge)"인 이유도 여기 있다 — 토큰 한 톨까지 아끼되, 정작 읽는 사람이 손해 보면 그건 아낀 게 아니다.

비슷해 보이지만 다른 것

	일반적인 출력 압축 도구	scrooge
압축의 근거	영어 약어·함축 관습 (암묵 전제)	언어별 규칙을 명시적으로 분리
다국어	사후에 "지원 추가"	첫 커밋부터 아키텍처에 내장
문제 정의	토큰 수 최소화	모국어로 토큰 절약 (accessibility)
언어 추가 비용	코어 수정 동반	rule 파일 1개 + registry 1줄

3. 동작 원리 — i18n을 "코어"가 아니라 "데이터"로

재정의가 말뿐이 되지 않으려면 아키텍처가 그걸 강제해야 한다. scrooge의 핵심 결정은 언어를 코드에 하드코딩하지 않고, registry라는 매핑 테이블의 데이터로 다룬 것이다.

구조는 단순하다. language × dial의 조합 하나가 정확히 하나의 규칙 파일 경로로 1:1 매핑된다. 코어 로직은 "어떤 언어인지"를 모른다. 그저 registry에서 경로를 찾아 해당 규칙을 로드할 뿐이다.

registry mapping

이 설계의 효과는 언어를 하나 추가할 때 드러난다. 일본어(ja)를 넣고 싶다면:

rules/ja/lite.md, rules/ja/full.md — 규칙 파일을 작성하고
registry에 ja 엔트리를 한 줄 추가한다

코어 코드 변경은 0이다. 언어가 if-else 분기나 switch 문에 박혀 있었다면 언어를 늘릴 때마다 코어를 건드려야 했겠지만, registry 매핑은 그 결합을 끊는다. 이게 "i18n-first"의 실질적 의미다 — 다국어가 기능이 아니라 구조다.

이 결정은 사후에 끼워넣은 게 아니다. scrooge의 아주 초기 커밋들이 이미 이 골격을 깔고 있다. 저장소 구조와 i18n 아키텍처를 세운 첫 커밋, 그리고 영어 규칙 골격에서 caveman 특유의 내부자(insider) 표현을 걷어낸 후속 커밋이 그 증거다. 무엇보다 README 최초 버전에는 아예 *"Why Scrooge — positioning is accessibility"라는 섹션이 있다. 즉 "접근성으로서의 압축"은 글을 쓰려고 나중에 붙인 서사가 아니라, *첫날부터 명시된 포지셔닝**이다.

4. 실무 적용 — registry 매핑이라는 패턴

이 시리즈는 FE 컴포넌트 코드 대신 설정·구조 예시가 그 자리를 채운다. 0화의 예시는 registry 패턴 그 자체다. 이건 scrooge만의 트릭이 아니라, 다국어·다설정 도구라면 어디든 적용되는 일반 패턴이다.

✅ Good Practice — 언어를 데이터로 다루기

# registry (개념적 표현)
ko.lite  → rules/ko/lite.md
ko.full  → rules/ko/full.md
en.lite  → rules/en/lite.md
en.full  → rules/en/full.md

# 코어 로직 (언어를 모른다)
def resolve(language, dial):
    path = registry[f"{language}.{dial}"]   # 매핑 조회
    return load(path)                        # 규칙 로드

# 언어 추가 = 위 매핑에 줄 추가 + 파일 작성. 코어는 그대로.

핵심은 resolve 함수 어디에도 "ko"나 "en" 같은 리터럴이 없다는 점이다. 코어는 "조회하고 로드한다"만 안다. 언어 지식은 전부 registry라는 데이터에 산다.

❌ Anti-Pattern — 언어를 코드에 박기

# 흔한 실수: 분기문에 언어를 하드코딩
def resolve(language, dial):
    if language == "ko":
        if dial == "lite": return load("rules/ko/lite.md")
        else:              return load("rules/ko/full.md")
    elif language == "en":
        if dial == "lite": return load("rules/en/lite.md")
        else:              return load("rules/en/full.md")
    # ja를 추가하려면? 이 함수를 또 수정해야 한다.

왜 문제인가. 언어가 늘 때마다 코어 함수를 수정해야 하고, 그 수정은 곧 회귀(regression) 위험이다. 언어 지식이 코드 곳곳에 흩어지면(파서에 하나, 검증기에 하나, UI에 하나…) "ja 추가"는 그 모든 곳을 빠짐없이 찾아 고치는 작업이 된다. 하나라도 놓치면 버그다.

실행 결과 — 무엇이 달라지나

registry 패턴에서 "ja 추가"는 파일 2개 + 매핑 1줄짜리 작업으로 수렴한다. 코어는 손대지 않으므로 기존 언어(ko/en)가 깨질 위험이 구조적으로 차단된다. 추가 비용이 "언어 수에 비례하는 코드 수정"에서 "언어당 고정된 데이터 추가"로 바뀌는 것 — 이게 i18n-first가 사주는 것이다.

5. 장단점 및 고려사항

장점	단점·비용
✓ 언어 추가가 코어 수정 없이 가능 (rule 파일 + registry 1줄)	✗ 초기에 추상화 레이어(registry)를 먼저 깔아야 함
✓ 언어 지식이 한곳(데이터)에 모여 일관성 유지	✗ 규칙이 코드가 아닌 외부 파일이라, 규칙-registry 동기화를 따로 강제해야 함
✓ "접근성으로서의 압축"이라는 포지셔닝이 구조로 뒷받침됨	✗ 도구가 한두 언어로 끝날 거면 over-engineering일 수 있음

실무 팁 — i18n-first가 정당화되는 조건

언어/설정 축이 늘어날 게 거의 확실할 때 registry 패턴은 값을 한다. 한 언어로 끝날 도구라면 분기문이 더 솔직하다.
registry는 계약(contract)이다. 규칙 파일을 옮기거나 이름을 바꾸면 같은 변경에서 registry도 동기화해야 한다. 이 동기화를 사람의 기억에 맡기지 말고 검증 게이트로 강제하는 게 좋다. (이 규율이 실제로 무엇을 막았는지는 시리즈 마지막 5화에서 다룬다.)
"1:1 매핑"을 깨고 싶은 유혹(한 규칙을 여러 언어가 공유 등)이 오면, 그게 접근성 약속을 깨는지 먼저 따져본다. 언어별로 압축 관습이 다르다는 게 이 도구의 출발점이었음을 기억할 것.

핵심 3줄 요약

출력 압축을 "영리한 트릭"이 아니라 "모국어로 토큰을 아끼는 접근성 문제"로 재정의하면 설계 우선순위가 바뀐다.
그 재정의를 말이 아니라 구조로 강제하려면, 언어를 코드가 아닌 데이터(registry 매핑)로 다뤄 i18n을 첫 커밋부터 깐다.
효과는 "언어 추가" 순간 드러난다 — 코어 수정 0, 파일 2개 + 매핑 1줄.

한국어로 토큰을 아껴보고 싶다면 scrooge를 직접 써보는 게 가장 빠르다.

저장소는 github.com/Kir93/scrooge-mode에 공개돼 있고, 이슈·PR·새 언어 rule 기여 모두 환영한다.

Next.js v14 → v15 마이그레이션 작업기

Kir93 — Sat, 6 Jun 2026 12:20:11 +0900

1. 도입부 (Why This Matters)

메이저 버전 업그레이드는 보통 하나씩 한다. Next.js 먼저 올리고, 안정화되면 React, 그다음 Node. 교과서적이고 안전하다. 그런데 우리는 Next.js 14→15, React 18→19, Node.js 20→24, ESLint 8→9를 단일 PR로 동시에 올렸다. 88개 파일이 한 번에 바뀌었고, 프로덕션 에러율은 0%를 유지했다.

이게 무모해 보인다면 정확한 직관이다. 다만 이 네 축은 서로 강하게 결합돼 있어서 따로 떼면 오히려 "중간 상태"가 더 위험해진다. React 19 타입은 Next.js 15가 요구하고, Next.js 15의 비동기 API는 Node 런타임과 맞물리고, ESLint 9는 그 위에서 새 코드를 검증한다. 절반만 올린 브랜치를 며칠씩 들고 있는 것 자체가 리스크였다.

이 글은 "동시에 올려도 된다"는 주장이 아니라, 무엇을 한 번에 묶고 무엇을 회피·고정(pin)했는지에 대한 결정 기록이다. 읽고 나면 본인 프로젝트의 메이저 업그레이드에서 "이건 묶고, 이건 핀으로 우회한다"를 스스로 판단할 수 있게 되는 게 목표다.

읽는 시간: 약 8분.

⚠️ 버전 고지: 이 글의 마이그레이션은 2026년 1월 Next.js 15.5 기준으로 수행됐다. 작성 시점(2026-06) 기준 최신 stable은 Next.js 16.2이며, 16부터는 Turbopack이 기본 번들러이고 React Compiler가 1.0 stable로 포함된다. 본문 마지막에서 이 방향성을 따로 다룬다.

2. 핵심 개념 (What & Why)

왜 "동시"가 오히려 안전할 수 있나

메이저 업그레이드를 순차로 하면 각 단계마다 "반쪽짜리 호환 상태"가 만들어진다. 예를 들어 React만 19로 올리고 Next.js를 14에 두면, Next.js 14는 React 19의 비동기 params를 전제하지 않으므로 타입과 런타임이 어긋난 채로 며칠을 버텨야 한다. 이 중간 상태는 정식 호환 매트릭스에 존재하지 않는 조합이라, 버그가 나도 "이게 React 탓인지 Next 탓인지" 분리가 안 된다.

반대로 강하게 결합된 축들을 한 번에 올리면, 검증해야 할 조합이 "확정된 최종 상태 하나"로 줄어든다. 핵심은 결합도가 높은 것은 묶고, 결합도가 낮거나 리스크가 큰 것은 외부로 밀어내는 것이다. 우리는 다음을 외부로 밀어냈다.

디자인 시스템 호환 → 사내 디자인 시스템 패키지를 React 19 호환 canary 버전으로 선반영
서드파티 타입 충돌 → overrides로 타입을 강제 주입
React Compiler 도입 → 이번 PR에서 제외, 정책만 설계 (부록 참조)
Turbopack next build → 이번 PR에서는 dev에만 적용, build 전환은 보류 (5장 판단표 참조)

즉 "한 PR로 동시에"는 모든 걸 한꺼번에 한다는 뜻이 아니라, 코어는 원자적으로 묶고 주변부 비호환은 회피 전략으로 격리한다는 뜻이다.

유사 개념과의 차이

흔히 말하는 "빅뱅 마이그레이션"과 다르다. 빅뱅은 "전부 한 번에"지만, 여기서는 코어 4축만 원자적이고 나머지는 의도적으로 분리했다. 점진적 마이그레이션(strangler fig)과도 다르다. 점진적 방식은 결합도 높은 프레임워크 코어에는 적용하기 어렵기 때문이다.

3. 동작 원리 (How It Works)

결합 구조와 작업 분해

Next.js v14 → v15 마이그레이션 작업기

#1이 모든 작업의 선행 조건이다. 일단 코어 버전을 올리면 #2~#6은 서로 독립적으로 병렬 가능하고, #7(CI/CD)은 #5(설정)에, #8(디자인 시스템)은 #3(타입)에만 의존한다. 실제로는 단일 PR로 통합 배포했지만, 내부적으로는 이 의존 그래프대로 진행해야 충돌 지점을 예측할 수 있다.

어디서 무엇이 깨지는가 — 레벨별 분해

레벨	깨지는 지점	원인
런타임(서버)	`cookies()`, `headers()`가 동기 → 비동기	Next.js 15가 동적 API를 Promise로 전환 (요청 단위 캐싱·스트리밍 최적화 목적)
라우팅	`params` / `searchParams`가 Promise	동일 — 동적 데이터의 지연 평가
미들웨어	`NextRequest.headers`가 읽기 전용	요청 헤더 불변성 강화
타입(컴파일)	`RefObject<T>` → `RefObject<T \| null>`	React 19의 ref 제네릭 변경
의존성	서드파티의 `@types/react` 18 고정	일부 라이브러리가 React 19 타입 미반영

핵심은 런타임 깨짐(비동기 API)과 컴파일 깨짐(타입)이 서로 다른 종류의 문제라는 점이다. 비동기 API는 await를 빠뜨리면 런타임에 조용히 틀린 값을 반환할 수 있어 더 위험하고, 타입 충돌은 빌드에서 즉시 멈추므로 오히려 안전하다. 그래서 비동기 API 전환을 가장 신중하게 다뤘다.

4. 실무 적용 (Practical Examples)

아래 코드는 실제 마이그레이션 변경분을 일반화한 예시다(핵심 패턴만 표시).

4-1. 비동기 Dynamic API — `cookies()` / `headers()`

// lib/auth/auth-server.ts

import { cookies, headers } from 'next/headers';

// ❌ Before (Next.js 14) — 동기 함수
export function isAuthenticated(): boolean {
  const cookieStore = cookies();
  const authToken = cookieStore.get('SESSION_TOKEN')?.value;
  return authToken !== undefined;
}

// ✅ After (Next.js 15) — async + await
export async function isAuthenticated(): Promise<boolean> {
  const cookieStore = await cookies(); // cookies()가 Promise 반환
  const authToken = cookieStore.get('SESSION_TOKEN')?.value;
  return authToken !== undefined;
}

export async function getNextUrl(): Promise<string> {
  const headerList = await headers(); // headers()도 동일
  const xPathname = headerList.get('x-next-url');
  return xPathname ?? `${process.env.APP_DOMAIN}/`;
}

이 변경의 진짜 함정은 함수 시그니처가 Promise로 바뀌는 순간 이 함수를 호출하는 모든 곳이 연쇄적으로 async가 되어야 한다는 것이다. 미들웨어를 보자.

// middleware.ts

// ❌ Before — 동기 호출
const authMiddleware = (req: NextRequest) => {
  if (!isAuthenticated()) {
    /* 리다이렉트 */
  }
  return intlMiddleware(req);
};

// ✅ After — async 전파 + 읽기 전용 헤더 우회
const authMiddleware = async (req: NextRequest) => {
  if (!(await isAuthenticated())) {
    /* 리다이렉트 */
  }
  return intlMiddleware(req);
};

export default async function middleware(req: NextRequest) {
  const { pathname, search } = req.nextUrl;
  const nextUrl = createRedirectUrl(pathname, search);

  // ⚠️ NextRequest.headers는 읽기 전용 → 직접 .set() 불가
  // 새 Headers를 만들어 복사 후 수정해야 한다
  const requestHeaders = new Headers(req.headers);
  requestHeaders.set('x-next-url', nextUrl);

  // ... 분기 ...
  return await authMiddleware(req); // 호출부도 await
}

실행 결과: await를 빠뜨리면 isAuthenticated()가 Promise<boolean> 객체를 반환하고, 객체는 항상 truthy라서 if (!isAuthenticated())가 언제나 false가 된다. 즉 미인증 사용자가 보호 페이지를 통과한다. 빌드는 통과하지만 인증이 뚫리는 사일런트 버그라, 이 부분은 라우트별로 수동 점검했다.

4-2. `searchParams` / `params` → Promise

서버 컴포넌트와 클라이언트 컴포넌트의 처리 방식이 다르다. 이게 React 19의 use() Hook이 빛을 보는 지점이다.

// ✅ 서버 컴포넌트 — await로 푼다
interface PageProps {
  searchParams: Promise<{ documentId: string }>;
}

export async function generateMetadata({ searchParams }: PageProps): Promise<Metadata> {
  const { documentId } = await searchParams; // await
  // ...
}

export default async function Page({ searchParams }: PageProps) {
  const { documentId } = await searchParams; // await
  // ...
}

// ✅ 클라이언트 컴포넌트 — use() Hook으로 푼다 (async 불가하므로)
'use client';
import { use, useState } from 'react';

interface PageProps {
  searchParams: Promise<{ initIndex: number; size: 'sm' | 'md' | 'lg' }>;
}

export default function Page(props: PageProps) {
  const searchParams = use(props.searchParams); // ← Promise를 use()로 언랩
  const { initIndex, size } = searchParams;
  const [data, setData] = useState<Record<string, unknown>>();
  // ...
}

❌ Anti-Pattern: 클라이언트 컴포넌트를 억지로 async function으로 만들려는 시도. 클라이언트 컴포넌트는 async가 될 수 없다. Promise prop은 반드시 use()로 풀어야 한다. 이 구분(서버=await / 클라이언트=use())을 명확히 두지 않으면 페이지마다 헤매게 된다. 참고로 Next.js 기본 ESLint 설정의 @next/next/no-async-client-component 규칙이 이 실수를 잡아주므로, 뒤에서 다룰 Flat Config 전환은 이런 마이그레이션 사고의 안전장치이기도 하다. 영향 범위는 7개 라우트 페이지 + 1개 레이아웃이었다.

4-3. React 19 타입 — `RefObject<T | null>`

// ❌ Before (React 18)
positionRef: React.RefObject<HTMLDivElement>;

// ✅ After (React 19) — 제네릭에 | null 명시
positionRef: React.RefObject<HTMLDivElement | null>;

React 19는 useRef의 초기값과 제네릭 정합을 강화하면서 RefObject<T>를 RefObject<T | null>로 바꿨다. 15개 이상 컴포넌트에서 ref 타입 선언을 일괄 수정했다. 이건 컴파일 에러로 전부 잡히므로 tsc --noEmit을 가이드 삼아 기계적으로 처리할 수 있다 — 위험하지 않은 종류의 깨짐이다.

4-4. 서드파티 타입 충돌 회피 — `overrides`

가장 실용적인 트릭. 일부 서드파티 라이브러리가 내부적으로 @types/react@18을 끌고 오면서 React 19 타입과 충돌했다. 라이브러리 업데이트를 기다리는 대신 타입을 강제로 통일했다.

# pnpm-workspace.yaml  (pnpm 11+ 기준)
overrides:
  '@types/react': ^19
  '@types/react-dom': ^19

  # 특정 패키지가 오래된 React 타입을 끌고 올 때만 좁혀서 강제
  'some-legacy-lib>@types/react': ^19

버전 위치 참고: pnpm 11부터는 overrides를 pnpm-workspace.yaml에서 읽으며, package.json의 pnpm 필드는 더 이상 읽지 않는다. pnpm 10 이하 프로젝트라면 기존처럼 package.json의 "pnpm": { "overrides": { ... } }에 둔다.

루트에 박은 버전을 자식 의존성 전체로 전파하고 싶을 때는, 버전 문자열을 다시 쓰는 대신 루트 의존성을 참조하는 $ 표기를 쓸 수 있다.

// (pnpm 10 이하) package.json — $ 참조로 루트 버전 계승
{
  "pnpm": {
    "overrides": {
      "@types/react": "$@types/react",
      "@types/react-dom": "$@types/react-dom"
    }
  }
}

"$@types/react"는 "루트 dependencies/devDependencies에 선언된 @types/react 버전을 그대로 자식 트리에 계승하라"는 의미다. 버전 숫자를 한 곳(루트)에서만 관리하게 되므로, 숫자를 양쪽에 중복으로 적고 어긋나는 실수를 막는다.

이렇게 하면 의존성 트리 전체에서 @types/react가 단일 버전으로 평탄화된다. 사내 디자인 시스템은 한발 더 나아가 React 19 호환을 미리 반영한 canary 버전을 핀으로 고정했다. "정식 릴리스를 기다린다"가 아니라 "호환 버전을 선반영하고 핀으로 박는다"가 핵심 회피 전략이었다.

// canary 의존성은 범위(^)가 아니라 exact pin으로
{
  "dependencies": {
    "@internal/design-system": "0.1.7-canary.2"
  }
}

canary 같은 prerelease는 semver 범위 매칭에서 쉽게 누락되거나 예상치 못한 버전으로 점프할 수 있으므로, 정확한 버전 핀이 더 예측 가능하다.

4-5. ESLint 9 Flat Config

.eslintrc.json은 ESLint 9에서 지원이 끊긴다. 다만 next/core-web-vitals 같은 기존 공유 설정은 아직 레거시 포맷이라, FlatCompat 브릿지로 감싸 점진 전환했다.

// eslint.config.mjs
import { dirname } from 'path';
import { fileURLToPath } from 'url';
import { FlatCompat } from '@eslint/eslintrc';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
const compat = new FlatCompat({ baseDirectory: __dirname });

const eslintConfig = [
  // 레거시 공유 설정을 FlatCompat로 브릿지
  ...compat.extends('next/core-web-vitals', 'next/typescript', 'prettier'),
  {
    rules: {
      '@typescript-eslint/no-explicit-any': 'warn',
      'react/react-in-jsx-scope': 'off', // React 19: 자동 JSX 런타임
      'prefer-const': 'error',
      eqeqeq: ['error', 'smart'],
    },
  },
  { ignores: ['.next/**', 'out/**', 'build/**', 'next-env.d.ts'] },
];

export default eslintConfig;

⚠️ 함정: ESLint 9 Flat Config 전환은 설정 파일 이름만 바꾸는 일이 아니다. 아직 v9 rule API를 따르지 않은 플러그인에서는 context.getScope is not a function 같은 오류가 날 수 있다. 이런 경우 FlatCompat 같은 호환 레이어로 감싸거나 구성을 재배치해야 한다.

4-6. Turbopack SVGR 호환 (dev 한정)

이번 PR에서 Turbopack은 dev에만 적용했고 next build는 webpack 경로를 유지했다(전환 보류 이유는 5장 판단표 참조). Turbopack은 webpack 로더 설정을 그대로 읽지 않으므로, SVG를 컴포넌트로 쓰던 SVGR 설정을 turbopack.rules로 별도 선언하고, webpack 빌드 경로도 폴백으로 함께 유지했다.

// next.config.mjs
const nextConfig = {
  turbopack: {
    rules: {
      '*.svg': { loaders: ['@svgr/webpack'], as: '*.js' },
    },
  },
  // next build는 아직 webpack 경로 → 동일 로더를 중복 선언해 폴백 유지
  webpack: (config) => {
    config.module.rules.push({ test: /\.svg$/i, use: ['@svgr/webpack'] });
    return config;
  },
};

5. 장단점 및 고려사항

무엇을 묶고 무엇을 canary로 미룰까 — 판단 기준표

이번 사례의 결정을 일반화하면, 새 프로젝트에서도 그대로 쓸 수 있는 판단표가 된다. 기준은 단순하다. 타입·런타임·린트 경계가 서로 맞물리는 것은 한 번에 묶고, 지원 단계가 beta/experimental이거나 운영 환경 편차가 큰 것은 canary로 분리한다.

판단 항목	한 번에 묶기 좋은 경우	canary로 미루기 좋은 경우	이번 사례의 권고
Next 15 + React 19	App Router, 타입 정렬, async API 정리가 함께 움직일 때	Pages Router 비중이 크고 React 18 유지가 전략적으로 필요할 때	묶기
`@types/react` 정렬	서드파티가 React 18 타입을 끌고 와 충돌할 때	충돌 범위가 좁고 임시 허용이 가능할 때	묶기
ESLint 9 + Flat Config	Next 15.5 이상, `next lint` 의존 탈피가 필요할 때	플러그인 호환성이 크게 불안정할 때	대체로 묶기
Turbopack dev	로컬 DX 개선이 목적일 때	custom webpack 진입점에 강하게 의존할 때	묶기
Turbopack `next build`	parity 테스트가 충분하고 알려진 차이를 감당할 때	CSS ordering·번들 최적화 격차·custom webpack 리스크가 클 때	canary 권장 (이번 PR 보류)
Node 24 + Alpine 베이스	native addon이 단순하고 musl 검증이 끝났을 때	glibc 의존·보안 릴리스 즉시 반영·멀티아키 민감도가 높을 때	Node 24는 묶고 Alpine 전환은 주의

핵심 분기점은 Turbopack이다. dev는 안정 단계라 묶었지만, next build --turbopack은 CSS ordering 차이와 일부 번들 최적화 격차가 알려져 있어 이번 PR에서는 의도적으로 보류했다. "Turbopack을 채택했다"가 아니라 "dev에만 적용했다"가 정확한 서술이다.

트레이드오프 요약

장점	단점 / 비용	예방책
✓ 검증 대상이 "최종 상태 하나"로 수렴 — 반쪽 호환 상태 제거	✗ 단일 PR이 88개 파일로 비대 → 리뷰 부담	의존 그래프 순서대로 커밋을 쪼개 리뷰 동선 확보
✓ 결합도 높은 축을 원자적으로 묶어 디버깅 시 변인 분리	✗ 문제 발생 시 롤백 단위가 큼	배포 전 스테이징에서 핵심 라우트 E2E 통과 확인
✓ canary 핀 + overrides로 서드파티 대기 시간 0	✗ canary 의존은 임시 부채	정식 stable 배포 시점에 핀 해제 캘린더 등록
✓ 정량 성과 명확 (아래)	✗ 비동기 API 사일런트 버그는 자동 검출 불가	인증·권한 분기는 라우트별 수동 점검 필수

정량 성과

지표	Before	After	변화
Dev 서버 시작	—	—	개선 (Turbopack, Vercel 공식 벤치마크: 대형 앱 기준 최대 76.7% 빠름)
Dev HMR (Fast Refresh)	—	—	개선 (Vercel 공식 벤치마크: 최대 96.3% 빠름)
배포 빌드 시간	평균 4분	평균 2분 20초	약 42%↓ (자체 CI 실측)
프로덕션 에러율	0%	0%	무장애 유지 (자체 관측)

빌드 42% 단축의 내역(자체 attribution): Next.js 15 빌드 최적화 ~20초 + Node.js 24 V8 개선 ~30초 + GitHub Actions .next/cache 캐시(actions/cache@v4) ~50초.

⚠️ 수치 고지: 76.7%·96.3%는 Vercel이 대형 Next.js 앱에서 측정한 공식 참고 수치로, 프로젝트 규모·환경에 따라 체감은 크게 달라진다(본 프로젝트의 독립 실측치가 아니다). 빌드 42%는 자체 CI 환경 실측이며, 내역 분해는 내부 attribution 가설이다. "에러율 0%"는 어떤 관측 도구·기간·분모 기준인지 함께 밝혀야 엄밀하다(여기서는 배포 후 안정화 관측 창 기준).

실무 도입 체크리스트

비동기 API(cookies/headers/params/searchParams) 호출부를 전수 조사했는가 — await 누락은 빌드를 통과하는 사일런트 버그다.
인증·권한처럼 boolean을 반환하던 동기 함수가 async로 바뀌었다면, 그 호출부의 조건문을 직접 점검했는가.
서드파티 타입 충돌은 라이브러리 업데이트를 기다리지 말고 overrides로 평탄화했는가.
CI/로컬/Docker의 Node 버전을 .nvmrc 단일 소스로 일원화했는가.
빌드 캐시(.next/cache)를 CI에 붙였는가 — 가장 가성비 높은 빌드 단축 수단이다.
Turbopack을 dev에만 적용했는지 build까지 켰는지 명확히 구분해 기록했는가.

6. 결론 및 다음 단계

세 줄 요약:

메이저 동시 업그레이드의 성패는 "전부 묶기"가 아니라 결합도 높은 코어는 원자적으로 묶고, 비호환 주변부는 canary 핀·overrides로 격리하는 분리 설계에 있다.
가장 위험한 깨짐은 빌드를 멈추는 타입 에러가 아니라, 빌드를 통과하는 비동기 API의 await 누락이다. 인증 같은 곳은 수동 점검이 필수다.
정량 측정(빌드 42%↓, 에러율 0%)을 붙이고, 공식 참고 수치와 내부 실측을 분리해 표기하면 "무장애"가 주장이 아니라 결과가 된다.

첫 단계 제안: 본인 코드베이스에서 cookies() / headers() / searchParams 사용처를 먼저 grep으로 전수 조사하라. 영향 범위를 알면 묶을지 나눌지가 보인다.

심화 학습 키워드: React Compiler, PPR(Partial Prerendering), use() Hook, Turbopack, pnpm overrides.

부록 — React Compiler를 열어둔 useMemo/useCallback 정책

이번 PR에서 React Compiler는 의도적으로 제외했다. 대신 "나중에 켜도 손해 보지 않는" 코드 정책을 설계했다.

React Compiler는 컴포넌트를 자동 메모이제이션하므로, 켜지는 순간 수동 useMemo/useCallback 상당수가 잉여가 된다. 그렇다고 기존 메모이제이션을 미리 대량으로 지우는 건 위험하다 — 컴파일러를 켜기 전까지는 그 메모이제이션이 실제로 동작 중이고, 수백 개를 한꺼번에 지웠다가 재생성 버그나 렌더 루프를 쫓는 비용이 더 크다. 그래서 기존 구문은 보존하되, 신규 코드에서는 성능을 위한 선제적 메모이제이션을 금지하고, useMemo/useCallback은 (a) 참조 동일성이 의미상 필요한 경우(의존성 배열, key, context value), (b) 실측으로 병목이 확인된 경우에만 쓰도록 했다. 이렇게 하면 컴파일러를 켰을 때 제거할 부채가 자연히 줄어든다.

방향성: 작성 시점(2026-06) 기준 React Compiler는 1.0 stable이고 Next.js 16부터 빌드에 내장됐지만, 여전히 기본 비활성이다. 도입 시에는 compiler를 켜기 전에 ESLint compiler linter(preserve-manual-memoization 등)를 먼저 도입해 기존 메모이제이션을 보존하면서 점진 전환하는 경로가 권장된다. 위 정책은 Next 16 전환 시 그대로 활용된다.

출처 (외부 수치)

개발자 원칙(확장판) - 박성철 , 강대명 , 공용준 , 김정 , 박미정 , 박종천 , 장동수 , 이동욱(향로) , 이동욱(네피림)

Kir93 — Wed, 3 Jun 2026 12:27:16 +0900

개발자 원칙(확장판) - 박성철 , 강대명 , 공용준 , 김정 , 박미정 , 박종천 , 장동수 , 이동욱(향로) , 이동욱(네피림)

이 책은 "좋은 개발자란 누구인가"라는 질문에 기술 스택이 아니라 업(業)의 원칙으로 답하는 책입니다.

컬리·카카오·무신사·몰로코·인프런 등에서 일해온 국내 테크 리더 9인이 각자 한 가지 원칙을 에세이로 풀어냈고, 확장판은 여기에 0장 「선배와의 인터뷰」와 각 장 말미의 「출간 후 2년, 그다음 이야기」를 더했습니다.

그래서 이 책은 "무엇을 코딩할까"보다 "어떻게 개발자로 살아갈까"에 가까운, 일종의 직업 정체성 안내서입니다.

0장. 선배와의 인터뷰

핵심 개념: 확장판에 새로 들어간 부분으로, 9인 저자 전원에게 같은 질문 세 가지를 던집니다. "좋은 개발자(좋은 개발 조직)란 무엇인가", "언제 가장 즐거웠나", "이 일을 계속하게 하는 원동력은 어디서 오는가"입니다.
주요 사례/에피소드: 각자의 답이 본문 9개 원칙의 출발점이 됩니다. 박성철은 개발자를 "현실의 문제를 해결하는 사람"으로 규정하고, 강대명은 "더 깊고 자세히, 더 많이 공부하라"는 한 문장으로 자기 태도를 압축합니다.
기억할 점: 본문보다 인터뷰가 더 흥미로운 대목이 있을 만큼, 저자들의 사람됨과 현재 직무 변화 자체가 책의 중요한 맥락입니다.

1장. 덕업일치를 넘어서

핵심 개념: 박성철(컬리 본부장)은 "좋아함(덕업일치)"은 출발점일 뿐이며, 직업으로서의 정체성을 의식적으로 탐구해야 지속 가능하다고 말합니다. 급여·복지 같은 위생 요인(Hygiene Factors: 부족하면 불만이 되지만 충족돼도 동기가 되지 않는 환경 요소)은 커트라인일 뿐, 진짜 만족은 성장을 자극하는 내재 동기(Intrinsic Motivation: 행동 자체에서 오는 즐거움)에서 나옵니다.
주요 사례/에피소드: SK플래닛 → 우아한형제들 → 컬리로 이어진 이직마다 '북극성'처럼 삼은 가치를 점검한 회고가 인상적입니다.
기억할 점: 번아웃은 에너지를 무조건 아끼기보다, 회복 탄력성을 키워 총량을 넓히는 방식으로 다스립니다. AI가 코드를 쏟아내는 시대일수록 "어떤 개발자가 될 것인가"라는 질문을 멈추지 말라고 당부합니다.

2장. 오류를 만날 때가 가장 성장하기 좋을 때다

핵심 개념: 강대명(레몬트리 기술책임자)은 장애와 오류를 방해물이 아니라 시스템 내부를 깊이 들여다볼 최고의 학습 자원으로 봅니다. AI가 준 정답 코드를 그대로 복사·붙여 넣는 습관은 장기적으로 자생력을 갉아먹는다고 경고합니다.
주요 사례/에피소드: 네이버·카카오·위버스의 데이터 플랫폼을 거치며 만난 난해한 오류들을, 짐작이 아니라 프레임워크의 소스 코드(Source Code: 프로그램의 원본 텍스트)를 한 줄씩 읽어 해결한 과정을 보여줍니다.
기억할 점: 오류를 고친 뒤에는 반드시 글로 정리해 지식을 내재화해야 합니다. 문제를 만나면 AI에 의존하기 전에 내부 동작을 먼저 추론해보는 훈련이 권장됩니다.

3장. 소프트웨어 디자인 원칙

핵심 개념: 공용준(카카오 클라우드 디렉터)은 거창한 패턴 카탈로그가 아니라, 실무에서 반복적으로 통하는 최소한의 설계 원칙(추상화·결합도 관리·확장성)을 정리합니다. 디자인을 곧 '의사소통'으로 보는 관점이 핵심입니다.
주요 사례/에피소드: 카카오톡 규모의 트래픽을 운영한 경험을 바탕으로, 비즈니스 요구와 시스템 설계가 충돌하는 전형적 딜레마와 그 조율 과정을 다룹니다.
기억할 점: 생성형 AI가 늘수록 사전 설계는 오히려 더 중요해집니다. 다만 거시적 설계를 다루는 만큼, 주니어가 한 번에 소화하기엔 진입 장벽이 느껴질 수 있는 장입니다.

4장. 나의 메이저 버전을 업그레이드하는 마이너 원칙들

핵심 개념: 김정(코드스쿼드 대표)은 자신을 소프트웨어에 비유해, 작은 마이너 패치를 꾸준히 쌓으면 메이저 버전이 올라간다고 봅니다. 시맨틱 버저닝(Semantic Versioning: 메이저·마이너·패치로 버전을 체계화하는 규칙)을 성장에 투영한 것입니다.
주요 사례/에피소드: "업무 관련 50% / 약하게 관련 30% / 관심사 20%"라는 학습 시간 가계부, 그리고 "개구리를 해부하지 말고 직접 만들어라"는 학습관이 구체적입니다.
기억할 점: 결과에 함몰되지 말고 과정을 기록하라(v0.5.0), 정답보다 해답을 찾으라는 조언은 직장인 누구나 바로 적용할 수 있는 자기계발 팁입니다.

5장. 이직, 분명한 이유가 필요해

핵심 개념: 박미정(무신사 개발실장)은 이직이 좋은 도구이지만, 분명한 이유와 방향이 없으면 '도망'이 된다고 말합니다. 성장 단계별로 적합한 이직 이유가 다르다는 4단계 프레임을 제시합니다.
주요 사례/에피소드: LG CNS → 네이버 → 쿠팡 → 코빗 → 배달의민족 베트남 → 무신사로 이어진 본인의 경로를 단계별 이유와 함께 솔직하게 공유합니다.
기억할 점: "왜 떠나는가"보다 "무엇을 얻는가"를 먼저 쓰고, 같은 이유로 두 번 이직하지 말 것. 주인의식을 발휘할 수 없거나 개발 문화에 기여하기 어려울 때가 이직의 적기입니다.

6장. 목표를 달성하는 나만의 기준, GPAM

핵심 개념: 박종천(몰로코 헤드 아키텍트)은 막연한 목표가 부르는 실행 지연을 깨기 위해, 개발 사이클을 일상에 접목한 GPAM(Goal·Plan·Action·Measure: 목표·계획·실행·측정) 프레임워크를 제안합니다. S.M.A.R.T.로 목표를 쪼개고 GPAM으로 돌립니다.
주요 사례/에피소드: 한컴 → 블리자드 → 넥슨 → 삼성전자 → 몰로코로 이어진 30여 년 경력, 그리고 '개발자의 7가지 고민'을 GPAM으로 분해하는 워크북식 적용이 실용적입니다.
기억할 점: 측정(Measure)이 빠진 목표 관리는 결국 추측이 됩니다. 분기마다 한 사이클을 돌리는 것만으로도 정체를 깰 수 있습니다.

7장. 프로덕트 중심주의

핵심 개념: 이동욱(네피림, 당근 엔지니어)은 개발자의 장기 성장 단위가 '기술 스택'이 아니라 '내가 끝까지 만든 프로덕트(Product: 완성된 제품)'라고 강조합니다. 그 프로덕트가 꼭 회사 업무일 필요도 없습니다.
주요 사례/에피소드: 플러터(Flutter) 학습을 예로, "문법책을 완독한다"는 추상적 계획과 "내 여행 기록 앱을 시장에 배포한다"는 제품 중심 계획이 만들어내는 결과물의 밀도 차이를 대조합니다.
기억할 점: 포트폴리오를 '기능'이 아니라 '완성된 프로덕트' 단위로 정리하세요. 완벽한 준비로 망설이기보다 빠르게 출시하고 반복 개선하는 감각이 필요합니다.

8장. 제어할 수 없는 것에 의존하지 않기

핵심 개념: 이동욱(향로, 인프랩 CTO)은 코드 설계든 이직이든 조직 매니징이든, 내 힘으로 제어할 수 없는 외부 변수에 의존하면 시스템이 깨지기 쉽다고 말합니다. 외부 의존을 줄일수록 견고해집니다.
주요 사례/에피소드: 많은 기업이 주민등록번호를 데이터베이스의 기본 키(Primary Key: 레코드를 고유하게 식별하는 키)로 삼았다가, 수집 금지법 개정으로 시스템 전체를 갈아엎어야 했던 사례가 대표적입니다.
기억할 점: 도메인 핵심 로직은 두텁게, 외부 통신·UI는 모킹(Mocking: 테스트용 가짜 객체로 격리하는 기법) 등으로 얇게 격리하세요. 커리어 결정도 "내가 제어할 수 없는 것"을 먼저 적어보고 시작하면 좋습니다.

9장. 달리는 기차의 바퀴를 갈아 끼우기

핵심 개념: 장동수(수수한기술 대표)는 운영 중인 서비스를 멈추지 않으면서 기술 부채를 점진적으로 갚는 현실적 리팩토링 철학을 다룹니다. "은탄환은 없다"는 인정에서 출발합니다.
주요 사례/에피소드: 세계 최초의 웹 기반 오피스 'Thinkfree Office Live' 개발, 그리고 패스트캠퍼스에서 60여 명 개발 조직을 맨땅에서 구축한 경험이 비유에 무게를 더합니다.
기억할 점: 처음부터 100점을 노리느라 일정을 어기기보다, 기한 내 80~90점으로 확실히 동작시키고 점진 개선하세요. 발견했을 때보다 한 단계 깨끗하게 두고 떠나는 보이스카우트 규칙이 핵심 습관입니다.

이 책을 관통하는 메시지는 분명합니다.

개발자의 수명을 결정하는 것은 계속 바뀌는 기술 스택이 아니라, 시대를 관통하는 단단한 원칙이라는 것입니다.

9인의 원칙은 코딩을 넘어 목표 관리와 조직 운영으로까지 확장됩니다.

특히 확장판의 추가분은 AI를 핑계로 기존 원칙을 폐기하지 않고, 오히려 설계·학습·문제 정의의 중요성을 더 강하게 만든다는 점에서 책의 신뢰도를 높입니다.

바로 적용해볼 만한 행동 포인트

장애를 겪으면 24시간 안에 원인 기록(RCA)을 남기고, 소스 코드 레벨까지 직접 확인한다.
구현 전 1페이지짜리 설계 문서를 먼저 쓴다.
분기마다 GPAM으로 개인 목표를 재설정하고 '측정' 항목을 반드시 넣는다.
이직을 검토할 때 "왜 떠나는가"보다 "무엇을 얻는가"를 먼저 적는다.
의사결정마다 통제 가능한 것과 불가능한 것을 분리해 적어본다.

마무리 평

강점

한 권에서 컬리·카카오·무신사·몰로코의 의사결정 스타일을 비교할 수 있는 다관점 자극.
GPAM, "제어할 수 없는 것에 의존하지 않기", "프로덕트 중심주의", "밥값 개발자"처럼 한 줄로 외울 수 있는 프레임이 많아, 회고나 1:1 면담에서 바로 인용하기 좋습니다.
같은 저자가 직접 쓴 '출간 후 2년' 후기로 원칙을 시간 검증한 구성.

아쉬운 점

저자 대부분이 국내 IT 대기업·유니콘 출신이라, SI·금융 같은 도메인과는 거리감이 있습니다.
챕터당 25~30쪽의 분량 제약 탓에 사례가 단편적으로 끝나는 장이 있고, 챕터 간 문체·깊이 편차도 느껴집니다.
AI 시대 대응이 주로 인터뷰와 후기 코너에 분산돼 있어, 본문 9개 원칙 자체가 AI를 정면으로 다루지는 않습니다.
시니어에게는 새로운 기술 지식이라기보다 "이미 알지만 정리하지 못한 원칙의 재문장화"에 가깝습니다.

최종 평가 ★★★★☆

한국 개발 조직의 실제 언어로 쓰인 드문 커리어 원칙집입니다.

성장 방향을 정리하려는 3~7년 차나 예비 리드라면 강하게 추천하고, 깊은 아키텍처·테스트 전략을 찾는 시니어라면 보조 텍스트로 곁들이길 권합니다.

개발 메모장

squash merge가 release마다 cherry-pick이 충돌하는 이유

1. 도입부 (Why This Matters)

2. 핵심 개념 (What & Why)

3. 동작 원리 (How It Works)

3-1. squash가 공통 조상을 지운다

3-2. merge --no-ff는 공통 조상을 살린다

4. 실무 적용 (Practical Examples)

❌ 안티패턴 (Anti-Pattern): squash + cherry-pick 릴리즈

✅ 권장 패턴 (Good Practice): main 기반 + merge --no-ff 직접 머지

실행 결과 (한 레포의 측정 사례)

5. 장단점 및 고려사항

6. 결론 및 다음 단계 (Conclusion)

프런트엔드 AX 설계기 0편 — 레거시 3개와 차세대 FE를 위한 워크플로우 설계기

1. 도입부 (Why This Matters)

2. 핵심 개념 (What & Why)

3. 동작 원리 (How It Works)

뼈대: 4-layer 책임 분리

4개의 축

4. 실무 적용 (Practical Examples)

✅ 권장 패턴 (Good Practice)

❌ 안티패턴 (Anti-Pattern)

실행 결과

5. 장단점 및 고려사항

6. 결론 및 다음 단계

안 만든 것이 규율이다 — 절제로 끌고 간 토이 프로젝트 회고 (Scrooge 5편)

scrooge

1. 도입부 — 토이 프로젝트가 망하는 진짜 이유

2. 핵심 개념 — 규율은 "막은 것"으로 측정된다

3. 동작 원리 — 각 규칙이 막은 것

4. 실무 적용 — 절제를 규칙으로 박기

✅ Good Practice — working rule을 명문화하고 "안 만들 것"을 적기

❌ Anti-Pattern — "이왕 만드는 김에"의 누적

실행 결과 — 절제가 남긴 궤적

5. 장단점 및 고려사항

켰는데 왜 안 먹지 — 하나의 모드를 Claude Code와 Codex 두 호스트에 (Scrooge 4편)

scrooge

1. 도입부 — "같은 기능"이 호스트마다 다른 표면을 갖는다

2. 핵심 개념 — 섞이기 쉬운 세 가지

3. 동작 원리 — 다른 메커니즘, 같은 기능

호스트별로 갈리는 hook 표면

활성 상태는 왜 "전역 파일 하나"인가, 그리고 그 함정

멱등한 설치기 — 재설치해도 같은 결과

4. 실무 적용 — 멀티 호스트 어댑터 + 멱등 설치

✅ Good Practice — 어댑터 분리 + 멱등 설치 + 상태 단일화

❌ Anti-Pattern — 세 개념을 섞고, 설치가 비멱등

실행 결과 — 분리가 사주는 것

5. 장단점 및 고려사항

재현 안 되는 버그의 정답은 버그가 아니었다 — 비자명한 디버깅 기록 (Scrooge 3편)

scrooge

1. 도입부 — 가장 비싼 버그는 "버그가 아닌 버그"다

2. 핵심 개념 — 표면 증상과 root cause의 거리

3. 동작 원리 ① — "무응답"의 4겹 오진

4. 동작 원리 ② — 한자 drift: 원인과 가중 요인 분리

5. 장단점 및 고려사항 — 이런 디버깅에서 배운 것

안 깎는 것이 실력이다 — 압축 도구가 거부해야 할 출력 (Scrooge 2편)

scrooge

1. 도입부 — 압축 도구의 진짜 위험은 "덜 압축"이 아니다

2. 핵심 개념 — register, 그리고 "압축하지 않는다"는 약속

"안전성 계약"이라는 프레임

3. 동작 원리 — 경계를 어디에 긋는가

안전 register에 들어가는 것 (압축 제외)

한자 가드 — "압축 규칙"이 아니라 "정합성 가드"

4. 실무 적용 — 거부 영역을 규칙으로 박기

✅ Good Practice — 안전 register를 dial과 분리해 선언

❌ Anti-Pattern — 안전 정보를 압축 대상에 섞기

실행 결과 — 계약이 있을 때의 동작

5. 장단점 및 고려사항

측정하지 않으면 압축이 아니다 — 출력 압축 도구의 효과를 재는 법 (Scrooge 1편)

scrooge

1. 도입부 — "더 압축하자"가 위험한 이유

2. 핵심 개념 — 프롬프트형 도구는 왜 측정이 어려운가

일반 코드 최적화와 다른 점

핵심 통찰: baseline 없는 % 는 의미가 없다

3. 동작 원리 — 코퍼스로 ground truth 만들기

4. 실무 적용 — 측정 파이프라인 만들기

✅ Good Practice — baseline을 고정하고 재현 가능하게 측정

❌ Anti-Pattern — 인상으로 절감률을 말하기

실행 결과 — 측정이 사주는 것

5. 장단점 및 고려사항

3-2. `merge --no-ff`는 공통 조상을 살린다

✅ 권장 패턴 (Good Practice): main 기반 + `merge --no-ff` 직접 머지

4-1. 비동기 Dynamic API — `cookies()` / `headers()`

4-2. `searchParams` / `params` → Promise

4-3. React 19 타입 — `RefObject<T | null>`

4-4. 서드파티 타입 충돌 회피 — `overrides`