[클로드 코드 완독 챌린지] - 2주차 : CLAUDE.md

CLAUDE.md 란?

개발자가 새로운 프로젝트에 투입되면 일반적으로 코딩 컨벤션을 확인하고, 프로젝트 구조글 파악하며, 사용중인 기술 스택을 이해한다.

CLAUDE.md 는 클로드 코드에게 이 모든 정보를 제공하는 지침서 역할을 한다. AI 가 개발자의 의도를 오해하지 않고 프로젝트 특성에 맞는 답변을 할 수 있도록 안내하는 일종의 사용 설명서라고 할 수 있다.

이를 통해 프로젝트마다 다른 규칙이나 맥락을 AI가 즉시 이해할 수 있으며, 코드리뷰, 테스트, 문서화 작업에서도 일관성을 유지할 수 있다.

---

CLAUDE.md

프로젝트 소개 파일

CLAUDE.md 는 클로드 코드가 자동을 읽어 들이는 특별한 파일이다. 클로드에게 “ 이 프로젝트에서는 이런 식으로 코드를 작성하고, 이런 규칙을 따라요” 라고 알려주는 역할을 한다.

필요한 이유

클로드가 자동으로 프로젝트 컨텍스트를 이해하고 맞춤형 답변을 제공한다. 결과적으로 팀 내 일관성이 높아지고, AI 를 실무에 더 안전하고 효과적으로 활용할 수 있다.

1. 매번 반복하는 설명 생략
2. 일관성 유지
   • 팀의 모든 구성원이 같은 스타일과 규칙을 따르며, 코드 품질이 균일해진다.
3. 프로젝트 이해도 향상
   • 클로드가 프로젝트의 목적과 구조를 이해해, 더 맥락에 맞는 제안을 제공한다.
4. 자동화

특징

1. 자동 컨텍스트 포함
   • 모든 대화에서 자동으로 프로젝트 맥락이 반영됨
2. 프로젝트 특화
   • 팀의 코딩 스타일과 규칙을 저장
3. 지속적 메모리
   • 세션이 끝나도 설정 유지
4. 계층적 구조
   • 여러 파일을 조합 가능

---

/init 명령어로 시작하기

첫 번째 프로젝트 설정

새로운 프로젝트에서 클로드 코드를 사용하려면 /init 명령어부터 시작한다. 이 단계는 단순히 CLAUDE.md 를 생성하는 것 이상으로, 프로젝트 전체를 클로드와 연결하는 준비 과정이라고 볼 수 있다.

초기화 단계

1. 프로젝트 디렉터리 생성
2. 기본 프로젝트 파일 생성(선택사항)
   1. npm init
   2. git init
3. 클로드 코드 시작 및 초기화
   1. claude /init
   2. 폴더 아래에 CLAUDE.md 파일이 자동으로 생성됨

/init 이 하는 일

/init 명령어는 현재 디렉터리를 분석해서 프로젝트에 맞는 CLAUDE.md 파일을 자동으로 생성한다. 프로젝트가 가진 특징을 AI 가 이해할 수 있도록 지식화된 지침서를 만들어주는 과정이다.

구체적으로

1. 현재 디렉터리의 주요 메타파일(package,json 등) 분석
2. 사용 중인 프레임워크와 라이브러리 감지
3. 프로젝트 구조 패턴 인식

---

실제 프로젝트로 실습하기

두 가지 예제 프로젝트(리액트, Express) 를 통해 프런트엔드와 백엔드 환경 모두에서 /init 이 어떻게 동작하는지 살펴보자.

리액트 프로젝트 생성 및 초기화

실습 공간을 만들고 클로드 코드 실행

1. npx create-react-app my-react-app
   • create-react-app 패키지를 이용해 새로운 React 프로젝트를 생성
2. cd my-react-app
3. claude
4. /init

리액트 프로젝트라는 맥락, CRA 에서 제공하는 기본 명령어, 디렉터리 구조까지 자동으로 분석되어 문서화되므로, 클로드 코드는 즉시 이 프로젝트의 컨텍스트를 이해하고 답변에 반영할 수 있다.

즉, “회원가입 기능 코들르 만들어줘” 라는 요청을 하더라도, CLAUDE.md 가 있으면 클로드 코드는 리액트 기반 코드 스타일과 CRA 구조에 맞는 답변을 생성한다.

Express.js 프로젝트 초기화

1. mkdir my-express-api
2. cd my-express-api
3. npm init -y
   • 새로운 Node.js 프로젝트를 초기화
   • -y 옵션을 주면 package.json 파일을 기본값으로 자동 생성
4. npm install express
   • Express.js 프레임워크를 설치
5. touch app.js
   • app.js라는 파일을 생성
6. claude /init
   • 클로드 코드를 실행하면서 바로 /init 호출

---

CLAUDE.md 커스터마이징

수동 편집하기

“이 프로젝트에 최적화된 CLAUDE.md 파일을 작성해줘” 와 같이 수동으로 클로드 코드에게 작성을 요청할 수 있다.

CLAUDE.md 메모리 스코프와 파일 위치

CLAUDE.md 는 단일 파일 이상이다. 프로젝트 전역에 걸친 규칙부터 개인 개발자의 선호까지 서로 다른 범위를 관리할 수 있으며, 팀 규칙과 개인 습관이 분리되면서도 함께 작동한다.

클로드 코드는 두가지 메모리 스코프를 통해 서로 다른 범위의 컨텍스트를 관리한다. 개발자 개인의 전역 설정부터 프로젝트별 팀 규칙, 그리고 로컬 환경의 개인적인 정보까지 체계적으로 분리하여 관리할 수 있다.

User Scope(사용자 범위)

• 파일 위치 및 이름 : ~/.claude/CLAUDE.md
• 적용 영역 : 모든 프로젝트
• 주요 용도 및 내용 : 개인 설정(코딩스타일, 툴, 환경 변수 등)

Project Scope(프로젝트 범위)

• 파일 위치 및 이름 : <프로젝트>/CLAUDE.md
• 적용 영역 : 특정 프로젝트
• 주요 용도 및 내용 : 공통 컨벤션, 구조, 협업 문서

이러한 스코프는 조합하여 활용되는데, 클로드 코드는 두 가지 스코르를 자동으로 조합하여 최적의 컨텍스트를 제공한다.

1. User Scope 의 개인 설정이 기본 베이스
2. Project Scope 의 프로젝트 규칙이 개인 설정을 덮어씀

예를 들어, 카페 예약 시스템에서 작업한다고 하면

개인 선호 도구는 User Scope 에서, 프로젝트 기술 스택은 Project Scope 에서 가져와 종합적인 컨텍스트를 구성한다.

프롬프트 작성 팁

1. 구체적이고 명확한 요청
2. 컨텍스트 제공 : 프로젝트 상황, 기술 스택, 제약 상황 등 명시
3. 단계별 접근 : 복잡한 작업은 작은 단위로 나누어 진행

CLAUDE.md 작성 베스트 프랙티스

결국 AI 에게 주는 가장 중요한 작업 설명서이다. 너무 길고 장황하면 토큰을 낭비하고, 너무 짧으면 규칙이 빠질 수 있다.

작성 원칙

1. 간결성 우선 : 장황한 설명보다는 짧고 명확한 표현
2. 선언적 형태 : 문장보다 점스타일 위주
3. 토큰 효율성 : 불필요한 서술 제거
4. 실시간 업데이트 : 프로젝트 진행에 따라 주기적으로 개선

필수 포함 요소

1. 기술 스택
2. 프로젝트 구조
3. 핵심 명령어
4. 코딩 스타일
5. 저장소 규칙

활용 고급 팁

1. 계층적 전략
   • 프로젝트 규모가 커질수록 영역별로 나눠 관리하는 것이 유용하다.
   • 프런트,백엔드, 문서화 등 각각에 맞게 특화된 설정을 해 두면 혼란을 줄일 수 있다.
2. 동적 관리
   • 프로젝트 진행 상황에 따라 계속 업데이트 해야 한다.
3. 팀 협업
   • 팀 단위 프로젝트에서는 코드 리뷰 규칙, 문서화 표준, 팀원 역할을 명확히 기록할 수 있어 , 새로 합류한 멤버도 빠르게 적응하고, 기존 팀원도 일관된 기준을 유지할 수 있다.

---

활용 전략

1. 프로젝트별 맞춤 설정
   • 프로젝트마다 목적과 상황이 다르기 때문에 달라져야 한다.
2. 팀 협업
   • 팀 다누이로 일할 때는 역할, 코드 리뷰 규칙, 협업 기준 등 담아 두는 것이 좋다.
3. 토큰 효율성 최적화
   • 모든 대화에서 자동으로 불러오므로 짧고 선언적인 표현이 필수이다.
4. 자동 업데이트 워크플로
   • 프로젝트는 끊임없이 변하기 때문에 지속적으로 업데이트 해야 한다.
   • 클로드에게 변경 사항을 반영하도록 요청하면 된다.
   • “이번 주 개발 진행 상황을 반영해서 CLAUDE.md 를 업데이트 해줘”

---

문제 해결

1. CLAUDE.md 가 간단할 때
   1. 프로젝트에 더 많은 파일을 추가한 후 /init 재실행
   2. 수동으로 내용 보완
   3. 클로드에게 작성 요청
2. 팀 프로젝트에서 CLAUDE.md 관리
   1. 깃에 CLAUDE.md 를 커밋하여 공유
   2. 팀 컨벤션 정의 후 명시
   3. 정기적으로 내용 업데이트
3. 팀원마다 다른 설정 사용
   1. 개인별 설정 파일을 .gitignore 에 등록해두고 CLAUDE.md 에서 참조하도록 작성
   2. 개인변 User Scope 의 CLAUDE.md 활