AI 에이전트가 훌륭한 코드를 작성하지만, 다음 날 모든 것을 잊어버리는 문제

지난 한 주 동안 제 코딩 에이전트와 나눈 대화 세 번을 공개합니다:

나: DEV.to API에서 403 오류가 발생하고 있어.
에이전트: User-Agent 헤더를 추가해 보세요 — 기본값은 그들의 봇 필터에 의해 거부됩니다.
나: 맞아. 이건 월요일에도 알아냈고, 화요일에도 그랬지.

에이전트는 매번 정확했습니다. 하지만 매번 처음부터 시작한다는 점도 문제입니다. 월요일에 어렵게 얻어낸 교훈 — dev.to는 기본 사용자 에이전트를 차단한다 — 은 세션이 종료되는 순간 증발해 버렸습니다. 수요일의 저는 월요일의 저와 똑같은 디버깅 비용을 지불해야 했습니다.

진짜 문제가 되는 부분은

그게 전부입니다. 데이터베이스도, 벡터 스토어 (vector store)도, 임베딩 파이프라인 (embedding pipeline)도 없습니다. 그저 인간과 모델이 모두 읽을 수 있는 마크다운 (Markdown) 파일뿐입니다.

핵심 비결은 파일 그 자체가 아니라, 에이전트가 언제 파일을 참조하고 업데이트해야 하는지 알 수 있도록 지침 파일 (instructions file)에 _트리거 (triggers)_를 연결하는 것입니다. 전체 메모리 프로토콜은 CLAUDE.md에 단 네 줄로 구성됩니다:

## 프로젝트 메모리 시스템 (Project Memory System)
- 에러 발생 시 → `bugs.md`를 먼저 검색할 것
- 아키텍처 변경 제안 시 → 충돌 여부를 확인하기 위해 `decisions.md`를 확인할 것
...

이제 DEV.to 403 에러는 다시 발견해야 할 숙제가 아니라, 하나의 사실로서 bugs.md에 단 한 번 기록됩니다:

### dev.to API가 모든 요청에 대해 403 반환
**원인:** dev.to가 기본 HTTP 클라이언트 User-Agent를 거부함 (봇 필터).
**해결책:** `User-Agent: Mozilla/5.0`을 전송할 것. 모든 /api/articles 호출에 적용됨.

그리고 저를 두 번이나 낚았던 함정 — 동일 인물이지만 사용자 이름이 두 개인 문제 — 은 key_facts.md에 저장되어 있습니다:

## 사용자 이름 (Usernames)
- GitHub:  enjoykumawat      (언더스코어 없음)
- DEV.to:  enjoy_kumawat     (언더스코어 있음)

다음에 에이전트가 사용자 이름을 찾을 때, 추측하여 절반만 맞히는 대신 이 사실을 읽게 됩니다.

실제로 작동하게 만드는 규칙: 완료 시 기록하기 (write-on-completion)

읽는 것은 쉽습니다. 진짜 규율은 _쓰는 것_에 있습니다. 지식이 다시 흘러 들어올 때만 메모리 시스템은 복리 효과를 냅니다. 따라서 가장 중요한 단 하나의 프로토콜은 마지막 것입니다: 작업 단위(chunk)를 마칠 때, 그것을 기록하십시오. 저의 issues.md는 추가 전용(append-only)이며, 최신 항목이 가장 위에 옵니다:

### 2026-06-23 - DEV.to 퍼블리셔 + 403 수정
- 상태: 완료됨
- 재사용 가능한 stdlib 퍼블리셔 구축. 근본 원인은
...

이 기록 하나 덕분에 미래의 저(그리고 미래의 에이전트)는 _결과와 그 이유_를 거저 얻게 됩니다. 작업 로그(work log)는 "노트가 있다"와 "메모리가 있다"의 차이를 만듭니다.

실제 적용 시 변화된 점

• 더 이상의 재디버깅(re-debugging)은 없습니다. 해결된 문제는 해결된 상태로 유지됩니다. 403번의 대화가 네 번째 반복되는 일은 발생하지 않습니다.
• 결정이 유지됩니다. 무언가를 다시 설계(re-architect)하고 싶은 유혹이 들 때, decisions.md는 왜 그렇게 설계되었는지를 상기시켜 줍니다. 대개는 이미 그 "더 나은" 아이디어를 시도해 보았고, 그것이 실패했기 때문입니다.
• 온보딩(onboarding) 비용이 거의 제로에 가깝게 떨어졌습니다. 새로운 세션이 네 개의 짧은 파일을 읽으면, 저만큼이나 상황을 파악하게 됩니다.

작게 유지하지 않으면 부패합니다

어렵게 배운, 피해야 할 두 가지 실패 모드(failure modes)가 있습니다:

1. 코드나 git이 이미 말해주고 있는 내용은 기록하지 마세요. "x를 y로 이름을 변경함"은 diff(차이점)에 나타나 있습니다. 메모리는 _명확하지 않은 것_들을 위한 것입니다. 즉, 이유(why), 막다른 길(dead end), 주의사항(gotcha) 같은 것들입니다. git이 답할 수 있는 것이라면 기록하지 마세요.
2. 잘못된 사실은 즉시 제거하세요. 오래된 사실은 사실이 없는 것보다 더 나쁩니다. 에이전트가 그것을 신뢰하기 때문입니다. decisions.md가 더 이상 현실을 반영하지 않는다면, 해결책은 내용을 추가하는 것이 아니라 _삭제_하는 것입니다.

이 전체 시스템은 4개의 마크다운(markdown) 파일과 4줄의 프로토콜(protocol)로 이루어져 있습니다. 프레임워크는 없습니다. 통찰은 기술적인 것이 아닙니다. 에이전트의 메모리는 에이전트의 _외부_에, 즉 세션이 종료되어도 살아남는 산출물(artifacts) 속에 존재해야 하며, 그것들을 언제 읽고 쓸지에 대한 명시적인 규칙이 있어야 한다는 점입니다.

당신의 에이전트에게 필요한 것은 더 큰 컨텍스트 윈도우(context window)가 아닙니다. 무언가를 적어둘 장소, 그리고 그것을 다시 읽어들이는 습관이 필요할 뿐입니다.