규칙 파일 제대로 쓰기

규칙 파일은 AI의 장기 기억입니다

대화는 끝나면 사라지지만, 프로젝트 폴더의 규칙 파일은 매 대화마다 자동으로 읽힙니다. 9강에서 만든 CLAUDE.md가 그것이고, 도구에 따라 AGENTS.md, .cursorrules 등 이름은 다르지만 역할은 같습니다. 여러 도구를 쓴다면 하나를 쓰고 나머지는 그 파일을 참조하게 하면 됩니다.

넣을 것 / 뺄 것

넣을 것

• 프로젝트가 뭔지 한 문단 + PLAN.md 참조
• 기술 스택과 버전 (Next.js 15인지 16인지에 따라 코드가 달라집니다)
• 폴더 규칙: 컴포넌트는 어디, API 라우트는 어디, 공용 함수는 어디
• 작업 규칙: 범위 제한, 설치 허락, 확인 방법 안내, 언어
• 하지 말 것: 비밀 파일, 위험 명령, 기획에서 뺀 기능
• 자주 쓰는 명령: dev, build, check
• 반복해서 지적한 것: "주석은 한국어", "any 금지", "이모지 아이콘 금지"

뺄 것

• 코드 자체: 파일이 곧 진실입니다. 규칙 파일의 코드는 금방 낡습니다.
• 일반 상식: "깨끗한 코드를 써라" 같은 말은 효과가 없습니다. 구체적이지 않으면 빼세요.
• 너무 긴 설명: 200줄이 넘으면 AI가 중요한 규칙을 놓칩니다. 100줄 안쪽이 이상적.
• 자주 바뀌는 상태: "지금 로그인 기능 만드는 중" 같은 건 TODO.md로.

좋은 규칙의 형태

규칙은 행동 + 조건으로 씁니다.

약한 규칙	강한 규칙
코드를 깔끔하게	파일이 200줄을 넘으면 분리를 제안한다
에러 처리를 잘	API 호출은 항상 try/catch로 감싸고 사용자에게 한국어 메시지를 보여준다
스타일 일관성	Tailwind 간격은 2,4,6,8,12만 쓴다. DESIGN.md 참조
조심해서	.env 파일은 읽지도 출력하지도 않는다

언제 고치나요?

AI가 같은 실수를 두 번 했을 때. 그 순간이 규칙을 한 줄 추가할 때입니다. 미리 상상해서 쓴 규칙은 대개 안 맞습니다.

반대로 한 달간 한 번도 필요 없었던 규칙은 지우세요. 파일이 짧을수록 지켜집니다.

프로젝트 밖의 규칙

도구마다 모든 프로젝트에 적용되는 개인 규칙 파일을 둘 수 있습니다(홈 폴더의 ~/.claude/CLAUDE.md 같은 곳). 여기엔 프로젝트와 무관한 취향을 넣습니다.

- 설명은 한국어로, 결론 먼저
- 코드 블록 앞에 파일 경로를 적는다
- 확신이 없으면 추측하지 말고 물어본다

여러 규칙 파일 나누기

프로젝트가 커지면 하위 폴더에 규칙 파일을 둘 수 있습니다. src/app/api/CLAUDE.md에 "모든 라우트는 zod로 입력 검증"처럼 그 폴더에만 해당하는 규칙을 적는 식입니다. 도구는 보통 루트 규칙 + 작업 중인 폴더의 규칙을 함께 읽습니다.

점검 방법

새 대화에서 규칙을 언급하지 않고 요청해보고, 지켜지는지 봅니다. 안 지켜지면 규칙이 모호한 겁니다. "왜 이 규칙을 안 지켰어?"라고 물으면 AI가 어떻게 해석했는지 알려주고, 그걸 바탕으로 문장을 고치면 됩니다.