Velog
CLAUDE.md 완벽 가이드
CLAUDE.md 는 프로젝트의 불문율을 AI 에게 전달하는 파일. 좋은 파일의 조건은 '짧고 단정하고 업데이트 가능' 이며, README 와는 목적이 다르다.
핵심 요약
좋은 CLAUDE.md 는 네 덩어리로 쓰인다. (1) 명령어: 실제 개발 시 칠 커맨드(npm run dev, task test)를 코드 블록으로, (2) 아키텍처 개요: 폴더 구조와 데이터 흐름을 한 다이어그램, (3) 규칙: 타이포그래피/스타일링/테스트 유무 같은 팀 선택을 짧은 문장으로, (4) 삭제된 경로: '/old/path 는 삭제됨' 처럼 하지 말아야 할 목록. 길이는 1~2 페이지. 너무 길면 AI 가 컨텍스트 창에서 다른 코드를 밀어낸다. 핵심 원칙은 '한 번 합의된 결정을 반복 설명하지 않게 만드는 것'.
CLAUDE.md 를 '새 팀원에게 처음 주는 1페이지 안내서' 로 본다. 긴 문서가 아니라 반복 질문이 생기는 지점만 담는 합의의 압축판. README 는 사람이 첫날 읽고, CLAUDE.md 는 AI 가 매 턴 읽는다.
AI 툴 도입 면접에서 'Cursor 써요' 로 끝내면 얕다. 'AI 에게 우리 팀 규칙을 어떻게 전달하나' 를 설명할 수 있어야 실제 생산성 향상 경험을 말할 수 있다. CLAUDE.md 는 그 문제의 표준 해답이며, 같은 원리가 AGENTS.md, RULES.md, Cursor Rules 에도 그대로 적용된다.
학습 포인트
면접 답변으로 연결할 학습 포인트입니다.
README vs CLAUDE.md — 독자가 다르다
| 파일 | 독자 | 길이 | 목적 |
|---|---|---|---|
README.md | 사람(첫날) | 길게 OK | 프로젝트 소개 + 시작 가이드 |
CLAUDE.md | AI(매 턴) | 1~2페이지 | 반복 지시를 줄이는 규칙 |
둘을 합쳐 하나로 만들면 AI 컨텍스트에 불필요한 마케팅 텍스트가 들어가 토큰 낭비. 분리가 정답.
CLAUDE.md 에 회사 소개/로고/배너를 쓰는 것. AI 에게는 불필요한 노이즈.
규칙은 'Do' 보다 'Don't' 가 강하다
AI 가 자주 실수하는 방향에 '하지 마라' 를 적는다.
## 금지
- `lodash` 추가 금지 — 내장 JS 로 대체
- `/* eslint-disable */` 전역 비활성화 금지
- `tailwind` 클래스 사용 금지 — Emotion 만 사용
## 권장
- 새 컴포넌트는 `src/components/` 아래
- 회사별 색상은 `theme.companies.*` 참조
'하지 마라' 한 줄이 '해라' 세 줄보다 재발 방지에 효과적이다.
추상적 원칙(clean code 를 지키자) 만 쓰는 것. AI 는 구체적 패턴 에서만 반응한다.
업데이트 가능성 — 살아있는 문서
CLAUDE.md 는 '작성 완료' 가 아닌 코드와 함께 커밋 되는 문서. 트리거:
- 같은 피드백을 AI 에게 두 번 준 순간 →
CLAUDE.md에 추가 - 폴더 구조를 바꿨다 → 다이어그램 갱신
- 라이브러리 교체 → 예시 코드 수정
실무 규칙: PR 템플릿에 [ ] CLAUDE.md 갱신이 필요한가? 체크박스.
한 번 쓰고 방치 — 6개월 지나면 다이어그램이 현실과 달라져 AI 가 틀린 답 을 내기 시작.
읽는 순서
- 1이론
좋은
CLAUDE.md예시 3개(Next.js, Anthropic 공식, 사내 성공 사례)를 비교해 공통 섹션을 추출. - 2구현
본인 프로젝트의
CLAUDE.md초판을 1페이지로 작성(명령어/아키텍처/금지/권장 4섹션). - 3실무
1주일 사용 후 AI 피드백 로그를 보고
CLAUDE.mdv2 PR 을 작성. PR 설명에 '반영된 피드백 5개' 를 명시. - 4설명
사내 문서에 '
CLAUDE.md작성 가이드' 를 올리고, PR 템플릿에 'CLAUDE.md갱신 체크박스' 추가.
면접 연결 질문
[좋은 답변] 컨텍스트 윈도우는 유한 자원 — README 의 마케팅/배지는 AI 답변 품질에 기여 0, 그런데 토큰은 차지. 두 독자가 필요한 정보가 다르므로 분리가 엔트로피(의미밀도) 를 높인다.
[좋은 답변] '금지' 섹션에 구체적 예시 로 추가. 'useCallback 을 무분별 남용 금지' 가 아니라 'useCallback 은 자식에게 전달되는 함수에만 사용. 이펙트 내부용은 useEffectEvent ' 처럼.
[좋은 답변] 일주일간 AI 에게 준 피드백 로그 를 모아 패턴 상위 5개만 추출. '모두 다 적기' 가 아니라 반복된 것만.
자기 점검
'처음엔 완벽하게' — 실제로는 반복 피드백에서 시작 해 점증.
'개인별 달라도 된다'. 실제로는 팀 규칙을 공유해야 일관된 코드 가 나옴.