클로드코드 CLAUDE.md 쓰는 법 — AI가 같은 실수를 반복하지 않게
AI는 지난 대화를 기억하지 못해서, 2주 뒤에 같은 데서 또 실수합니다. 프로젝트에 규칙 파일(CLAUDE.md)을 하나 두고 무엇을 적는지, 실제로 쓰는 규칙 예시와 함께 정리했습니다.
AI 로 사이트를 고칠 때 같은 실수가 반복되면, 프로젝트에 규칙 파일을 하나 두고 AI 가 작업 전에 그 파일부터 읽게 하면 됩니다. Claude Code 는 프로젝트 맨 위의 CLAUDE.md 를 새 대화를 시작할 때 자동으로 읽습니다. 저는 프로젝트마다 이 파일을 두고, 문제가 한 번 생기면 거기에 한 줄을 적습니다.
왜 같은 실수가 반복되나
AI 는 지난 대화를 기억하지 못합니다. 2주 전에 “키는 서버에만 둬야 한다”고 한참 이야기하고 고쳤어도, 새로 열어서 “이거 왜 안 돼?”라고 물으면 처음 보는 코드처럼 읽기 시작합니다. 그러다 고치지 말아야 할 곳을 다시 바꾸기도 합니다.
대화는 사라져도 파일은 남습니다. 그래서 기억해야 할 것은 파일에 적어 둡니다.

CLAUDE.md 파일 위치 — Cursor·Codex 는 AGENTS.md
- Claude Code: 프로젝트 맨 위에
CLAUDE.md. 모든 프로젝트에 공통으로 쓸 규칙은 내 컴퓨터의~/.claude/CLAUDE.md - Cursor, Codex 등:
AGENTS.md를 읽는 도구가 많습니다. Cursor 는.cursor/rules폴더도 씁니다 - Lovable 같은 화면형 도구: 프로젝트 설정의 지식(Knowledge) 칸에 같은 내용을 적습니다
이름은 도구마다 달라도 하는 일은 같습니다. 작업 전에 읽는 메모입니다.
CLAUDE.md 에 무엇을 적나
길게 쓸 필요는 없습니다. 세 가지면 됩니다.
1. 절대 하면 안 되는 것
- API 키·비밀 키는 서버 환경 변수에만 둔다. 화면 코드에 넣지 않는다
- DB 보안 규칙(RLS)을 끄지 않는다. 안 되면 끄지 말고 멈춰서 물어본다
- 데이터를 지우는 작업은 하기 전에 물어본다
2. 이 프로젝트의 방식
- 배포는 main 브랜치에 합치면 자동으로 된다
- 결제는 테스트 키로 확인한 뒤에만 실제 키로 바꾼다
- 문의 폼은 메일과 시트 두 군데로 간다. 하나만 고치지 않는다
3. 지난번에 문제 됐던 것
한 번 문제가 생겼던 자리와, 그때 어떻게 고쳤는지를 한 줄씩 적습니다. 무엇을 바꾸면 어디가 같이 깨지는지 같은 것들입니다.
3번이 제일 중요합니다. 문제가 생긴 날 고치고 끝내지 말고, 한 줄 적어 두면 다음에 같은 데서 안 막힙니다.
제가 모든 프로젝트에 공통으로 두는 규칙은 이 정도입니다. 내 컴퓨터의 ~/.claude/CLAUDE.md 에 두면 어느 프로젝트를 열어도 같이 읽힙니다.

- 강제 푸시(git push --force) 하지 않는다
- 시크릿·API 키를 코드나 커밋에 넣지 않는다
- 컴퓨터 시스템 설정은 바꾸지 말고 멈춰서 물어본다
- "잘 됐을 것" 같은 추측으로 보고하지 않는다. 실제로 돌려 본 결과만 말한다
쓸 때 주의할 것
- 짧게 유지합니다. 너무 길면 중요한 줄이 묻힙니다. 한 줄에 하나씩, 명령형으로 씁니다
- 사실만 적습니다. “가능하면 깔끔하게” 같은 말은 AI 가 지키기 어렵습니다. “함수는 한 파일에 하나” 처럼 확인할 수 있게 씁니다
- 꼭 지켜지는 건 아닙니다. AI 는 이 파일을 참고로 읽을 뿐이라 가끔 놓칩니다. 지우기·배포처럼 되돌리기 어려운 건 파일에 적는 것과 별개로 직접 확인합니다
- 비밀 값은 적지 않습니다. 이 파일도 코드와 같이 저장소에 올라갑니다. 키가 어디에 있는지는 적어도 되지만 키 자체는 안 됩니다
처음 만들 때
빈 파일에서 시작하기 어려우면 AI 에게 먼저 만들게 하고 고치면 됩니다.
이 프로젝트를 읽고 CLAUDE.md 를 만들어 주세요. 배포 방법, 환경 변수가 어디에 있는지, 절대 하면 안 되는 것(키를 화면 코드에 넣기, DB 보안 규칙 끄기, 데이터 지우기)을 짧게 적고, 끝에 “지난번에 문제 됐던 것” 칸을 비워 두세요.
오픈 전에 확인할 다른 것들은 오픈 전에 확인할 12가지에 모아 두었습니다.
2026년 10월 Claude Code 문서(메모리) 기준입니다.