AGENT_LEARNINGS.md를 활용한 AI 에이전트 자가 개선 및 외부 메모리 스캐폴딩 기법
모델 재학습 없이 Claude 등 AI 코딩 에이전트가 실수와 개선 패턴을 스스로 기록하고 작업 전 참조하는 '외부 메모리 스캐폴딩(AGENT_LEARNINGS.md)' 실전 팁과 파일 비대화 방지 노하우.
Anthropic 내부 엔지니어들이 Claude 기반 AI 코딩 에이전트를 운용할 때 활용하는 것으로 알려진 실전 팁이 테크 크리에이터 Swadesh Kumar(@swadeshkumar_)를 통해 공유되었습니다. 모델을 재학습하거나 파인튜닝할 필요 없이, 단일 마크다운 파일에 실수와 해결책을 기록해 에이전트가 시간이 지날수록 스스로 더 똑똑해지도록 유도하는 '외부 메모리 스캐폴딩(External Memory Scaffolding)' 기법입니다.
이미지 출처: @swadeshkumar_ / X
소프트웨어 엔지니어링 환경에서 AI 에이전트가 복잡한 작업을 수행하다 보면 동일한 유형의 빌드 실패, 잘못된 API 사용, 프로젝트 컨벤션 위반을 반복하는 문제가 빈번하게 발생합니다. 세션이 리셋될 때마다 이전 대화의 맥락이 소실되기 때문입니다. 이번에 공개된 패턴은 이를 파일 기반 외부 메모리로 간단하게 해결합니다.
외부 메모리 스캐폴딩: AGENT_LEARNINGS.md의 핵심 구조
외부 메모리 스캐폴딩의 핵심은 프로젝트 루트에 AGENT_LEARNINGS.md라는 전용 파일을 두고, 에이전트가 스스로 이를 지속적으로 갱신하고 참조하도록 워크플로우를 구성하는 것입니다.
에이전트는 작업 중 실수나 오류를 마주할 때마다 다음 세 가지 필수 요소를 해당 파일에 기록합니다:
- 발생한 실수 (Mistakes it made): 빌드 오류, 잘못된 매개변수 전달, 환경 제약 위반 등 실패한 구체적 상황
- 피해야 할 패턴 (Patterns to avoid): 동일한 실수를 유발하는 코드 패턴이나 잘못된 가정
- 개선된 접근법 (Better approaches): 문제를 올바르게 해결한 대안, 검증된 명령어나 안전한 구현 방식
에이전트는 새로운 작업이나 세션을 시작하기 전, 프롬프트 규칙에 따라 가장 먼저 AGENT_LEARNINGS.md를 읽어 과거의 실패와 성공 사례를 컨텍스트에 적재합니다. 이를 통해 모델 자체의 가중치를 수정하지 않고도 세션이 거듭될수록 프로젝트 맞춤형 학습 효과를 얻을 수 있습니다.
커뮤니티 검증과 주의사항: 파일 비대화 방지와 린트·테스트 승격
Swadesh Kumar의 팁 공유 이후, 엔지니어 Ian Finlay(@ian_finlay)는 실무 프로젝트 적용 시 반드시 짚고 넘어가야 할 핵심 한계와 관리 방안을 제기했습니다:
"The ones that repeat should graduate to lint rules or tests. otherwise the file just grows forever" (반복적으로 발생하는 실수는 린트(lint) 규칙이나 자동화 테스트로 승격시켜야 하며, 그렇지 않으면 파일이 무한정 비대해집니다)
마크다운 파일에 모든 실수를 무제한으로 누적할 경우 발생하는 문제는 명확합니다:
- 컨텍스트 윈도우 잠식: 파일 크기가 커질수록 작업 시작 시 불필요한 토큰 소비가 급증하고, 실제 코딩 작업에 사용할 수 있는 유효 컨텍스트가 축소됩니다.
- 주의 분산(Attention Dilution): 수십 페이지 분량의 반성 로그가 쌓이면 모델이 당면 과제와 관련된 핵심 교훈에 집중하기 어려워집니다.
따라서 실전 운영에서는 지속적으로 반복되는 안티패턴을 감지했을 때, 이를 텍스트 파일에 머무르게 두지 않고 정적 분석 린트 규칙(ESLint, Ruff 등)이나 자동화된 단위 테스트(Test Case)로 승격(Graduate)시켜 기계적인 가드레일로 고정하는 것이 권장됩니다. 이와 함께 정기적으로 해결된 항목을 정리하는 메모리 가지치기(Pruning)가 병행되어야 합니다.
Anthropic 공식 컨텍스트 관리 및 메모리 도구 아키텍처와의 연계
이러한 패턴은 최근 Anthropic이 Claude 개발자 플랫폼(Claude Developer Platform)에 도입한 공식 컨텍스트 관리(Context Management) 및 메모리 도구(Memory Tool) 전략과도 일치합니다.
Anthropic은 에이전트가 오래 실행될 때 컨텍스트 한계에 부딪히는 문제를 해결하기 위해, 오래된 도구 실행 결과를 컨텍스트에서 자동으로 정리하는 '컨텍스트 편집(Context Editing)'과 외부 파일 시스템에 세션 간 지식을 보존하는 '메모리 도구'를 제공하고 있습니다. 이를 통해 Claude는 파일 기반 메모리 디렉토리를 구축하고 장기 실행 작업 전반에서 컨텍스트를 효율적으로 유지할 수 있습니다.
개인 개발자나 소규모 팀이라도 AGENT_LEARNINGS.md와 같은 단일 파일 스캐폴딩을 에이전트 시스템 지침에 추가하면, 복잡한 인프라 없이도 즉시 에이전트의 자기 교정 역량을 극대화할 수 있습니다.