AI가 우리 프로젝트 규칙을 자꾸 까먹는다면 — 규칙 파일 하나면 끝

"들여쓰기는 2칸이고, 테스트는 vitest 쓰고, 데이터 조회는 이 래퍼로만…" AI한테 코드를 시킬 때마다 우리 프로젝트 규칙을 처음부터 다시 설명하고 있진 않나요? 새 대화를 열 때마다 반복되는 이 피로, 규칙 파일 하나로 끝낼 수 있어요.

CLAUDE.md 규칙 파일이 뭐예요?

프로젝트 루트에 두는 마크다운 파일이에요. AI 코딩 도구가 작업을 시작할 때 이 파일을 자동으로 먼저 읽어서, 우리 프로젝트의 스택·구조·취향을 미리 알고 들어와요. 한 번 적어두면 매 대화마다 다시 물려주지 않아도 됩니다.

도구마다 읽는 파일 이름이 달라요.

여러 도구를 섞어 쓴다면 AGENTS.md 하나만 만들어도 돼요. Codex·Cursor·Copilot·Gemini CLI·Aider 등이 공통으로 읽는 열린 표준이라, 팀원이 어떤 도구를 쓰든 같은 규칙이 걸립니다. (Cursor는 예전 .cursorrules 단일 파일을 접고 .cursor/rules 폴더 방식으로 바뀌었어요.)

CLAUDE.md 작성법 — 이렇게 적으면 돼요

거창할 필요 없어요. 우리 프로젝트에서 AI가 자꾸 틀리는 것만 적으면 됩니다.

# 프로젝트 규칙
 
## 기술 스택
# ↑ 뭘 쓰는지 한 줄로. AI가 엉뚱한 라이브러리 꺼내는 걸 막아요
- Next.js 14 App Router, TypeScript, Tailwind
 
## 코드 스타일
# ↑ 매번 지적하던 취향을 여기 박아두면 다시 안 틀려요
- 들여쓰기 2칸, 세미콜론 없음
- 데이터 조회는 반드시 src/lib/db.ts 래퍼로만
 
## 테스트
# ↑ "테스트도 짜줘" 할 때 우리 방식대로 나오게
- vitest 사용, 파일명은 *.test.ts
 
## 하지 말 것
# ↑ 금지 목록이 의외로 제일 강력해요
- .env 파일 수정 금지
- 새 의존성 추가 전에는 먼저 물어볼 것

핵심은 짧게, 우리 프로젝트 고유한 것만이에요. "좋은 코드를 짜라" 같은 뻔한 말은 토큰만 먹고 효과가 없어요. 반대로 "우리는 date-fns 말고 dayjs 써요" 같은 한 줄이 반복 실수를 확 줄여줍니다.

CLAUDE.md·AGENTS.md 규칙은 이렇게 키우세요

처음부터 완벽하게 쓰려 하지 마세요. AI가 같은 실수를 두 번째 하는 순간, 그걸 한 줄로 규칙에 추가하는 게 가장 좋은 방법이에요. 이렇게 쌓으면 파일이 "우리 팀이 AI한테 자주 당하는 것들"의 목록이 돼요 — 억지로 짜낸 규칙보다 훨씬 잘 들어맞습니다.

이럴 땐 오히려 독이 돼요

규칙 파일도 관리 안 하면 방해가 됩니다.

• 너무 길어질 때 — 규칙이 수백 줄이면 AI가 다 못 챙기고, 매 요청 토큰만 먹어요. 안 지켜지는 낡은 규칙은 지우세요.
• 서로 모순될 때 — "A로 해라"와 "A 쓰지 마라"가 공존하면 AI가 헷갈려요.
• 뻔한 일반론만 있을 때 — "가독성 좋게"는 규칙이 아니에요. 우리 프로젝트에서만 참인 것만 남기세요.

오늘 5분만 투자해서 자주 쓰는 레포에 규칙 파일 하나 만들어 보세요. 여러분 프로젝트엔 어떤 규칙을 넣으셨는지 방에 공유해 주시면, 좋은 건 같이 훔쳐 써요 ⚡