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

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

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

없으면 무엇이 불편한가요

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

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

[메모리 파일 있음]
  새 대화 → 파일 자동 로드 → 처음부터 한국어

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

무엇을 적어야 하나요

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

어떻게 만드나요

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

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

AI에게 시키기

이 프로젝트의 에이전트 메모리 파일을 만들어줘.

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

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

혼동 주의

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