Claude Code가 같은 실수를 반복할 때, CLAUDE.md 한 줄로 바꾼 결과

Claude Code에 “우리는 pnpm 써요”라고 매번 말하고 있다면, 그 말을 CLAUDE.md에 한 번 적으면 됩니다. 공식 문서도 “Claude가 같은 실수를 두 번째 하면” CLAUDE.md에 추가하라고 권합니다.

근거: Claude Code 문서 How Claude remembers your project (2026년 11월 2일 확인). 실행 결과는 Claude Code 2.1.316에서 직접 확인했습니다.

직접 해 봤다

package.json만 있는 새 폴더에서 같은 질문을 두 번 했습니다. “이 프로젝트에 dayjs를 추가하는 명령 한 줄만 답해.”

넣은 내용은 이것뿐입니다.

# 프로젝트 규칙

- 패키지 매니저는 pnpm 만 쓴다. npm·yarn 금지.

어디에 두나

작업 폴더와 그 위 폴더의 CLAUDE.md는 시작할 때 모두 읽히고, 아래 폴더의 것은 Claude가 그 폴더 파일을 건드릴 때 읽힙니다. 세션에서 /context를 실행하면 어떤 파일이 들어갔는지 볼 수 있습니다. 처음 만든다면 /init이 코드베이스를 보고 초안을 만들어 줍니다.

잘 지키게 쓰는 법

• 확인할 수 있게 씁니다. “코드 정리 잘하기” 대신 “커밋 전에 npm test 실행”, “API 핸들러는 src/api/handlers/에”.
• 짧게 둡니다. 문서 권장은 파일당 200줄 아래입니다. 길수록 덜 지킵니다. 일부 폴더에만 해당하는 규칙은 .claude/rules/에 경로를 지정해 따로 둡니다.
• 모순을 지웁니다. 두 규칙이 부딪히면 Claude가 아무거나 고를 수 있습니다.
• 여러 단계짜리 절차는 CLAUDE.md보다 스킬이 맞습니다.

한계: 지시일 뿐입니다

공식 문서에 따르면 CLAUDE.md는 맥락으로 읽힐 뿐, 강제로 적용되는 설정이 아닙니다. 대부분 따르지만 반드시 지킨다는 보장은 없습니다. rm -rf처럼 절대 실행되면 안 되는 것은 PreToolUse 훅으로 막으세요.

오늘 할 일

이번 주에 Claude에게 두 번 이상 한 말이 있다면, 그 한 줄을 CLAUDE.md에 적으세요. 다음 세션부터는 말하지 않아도 됩니다.

관련 글: Claude Code가 rm -rf 치기 전에 막아 두는 훅 하나