복리 엔지니어링: 느려지지 않고 가속하는 코드베이스

대부분의 코드베이스는 성장할수록 느려집니다. 제 코드베이스는 가속합니다. .claude/ 인프라에 95개의 hook, 44개의 skill, 14개의 설정 파일을 구축한 후, 인프라가 더 많은 작업을 처리해주기 때문에 새로운 기능의 비용이 이전보다 줄어들고 있습니다.¹

요약

복리 엔지니어링이란 기능을 추가할 때마다 이후 기능의 구축 비용이 줄어드는 코드베이스를 말합니다. 저는 이것을 직접 경험했습니다. 제 Claude Code hook 시스템은 3개의 hook에서 시작하여 95개로 성장했습니다. 첫 번째 hook을 만드는 데 한 시간이 걸렸습니다. 최근 hook은 인프라(라이프사이클 이벤트, 설정 로딩, 상태 관리, 테스트 하네스)가 이미 존재하기 때문에 10분이면 완성됩니다. 반대 패턴인 엔트로피 엔지니어링은 기능을 추가할 때마다 이후 기능의 비용이 증가하는 코드베이스를 말합니다. 3년 차에 1년 차보다 더 빠르게 배포하는 팀과 정체에 빠지는 팀의 차이는 엔지니어링 결정이 긍정적으로 복리 효과를 내는지 부정적으로 작용하는지에 달려 있습니다.

실전에서의 복리: 제 .claude/ 인프라

성장 곡선

첫 번째 hook(git-safety-guardian.sh)은 전체 hook 라이프사이클을 구축해야 했습니다. PreToolUse 이벤트를 이해하고, JSON 입력을 파싱하는 bash를 작성하고, 에러 케이스를 처리하고, 수동으로 테스트해야 했습니다. 95번째 hook은 그 모든 인프라를 물려받았습니다. hook당 소요 시간이 6배 줄어든 것은 hook이 더 단순해져서가 아니라, 인프라가 더 많은 작업을 처리해주기 때문입니다.

복리 효과를 만드는 요소들

패턴의 일관성. 모든 hook은 동일한 구조를 따릅니다: JSON 입력 읽기, jq로 파싱, 조건 확인, 결정 JSON 출력. 개발자(또는 AI 에이전트)가 어떤 hook을 읽더라도 즉시 패턴을 인식합니다. 제 12모듈 블로그 린터도 동일한 일관성 원칙을 따릅니다. 각 모듈이 동일한 인터페이스(check(content, meta) -> findings)를 내보내므로 새 모듈 추가가 간단합니다.

설정 기반 동작. 14개의 JSON 설정 파일 모두 원래 하드코딩되어 있던 임계값과 규칙을 인코딩합니다. 합의 임계값을 Python의 하드코딩된 0.70에서 deliberation-config.json으로 옮겼을 때, 코드 변경 없이 작업 유형별로 조정할 수 있는 능력을 얻었습니다(보안=85%, 문서=50%).²

테스트 인프라. 처음 20개의 hook에는 테스트가 없었습니다. 테스트 하네스(48개의 bash 통합 테스트, 81개의 Python 단위 테스트)를 추가하는 데 2주가 걸렸습니다. 그 이후의 모든 hook은 픽스처, 어설션 헬퍼, 테스트 러너가 이미 존재하기 때문에 5분 이내에 테스트와 함께 배포됩니다.

메모리 시스템. 제 MEMORY.md 파일은 세션 간 오류, 결정, 패턴을 기록합니다. 54개 항목으로 같은 실수를 반복하지 않도록 해줍니다. hook #23에서 발견한 ((VAR++)) bash 문제는 hook #24부터 #95까지 동일한 버그를 방지해 주었습니다. 각 항목은 이후 모든 세션에 걸쳐 복리 효과를 냅니다.³

복리 모델

긍정적 복리

엔지니어링 생산성은 복리 이자 공식을 따릅니다:

Productivity(n) = Base × (1 + r)^n

여기서 r은 기능당 생산성 변화율이고 n은 배포된 기능의 수입니다.

양의 r (복리): 각 기능이 다음 기능을 2~5% 저렴하게 만듭니다. 50개 기능 후: 1.03^50 = 4.38배 생산성 향상.

음의 r (엔트로피): 각 기능이 다음 기능을 2~5% 비싸게 만듭니다. 50개 기능 후: 0.97^50 = 0.22배 생산성, 78% 저하.

50개 기능 후 이 두 궤적의 차이는 엔지니어링 속도에서 20배의 격차를 만듭니다.⁴

제 실제 수치

blakecrosley.com 사이트는 하나의 FastAPI 라우트와 HTML 템플릿으로 시작했습니다. 9개월 후:

마지막 항목이 복리의 결실입니다. 새 린터 모듈을 추가하는 데 15분이 걸리는 이유는 모듈 인터페이스, CLI 통합, 테스트 하네스, CI 파이프라인이 이미 존재하기 때문입니다. 첫 번째 모듈은 그 어떤 인프라도 존재하지 않았기 때문에 3시간이 걸렸습니다.⁵

제 코드베이스에서 겪은 엔트로피 사례

복리는 자동으로 일어나지 않습니다. 저도 엔트로피를 경험했습니다:

ContentMeta 스키마 지름길

블로그 포스트 ContentMeta 데이터클래스를 한 세션에서 정의했습니다: title, slug, date, description, tags, author, published. category, series, hero_image, scripts, styles는 포함하지 않았습니다. 나중에 각 항목을 추가할 때마다 파서를 수정하고, 메타데이터를 소비하는 모든 템플릿을 업데이트하고, 전체 파이프라인을 재테스트해야 했습니다. 3개월에 걸친 다섯 번의 추가 작업은 처음에 스키마를 신중하게 설계했을 때보다 총 시간이 더 많이 들었습니다. 이것이 결정 타이밍 문제입니다: 되돌릴 수 없는 결정은 사전 분석을 받을 가치가 있습니다.

i18n 캐시 키 충돌

번역 캐싱의 빠른 구현에서 블로그 슬러그를 캐시 키로 사용했습니다. 같은 슬러그의 번역이 서로 다른 로케일에 존재할 때, 캐시가 잘못된 언어를 반환했습니다. 디버깅에 3시간이 걸렸습니다. 수정은 15분이면 됐습니다(캐시 키에 로케일 접두사 추가). 구현 중 5분을 아끼려던 지름길이 디버깅에 3시간과 시스템 전체 캐시 키의 아키텍처 리뷰라는 비용을 초래했습니다.⁶

3.2GB 디버그 디렉토리

hook 디버그 출력이 정리 없이 ~/.claude/debug/에 쌓였습니다. 3개월에 걸쳐 디렉토리가 3.2GB로 커졌습니다. 나중에 만든 컨텍스트 감사 skill이 이를 발견하고 7일 이상 된 파일을 정리했지만, 정리 인프라는 첫 번째 디버그 출력과 함께 구축했어야 했습니다.

복리 효과를 만드는 실천법

최적의 패턴보다 일관된 패턴

50개 기능에 걸쳐 동일한 “충분히 좋은” 패턴을 사용하는 팀이, 각 기능마다 “최적의” 패턴을 사용하는 팀보다 더 빠르게 운영됩니다. 일관성은 인지 부하를 줄이고, 자동화 도구를 가능하게 하며, 코드 리뷰를 빠르게 만듭니다.⁷

제 hook 시스템은 일부 hook이 Python으로 표현하는 것이 더 자연스럽더라도 95개 모든 hook에 동일한 bash 패턴을 사용합니다. 이 일관성 덕분에 하나의 hook을 읽어본 사람(또는 AI 에이전트)이라면 어떤 hook이든 읽을 수 있습니다. 최적이 아닌 언어 선택은 새 hook에 대한 학습 비용이 0이라는 점에 의해 충분히 상쇄됩니다.

인프라를 첫 번째 기능으로

blakecrosley.com에서 제품 기능을 만들기 전에 CI/CD 파이프라인, 테스트 하네스, 배포 워크플로우를 먼저 구축했습니다. 당시에는 느리게 느껴지는 투자였습니다. 그 이후 모든 기능은 자동화된 테스트와 함께 2분 이내에 배포되고 있습니다.⁸

마인드 팰리스 패턴

제 .claude/ 디렉토리는 “마인드 팰리스” — 인간과 AI 모두의 소비에 최적화된 구조화된 문서 집합으로 기능합니다:

~/.claude/
├── configs/     # 14 JSON files — system logic, not hardcoded
├── hooks/       # 95 bash scripts — lifecycle event handlers
├── skills/      # 44 directories — reusable knowledge modules
├── docs/        # 40+ markdown files — system documentation
├── state/       # Runtime tracking — recursion depth, agent lineage
├── handoffs/    # 49 documents — multi-session context preservation
└── memory/      # MEMORY.md — 54 cross-domain error/pattern entries

마인드 팰리스는 새로운 항목이 추가될 때마다 이후 개발 세션에서 사용할 수 있는 컨텍스트를 풍부하게 만들기 때문에 복리 효과를 냅니다. 54개의 MEMORY.md 항목 후, AI 에이전트는 이미 해결한 실수를 피합니다. 95개의 hook 후, 새 hook은 확립된 패턴을 따라 스스로 작성됩니다. 풍부해진 컨텍스트가 더 적합한 AI 생성 코드를 만들어내고, 이는 다음 기능을 더 저렴하게 만듭니다.⁹

AI 시대의 복리

AI는 양방향 모두를 증폭시킵니다

AI 코딩 어시스턴트는 코드베이스가 이미 따르고 있는 패턴을 가속화합니다. 일관된 패턴을 가진 제 95개의 hook은 AI가 확립된 구조를 매칭하기 때문에 우수한 AI 생성 hook을 만들어냅니다. 5가지 다른 hook 스타일을 가진 코드베이스는 AI가 매칭할 일관된 패턴이 없기 때문에 더 나쁜 AI 생성 코드를 만들어냅니다.¹⁰

복리 효과가 두 배로 작용합니다: 일관된 패턴은 인간 개발을 더 빠르게 만들고(인지 부하 감소) AI 보조 개발도 더 빠르게 만듭니다(패턴 매칭). 일관성 없는 패턴은 둘 다 느리게 만듭니다.

에이전트가 읽을 수 있는 코드베이스

저는 .claude/ 인프라를 AI 에이전트가 소비할 수 있도록 설계했습니다:

• 구조화된 설정 (하드코딩된 값이 아닌 JSON)으로 에이전트가 프로그래밍 방식으로 파싱
• 일관된 명명 규칙 (hook은 verb-noun.sh, skill 정의는 SKILL.md)
• 기계 검증 가능한 품질 검사 (에이전트가 자율적으로 실행하는 141개 테스트)
• 명시적 문서화 (MEMORY.md, 핸드오프, docs/)로 에이전트가 세션 시작 시 읽기

에이전트 가독성에 대한 각 투자는 AI 도구가 더 강력해질수록 복리 효과를 냅니다.¹¹

핵심 시사점

엔지니어를 위한 조언: - 코드베이스가 성장함에 따라 “기능당 소요 시간”을 추적하세요. 증가하면 엔트로피이고, 감소하면 복리입니다 - 추상화를 추출하기 전에 3의 법칙을 적용하세요: 구체적인 솔루션을 두 번 만든 후, 세 번째에 재사용 가능한 패턴을 추출하세요 - 각 스프린트의 15~20%를 인프라와 도구 개선에 투자하세요. 복리 수익은 3~5 스프린트 내에 단기 기능 배포 속도 비용을 초과합니다

엔지니어링 매니저를 위한 조언: - 시간에 따른 기능당 리드 타임으로 엔지니어링 건강 상태를 측정하세요. 리드 타임 증가는 엔트로피 신호입니다 - 문서와 테스트 인프라를 오버헤드가 아닌 기능으로 취급하세요. 제 테스트 인프라 투자(2주)는 95개 hook에 걸쳐 50시간 이상을 절약했습니다

참고 문헌