어제 고친 버그를 오늘 또 만드는 AI — 컨텍스트 엔지니어링

AI 페어 프로그래밍

어제 고친 버그를 오늘 또 만드는 AI

기억이 리셋되는 천재 동료와 일하는 법 (컨텍스트 엔지니어링)

핵심 요약

• AI는 매일 아침 기억이 리셋되는 뛰어난 동료와 같다 — 어제 함께 알아낸 걸 오늘은 하나도 기억하지 못한다(구조적 한계).
• 하필 무는 건 코드만 봐선 모르는 비자명한 함정이라, "다음엔 코드를 다시 읽으면 되지"가 안 통한다 — 그 지식은 코드 안에 없다.
• 그래서 내가 그 동료의 외장 기억이 되어준다 — 비자명한 함정을 풀 때마다 한 줄 적고, 그 파일을 모든 새 세션에 자동 주입.
• 이게 컨텍스트 엔지니어링이다. "항상 로드"와 "조건부 로드"를 나눠 노이즈를 관리하는 것까지가 기술이다.

1.매일 아침 기억을 잃는 천재 동료

뛰어난 동료가 한 명 있다고 하자. 코드는 기막히게 짠다. 그런데 매일 아침 출근하면 어제 일을 하나도 기억하지 못한다 — 어제 둘이 한참 헤매다 고친 버그도, 심지어 그걸 고쳤다는 사실조차. 매번 처음부터 다시 설명해야 한다.

LLM이 정확히 그렇다. 어제 대화에서 알아낸 걸 오늘 새 대화는 하나도 모른다. 비슷한 버그가 아니라 똑같은 버그를 다시 만든다 — 같이 고쳤다는 사실 자체가 사라졌으니까.

새 세션은 매번 0에서 시작한다. 이건 버그가 아니라 구조다. LLM은 대화와 대화 사이에 아무것도 들고 가지 않는다. 그래서 "기억해 둬"라고 부탁하는 건 소용없고, 다른 방법이 필요하다.

2.하필 무는 건 비자명한 함정

그리고 하필 우리를 무는 건 그 비자명한 함정들이다 — 코드를 아무리 들여다봐도 안 보이는 것들.

• 어떤 로깅 라이브러리는 출력이 테스트 캡처에 안 잡힌다(다른 경로로 새서). 코드는 멀쩡해 보인다.
• 어떤 CSS 프레임워크의 특정 버전에선, 흔히 쓰는 색상 표기 패턴이 조용히 무효가 된다.
• DB 마이그레이션 도구의 식별자가 길이 한도를 넘으면, "새로 만든 DB"에서만 부팅이 깨진다(기존 DB는 멀쩡해서 로컬에선 안 잡힘).

공통점이 있다. 코드를 다시 읽어도 안 보인다. 한 번 데어 봐야만 아는 것들이다. 그러니 "다음 세션엔 코드를 다시 읽으면 되지"가 통하지 않는다 — 이 지식은 코드 안에 없고, 코드와 현실이 부딪힌 자리에만 있다.

3."다시 설명하면 되잖아"가 안 통하는 이유

그냥 매번 다시 설명하면 되지 않냐고? 세 가지가 막는다.

• 사람이 먼저 잊는다 — 함정이 수십 개인데, 어느 게 있었는지 사람 머릿속도 휘발성이다.
• 확장이 안 된다 — 작업을 시킬 때마다 "아 그리고 이 함정, 저 함정, 그 함정…"을 매번 읊을 순 없다.
• 다른 세션·다른 사람은 모른다 — 머릿속 부족지식(tribal knowledge)은 공유도, 인수인계도 안 된다.

결론은 분명하다. 그 지식은 지속되는 곳에 있어야 하고, 동시에 알아서 불려와야 한다. 사람의 기억력에도, 모델의 휘발성 컨텍스트에도 기대면 안 된다.

4.기억을 모델이 아니라 저장소에 둔다

방법은 단순하다. 비자명한 에러를 풀 때마다, 그 자리에서 한 줄로 적는다. 모델의 휘발성 기억을 저장소(파일)로 옮기는 것이다. 함정 하나당 한 줄, 증상과 해법만.

learnings.md — 코드만 봐선 모르는 함정 (한 줄씩)Learnings

# 학습 기록
- 그 로깅 라이브러리 로그는 테스트 캡처에 안 잡힘 → 전용 캡처 API로 검증
- CSS 프레임워크 vN + 특정 색공간에서 흔한 색상 표기 무효 → 변수 직접 사용
- 마이그레이션 식별자가 32자를 넘으면 "새 DB"에서만 부팅 실패 (기존 DB는 멀쩡)
- 이벤트 봉투 키는 "data"가 표준 ("payload" 아님) — 틀리면 메시지가 조용히 사라짐

핵심은 '즉시'다. "나중에 정리"는 오지 않는다. 그래서 "해결하는 즉시 기록"을 별도의 다짐이 아니라 상시 규칙으로 박아둔다 — 커밋 전에, 결과 보고 전에.

지속 지침 파일 (도구마다 이름은 다름)Convention

# 규칙 유지
- 비자명한 에러를 해결하면 "즉시" 학습 기록에 한 줄 남긴다.
  ("나중에"는 없다. 해결 직후, 커밋 전에 적는다.)

5.적는 것만으론 죽는다 — 자동 주입이 핵심

파일에 적기만 하면 아무도 안 읽는 죽은 문서가 된다. 진짜 열쇠는 그 파일이 모든 새 세션의 컨텍스트에 자동으로 주입되는 것이다. 요즘 AI 코딩 도구 대부분은 지속 지침(persistent instructions) 파일을 지원한다 — 이름은 도구마다 달라도, 새 세션이 시작될 때 매번 읽어 들이는 파일이 있다.

그럼 어떤 파일을 어디에 두고, 파일 패턴별 자동 로드를 어떻게 거는지가 관건인데 — 설정이 제법 구체적이라 별도 글에서 단계별로 정리했다. 개념은 여기서 마무리하고, 실제 세팅은 아래 글로 잇는다.

실전 가이드

AI에게 규칙을 한 번만 가르치는 법

CLAUDE.md·AGENTS.md부터 파일 패턴별 규칙까지, 예시 그대로 따라 할 수 있게. →

세션 N 함정을 1시간 만에 해결 │ ▼ learnings.md ──▶ 한 줄로 기록 (기억을 모델 밖 = 저장소로) │ │ (지속 지침 = 모든 세션 컨텍스트에 자동 주입) ▼ 세션 N+1, N+2… 그 함정을 "이미 알고" 시작 ──▶ 재발 0

그런데 — 다 항상 주입하면 그게 또 노이즈다

여기서 한 단계 더 들어가는 게 진짜 기술이다. 모든 규칙을 "항상" 컨텍스트에 욱여넣으면, 그 자체가 노이즈가 된다 — 중요한 게 분량에 묻힌다. 그래서 "항상 로드"와 "조건부 로드"를 나눈다. 핵심 함정·컨벤션은 항상 싣고, 세부 규칙은 지금 만지는 파일 종류에 해당할 때만 불러온다.

로드 조건을 나눈다 (컨텍스트 엔지니어링)Context

항상 로드:        핵심 함정 카탈로그 · 프로젝트 컨벤션
*.py 수정 시:     파이썬 / DB 규칙
프론트 수정 시:   React / CSS 규칙
테스트 수정 시:   테스트 패턴

기억하는 주체가 바뀐다

모델에게 "기억해 둬"는 통하지 않는다. 대신 알아낸 것을 파일로 박고, 매 세션 그 파일을 (필요한 만큼만) 강제로 주입한다. 그러면 시간이 갈수록 같은 함정에 덜 빠진다 — 기억하는 주체가 모델에서 저장소로 옮겨갔기 때문이다.

6.트레이드오프 — 기록도 유지보수 대상이다

공짜는 아니다. 기록을 외부화하는 순간, 그 기록도 코드처럼 관리해야 한다.

• 비자명한 것만 적는다 — 당연한 걸 적으면 노이즈가 된다.
• 낡으면 덜어낸다 — 해결됐거나 더 안 쓰는 항목은 주기적으로 아카이브로 옮긴다.
• 오래된 기록은 현재 코드로 다시 확인 — 항목이 가리키던 파일이 옮겨졌을 수 있다. 기록은 "그때의 사진"이지 실시간 상태가 아니다.

⚠ 한 줄 규율이 곧 품질이다

"비자명한 것만, 한 줄로, 즉시" — 이 세 조건이 무너지면 학습 기록은 금세 아무도 안 읽는 위키가 된다. 적는 행위보다 적을 가치가 있는지 판단하는 것이 더 중요하다.

7.정리

LLM은 똑똑하지만 망각한다. 그 망각은 더 큰 모델로도, 더 긴 컨텍스트 창으로도 근본적으론 안 메워진다 — 세션은 언젠가 끝나고, 다음 세션은 다시 0에서 시작하니까.

메우는 건 모델이 아니라 시스템이다 — 알아낸 걸 적고, 적은 걸 (필요한 만큼) 자동으로 불러온다. 이걸 컨텍스트 엔지니어링이라 부른다. 기억상실증 천재와 오래 잘 일하는 비결은, 그가 기억해 주길 바라는 게 아니라 내가 그의 기억을 관리하는 것이다 — 더 영리한 프롬프트가 아니라.

바이브코딩 · AI와 더 잘 일하는 법