책에 포함된 노트요즘 바이브 코딩: Codex로 일하는 개발자의 완전 가이드

Chapter 07. 컨텍스트 관리와 메모리

2026-04-25Views 68약 11분생성형 AI 활용

Chapter 07. 컨텍스트 관리와 메모리

바이브 코딩을 조금만 해보면 이상한 순간을 만나게 된다. 처음 10분은 Codex가 아주 똑똑하다. 그런데 40분쯤 지나면 갑자기 엉뚱한 파일을 건드리고, 이미 끝난 논쟁을 다시 꺼내고, 아까 합의한 제약을 슬쩍 잊는다. 많은 사람이 이때 "모델이 별로네"라고 말한다. 하지만 실무에서는 다른 경우가 더 많다. 모델이 나빠진 게 아니라, 컨텍스트가 더러워진 것이다.

이 장에서 다룰 핵심은 간단하다. 긴 작업에서 품질을 지키는 사람은 프롬프트를 멋지게 쓰는 사람이 아니라, 컨텍스트를 운영할 줄 아는 사람이다. 메모리가 무엇을 맡고, AGENTS.md가 무엇을 맡고, /compact는 언제 눌러야 하며, /fork는 왜 대안 실험보다 문맥 분리에 더 중요한지 이해하면 Codex의 결과 품질이 눈에 띄게 안정된다.

쉽게 말해, 좋은 바이브 코더는 말을 잘 거는 사람이 아니라 작업장을 잘 정리하는 사람이다.

PART 02-7. 컨텍스트 관리와 메모리

Codex의 기억은 네 층으로 이해하면 쉽다

Codex의 컨텍스트를 한 덩어리로 생각하면 자꾸 헷갈린다. 실제로는 서로 성격이 다른 네 층이 겹쳐서 돌아간다.

첫째는 현재 스레드의 대화 컨텍스트다. 지금 이 세션에서 주고받은 요청, 읽은 파일, 실행한 명령, 생성된 diff가 여기에 쌓인다. 가장 즉각적이고 가장 강력하지만, 동시에 가장 쉽게 혼탁해지는 층이다.

둘째는 세션 기록이다. Codex는 세션 롤아웃 파일을 남기고, 이것이 resume과 fork의 기반이 된다. 즉 "어제 하던 일 이어서 하기"는 이 층의 도움을 받는다. 다만 이건 검색 가능한 지식창고라기보다, 작업 녹화본에 가깝다.¹

셋째는 내장 메모리다. Codex의 메모리는 이전 스레드에서 얻은 안정적인 선호, 반복 워크플로, 프로젝트 관습, 자주 걸리는 함정 같은 것을 다음 작업에 가져오도록 돕는다. 공식 문서도 이 메모리를 "팀 정책의 저장소"가 아니라, 사용자의 반복 설명을 줄여주는 로컬 회상 장치로 설명한다.²

넷째는 AGENTS.md와 체크인된 프로젝트 문서다. 이건 기억이라기보다 헌법에 가깝다. 메모리는 "지난번엔 이렇게 했더라"에 가깝고, AGENTS.md는 "이 레포에서는 이렇게 해야 한다"에 가깝다. 그래서 팀 규칙, 구조 규칙, 금지 구역은 메모리보다 AGENTS.md에 있어야 한다.²

이 네 층의 역할을 섞어 쓰기 시작하면 일이 꼬인다. 예를 들어 팀 공통 규칙을 메모리에만 기대면 사람마다 다른 기억이 붙는다. 반대로 매번 바뀌는 디버깅 흔적을 AGENTS.md에 넣으면 문서가 금세 비대해진다. 기억과 규칙은 닮았지만 같은 것이 아니다.

메모리가 있다고 해서 Codex가 다 기억하는 것은 아니다

여기서 기대치를 바로 잡는 것이 중요하다. Codex의 메모리는 "프로젝트의 모든 역사"를 완벽하게 저장하는 무한 노트가 아니다. 실무 감각으로는 이렇게 이해하는 편이 정확하다.

메모리는 다음에도 유효할 가능성이 높은 것을 다시 떠올리게 하는 장치다. 반면 지금 막 본 로그 한 줄, 오늘만 임시로 쓴 우회책, 방금 실패한 실험 하나는 기억할 가치가 낮을 수 있다. 기억이 많다고 좋은 것도 아니다. 오래가는 작업에서는 기억의 양보다 기억의 밀도가 더 중요하다.

예를 들어 Next.js + Supabase 프로젝트에서 아래 셋을 비교해 보자.

"이 프로젝트는 pnpm을 쓰고, 인증은 Supabase Auth 기준이다."
"middleware.ts에서 세션 리다이렉트 조건을 잘못 걸면 로그인 루프가 생긴다."
"오전 11시 23분에 console.log(user)가 null이었다."

첫 번째는 AGENTS.md에 어울린다. 두 번째는 메모리 후보가 될 수 있다. 세 번째는 대부분 세션 안에서만 의미가 있다. 이 구분을 못 하면, Codex는 자꾸 중요하지 않은 자잘한 흔적을 오래 끌고 가게 된다.

그래서 컨텍스트 운영의 첫 원칙은 이것이다. 안정적인 사실은 문서로, 반복해서 유용한 발견은 메모리로, 순간적인 흔적은 세션 안에만 둔다.

긴 작업이 망가지는 진짜 이유는 토큰 부족보다 잡음 증가다

컨텍스트 관리 이야기를 하면 많은 사람이 곧바로 "토큰이 부족해서 그렇죠?"라고 묻는다. 맞는 말이지만 절반만 맞다. 실제로 더 흔한 문제는 토큰 부족 그 자체보다, 중요한 정보와 덜 중요한 정보가 한 데 섞여 신호 대 잡음 비율이 무너지는 것이다.

예를 들어 Express + MongoDB 서비스에서 회원가입 오류를 잡다가 다음 일이 한 스레드에 모두 섞였다고 해 보자.

DTO 검증 수정
Mongo 인덱스 재점검
테스트 실패 원인 분석
README 업데이트
Docker 설정 질문
배포 에러 상담

이쯤 되면 세션은 마치 책상 위에 버그 리포트, 영수증, 커피 쿠폰, 회의 메모가 한꺼번에 쌓인 상태와 비슷하다. 공간이 부족한 것도 문제지만, 더 큰 문제는 찾기가 어려워진다는 점이다. Codex도 비슷하다. 긴 세션에서 성능이 떨어지는 이유는 많이 담겨서라기보다, 섞이면 안 될 것이 섞였기 때문이다.

그래서 바이브 코딩의 실력 차이는 "어떤 프롬프트를 썼는가"보다 "무엇을 같은 스레드에 넣고 무엇을 분리했는가"에서 크게 벌어진다.

diff 기반 망각은 나쁜 일이 아니라 건강한 일이다

사람들은 AI가 잊는 것을 단점으로만 생각한다. 그런데 오래 쓰는 도구에게는 잘 잊는 능력도 품질이다. Codex의 메모리 시스템은 세션에서 추출한 내용을 통합하면서, 더 이상 유효하지 않거나 선택에서 밀려난 근거를 정리하는 흐름을 갖고 있다. 이 과정을 설명할 때 자주 나오는 표현이 diff 기반 망각이다.³

쉽게 말하면 이렇다. 메모리 시스템은 이전에 반영된 근거와 새로 들어온 근거를 비교하면서, 지금도 살아 있어야 할 것과 밀려나야 할 것을 구분한다. 어떤 항목은 새로 추가되고, 어떤 항목은 유지되고, 어떤 항목은 제거된다. 즉, 메모리가 무한정 덧붙기만 하는 구조가 아니라는 뜻이다.³

이게 왜 중요할까. 예를 들어 슈퍼앱 클론 프로젝트에서 알림 시스템을 처음엔 폴링 방식으로 구현했다가, 나중에 WebSocket 기반으로 바꿨다고 해 보자. 메모리가 예전 결정만 붙잡고 있으면 이후 작업마다 자꾸 폴링 전제를 들고 나온다. 하지만 사용 빈도와 최신 근거를 바탕으로 정리하는 구조가 있으면, 오래된 사실은 점점 뒤로 밀리고 최신 관찰이 앞에 남는다.¹³

재미있게 말하면, 이건 Codex가 멍청해서 잊는 게 아니라 계속 일하려면 치워야 해서 잊는 것이다. 서랍정리를 안 하는 사람보다, 계절 바뀔 때 옷 갈아입는 사람이 더 유능한 것과 비슷하다.

메모리와 AGENTS.md를 헷갈리면 품질이 무너진다

이 지점은 꼭 분리해서 기억해 두자.

역할	무엇을 담아야 하나	예시
AGENTS.md	팀이 강제해야 하는 규칙	`pnpm`만 사용, `generated/` 수정 금지
메모리	반복해서 도움이 되는 개인적·실전적 회상	이 레포에선 인증 리다이렉트 루프가 자주 남
세션 컨텍스트	지금 문제를 푸는 데만 필요한 흔적	현재 에러 로그, 이번 테스트 결과

이 표를 머리에 넣어두면, 어떤 내용이 어디에 가야 할지 훨씬 빨라진다.

많은 초보자가 하는 실수는 "한 번 유용했던 것"을 전부 기억시키려는 것이다. 하지만 기억이 늘수록 회상 품질이 자동으로 좋아지는 건 아니다. 오히려 잘못 저장된 기억 하나가 좋은 프롬프트 열 개를 망칠 때도 있다.

특히 한국 개발자 실무에서는 이런 구분이 중요하다. 예를 들어 Windows PowerShell 인코딩 이슈, 한글 깨짐 회피 명령, 사내 프록시 설정처럼 자주 재현되는 환경 함정은 메모리 후보가 될 수 있다. 반면 "이번 세션에서만 임시로 UTF-8 강제 옵션을 켰다"는 사실은 세션 메모 수준에서 끝나는 편이 낫다.

`/compact`는 기억을 늘리는 기능이 아니라 잡음을 줄이는 기능이다

이전 장에서 /compact의 기본 사용법을 봤다면, 여기서는 한 단계 더 실무적으로 봐야 한다. /compact는 대화를 예쁘게 요약하는 버튼이 아니다. 핵심은 현재 세션의 문맥을 다시 압축해서, 중요한 것만 남기고 다음 턴의 품질을 살리는 것이다.⁴⁵

중요한 오해 하나를 먼저 없애자. /compact를 눌렀다고 해서 모든 세부 맥락이 완벽히 보존되는 것은 아니다. 압축이기 때문에 덜 중요한 중간 흔적은 사라질 수 있다. 그러므로 /compact는 늦게 쓰는 것보다 제때 쓰는 것이 중요하다.

실전에서 타이밍은 대개 이 네 순간이다.

원인 분석이 끝나고 구현 단계로 넘어갈 때
하나의 대안이 탈락하고 방향이 확정됐을 때
로그와 diff가 너무 많아져 답변이 흐려질 때
다른 주제로 넘어가기 전에 현재 작업을 정리하고 싶을 때

예를 들어 Next.js + Supabase 로그인 리팩터링을 하다가 "미들웨어에서 처리할지, 서버 액션에서 처리할지" 논쟁을 끝냈다면, 그다음 구현으로 넘어가기 전 /compact를 한 번 쓰는 편이 좋다. 앞선 공방은 길어도, 구현 단계에 진짜 필요한 것은 보통 아래 셋뿐이다.

최종 결정
금지사항
남은 작업

그래서 /compact 직전에 가장 실전적인 한 줄은 이거다.

"압축 전에 결정사항, 금지사항, 남은 작업만 10줄 안으로 정리해줘."

이 한 줄이 있고 없고의 차이가 크다. 마치 이사 전에 버릴 물건과 챙길 물건을 먼저 나누는 것과 같다.

"한 스레드 한 문제" 원칙이 생각보다 강력하다

긴 작업에서 품질을 지키는 가장 단순하고 강력한 원칙은 의외로 화려하지 않다. 그냥 한 스레드에 하나의 문제만 넣는 것이다.

왜 이게 중요할까. 같은 레포 안에서도 문제의 종류가 다르면 필요한 문맥이 다르기 때문이다. 인증 리팩터링에 필요한 문맥과, 배포 에러 조사에 필요한 문맥은 거의 다른 세계다. 둘을 한 스레드에 넣는 순간 Codex는 어느 문제를 중심으로 읽어야 할지 애매해진다.

예를 들어 이런 식은 좋지 않다.

"로그인 리다이렉트 버그도 고치고, 그 김에 알림 배지도 손보고, 배포 전에 README도 업데이트해줘."

사람이 보기에도 욕심 많은 요청이고, Codex에게는 더 그렇다. 반대로 아래처럼 나누면 훨씬 낫다.

스레드 A: 로그인 리다이렉트 루프 원인 분석과 수정
스레드 B: 알림 배지 숫자 계산 로직 정리
스레드 C: 문서 업데이트와 릴리즈 노트 정리

이 원칙을 지키면 /compact의 품질도 좋아지고, resume으로 이어 붙일 때도 덜 헷갈린다. 한마디로 스레드가 작업 단위가 된다.

`/fork`는 대안 생성기보다 문맥 분리기로 써야 한다

많은 사람이 /fork를 "다른 방법도 한 번 해보는 기능" 정도로 이해한다. 물론 맞는 말이다. 하지만 긴 작업에서 /fork의 진짜 가치는 실험 그 자체보다 메인 문맥을 깨끗하게 지키는 것에 있다.⁴

가령 Express + MongoDB API에서 에러 처리 방식을 손보는 상황을 생각해 보자. 지금 선택지는 두 가지다. 기존 미들웨어를 유지하면서 최소 수정으로 가는 보수안, 공통 핸들러 구조를 크게 정리하는 개편안이다. 이 둘을 한 스레드 안에서 왔다 갔다 하면 대화는 금세 뒤죽박죽이 된다.

이럴 때 메인 스레드에는 문제 정의와 선택 기준만 남겨 두고, /fork로 두 갈래를 분리한다. 그러면 얻는 이점이 크다.

메인 스레드는 의사결정 기록으로 남는다.
각 포크는 하나의 가설만 밀고 갈 수 있다.
실패한 실험이 메인 문맥을 더럽히지 않는다.

Git 브랜치가 코드를 분리한다면, /fork는 생각의 잔가지를 분리한다고 보면 된다. 이 감각을 익히면, Codex와 오래 일할수록 대화가 덜 지저분해진다.

프로젝트 분리는 생각보다 더 엄격해야 한다

Codex를 여러 레포에서 오가며 쓰다 보면 생기는 대표적인 문제가 있다. 프로젝트 A에서 잘 맞았던 습관이나 맥락이 프로젝트 B에까지 은근히 번지는 것이다. 실제 사용자들도 전역 메모리만으로는 프로젝트 간 오염이 생길 수 있고, 더 명시적인 스코프 관리가 필요하다고 꾸준히 요청해 왔다.⁶

이 문제는 특히 한국 개발자에게 더 현실적이다. 낮에는 회사 레거시 Spring API를 보고, 밤에는 Next.js + Supabase 사이드 프로젝트를 만들고, 주말에는 오픈소스 Express 패키지를 손보는 식으로 작업하는 경우가 많기 때문이다. 이 세 프로젝트는 코드 스타일도, 테스트 문화도, 금지사항도 다르다. 그런데 머릿속뿐 아니라 Codex의 회상 층까지 섞이면 품질이 흔들린다.

그래서 실전 원칙은 명확하다.

다른 레포는 다른 세션으로 시작한다.
항상 레포 루트에서 시작해 현재 작업 범위를 명확히 한다.
팀 규칙은 메모리가 아니라 AGENTS.md에 둔다.
완전히 다른 프로젝트로 넘어갈 땐 메모리 정리를 고려한다.

특히 monorepo에서는 "같은 레포니까 같은 문맥"이라고 착각하기 쉽다. 하지만 apps/web와 services/payments는 같은 집 주소를 쓰는 다른 사람일 수 있다. 이럴수록 디렉터리별 AGENTS.md, 필요한 경우 /fork, 그리고 작업 단위 분리가 더 중요해진다.

`codex debug clear-memories`는 망했을 때 쓰는 명령이 아니라, 전환할 때 쓰는 명령이다

메모리 오염이 의심될 때 가장 극적인 정리 방법은 codex debug clear-memories다. 이 명령은 메모리 아티팩트와 상태를 비워서, 사실상 새 출발에 가깝게 만들어 준다.³

많은 사람이 이 명령을 "뭔가 완전히 꼬였을 때만 쓰는 비상탈출 버튼"처럼 여긴다. 물론 그럴 때도 유용하다. 하지만 더 좋은 사용법은 작업 세계가 완전히 바뀔 때 선제적으로 쓰는 것이다.

예를 들어 아래 상황에서는 꽤 합리적이다.

회사 모노레포 작업을 며칠 하다가, 전혀 다른 개인 프로젝트로 넘어갈 때
잘못된 기억이 반복 회상돼 계속 엉뚱한 제안을 할 때
특정 프로젝트 관련 메모리를 더 이상 유지할 가치가 없을 때
데모용 환경과 실서비스 환경을 번갈아 쓰며 오염이 누적됐을 때

물론 무조건 자주 지우라는 뜻은 아니다. 메모리는 반복 설명을 줄여주는 자산이기도 하다. 다만 좋은 개발자가 Git 브랜치를 정리하듯, 좋은 바이브 코더는 메모리도 필요할 때 비운다.

1M 컨텍스트가 필요한 순간은 생각보다 드물다

긴 컨텍스트 이야기를 하면 다들 설렌다. 마치 더 큰 서랍을 얻은 느낌이기 때문이다. 실제로 Codex는 지원되는 구성에서 long-context 모드로 약 1M 수준의 큰 컨텍스트 창을 활용할 수 있다.⁷ 하지만 여기서 중요한 진실이 하나 있다.

큰 컨텍스트는 더 많은 문제를 동시에 풀라는 뜻이 아니다.

오히려 일상 작업 대부분은 1M가 필요 없다. 버튼 하나 깨진 UI 수정, 테스트 하나 고치기, Express 라우트 하나의 검증 로직 추가 같은 일은 큰 컨텍스트보다 깨끗한 스레드가 더 중요하다.

1M 컨텍스트가 진짜 빛나는 순간은 보통 이런 때다.

상황	왜 큰 컨텍스트가 유리한가
대형 모노레포 구조 파악	여러 패키지, 규칙, 호출 흐름을 한 번에 본다
인증·권한 리팩터링	미들웨어, 서버 액션, DB 정책, 테스트를 함께 엮어야 한다
대규모 인시던트 조사	로그, 관련 diff, 설정 파일, 최근 변경 이력을 같이 읽어야 한다
코드베이스 고고학	누가 왜 이렇게 짰는지 오래된 흔적까지 따라가야 한다

반대로 아래는 큰 창보다 작은 방 정리가 더 중요하다.

CSS 정렬 깨짐
단일 API 버그 수정
테스트 하나 추가
간단한 문구 변경

비유하면 이렇다. 1M 컨텍스트는 큰 창고지, 자동 정리 로봇이 아니다. 창고가 넓다고 바닥에 아무거나 던져 놓으면 찾기 더 어려워진다.

긴 컨텍스트보다 먼저 챙겨야 할 것은 컨텍스트 밀도다

실무에서 더 많이 먹히는 질문은 "얼마나 많이 넣을까?"보다 "무엇만 남길까?"다. 이를 컨텍스트 밀도라고 생각하면 쉽다.

좋은 밀도는 보통 이런 모습이다.

현재 목표가 한 문장으로 말해진다.
변경 가능한 범위가 잠겨 있다.
이미 시도한 것과 실패한 것이 짧게 정리돼 있다.
금지사항이 분명하다.
다음 행동이 하나 또는 둘로 좁혀져 있다.

이 밀도를 만들기 위해 필요한 도구가 바로 AGENTS.md, /compact, /fork, 새 세션 시작, 그리고 필요할 때의 메모리 정리다. 결국 컨텍스트 운영은 새로운 기능을 외우는 일이 아니라, 잡음을 구조적으로 줄이는 습관이다.

실전 패턴 1: Next.js + Supabase 인증 리팩터링

이제 실제로 어떻게 운영하는지 감을 잡아보자.

상황은 이렇다. 로그인 후 대시보드로 가야 하는데, 특정 조건에서 홈으로 튕긴다. 문제는 인증, 미들웨어, 서버 액션, 쿠키, 라우팅이 다 얽혀 있다.

이럴 때 좋은 흐름은 보통 다음과 같다.

먼저 한 스레드에서 원인 분석만 한다.
가능한 원인을 둘셋으로 좁힌다.
방향이 갈리면 /fork로 미들웨어 중심안과 서버 액션 중심안을 분기한다.
결론이 나면 메인 스레드로 돌아와 선택 기준만 남긴다.
구현 직전에 /compact로 결정사항과 금지사항만 압축한다.

이 패턴의 핵심은 "분석 스레드"와 "구현 스레드"의 문맥을 과하게 섞지 않는 것이다. 분석 단계의 긴 논쟁은 구현 단계에선 대부분 잡음이 된다. 반대로 구현 단계의 세부 diff는 나중에 아키텍처 판단을 다시 볼 때 중요하지 않을 수 있다.

실전 패턴 2: Express + MongoDB 장애 대응

장애 대응에서는 특히 문맥 오염이 치명적이다. 이유는 단순하다. 조급하기 때문이다. 조급하면 한 스레드에서 원인 분석, 핫픽스, 롤백 고민, 문서 수정까지 다 해버리게 된다.

더 안전한 패턴은 이렇다.

처음엔 read-only에 가깝게 원인만 좁힌다. 로그와 재현 경로를 확인하고, 어디까지가 사실이고 어디부터가 추정인지 나눈다. 핫픽스 경로와 구조 수정 경로가 동시에 보이면 /fork로 갈라 놓는다. 그리고 실제 수정으로 들어가기 직전 /compact를 걸어 "지금 당장 서비스 복구에 필요한 사실"만 남긴다.

장애 상황에서 /compact가 좋은 이유는 감정적인 대화를 잘라내 주기 때문이다. 새벽 장애 대응 세션에는 사람이 봐도 쓸모없는 말이 많이 쌓인다. "이상하네", "왜 또 이러지", "아까는 됐는데" 같은 흔적이다. 그런 대화는 사람에겐 위로가 될 수 있어도, Codex에겐 거의 쓰레기 데이터다.

실전 패턴 3: 슈퍼앱 클론 같은 대형 프로젝트

슈퍼앱 클론처럼 기능이 많은 프로젝트에선 "한 기능 한 스레드" 원칙이 거의 생존 규칙이다. 알림, 결제, 채팅, 지도, 프로필을 한 세션에서 계속 오가면 어느 순간 Codex도 사람도 둘 다 지친다.

이럴 때는 기능별로 스레드를 명확히 나누고, 기능 내부에서도 단계별로 나누는 편이 좋다.

기획 스레드
구현 스레드
테스트 스레드
리뷰 스레드

처음엔 이게 번거롭게 느껴질 수 있다. 하지만 며칠만 지나면 반대로 느껴진다. 안 나누면 어디서 무슨 결정을 했는지 찾느라 더 오래 걸린다. 특히 resume으로 다음 날 이어 붙일 때 이 차이가 크다. 잘 나뉜 스레드는 다시 열었을 때 바로 맥락이 떠오르고, 섞인 스레드는 다시 읽어도 머리가 복잡하다.

외부 메모리 레이어는 언제 필요할까

기본 내장 메모리만으로도 많은 작업이 편해진다. 하지만 프로젝트가 길어지고, 여러 에이전트나 여러 도구를 함께 쓰기 시작하면 "검색 가능한 장기 기억"이 아쉬워지는 순간이 온다. 실제로 Codex 생태계에는 MCP 기반의 외부 메모리 서버와 확장 도구들이 등장하고 있다.¹⁸

다만 여기서도 순서를 바꾸면 안 된다. 기본 내장 메모리와 AGENTS.md 운영이 먼저다. 외부 메모리 레이어는 그다음이다. 방 정리도 안 된 집에 창고부터 늘리는 것과 비슷한 실수를 하지 말자는 뜻이다.

그리고 또 하나. ChatGPT와 Codex 사이의 기억 공유나, 여러 에이전트 간의 자연스러운 공용 기억은 여전히 사용자가 많이 원하는 영역이다. 관련 요구도 공개 이슈에서 계속 보인다.⁹ 즉, "도구가 알아서 다 이어주겠지"라고 기대하기보다, 지금은 인수인계 구조를 설계하는 쪽이 더 현실적이다.