클로드가 이상한 코드를 만든다면 컨텍스트부터 봐야 합니다
2026. 06. 11. 16:20
Claude Code를 쓰다 보면 이런 순간이 있습니다. 분명히 말하지 않은 기능을 만들고, 기존 컨벤션과 다른 코드를 쓰고, 앞에서 정한 구조를 잊은 것처럼 움직입니다. 처음에는 모델이 별로라고 느끼기 쉽습니다. 하지만 긴 작업에서는 모델 성능만큼 중요한 변수가 있습니다. 컨텍스트를 어떻게 관리하느냐입니다.
AI 모델은 무한히 기억하지 못합니다. 한 번에 들고 갈 수 있는 작업 기억이 있고, 대화가 길어지고 파일을 많이 열수록 그 기억은 차오릅니다. 이 상태에서 계속 작업을 시키면 앞선 결정이 흐려지고, 구조를 잘못 이해하고, 불필요한 구현이 붙기 쉽습니다. Claude가 이상한 코드를 만든다면 먼저 물어봐야 합니다.
지금 Claude에게 필요한 기억이 정리되어 있는가. 작업 단위가 너무 커지지는 않았는가. 진행 상태와 완료 기준이 파일로 남아 있는가. 세부 작업을 한 세션에 너무 많이 몰아넣고 있지는 않은가. 이 질문에 답하지 않은 채 더 긴 프롬프트만 붙이면 결과가 크게 좋아지기 어렵습니다.
컨텍스트가 차면 작업 기억이 흔들립니다
Claude Code는 코드를 읽고, 파일을 수정하고, 명령을 실행하고, 오류를 확인합니다. 이 과정에서 많은 정보가 컨텍스트에 들어갑니다. 처음에는 괜찮습니다. 요구사항도 선명하고, 프로젝트 구조도 기억하고, 방금 수정한 파일도 따라갑니다. 문제는 작업이 길어질 때입니다.
기능 하나를 만들고, 버그를 고치고, UI를 다듬고, 테스트를 추가하고, 다시 리팩터링하는 흐름이 이어지면 컨텍스트가 빠르게 커집니다. 그러면 Claude는 앞에서 정한 판단 기준을 놓칠 수 있습니다. 예를 들어 이런 일이 생깁니다.
이미 있는 패턴을 재사용하지 않고 새 구조를 만듭니다.
요청하지 않은 기능을 붙입니다.
기존 컨벤션과 다른 네이밍을 씁니다.
테스트나 상태 관리 흐름을 충분히 보지 않고 수정합니다.
완료 기준을 흐리게 이해합니다.
이건 단순히 “Claude가 멍청하다”로 끝낼 문제가 아닙니다. 작업 기억을 운영하는 방식이 흔들린 신호일 수 있습니다.
자동 compaction만 믿으면 빠지는 정보가 생길 수 있습니다
Claude에는 자동 compaction이 있습니다. 컨텍스트가 커지면 지금까지의 작업을 요약해서 다음 흐름으로 넘기는 방식입니다. 이 기능은 필요합니다. 긴 작업을 계속 이어가려면 어느 순간 요약이 있어야 합니다. 하지만 자동 compaction에는 한계가 있습니다.
언제 요약할지, 무엇을 반드시 남길지, 어떤 세부 결정을 버릴지 사용자가 완전히 통제하기 어렵습니다. 사람 입장에서는 매우 중요한 결정인데 요약에서는 빠질 수 있습니다. 예를 들어 이런 정보가 빠지면 문제가 됩니다.
왜 이 라이브러리를 골랐는지
어떤 구현은 일부러 제외했는지
어떤 테스트가 완료 기준인지
어떤 UI 상태가 깨지면 안 되는지
어떤 파일은 건드리지 말아야 하는지
자동 요약은 편하지만, 중요한 작업에서는 사람이 기준을 잡아줘야 합니다. 작업 하나가 끝났을 때 핵심 결정과 다음 할 일을 직접 정리해두는 편이 안전합니다.
작업 노트는 AI의 외부 기억입니다
긴 작업에서 가장 단순하고 효과적인 방법은 작업 노트를 만드는 것입니다. 예를 들어 `tasks.md` 같은 파일에 다음 내용을 적어둡니다.
전체 목표
작업 목록
진행 상태
완료 기준
확인해야 할 명령
결정한 설계 방향
다음 작업 전에 다시 읽어야 할 주의점
그리고 Claude에게 작업할 때마다 이 파일을 확인하고 업데이트하게 합니다. 이 방식은 AI에게 외부 기억을 주는 것과 비슷합니다. 세션 안의 기억이 흔들려도 파일에는 현재 상태가 남아 있습니다. 컨텍스트가 줄어들거나 compaction이 일어나도, Claude는 다시 파일을 읽고 흐름을 이어갈 수 있습니다. 중요한 점은 노트를 예쁘게 쓰는 것이 아닙니다.
작업이 끝날 때마다 실제 상태가 반영되어야 합니다. 무엇을 끝냈는지, 무엇이 남았는지, 어떤 기준을 통과했는지 남아 있어야 합니다. 이 기록이 없으면 Claude는 매번 현재 위치를 다시 추측해야 합니다. 추측이 늘어나면 결과도 흔들립니다.
서브 에이전트는 컨텍스트 낭비를 줄입니다
긴 작업을 하나의 Claude 세션에 모두 맡기면 메인 세션이 너무 많은 정보를 들고 있어야 합니다. 게임 로직도 봐야 하고, UI 컴포넌트도 봐야 하고, 테스트도 봐야 하고, 성능도 봐야 합니다. 모든 파일과 판단을 한 흐름에 밀어 넣으면 컨텍스트가 빨리 찹니다. 서브 에이전트는 이 문제를 줄이는 방식입니다. 예를 들어 2048 게임을 만든다고 하면 역할을 나눌 수 있습니다.
게임 로직 담당
React 컴포넌트 담당
테스트 작성 담당
성능 점검 담당
상태 관리 담당
각 역할은 자기 범위의 파일과 판단을 더 좁게 봅니다. 메인 세션은 모든 세부 구현을 계속 들고 있지 않아도 됩니다. 이 구조가 항상 필요한 것은 아닙니다. 작은 수정 하나라면 오히려 과합니다.
하지만 작업이 길고 역할이 나뉘는 프로젝트라면, 서브 에이전트는 컨텍스트를 분리하는 좋은 방법입니다. 중요한 것은 “AI를 여러 개 켠다”가 아니라 “기억해야 할 범위를 나눈다”입니다.
초반에는 무계획 작업이 더 빨라 보입니다
컨텍스트 엔지니어링을 적용하면 초반 속도는 느려 보일 수 있습니다. 작업 목록을 만들고, 노트를 쓰고, 규칙을 정하고, 서브 에이전트를 만들고, 단계별로 확인하기 때문입니다. 반대로 아무 계획 없이 “바로 만들어줘”라고 하면 Claude는 곧바로 프로젝트를 생성하고 코드를 쓰기 시작합니다. 처음 10분만 보면 무계획 작업이 이긴 것처럼 보일 수 있습니다. 하지만 긴 작업은 뒤로 갈수록 차이가 납니다.
기능이 늘어나고, 수정이 반복되고, 오류를 고치고, UI 디테일을 다듬기 시작하면 기준이 필요합니다. 노트가 없는 작업은 어디까지 했는지 흐려지고, 자동 compaction 이후에는 앞선 맥락이 더 약해질 수 있습니다. 반대로 작업 노트와 역할 분리가 있으면 다음 단계로 넘어가기 쉽습니다. 무엇을 끝냈는지 알고, 다음에 무엇을 해야 하는지 알고, 어떤 테스트를 통과해야 하는지 알기 때문입니다.
결과 차이는 디테일에서 보입니다
2048 게임 개발 비교에서는 양쪽 모두 겉으로는 게임을 만들었습니다. 그래서 처음에는 차이가 크지 않아 보일 수 있습니다. 버튼이 있고, 타일이 움직이고, 점수가 올라가면 비슷해 보입니다. 하지만 디테일에서 차이가 납니다.
컨텍스트 엔지니어링을 적용한 쪽은 작업을 더 작게 쪼개고, 진행 상태를 기록하고, 필요한 역할을 분리했습니다. 그 결과 favicon, 모바일 UI, 로딩 상태, 테스트 코드 같은 부분까지 더 안정적으로 챙길 수 있었습니다. 반대로 빠르게 만든 쪽은 초반 결과는 빨랐지만, 후반으로 갈수록 UI 어긋남이나 상태 관리 디테일에서 약점이 보였습니다. AI 코딩의 품질은 “첫 화면이 떴는가”만으로 판단하기 어렵습니다.
다음 기능을 붙일 수 있는가. 테스트가 남아 있는가. 모바일에서 깨지지 않는가. 작업 상태를 다시 이어갈 수 있는가. 이런 질문에서 차이가 납니다.
좋은 프롬프트보다 좋은 작업 기억이 필요합니다
Claude Code를 잘 쓰는 방법을 프롬프트 문장으로만 생각하면 한계가 있습니다. 물론 프롬프트도 필요합니다. 요구사항을 명확히 쓰고, 금지할 범위를 알려주고, 검증 기준을 주는 일은 결과를 안정시키는 기본 조건입니다. 하지만 긴 작업에서는 문장 하나보다 구조가 더 오래갑니다. 작업을 파일로 남기고, 단계별로 compaction하고, 역할을 나누고, 완료 기준을 계속 업데이트하는 구조가 필요합니다.
Claude가 앞선 결정을 잊지 않게 하려면 기억해야 할 것을 파일과 작업 단위에 남겨야 합니다. Claude가 모든 세부 파일을 한꺼번에 들고 있지 않게 하려면 역할을 나눠야 합니다. Claude가 자동 요약에서 중요한 결정을 놓치지 않게 하려면 작업 단위가 끝날 때 직접 정리해야 합니다. Claude가 이상한 코드를 만든다면 모델만 탓하기 전에 컨텍스트를 먼저 봐야 합니다.
긴 작업에서 결과를 바꾸는 것은 더 화려한 지시문이 아니라, AI가 기억하고 이어갈 수 있는 작업 구조입니다.