목록으로

CLAUDE.md 하나로 AI가 내 코드 스타일을 따라한다

HANUI·
Claude CodeAICLAUDE.md개발도구자동화

Claude Code 시리즈

(6편)
  1. 1.Claude Code로 CMS 프로젝트 하루만에 만들기 — 기획부터 코딩까지 자동화
  2. 2.Claude Code 슬래시 커맨드 21종 — 설치 한 줄이면 끝
  3. 3.CLAUDE.md 하나로 AI가 내 코드 스타일을 따라한다
  4. 4.나만의 Claude Code 커맨드 만들기 — 마크다운 하나로 자동화
  5. 5.Claude Code + MCP로 노션·피그마 연동하기
  6. 6.백엔드 잘 모르는 프론트가 Spring Boot API 짠 이야기

Claude Code 시리즈 3편이에요. 1편에서 CMS를 하루만에 만든 이야기, 2편에서 슬래시 커맨드 21종을 다뤘는데요.

오늘은 그 모든 것의 기반이 되는 파일 — CLAUDE.md에 대해 이야기할게요.

CLAUDE.md가 뭐예요?

프로젝트 루트에 놓는 마크다운 파일 하나예요. Claude Code가 작업을 시작할 때 이 파일을 제일 먼저 읽어요.

쉽게 말하면 **"이 프로젝트에서는 이렇게 해줘"**라는 규칙서예요.

.eslintrc가 코드 스타일을 강제하는 것처럼, CLAUDE.md는 AI의 행동을 강제해요.

없으면 어떻게 되나?

CLAUDE.md 없이 작업하면 이런 일이 생겨요:

매번 같은 말을 반복해야 해요. 대화가 길어지면 앞에서 했던 말을 잊어버리기도 하고요.

CLAUDE.md가 있으면?

한번 써두면 끝이에요. 세션이 바뀌어도, 컨텍스트가 날아가도, CLAUDE.md는 항상 읽히니까요.

실제 CLAUDE.md 공개 — HANUI 프로젝트

우리 HANUI 프로젝트의 CLAUDE.md를 공개할게요. 실제로 쓰고 있는 파일이에요.

1. 작업 순서 제안

이게 의외로 유용해요. "에디터 만들자"라고 하면 Claude가 "게시판 CRUD가 먼저 되어야 에디터를 붙일 수 있는데, 게시판부터 할까요?"라고 물어봐요.

AI가 순서를 챙겨주는 시니어 개발자 역할을 하는 거예요.

2. 프로젝트 컨텍스트

이걸 써두면 "대시보드 만들어줘"라고만 해도 Claude가 Next.js + KRDS 토큰 + 공공기관 스타일로 만들어요. "React로 해줘", "Tailwind 써줘" 같은 말을 안 해도 돼요.

3. 컴포넌트 구분 체계

이게 HANUI CLAUDE.md의 핵심이에요. Component → Block → Kit 3단 구조를 정의해뒀더니, Claude가 새 컴포넌트를 만들 때 "이건 Block 레벨이니까 blocks/ 폴더에 만들겠습니다"라고 알아서 판단해요.

4. 코드 패턴

이걸 안 써두면 Claude가 매번 다른 패턴으로 코드를 짜요. forwardRef를 쓰기도 하고 안 쓰기도 하고, interface를 쓰기도 하고 type을 쓰기도 하고.

써두면 50개 컴포넌트가 전부 같은 패턴으로 만들어져요.

잘 쓰는 법 5가지

1. 구체적으로 써라

"깔끔하게"는 사람마다 다르지만, "Named export만"은 명확해요.

2. 예시를 넣어라

Claude는 예시를 보면 패턴을 정확히 복제해요. 규칙만 있으면 해석의 여지가 생기고, 예시가 있으면 없어요.

3. "하지 마라"도 써라

뭘 해야 하는지만큼, 뭘 하면 안 되는지도 중요해요. 특히 프로젝트에서 이전에 문제가 됐던 것들을 적어두면 같은 실수를 반복하지 않아요.

4. 프로젝트 고유 정보를 넣어라

라이브러리 문서에 없는, 우리 프로젝트만의 특이사항이에요. 이걸 안 써두면 Claude가 일반적인 방식으로 코드를 짜고, 빌드할 때 타입 에러가 나요.

5. 짧게 유지하라

너무 길면 Claude가 뒤에 있는 규칙을 놓칠 수 있어요. 정말 중요한 것만 넣으세요.

CLAUDE.md의 위치

모노레포라면 각 패키지/앱마다 별도의 CLAUDE.md를 둘 수 있어요. Claude가 해당 디렉토리에서 작업할 때 자동으로 읽어요.

루트 CLAUDE.md에는 공통 규칙을, 하위에는 패키지별 규칙을 넣으면 돼요.

Before / After

CLAUDE.md 없을 때있을 때
코드 일관성매번 다른 패턴동일 패턴 유지
반복 설명"named export로 해줘" 매번한번 쓰면 끝
빌드 에러프로젝트 규칙 몰라서 에러처음부터 맞춤
컨텍스트 유지세션 넘어가면 리셋항상 읽힘
온보딩새 팀원도 매번 설명CLAUDE.md 읽으면 파악

시작하기

빈 파일부터 시작하세요.

처음에는 이것만 적어도 충분해요:

그리고 작업하면서 Claude가 틀릴 때마다 규칙을 추가하면 돼요. "아 이거 이렇게 해줘"라고 말한 게 두 번 이상이면 CLAUDE.md에 넣을 타이밍이에요.

claude-settings에 CLAUDE.md 템플릿도 포함되어 있어요:

Claude Code 시리즈:

관련 프로젝트:

  • claude-settings — Claude Code 슬래시 커맨드, 에이전트, 훅 설정 모음
  • HANUI — KRDS 기반 React 디자인 시스템

HANUI

KRDS 기반 React 컴포넌트 라이브러리. 공공 웹 개발을 더 쉽게.