클로드 코드는 왜 가끔 산으로 갈까?

클로드 코드(Claude Code)를 쓰다 보면, 어느 순간 얘가 왜 이러나 싶은 순간이 옵니다.
잘 짜인 코드를 엉망으로 만들거나, 방금 한 약속을 어겨버리기도 합니다.
이 이유가 너무 궁금해 직접 공부하고 정리해 보았습니다. 부족할 수 있지만, 제가 공부한 클로드 코드가 '산'으로 가는 5가지 기술적 이유를 공유합니다.
 

1. 시점 편향 (Recency Bias)

출처

 Primacy Bias - Equalture

 
클로드 코드와 대화하다 보면 초반에 한 약속을 어겨버리는 일이 생깁니다.
예를 들어 "우리 프로젝트는 절대 이 라이브러리를 쓰지 마!" 혹은 "절대 이 코드는 건들지마!"라고 했는데, 어느새 슬쩍 약속을 어겨버리는 모습이 보입니다.
이것이 바로 시점 편항(Recency Bias)입니다.
 
1. 시점 편향이란? 
AI 모델이 컨텍스트(대화 기록) 내에서 가장 최근에 입력된 정보나 명령어에 압도적인 가중치를 두는 현상을 말합니다. 모델에게는 10분 전에 나눈 '중요한 원칙'보다, 10초 전에 던진 '사소한 요청'이 더 강한 자극으로 작용합니다.
 
2. 구체적 사례
상황: 엄격한 Lint 규칙이 있는 프로젝트

• T+0분 (초기 설정): "이 프로젝트는 함수형 컴포넌트만 쓰고, 스타일은 무조건 Tailwind CSS만 사용해줘. 절대 인라인 스타일을 써선 안돼!!!"
  • 클로드: "네, 알겠습니다. Tailwind 컨벤션을 준수하겠습니다."
• T+20분 (치열하게 로직을 수정하는 중): 복잡한 데이터 처리 로직을 수정하느라 대화가 수십 번 오갔습니다. 컨텍스트가 점점 꽉차기 시작합니다.
• T+25분 (문제의 시작): "클로드야, 여기 데이터 로딩 중에 보여줄 스피너 하나만 만들어봐"
  • 결과: 클로드가 코드를 뱉습니다.

// 클로드의 코드
<div style={{ display: 'flex', color: 'blue' }}>Loading...</div>

 
이런?!? Tailwind를 쓰기로 한 약속은 온데간데 없고 갑자기 인라인 스타일을 쓰기 시작합니다.
 
3. 왜 이런 일이 벌어질까?

• 주의력(Attention)의 분산: 대화가 길어지면 초반의 '시스템 프롬프트' 성격의 지시사항은 컨텍스트의 뒤편으로 밀려납니다.
• 보상 체계의 착각: AI는 사용자의 '직전 요구'를 만족시키는 것이 가장 큰 보상(유저의 긍정적 피드백)을 얻는 길이라고 판단합니다.
• 컨텍스트 포화: 새로운 정보가 계속 들어오면 모델은 '신선한 데이터'를 처리하느라 바빠서 과거의 '제약 조건'을 대조해 볼 여유가 없습니다.

4. 어떻게 방어할 것인가?
이 시점 편향을 이기는 방법은 크게 두 가지입니다.

• 지시사항의 재강조: 중요한 규칙은 대화 중간중간 "우리 원칙 잊지 않았지?"라고 다시 상기시켜줘야 합니다.
• 고정된 컨텍스트(External Memory): 대화 로그와 상관없이 클로드가 파일을 수정할 때마다 강제적으로 읽게 만드는 규칙 파일을 두는 것입니다. (이게 마지막에 말할 CLAUDE.md의 핵심 역할입니다.)

 

2. 오류 중첩 (Error Cascading)

클로드 코드를 쓰다 보면 하나를 고쳤는데, 열 개가 고장 나는 상황이 발생합니다. 마치 수도꼭지의 여러 개가 동시에 터져서 급하게 한 곳을 막았는데, 다른 멀쩡했던 배관이 터져버리듯이 말입니다. 클로드가 스스로 에러를 고치려고 발버둥 칠수록 코드는 점점 더 기괴해지고, 결국 작동 불능 상태에 빠지는 이 현상을 오류 중첩이라 부릅니다.
 
1. 오류 중첩이란?
하나의 오류를 수정하기 위해 내린 처방이 새로운 오류를 유발하고, 그 새로운 오류를 잡으려다 기존의 정상적인 로직까지 파괴하며 에러가 꼬리에 꼬리를 무는 현상입니다.
 
2. 구체적 사례
무한 루프의 늪을 구체적 사례로 들 수 있습니다.
상황: API 응답 데이터 처리 로직 수정

• 발단 (Error A): 클로드가 짠 코드에서 TypeError: 'NoneType' object is not subscriptable 에러가 납니다.
• 클로드의 1차 대응: "죄송합니다. 데이터가 없을 경우를 대비해 예외 처리를 추가하겠습니다." -> if data is not None: 구문을 마구 덕지덕지 붙입니다.
• 새로운 에러 (Error B): 예외 처리는 됐는데, 정작 데이터가 필요한 다른 함수에서 값이 안 들어오니 KeyError가 터집니다.
• 클로드의 2차 대응: "KeyError를 해결하기 위해 딕셔너리 get 메서드를 쓰겠습니다!" -> 코드가 점점 복잡해지며 들여쓰기가 깊어집니다.
• 결과: 이제 에러는 안 나지만, 원래 구현하려던 데이터 정렬 기능은 온데간데 없고 파일은 온통 try-catch와 if문으로 가득 찬 누더기가 되어버립니다.

3. 왜 이런 일이 벌어질까?

• 작업 기억(Working Memory)의 매몰: 클로드는 에러 로그가 뜨면 그 에러를 지우는 것을 최우선 목표로 삼습니다. 이 과정에서 내가 원래 뭘 만들려고 했지?라는 근본적인 아키텍처는 컨텍스트 뒤편으로 밀려납니다.
• 부분 최적화의 함정: 전체 코드의 흐름을 보기보다는, 에러가 난 그 줄만 고치려다 보니 다른 모듈과의 의존성이 깨지는 것을 간과합니다.
• 컨텍스트 포화: 에러 로그와 수정 시도가 반복되면 대화 기록이 에러 메시지로 가득 찹니다. 정작 참조해야 할 정상 작동하던 이전 버전의 코드 정보는 컨텍스트 밖으로 밀려나 사라집니다.

4. 어떻게 방어할 것인가?
클로드가 오류 중첩의 늪에 빠진 것 같다면, 즉시 작업을 중단시키고 다음의 심폐소생술을 실시해야 합니다.

• Undo & Reset: 클로드가 세 번 이상 같은 곳에 삽질한다면 "하던 거 멈추고, 3단계 전으로 롤백해"라고 말해야 합니다.
• 에러 원인 재정의: 클로드가 스스로 원인을 찾게 두면 안됩니다. 개발자인 우리가 "이건 예외 처리 문제가 아니라 데이터 타입 자체가 잘못 들어온거야!!"라고 근본 원인을 짚어줘야 합니다.
• 새로운 세션 시작: 컨텍스트가 에러 로그로 오염되었다면, 필요한 코드만 복사해서 아예 새로운 대화를 시작하는 것이 훨씬 빠릅니다.

 

3. 스펙 자체의 모호성 (Ambiguity of Specs)

사람끼리는 "거기 버튼좀 이쁘게 만들어봐"라고 대충 말해도 그냥 통합니다. 하지만 터미널과 파일을 직접 건드리는 클로드 코드에게 이런 모호함은 독입니다. 정보의 빈틈을 발견하는 순간, 클로드는 질문하는 대신 추측을 해버립니다.
 
1. 스펙의 모호성이란?
사용자가 내린 지시에 제약 조건이나 구현 방식이 누락되어 있을 때, AI가 자신의 학습 데이터 중 가장 확률이 높은 답변으로 그 빈칸을 마음대로 채워버리는 현상입니다.
우리가 AI랑 대화할 때 "이 녀석 그냥 모르면 모른다고 하지 끝까지 고집피우고 그럴듯한 오답을 내놓네!!"라고 생각한 경험이 다들 있으시죠?
 
2. 구체적 사례
상황: 게시판 페이징 기능 구현

• 사용자의 요청: "클로드야, 게시판 리스트에 페이징 기능을 추가해줘"
• 발생하는 모호성:
  • 한 페이지에 몇 개씩 보여줘야하지? (10개? 20개?)
  • 쿼리 파라미터 방식인가, 오프셋 방식인가?
  • UI 라이브러리는 뭘 쓸까? (MUI? Ant Design? Pure HTML?)
• 클로드의 추측 결과: 우리 프로젝트는 Tailwind CSS를 쓰고 있는데, 클로드는 갑자기 학습 데이터에서 가장 많이 본 Bootstrap 스타일의 페이지네이션 코드를 짜서 파일에 박아버립니다. 심지어 백엔드 API 명세도 확인 안 한채 ?page=1 이라는 가상의 파라미터를 사용해 버립니다.

3. 왜 이런 일이 벌어질까?

• High-Context vs Low-Context: 인간은 많은 맥락을 공유하는 'High-Context' 소통을 하지만, AI 에이전트는 명시된 것만 읽는 'Low-Context' 존재입니다.
• 학습 데이터의 일반화: 클로드는 전 세계의 수억 줄기 코드를 공부했습니다. 별다른 지시가 없으면 가장 대중적인(하지만 내 프로젝트엔 틀린) 방식을 선택합니다.
• 확신 편향: 에이전트는 사용자를 돕고 싶어 합니다. 질문해서 흐름을 끊기보다는 일단 코드를 짜서 결과를 보여주는 것이 유능하다고 판단할 때가 많습니다.

4. 어떻게 방어할 것인가?
클로드의 창의적인 삽질을 막으려면 지시의 밀도를 높여야 합니다.

• 체크리스트 제공: "페이징 만들어줘. 단 한 페이지당 15개씩, Tailwind CSS를 사용하고, API는 fetchBoardList를 재사용해"
• 참조 코드 지정 (Few-Shot): "기존에 구현된 UserList.tsx의 페이징 로직과 동일한 스타일로 만들어줘"
• 질문 유도: "코드를 짜기 전에 네가 판단하기에 모호한 부분이 있다면 먼저 나에게 질문해줘."라고 명시하는 것도 아주 좋은 방법입니다.
• ⭐️ Spec-driven Development (SDD)
  • 클로드 코드와 같은 에이전트를 다룰 때 가장 주목받는 방법론이 바로 스펙 주도 개발(SDD)입니다.
  • 상세한 스펙이 담긴 md파일을 잘 작성하면 이 문서는 클로드에게 절대 틀려서는 안 되는 지도가 되어줍니다.
  • 스펙 주도 개발(SDD) 심층 탐구하기

스펙 주도 개발(SDD) 심층 탐구하기 | 요즘IT

 
 

4. Lost in the Middle

출처

Lost in the Middle: The Unspoken Risk in Enterprise AI Programs

 

에이전트에게 아주 긴 코드를 주고 "중간에 이 로직만 살짝 바꿔"라고 했는데, 뜬금 없이 코드 상단의 import 문을 지우거나 하단의 return 형식을 바꿔버려 당황한 적이 있습니다. 이것은 클로드의 지능 문제라기보다 LLM이 가진 구조적 한계인 'Lost in the Middle' 현상 때문입니다.
 
1. Lost in the Middle이란?
스탠퍼드와 UC 버클리 연구진이 발표한 이 현상은, AI 모델이 긴 컨텍스트의 처음과 끝에 있는 정보는 아주 잘 기억하고 활용하지만, 정작 중간에 위치한 정보는 인식률이 급격히 떨어지는 U자형 성능 곡선을 보이는 현상을 말합니다.
 
2. 구체적 사례
상황: 400라인이 넘는 비즈니스 로직 수정

• 파일 구조:
  • (상단) 각종 라이브러리 import 및 환경 변수 설정
  • (중간) 가장 복잡하고 중요한 계산 알고리즘 및 예외 처리 로직
  • (하단) 결과 데이터를 포맷팅하여 리턴하는 함수
• 사용자의 요청: "클로드, 마지막 리턴 부분에 날짜 포맷만 'YYYY-MM-DD'로 바꿔줘."
• 클로드의 산으로 가는 결과: 리턴 포맷은 완벽하게 바꿨습니다. 그런데 파일을 저장하고 보니, 중간에 있던 복잡한 계산 알고리즘 50줄이 주석으로 대체되어 사라지거나, 아예 엉뚱한 기본 함수로 대폭 축소되어있습니다.
• 결과: 코드는 에러 없이 실행되지만, 계산 결과값은 완전히 틀리게 나옵니다.

3. 왜 이런 일이 벌어질까?

• 주의력의 병목 현상: 모델이 수천 토큰을 한 번에 처리할 때, 모든 단어에 동일한 집중력을 발휘할 수 없습니다. 대개 지시사항이 담긴 '마지막'과 설정이 담긴 '처음'에 집중력이 쏠립니다.
• 요약 본능: AI는 긴 맥락을 처리할 때 효율성을 위해 스스로 정보를 압축하려 합니다. 이때 '중간 로직'을 중요하지 않은 반복으로 오해하면 과감하게 생락(Hallucination-driven omission)해 버립니다.
• 작업 영역의 분리 실패: 클로드 코드는 파일 전체를 읽고 다시 쓰는 방식을 자주 택하는데, 이때 전체를 기억하지 못한 채 다시 쓰기를 시도하다가 중간을 통째로 날려먹는 것입니다.

4. 어떻게 방어할 것인가?
클로드가 중간을 떼어먹지 못하게 하려면 '집중할 범위'를 강제로 좁혀줘야 합니다.

• 부분 수정 요청: "전체 파일을 수정하지 말고, formatDate함수 부분만 찾아서 수정해줘"라고 범위를 한정하세요.
• 코드 블록 인용: 수정이 필요한 중간 로직을 직접 복사해서 대화창에 넣고 "이 부분만 집중해서 봐줘"라고 강조하는 것이 안전합니다.
• 결과 검증 지시: "수정 후 기존의 중간 알고리즘 로직이 그대로 유지되었는지 다시 한번 확인해"라는 검증 단계를 추가하세요.
• 중요 규칙의 전진 배치: 유실되면 안 되는 핵심 제약 조건은 컨텍스트의 가장 앞부분이나 뒷부분에 중복 배치하여 모델의 주의력을 고정시켜야 합니다.

 

5. 작업 기억의 한계와 컨텍스트 포화 (Context Saturation)

컴퓨터에서 RAM이 부족하면 버벅거리다가 결국 뻗어버리듯이 클로드에게도 작업 기억의 한계가 있습니다. 한창 신나게 코딩을 이어가다가 갑자기 클로드가 "제가 무엇을 도와드릴까요?"라며 첫 만남처럼 행동하거나, 방금 전의 약속을 까먹는다면 바로 이 컨텍스트 포화 상태에 도달한 것입니다.
 
1. 컨텍스트 포화란?
AI 모델은 한 번에 기억하고 처리할 수 있는 정보의 양(Context Window)이 정해져 있습니다. 대화가 길어지고, 수많은 에러 로그와 소스 코드가 오가며 이 용량이 꽉 차게 되면, 모델은 가장 오래된 기억부터 지우거나 전체적인 맥락을 희미하게 처리하기 시작합니다.
 
2. 구체적 사례

• 진행 과정:
  • 처음엔 DB 스키마를 설명했습니다.
  • 그 다음엔 API 엔드포인트를 짰습니다.
  • 중간에 발생한 5개의 버그를 잡느라 수백 줄의 에러 로그가 터미널에 쌓였습니다.
• 사용자의 요청: "자, 이제 아까 처음에 말한 DB 스키마 규칙에 맞춰서 최종 검증 로직 짜줘."
• 클로드의 산으로 가는 결과: "DB 스키마가 어떻게 되나요?"라고 되묻거나, 아예 처음 보는 엉뚱한 테이블 구조를 상상해서 코드를 짭니다. 혹은 방금 전까지 같이 고생해서 고친 버그를 다시 발생시키는 코드로 되돌려놓기도 합니다.
• 결과: 개발자는 "아니 미친거 아니야? 조금 전까지 같이 해놓고 왜 이래?"라며 뒷목을 잡게 됩니다.

3. 왜 이런 일이 벌어질까?

• FIFO(First-In-First-Out)의 저주: 컨텍스트가 꽉 차면 모델은 새로운 정보를 입력받기 위해 가장 예전 정보(보통 가장 중요한 초기 기획이나 원칙)을 삭제합니다.
• 정보 밀도의 희석: 에러 로그 같은 '노이즈'데이터가 컨텍스트의 절반 이상을 차지하게 되면, 정작 중요한 코드 로직에 할당되는 주의력의 밀도가 급격히 낮아집니다.
• 토큰 소모의 가속화: 클로드 코드는 터미널 명령 결과, 파일 내용 등을 계속해서 컨텍스트에 집어넣습니다. 우리가 눈으로 보는 대화보다 훨씬 많은 데이터가 백그라운드에서 소모되고 있습니다.

4. 진화하는 해결책: Claude Memory (Long-term Memory)
최근 Anthropic은 이 문제를 해결하기 위해 'Claude Memory' 기능을 도입했습니다. 휘발성인 작업 기억의 한계를 넘어, 중요한 맥락을 장기 기억 저장소에 따로 보관하는 방식입니다.

Bringing memory to teams | Claude

 

• 장기 기억의 활용: 프로젝트별로 독립된 메모리 공간을 두어, 대화가 길어져 작업 기억이 포화되더라도 핵심 규칙 (예: 우리 팀은 pnpm을 사용함)을 잊지 않게 돕습니다.
• 또 다른 리스크: 하지만 긱뉴스(GeekNews) 유저들이 지적하듯, '잘못된 오답'이나 '지저분한 코드'가 메모리에 기록되면 새로운 세션에서도 그 실수에 집착하는 부작용이 생길 수 있습니다.
  • https://news.hada.io/topic?id=23889

Claude Memory | GeekNews

 
5. 어떻게 방어할 것인가?
클로드의 뇌가 과부하 걸리는 것을 막으려면 주기적으로 기억 정리를 해줘야합니다.

• 세션 리프레시 (New Session): 대화가 너무 길어졌다 싶으면, 현재까지의 핵심 코드와 진행 상황만 요약해서 새 대화를 시작하세요. (/clear 활용)
• 불필요한 로그 차단: 너무 긴 에러 로그나 불필요한 파일 내용을 클로드가 다 읽게 하지 마세요. 필요한 부분만 잘라서 보여주는 센스를 발휘하세요.
• 체크포인트 활용: 중요한 지점마다 "지금까지 진행된 상황을 한 문장으로 요약해줘"라고 시킨 뒤, 그 요약본을 들고 새 세션으로 넘어가는 것이 가장 효과적입니다.

 

6. 핵심 무기 CLAUDE.md

이러한 문제들을 해결할 수 있는 핵심 무기가 바로 CLAUDE.md입니다.
 
1. CLAUDE.md란 무엇인가?
클로드 코드가 실행될 때 가장 먼저, 그리고 프로젝트 내 파일을 건드릴 때마다 참조하는 프로젝트 전용 지침 파일입니다.
 

대화 기록은 사라져도, 이 파일에 적힌 규칙은 영원하다.

 
우리가 겪었던 작업 기억의 한계(5번)이나 시점 편향(1번)을 방어하기 위해, 클로드의 단기 기억 대신 프로젝트 폴더라는 장기 기억에 규칙을 박아넣는 전략입니다.
 
2. CLAUDE.md가 해결하는 고질병들

• 시점 편향 방지: "방금 한 말"보다 CLAUDE.md에 적힌 기술 스택 원칙을 더 우선시하도록 설정합니다.
• 스펙 모호성 제거: 우리 프로젝트의 디렉토리 구조, 빌드 명령어, 텍스트 실행법을 미리 적어두어 클로드가 추측하지 않게 만듭니다.
• 오류 중첩 차단: "에러 발생 시 무작위 수정을 금지하고, 먼저 로그를 분석한 뒤 해결 게획부터 보고하라"는 절차를 강제할 수 있습니다.

3. CLAUDE.md에 반드시 들어가야 할 4가지 필수 요소
 
1️⃣ 프로젝트 개요 (What & Why)
이 프로젝트가 무엇인지, 어떤 언어와 프레임워크를 쓰는지 명시합니다.
예: "이 프로젝트는 Next.js 기반의 뉴스레터 관리 도구다. 패키지 매니저는 pnpm을 사용한다."
 
2️⃣ 기술 스택 및 스타일 가이드 (How)
코딩 컨벤션을 명확히 합니다.
예: "모든 스타일은 Tailwind CSS로 작성하며, 아이콘은 Lucide-React를 사용한다. 비동기 처리는 React Query를 원칙으로 한다."
 
3️⃣ 주요 명령어 (Commands)
클로드가 터미널에서 헤매지 않도록 정답지를 줍니다.
예:

• 빌드: pnpm build
• 테스트: pnpm test
• 린트: pnpm lint --fix

4️⃣ 워크플로우 제약 조건 (Guardrails)
클로드의 돌발 행동을 막는 가장 중요한 부분입니다.
예: "파일을 수정하기 전 반드시 계획(Plan)을 먼저 제안하고 승인을 받아라.", "복잡한 로직 수정 시 주석을 삭제하지 마라." (Lost in the Middle 방어)
 
4. 나만의 CLAUDE.md 만들기
프로젝트 루트 디렉토리에 CLAUDE.md 파일을 만들고 아래 내용을 복사해서 수정해보세요.

# Project: [프로젝트 이름]

## Tech Stack
- Framework: Next.js (App Router)
- Language: TypeScript
- Styling: Tailwind CSS
- Package Manager: pnpm (절대 npm/yarn 사용 금지)

## Directory Structure
- /src/components: 공통 UI 컴포넌트
- /src/lib: 유틸리티 및 API 통신 로직

## Coding Rules
- 모든 컴포넌트는 함수형으로 작성한다.
- 인라인 스타일은 금지하며, 무조건 Tailwind 클래스를 사용한다.
- 에러 발생 시 수정을 시도하기 전, 에러의 원인을 3줄로 요약해 먼저 보고한다.
- 긴 파일을 수정할 때 중간 로직을 주석(`//...`)으로 생략하지 말고 전체를 유지한다.

## Common Commands
- Dev: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm test`

 
Solving Claude Code's (Short-Term) Memory Problem

추가로 이 영상은 클로드 코드의 메모리 문제를 해결하기 위해 CLAUDE.md와 같은 컨텍스트 엔지니어링을 어떻게 활용하는지 실전 팁을 담고 있어 참고하시는게 좋습니다. 다음에 이 영상을 더 공부해서 포스팅해보도록 하겠습니다..😄
 

---

 
추가 출처
- Claude Code를 활용한 예측 가능한 바이브 코딩 전략
- Why Memory Matters in LLM Agents: Short-Term vs Long-Term Memory Architectures

Why Memory Matters in LLM Agentss |Skymod