메모리와 AGENTS.md

메모리 memory

• 대화에서 얻은 유용한 정보를 저장해뒀다가 다음 대화에 사용하는 기술
• Codex
  • 실험적 기능으로 기본적으로 꺼져 있음
  • "설정 -> 개인 맞춤 설정"에서 켤 수 있음
  • 메모리 파일 위치: ~/.codex/memories/
• Claude
  • 기본적으로 켜져 있음
  • "설정 -> 기능" 메뉴에서 켜고 끌 수 있음
  • 메모리 파일 위치: ~/.claude/projects/<project>/memory/

크로니클 chronicle

• macOS용 Codex 앱에서 제공하는 기능
• 크로니클을 켜면 사용자 화면을 캡처
• 사용자가 무엇을 보고 있는지, 어떤 파일이나 대화, 문서, 대시보드, Pull Request를 가리키는지, 어떤 도구와 워크플로를 자주 쓰는지 파악
• 화면에 보이는 민감한 정보가 메모리 생성에 포함될 수 있음
• 마이크나 시스템 오디오에는 접근하지 않음
• 단점
  • 프롬프트 인젝션 위험: 화면의 내용을 지시로 이해할 수 있음
  • 캡처된 화면 이미지에서 메모리를 만들기 위해 백그라운드에서 샌드박스된 에이전트를 실행하므로 사용량 제한을 빠르게 소모

AGENTS.md

• 에이전트가 작업을 시작하기 전에 읽는 지침 파일
• 항상 지켜야 하는 규칙들
  • 빌드, 테스트, 린트 명령
  • 코드 리뷰에서 기대하는 기준
  • 저장소 고유의 코드 작성 규칙
  • 특정 디렉터리에만 적용되는 작업 방식
  • 반복해서 잘못 이해되는 코드베이스 맥락
• 한 번만 필요한 지시는 프롬프트에 직접, 여러 번 반복되는 지시는 AGENTS.md에 작성
• README.md는 사람을 위한 안내, AGENTS.md는 에이전트를 위한 안내

AGENTS.md의 위치

• 전역: 리뷰 스타일, 답변 길이, 기본 선호 사항처럼 개발자 개인에게 적용되는 지침
  • 위치: ~/.codex/AGENTS.md
• 저장소: 특정 프로젝트, 또는 팀이 공유하는 빌드, 테스트, 코드 작성, 리뷰 규칙
  • 위치 예시: repo/AGENTS.md
• 하위 디렉터리: 특정 모듈이나 서비스에만 적용되는 규칙
  • 위치 예시: repo/services/payments/AGENTS.md
• AGENTS.override.md 파일이 있으면 AGENTS.md는 무시
  • 임시로 지시를 변경할 때 AGENTS.md를 수정하는 대신 사용

CLAUDE.md

• Claude가 사용하는 지침 파일
• Codex와 Claude를 모두 사용하는 경우
  • AGENTS.md를 CLAUDE.md로 심볼릭 링크

ln -s AGENTS.md CLAUDE.md

• CLAUDE.md에 AGENTS.md를 참고하라는 지침을 포함할 수도 있음
  • 다른 에이전트와 클로드용 지침을 구분할 때
  • 특정 파일을 가리킬 때 @를 사용
  • AGENTS.md 이외에 다른 파일을 참고하라고 할 수도 있음

@AGENTS.md

LLM은 무관한 맥락에 쉽게 산만해진다

컨텍스트 부패 Context Rot

• 컨텍스트 길이가 증가함에 따라 모든 모델에서 성능이 일관되게 저하

Context Anxiety

• LLM이 대화나 작업 맥락이 길어질수록 "이제 맥락 창이 부족하다"고 판단해 답변 품질이 떨어지거나, 작업을 너무 빨리 마무리하려는 현상
• 주요 양상
  • 이전 지시나 중요한 제약을 놓치거나, 최근 메시지에 과도하게 끌림
  • 작업을 성급히 끝냄
  • 세부 검토, 테스트, 검증 단계를 생략함
  • 일관성이 약해짐
• 대처 방법
  • 긴 작업을 단계별로 나누어 따로 처리
  • 중요한 요구사항은 요약해서 반복 제공
  • "아직 마무리하지 말고 검토/테스트까지 수행하라"처럼 작업 절차를 지정
  • 긴 대화는 중간에 구조화된 요약을 만들고 새 세션에서 이어가기
  • 문서·코드·결정사항은 대화창이 아니라 파일이나 저장소에 남기기
  • 체크리스트로 누락 사항을 점검하게 하기

AGENTS.md 사용이 도움이 안된다는 연구

• Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?
• AGENTS.md가 없는 경우, LLM이 만든 경우, 개발자가 만든 경우를 비교
• AGENTS.md가 없는 경우에 비해 추론에 더 많은 토큰을 사용

AGENTS.md 팁

• 반복적으로 사용하는 꼭 필요한 지시만 포함
  • 에이전트가 같은 실수를 반복하는 경우
  • 에이전트가 특정 파일을 찾기 위해 너무 많은 파일을 검색할 경우, 해당 파일의 위치를 알려줌
• AGENTS.md 파일 이외에도 다른 파일들도 참고하게 할 수 있음
  • AGENTS.md에서 언급하거나 설정 파일을 수정
  • 주제별로 파일을 나누어 필요한 지시만 컨텍스트에 들어가도록
• 에이전트에게 현재 참고하고 있는 설정 파일 목록을 물어볼 수 있음

Summarize the current instructions.
Show which instruction files are active.

• 프롬프트에서 에이전트에게 AGENTS.md 파일에 추가/삭제하라고 지시할 수도 있음