Claude의 과잉 엔지니어링(Over-engineering) 본능을 억제하는 CLAUDE.md의 한 줄

네 번째는 너무 늦습니다

이전 에피소드([CANONICAL URL #52: to complete after push of over-engineering-3-recadrages])에서, 저는 Claude가 인터페이스, 레지스트리(Registry), 그리고 3개의 파일이 포함된 버전 대신 마침내 8줄짜리 함수 버전을 제안하기 전까지, 한 세션 내에서 세 번의 재구성(Reframing) — 더 단순하게, 더 단순하게, 더 단순하게 — 을 거쳤던 과정을 설명했습니다. 다음 날 아침 프로젝트를 다시 열고 동일한 모듈에 대한 사소한 수정을 요청하자, 답변은 전날과 정확히 똑같은 구조로 도착했습니다. 전략 패턴(Strategy pattern), 레지스트리(Registry), 그리고 3개의 통합 테스트(Integration tests). 재구성은 /clear 명령어를 견뎌내지 못했습니다. 그럴 이유가 없었기 때문입니다. 어떤 파일도 이를 유지하지 않았고, 본능이 되살아날 때 이를 트리거할 메커니즘도 없었습니다.

네 번째는 너무 늦습니다. 세 번째에 그 문장을 작성해야 합니다.

그 문장

저는 CLAUDE.md의 Conventions(규약) 섹션 내, Server Component 규칙 바로 위 블록에 다음 내용을 추가했습니다:

적합한 가장 작은 변경을 기본값으로 합니다(Default to the smallest change that fits). 추상화(Abstractions)는 두 번째 발생했을 때만 추가하며, 첫 번째에는 절대 추가하지 마십시오.

두 문장 안에 네 가지 선택지가 담겨 있습니다. 각 선택지는 제대로 자리 잡기까지 여러 번의 초안을 거쳤습니다.

왜 이 네 가지인가

avoid(피하라)가 아닌 Default to(~를 기본값으로 한다). 제가 처음 시도했던 버전은 _조기 추상화(premature abstraction)를 피하라_였지만, 실제로는 아무것도 바뀌지 않았습니다. 부정어는 그것이 지칭하는 대상을 활성화합니다. 에이전트는 _조기 추상화_를 읽고 추상화(abstraction) 카테고리를 떠올리며, 이는 에이전트가 학습한 기본값인 '추상화를 만들어내는 본능'을 자극합니다. 긍정문은 반대되는 본능을 명시하지 않고도 방향을 설정합니다. 이는 이번 작업에서 가장 눈에 띄지 않는 세부 사항이었으며, 테스트의 성패를 가른 결정적인 부분이었습니다.

단순히 smallest(가장 작은)가 아닌 That fits(적합한). _가장 작은 변경(The smallest change)_만으로는 해킹(Hack)에 가까운 코드로 치우칠 수 있습니다. _가장 단순한 해결책(The simplest solution)_은 '단순함'이 무엇인지에 대한 논쟁을 불러일으킵니다. _That fits(적합한)_는 기준을 명시합니다. 즉, 우아함이 아니라 필요를 충족하는 것을 기준으로 삼는 것입니다.

세 번째가 아니라 두 번째입니다. Martin Fowler의 저서 _Refactoring_에 나오는 '3의 법칙(rule of three)'은 "유사한 작업을 세 번째 수행할 때 리팩터링(refactor)하라"고 말합니다. 저는 아마도 Claude Code를 단독으로 개발할 때만 유효할 법한 이유로 이 기준을 두 번으로 낮추었습니다. 즉, PR 리뷰(Pull Request review)가 없기 때문에, 두 번째 발생이 제가 도입하려는 추상화(abstraction)에 대해 여전히 명료한 정신을 유지하고 있는 마지막 순간이기 때문입니다. 세 번째가 되면 Claude는 자발적으로 추상화를 제안하고, 저는 세션의 압박감에 지쳐 확인도 하지 않은 채 승인해 버립니다.

결코 첫 번째는 안 된다. 여기서 _결코(never)_라는 표현은 의도적이며 아마도 과도할 것입니다. 하지만 예외를 포함하여 공식화된 기본값은 결국 찾아내야 할 예외가 되어버립니다. _결코_라는 표현은 내부적인 협상을 차단합니다. 진정으로 예외적인 사례가 발생했을 때 — 그리고 그런 일은 반드시 일어납니다 — 저는 명시적으로 그 규칙에 반대하여 논쟁해야 하며, 이것이 바로 제가 원하는 마찰(friction)입니다.

지금까지 목격한 것

세 번의 세션, 세 개의 주제, 세 개의 모듈. Claude는 지난주 세션당 3~4번씩 발생하던 것과 달리, 제가 포착하여 단 한 번의 대화 만에 철회하게 만든 조기 추상화(premature abstraction)를 단 한 번 제안했습니다. 이것은 연구가 아닙니다. 관찰자 한 명, 확증 편향(confirmation bias), 터무니없이 적은 표본입니다. 하지만 매 시작 시 CLAUDE.md가 로드되면서, 현재의 기준점(baseline) 압박은 훈련된 기본값에 반하는 방향을 가리키고 있습니다. 제대로 된 A/B 테스트는 이후 포스트의 주제로 다룰 예정입니다.

코다 (Coda)

CLAUDE.md에 담긴 교리는 베스트 프랙티스(best practices)의 목록이 아닙니다. 그것은 제가 네 번째 반복하기를 거부했던 교훈들의 물리적 축적입니다. '3의 법칙(Fowler의 추상화 규칙)'이 '3의 법칙(나의 규칙, 세션 중 구두 재구성)'에 적용된 것입니다. 제가 Claude에게 똑같은 말을 세 번째 하는 상황이 오면, 그것은 CLAUDE.md에 한 줄의 문장으로 기록됩니다. 그렇지 않으면 저는 다음 세션에서 또다시 그 말을 하게 될 것이고, 그 교훈은 컨텍스트(context)와 함께 사라져 버릴 것이기 때문입니다.

sequel to [CANONICAL URL #52: to complete after push of over-engineering-3-recadrages]. Claude Code 출력물에 대한 CLAUDE.md 효과의 A/B 테스트: 이 시리즈의 후속 포스트 주제.