#Rule — AI 규칙 파일

매번 같은 말을 반복하지 않으려고 프로젝트에 상주시키는 프롬프트입니다. 도구마다 이름이 다를 뿐 성격은 같습니다.

작성 방법은 다 비슷하므로, 이 문서는 어떤 규칙이 실제로 동작하는가를 다룹니다. CLAUDE.md 를 처음부터 만들어내는 프롬프트는 claude.md에 있습니다.

#규칙 파일은 프롬프트다

가장 흔한 오해가 "규칙을 적어두면 지켜진다"입니다. 규칙 파일은 매 요청의 시스템 프롬프트에 얹히는 텍스트일 뿐입니다. 즉:

• 토큰을 먹습니다. 길수록 매 요청이 비싸집니다.
• 강제력이 없습니다. 모델이 무시할 수 있습니다.
• 프롬프트의 모든 원칙이 그대로 적용됩니다. → 프롬프트 엔지니어링

⚠️ 함정: 규칙이 길수록 잘 지켜질 것 같지만 반대입니다. 500줄짜리 규칙 파일은 모델이 그중 일부만 반영합니다. 모순된 규칙이 섞여 있으면 에러 없이 조용히 하나를 무시합니다. 진짜 강제가 필요한 것은 규칙이 아니라 린터·타입체커·CI·훅으로 막아야 합니다.

#좋은 규칙의 조건

#1. 검증 가능해야 한다

나쁜 규칙은 판정이 불가능합니다.

// 나쁨 — 무엇이 "깨끗한" 코드인지 모델도 모릅니다
- 깨끗하고 읽기 좋은 코드를 작성한다
- 성능을 고려한다
- 좋은 네이밍을 사용한다

// 좋음 — 지켰는지 아닌지 판정할 수 있습니다
- 파일 1개는 300줄을 넘지 않는다
- any 를 쓰지 않는다
- API 호출은 src/api/ 아래 함수를 통해서만 한다

#2. 금지가 아니라 지시로 쓴다

Best practices 7번(무엇을 하지 말지 대신 무엇을 할지)이 여기서도 그대로입니다.

// 나쁨
- 인라인 스타일을 쓰지 마라

// 좋음
- 스타일은 styled-components 로 작성하고 컴포넌트 파일에 함께 둔다

#3. 프로젝트 고유의 것만 쓴다

모델이 이미 아는 일반론은 토큰 낭비입니다.

// 낭비 — 모델이 이미 압니다
- React 훅은 조건문 안에서 호출하지 않는다
- SQL 인젝션을 조심한다

// 가치 있음 — 이 프로젝트에서만 참인 사실
- 날짜는 전부 UTC 로 저장하고 표시 직전에 KST 로 바꾼다
- 결제 로직은 payments/ 아래에 있고 수정 전 승인이 필요하다
- 레거시 user_v1 테이블은 읽기 전용이다

#4. 이유를 붙인다

이유가 있으면 모델이 새로운 상황에도 규칙을 확장 적용합니다. 이유가 없으면 규칙이 적힌 상황에서만 지킵니다.

// 이유 없음
- fetch 를 직접 쓰지 마라

// 이유 있음
- fetch 를 직접 쓰지 말고 src/api/client.ts 를 쓴다.
  인증 토큰 갱신과 재시도가 거기에만 구현돼 있다.

#구조

# 프로젝트 이름

## 명령어          ← 가장 먼저. 모델이 즉시 실행해야 하는 것
## 아키텍처        ← 어디에 무엇이 있는지, 왜 그렇게 나뉘었는지
## 코드 규칙       ← 이 프로젝트 고유의 것만
## 하지 말 것      ← 되돌리기 어려운 것 (스키마 변경, 인증 수정 등)

명령어를 맨 위에 두는 이유는, 모델이 가장 자주 필요로 하고 틀렸을 때 손해가 크기 때문입니다.

## 명령어

- 개발: pnpm dev
- 빌드: pnpm build
- 테스트: pnpm test          (단일 파일: pnpm test path/to/file)
- 타입 검사: pnpm typecheck
- 린트: pnpm lint --fix

작업을 끝냈다고 말하기 전에 typecheck 와 test 를 반드시 통과시킨다.

#운영

• 짧게 유지한다. 지켜지지 않는 규칙은 지우세요. 남아 있으면 나머지 규칙의 신뢰도까지 떨어집니다.
• 모델이 틀렸을 때 추가한다. 미리 다 적으려 하지 말고, 실제로 틀린 것만 한 줄씩 쌓으세요.
• 정기적으로 지운다. 리팩터링으로 사라진 규칙이 남아 모델을 옛 구조로 유도하는 일이 흔합니다.
• 코드로 강제할 수 있으면 그렇게 한다. 규칙 한 줄보다 ESLint 규칙 하나가 훨씬 확실합니다.

#참고 자료

• Anthropic — Claude Code best practices
• AGENTS.md
• Cursor — Rules