Claude Code CLAUDE.md 작성법 2026 — 프로젝트 생산성 2배 높이는 설정

      u_a395b12a

      Claude Code CLAUDE.md 작성법 2026 — 프로젝트 생산성 2배 높이는 설정

      CLAUDE.md, 알고 쓰면 완전히 다르다

      Claude Code를 처음 사용하는 분들이 가장 많이 놓치는 기능이 있습니다. 바로 CLAUDE.md 파일입니다. 이 파일 하나만 제대로 작성해도 Claude Code의 응답 품질이 눈에 띄게 달라집니다.

      CLAUDE.md는 Claude Code가 프로젝트를 시작할 때 자동으로 읽어오는 특별한 파일입니다. 프로젝트에 대한 중요한 정보, 규칙, 자주 사용하는 명령어를 미리 정리해두면 매번 같은 설명을 반복하지 않아도 됩니다. Claude Code가 처음부터 프로젝트 맥락을 파악하고 작업을 시작하기 때문에 결과물의 품질과 정확도가 올라갑니다.

      이 글에서는 CLAUDE.md가 무엇인지, 어떻게 작성해야 하는지, 실제로 어떤 내용을 담아야 생산성이 올라가는지를 2026년 기준으로 정리합니다.

      CLAUDE.md란 무엇인가?

      CLAUDE.md는 프로젝트 루트 디렉토리에 위치하는 마크다운 파일입니다. Claude Code는 실행될 때 이 파일을 자동으로 찾아서 컨텍스트에 포함시킵니다. 별도의 설정 없이 파일만 만들어두면 됩니다.

      쉽게 말하면 새로운 팀원에게 프로젝트를 소개하는 문서와 비슷합니다. 프로젝트의 구조, 코딩 규칙, 자주 쓰는 명령어, 주의사항을 정리해두면 Claude Code가 매번 물어보지 않고 스스로 파악하고 작업합니다.

      CLAUDE.md 파일은 프로젝트마다 별도로 작성합니다. 프로젝트마다 사용하는 기술 스택과 규칙이 다르기 때문에, 각 프로젝트 루트에 맞는 내용을 담은 CLAUDE.md를 두는 것이 좋습니다.

      CLAUDE.md 파일 만들기

      프로젝트 루트 디렉토리에서 아래 명령어로 CLAUDE.md 파일을 생성할 수 있습니다.

      touch CLAUDE.md

      또는 Claude Code에게 직접 생성을 요청할 수 있습니다.

      이 프로젝트에 맞는 CLAUDE.md 파일을 생성해줘

      Claude Code가 프로젝트 구조를 분석해서 기본 CLAUDE.md 초안을 작성해줍니다. 이후 내용을 직접 수정하고 보완하면 됩니다.

      CLAUDE.md에 담아야 할 핵심 내용

      1. 프로젝트 개요

      프로젝트가 무엇을 하는 서비스인지, 어떤 기술 스택을 사용하는지 간략하게 정리합니다. Claude Code가 프로젝트의 목적과 구조를 빠르게 파악할 수 있도록 돕습니다.

      ## 프로젝트 개요
- 서비스명: 온라인 쇼핑몰 관리 시스템
- 주요 기능: 상품 관리, 주문 처리, 재고 관리
- 기술 스택: Node.js, Express, PostgreSQL, React
- 배포 환경: AWS EC2, RDS

      2. 자주 사용하는 명령어

      빌드, 테스트, 배포에 사용하는 명령어를 정리해두면 Claude Code가 작업 중에 직접 실행할 수 있습니다. 매번 명령어를 알려줄 필요가 없어집니다.

      ## 주요 명령어
- 개발 서버 실행: npm run dev
- 빌드: npm run build
- 테스트 실행: npm test
- 테스트 커버리지 확인: npm run test:coverage
- 린트 검사: npm run lint
- 린트 자동 수정: npm run lint:fix
- 데이터베이스 마이그레이션: npm run migrate

      3. 코딩 규칙

      팀에서 사용하는 코딩 컨벤션, 네이밍 규칙, 파일 구조 규칙을 정리합니다. Claude Code가 코드를 작성하거나 수정할 때 이 규칙을 따르도록 합니다.

      ## 코딩 규칙
- 들여쓰기: 스페이스 2칸
- 따옴표: 싱글 쿼트 사용
- 세미콜론: 사용하지 않음
- 함수명: camelCase
- 컴포넌트명: PascalCase
- 상수명: UPPER_SNAKE_CASE
- 파일명: kebab-case

      4. 디렉토리 구조

      프로젝트의 주요 디렉토리 구조와 각 폴더의 역할을 정리합니다. Claude Code가 파일을 어디에 만들어야 할지, 어떤 파일이 어디에 있는지 빠르게 파악할 수 있습니다.

      ## 디렉토리 구조
- src/components: React 컴포넌트
- src/pages: 페이지 컴포넌트
- src/hooks: 커스텀 훅
- src/utils: 유틸리티 함수
- src/api: API 호출 함수
- src/types: TypeScript 타입 정의
- tests: 테스트 파일

      5. 주의사항

      Claude Code가 작업할 때 특히 주의해야 할 사항을 명시합니다. 수정하면 안 되는 파일, 특별한 처리가 필요한 부분, 알려진 이슈 등을 정리합니다.

      ## 주의사항
- config/production.env 파일은 절대 수정하지 말 것
- 데이터베이스 스키마 변경 시 반드시 마이그레이션 파일 생성
- 외부 API 키는 환경 변수로만 관리, 코드에 직접 입력 금지
- 테스트 없이 main 브랜치에 직접 커밋하지 말 것

      6. 자주 겪는 문제와 해결 방법

      개발 중 반복적으로 겪는 문제와 해결 방법을 정리해두면, Claude Code가 비슷한 상황에서 올바른 방향으로 안내해줍니다.

      ## 자주 겪는 문제
- 로컬 DB 연결 오류: PostgreSQL 서비스 실행 확인 (brew services start postgresql)
- 포트 충돌: lsof -i :3000 으로 사용 중인 프로세스 확인 후 종료
- 환경 변수 오류: .env.local 파일이 프로젝트 루트에 있는지 확인

      실제 CLAUDE.md 예시 전체 템플릿

      아래는 Node.js 프로젝트를 기준으로 작성한 CLAUDE.md 전체 템플릿입니다. 프로젝트에 맞게 수정해서 바로 사용할 수 있습니다.

      # 프로젝트명

## 프로젝트 개요
- 서비스 설명: [서비스 설명 입력]
- 기술 스택: Node.js, Express, PostgreSQL, React, TypeScript
- 배포 환경: AWS

## 주요 명령어
- 개발 서버 실행: npm run dev
- 빌드: npm run build
- 테스트 실행: npm test
- 린트 검사: npm run lint
- 데이터베이스 마이그레이션: npm run migrate

## 디렉토리 구조
- src/components: React 컴포넌트
- src/pages: 페이지 컴포넌트
- src/hooks: 커스텀 훅
- src/utils: 유틸리티 함수
- src/api: API 호출 함수
- tests: 테스트 파일

## 코딩 규칙
- 들여쓰기: 스페이스 2칸
- 따옴표: 싱글 쿼트
- 세미콜론: 사용하지 않음
- 함수명: camelCase
- 컴포넌트명: PascalCase

## 주의사항
- 환경 변수는 코드에 직접 입력하지 말 것
- 테스트 없이 main 브랜치에 직접 커밋하지 말 것
- 데이터베이스 스키마 변경 시 마이그레이션 파일 필수 생성

## 자주 겪는 문제
- 로컬 DB 연결 오류: PostgreSQL 서비스 실행 상태 확인
- 포트 충돌: lsof -i :3000 으로 확인

      CLAUDE.md 작성 시 주의할 점

      간결하게 작성한다

      CLAUDE.md는 길수록 좋은 것이 아닙니다. 너무 길면 핵심 내용이 묻혀버립니다. 꼭 필요한 정보만 담고 간결하게 유지하는 것이 좋습니다. 사람이 읽기 편한 수준으로 작성하면 Claude Code도 잘 이해합니다.

      최신 상태로 유지한다

      프로젝트가 변경될 때마다 CLAUDE.md도 함께 업데이트해야 합니다. 오래된 정보가 담겨 있으면 Claude Code가 잘못된 방향으로 작업할 수 있습니다. 프로젝트 주요 변경사항이 생길 때 CLAUDE.md 업데이트를 함께 진행하는 습관을 들이세요.

      팀 프로젝트라면 Git으로 관리한다

      CLAUDE.md를 Git 저장소에 포함시켜 팀원들과 공유하면, 모든 팀원이 동일한 설정으로 Claude Code를 사용할 수 있습니다. 팀 전체의 Claude Code 활용 일관성이 높아집니다.

      글로벌 CLAUDE.md 설정

      프로젝트별 CLAUDE.md 외에 모든 프로젝트에 공통으로 적용되는 글로벌 설정도 가능합니다. 홈 디렉토리에 CLAUDE.md 파일을 만들면 됩니다.

      touch ~/.claude/CLAUDE.md

      글로벌 CLAUDE.md에는 개인적인 코딩 스타일 선호도, 자주 쓰는 도구, 응답 언어 설정 등을 담을 수 있습니다.

      # 글로벌 설정

## 응답 설정
- 항상 한국어로 응답할 것
- 코드 변경 전 변경 내용을 먼저 설명할 것
- 중요한 파일 삭제 전 반드시 확인 요청할 것

## 선호하는 코딩 스타일
- 함수형 프로그래밍 선호
- 주석은 한국어로 작성
- 변수명은 의미를 명확하게 표현

      마무리

      CLAUDE.md는 Claude Code를 제대로 활용하기 위한 핵심 설정 파일입니다. 처음에는 간단하게 시작해도 됩니다. 프로젝트 개요와 주요 명령어 몇 가지만 정리해두는 것만으로도 Claude Code의 응답 품질이 달라집니다.

      사용하면서 불편한 점이 생기거나 자주 같은 설명을 반복하게 된다면 그 내용을 CLAUDE.md에 추가하는 방식으로 점진적으로 발전시켜 나가는 것을 권장합니다. 다음 글에서는 Claude Code를 직장인 업무에 활용하는 실전 사례 7가지를 정리해드리겠습니다.

      다음 글 예고: Claude Code 직장인 활용법 2026 — 반복 업무 자동화 실전 사례 7가지

      11번 글로 바로 이어서 작성할까요? “네”라고 답해주시면 진행하겠습니다.

      Related Posts

      답글 남기기

      이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다