개념한 문장
세션마다 항상 주입되는 규칙 파일
CLAUDE.md는 작업 폴더에 두면 Claude가 매 세션 시작마다 읽는 파일입니다. A-1의 지침과 같은 역할을, 에이전트 환경에서 합니다.
한 문장으로정보의 중복이 성능 하락과 비용 증가의 핵심 원인입니다. 많이 넣는 게 아니라 제대로 넣습니다.
원칙네 가지
무엇을 넣고 무엇을 빼나
① 중복 정보를 넣지 않는다
React 18 · TypeScript 같은 정보는 Claude가 package.json을 열어 스스로 압니다.
불일치의 함정실제 package.json은 19인데 CLAUDE.md엔 18로 적혀 있다면 — 이 불일치가 오히려 성능을 떨어뜨립니다.
② /init은 초안까지만
공식 문서는 첫 세션에 /init으로 시작용 CLAUDE.md를 만들라고 안내합니다. 다만 자동 생성물은 프로젝트 전체를 훑느라 시간·토큰을 쓰고, AI가 파일만 봐도 아는 뻔한 정보가 섞입니다. 초안으로만 쓰고 ①의 기준으로 덜어내세요.
③ 금지엔 반드시 대안을 붙인다
| ❌ 이렇게 쓰면 | ✅ 이렇게 써야 |
|---|---|
| Lodash 쓰지 마라 → AI가 다른 걸 임의 선택 | Lodash 금지 — 대신 Native Array/Object 사용 → 의도대로 |
④ 200줄을 넘기면 조건부 규칙으로
공식 문서는 200줄 이내를 권장합니다. 넘치면 .claude/rules/ 아래 파일로 나누고, 프론트매터의 paths로 적용 범위를 좁힙니다. 해당 경로의 파일을 다룰 때만 주입됩니다.
# .claude/rules/frontend.md
---
paths:
- "src/**/*.{ts,tsx}"
---
- 상태 관리는 Zustand만 사용 (Redux 금지)
- API 호출은 services/ 레이어를 통해서만참고paths가 없는 규칙 파일은 항상 읽힙니다. 특정 폴더·확장자에만 필요한 규칙일수록 paths로 좁히세요.
실습15분
우리 프로젝트의 CLAUDE.md 쓰기
우리 프로젝트의 CLAUDE.md 초안을 만들어줘. 단, 아래 규칙을 지켜. - package.json 등 파일을 보면 알 수 있는 정보는 넣지 말 것 - 팀 컨벤션 / 금지사항(+대안) / 아키텍처 결정 이유만 - 30줄 이내 - 내가 알려줄 내용: (여기에 팀 규칙 3~5개 적기)
- 파일만 봐선 모르는 것만 남겼다
- 금지 항목에 대안을 함께 적었다
- 200줄을 넘지 않는다
참고화면(UI)을 만드는 프로젝트라면 같은 방식으로 디자인 규칙도 파일에 담을 수 있습니다 — 참고 · 디자인. 과정 순서와는 무관한 선택 주제입니다.
클로드코드 시작하기Claude Code · 규칙과 확장