에이전트 메모리 파일 (CLAUDE.md · AGENTS.md)

에이전트 메모리 파일은 AI에게 주는 사내 온보딩 문서입니다. 새 직원이 올 때마다 "우리 팀은 이 도구를 쓰고, 화면 스타일은 이렇게 맞추고, 설명은 한국어로 쓴다"를 말로 반복하지 않고 문서 하나를 건네주는 것과 같아요.

파일 이름은 도구마다 다릅니다. Claude Code는 CLAUDE.md, 여러 도구가 함께 채택한 이름으로 AGENTS.md가 있고, 도구에 따라 둘 다 읽기도 합니다. 형식은 그냥 마크다운이라 특별한 문법이 없어요.

없으면 뭐가 불편한가요?#

같은 지적을 반복하게 됩니다. 이게 바이브코딩에서 가장 흔한 소모예요.

[메모리 파일 없음]
  새 대화 → AI가 설명을 영어로 씀 → "한국어로 써줘" → 수정
  새 대화 → AI가 설명을 영어로 씀 → "한국어로 써줘" → 수정   (무한 반복)
 
[메모리 파일 있음]
  새 대화 → 파일 자동 로드 → 처음부터 한국어

대화 안에서 고쳐주는 건 그 대화에서만 유효합니다. 대화를 비우면 같이 사라져요. 파일에 적어야 다음 대화로 넘어갑니다.

뭘 적어야 하나요?#

코드를 읽으면 알 수 있는 건 적지 마세요. 파일 구조나 함수 목록은 AI가 직접 보면 됩니다. 적어야 할 건 코드에 안 드러나는 것들이에요.

어떻게 만드나요?#

대부분의 도구에 초기화 커맨드가 있습니다. 프로젝트를 훑어서 초안을 만들어줘요. 클로드 코드는 /init 이고, 만든 뒤에는 /memory 로 열어서 고칩니다.

그다음부터는 일하다가 같은 지적을 두 번 하게 되는 순간 한 줄씩 추가하는 게 가장 현실적인 관리법입니다.

AI에게 시키기#

이 프로젝트의 에이전트 메모리 파일을 만들어줘.
 
- 내가 쓰는 도구가 어떤 파일 이름을 읽는지 공식 문서로 먼저 확인해
- 코드를 읽으면 알 수 있는 내용(폴더 구조, 함수 목록)은 넣지 마
- 대신 실행 명령, 배포 방식, 건드리면 안 되는 영역, 지켜야 할 규칙 위주로
- 확신이 안 서는 항목은 넣지 말고 나한테 물어봐
- 전체 40줄을 넘기지 마

줄 수 제한을 안 걸면 백과사전이 나옵니다.

혼동 주의#

• README와 다릅니다. README는 사람이 읽는 문서라 소개·설치법·스크린샷이 들어가요. 메모리 파일은 AI가 매번 읽는 지시서라 "하지 마라"가 중심입니다. 같이 쓰되 내용을 복붙하진 마세요
• 비밀값을 적는 곳이 아닙니다. API 키나 비밀번호는 절대 넣지 마세요 — 이 파일은 보통 팀 전체에 공유되고, AI가 읽어서 대화에 그대로 옮길 수도 있습니다. 그건 환경변수의 자리예요
• 팀 규칙과 개인 취향을 섞지 마세요. 같이 공유되는 파일이라 "나는 이 방식이 편하다"까지 넣으면 팀원 전부에게 적용됩니다. 도구들은 보통 나 혼자만 쓰는 파일 위치를 따로 두고 있어요
• 적었다고 100% 지켜지는 건 아닙니다. 강한 힌트일 뿐 강제 규칙이 아니에요. 반드시 막아야 하는 건 문서가 아니라 도구 설정으로 막아야 합니다