CLAUDE.md 작성법 — Claude Code를 내 프로젝트에 맞게 설정하기

“TypeScript로 써줘”를 오늘 하루에 12번 말했다면, 그건 당신 잘못이 아니라 CLAUDE.md가 없어서다. CLAUDE.md는 Claude Code에게 프로젝트 규칙을 한 번만 알려주면 매 대화에서 자동 적용되는 설정 파일이다. 나도 블로그 자동화 프로젝트에서 “아첨 금지”, “결론 먼저”, “시크릿은 환경변수로” 같은 규칙을 매번 반복하다가 CLAUDE.md를 만들었다. 그 뒤로는 한 번도 같은 말을 반복하지 않았다.

CLAUDE.md가 필요한 순간

Claude Code에게 매번 이런 말을 하고 있다면:
- “TypeScript로 써줘” (매번)
- “테스트도 같이 만들어줘” (매번)
- “console.log 쓰지 마” (매번)
- “한국어로 주석 달아줘” (매번)

이걸 CLAUDE.md에 한 번 적어두면
다시는 반복하지 않아도 된다.

기본 구조

프로젝트 루트에 CLAUDE.md 파일을 만든다:

# 프로젝트 규칙

## 언어
- TypeScript 사용
- 주석은 한국어로

## 코딩 스타일
- 함수는 50줄 이하
- console.log 금지
- 에러는 반드시 처리

## 테스트
- 모든 함수에 테스트 작성
- jest 사용

## 금지 사항
- any 타입 사용 금지
- 하드코딩된 비밀번호 금지

실전 예시 — 블로그 자동화 프로젝트

내가 실제로 쓰고 있는 CLAUDE.md의 핵심:

# 블로그 자동화 프로젝트

## 환경
- Python 3.14
- Blogger API v3 + Threads API

## 규칙
- 시크릿은 환경변수로만
- credentials 파일은 chmod 600
- 모든 외부 호출에 에러 처리

## 글쓰기 규칙
- 아첨 금지 (칭찬 표현 사용 안 함)
- 결론 먼저, 근거 나중
- 첫 200자에 답변 포함

위치별 CLAUDE.md

Claude Code는 3가지 위치의 CLAUDE.md를 읽는다:

위치 적용 범위 용도
~/.claude/CLAUDE.md 모든 프로젝트 개인 전역 규칙
프로젝트루트/CLAUDE.md 해당 프로젝트만 프로젝트별 규칙
하위폴더/CLAUDE.md 해당 폴더만 폴더별 규칙

전역 규칙(코딩 스타일, 언어)은 ~/.claude/CLAUDE.md에,
프로젝트 규칙(API 설정, 테스트 방식)은 프로젝트 루트에 두면 된다.

잘 쓰는 팁

짧게 쓴다.
CLAUDE.md가 100줄이 넘으면 역효과다.
핵심 규칙 10~20줄이 적당하다.

금지 사항을 명확히.
“좋은 코드를 써줘”보다
“console.log 금지, any 타입 금지”가 효과적이다.

점진적으로 추가.
처음부터 완벽하게 쓰려 하지 마라.
작업하면서 “이거 또 말해야 하네” 할 때마다 한 줄씩 추가.

지금 바로 해볼 것

터미널을 열고, 지금 작업 중인 프로젝트 폴더에서 이 명령어를 실행하라:

cat > CLAUDE.md << 'EOF'
# 프로젝트 규칙

## 언어
- 한국어로 주석 작성

## 금지
- console.log 금지
- 하드코딩된 비밀번호 금지
EOF

3줄짜리 CLAUDE.md면 충분하다. 이후 Claude Code에게 아무 작업이나 시켜보라. 주석이 한국어로 달리고, console.log가 없는 코드가 나온다. “이거 또 말해야 하네” 싶을 때마다 한 줄씩 추가하면 된다.

자주 묻는 질문

CLAUDE.md가 뭔가?

프로젝트 루트에 두는 설정 파일이다.
Claude Code가 이 파일을 읽고 프로젝트의 규칙, 코딩 스타일, 금지 사항을 파악한다.

CLAUDE.md가 없으면 Claude Code가 안 되나?

된다. 없어도 작동한다.
하지만 CLAUDE.md가 있으면 같은 지시를 매번 반복할 필요가 없다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

[알고리즘] Suffix Tree

이미지
Suffix tree는 문자열의 모든 접미사들을 표현하는 trie 모양의 자료 구조이다. prefix tree라 불리는 trie가 근간이 되는 자료구조인듯 한데 두 자료구조의 차이는 banana라는 단어가 있을 때 trie는 banana라는 단어만 저장을 하지만 suffix tree는 banana, anana, nana, ana, na, a 와 같이 banana라는 단어에서 나올 수 있는 모든 경우의 수를 다 저장한다는 것이다. 쓸데없이 모든 경우를 저장하는 이유는 문자열에 대한 검색을 할 때 필요하기 때문이다. Trie 자료구조 같은 경우에는 ban, ba와 같은 일부분의 단어로 banana라는 완전한 단어를 찾을 수 있지만 nan, ana와 같은 단어로는 banana를 찾을 수 없다. 이러한 문제를 해결하기위해 trie를 개선시킨 것이 suffix tree인듯 하다.  Suffix trie는 trie에 모든 suffix들을 저장한 구조를 의미한다. 아래 그림은 abaaba라는 문자열 T를 suffix tree에 저장하는 예시이다. suffix tree나 suffix trie에 문자열을 저장할 때는 문자열의 끝에 $를 붙이는데 그 이유는 정확히 모르겠다... 아마 문자열의 끝을 알리기 위한 용도인 것 같다. Suffix Trie의 형태  위 그림의 왼쪽과 같은 모양이 suffix trie이다. 여기서 자식 노드가 1개 뿐인 것들을 합치면 오른쪽과 같은 모양이 되는데 저러한 형태의 자료구조를 suffix tree라 한다. Suffix Tree  이 suffix tree는 문자열의 길이만큼의 leaf node를 갖는다  위 그림에서 오른쪽 그림은 tree의 edge label을 (offset, length)의 형태로 T를 나타낸 것이다. Suffix tree의 label  각 노드의 label은 root로부터 node로 연결된 edge의 label과 ...
자세한 내용 보기

[기타IT] php설치

이미지
 이번에는 php 설치하는 법에 대해 알아보겠습니다. 저는 개발할 때 node.js를 사용 하지만 이번에 프로젝트하는데 필요한 xibo가 php기반이라 설치하게 되었습니다. php란?  php(약칭 : Hypertext Preprocessor)는 프로그래밍 언어의 일종으로 동적 웹 페이지를 만들기 위해 설계되었습니다. php는 일반적으로 혼자 설치되지 않고 apache와 MySql과 함께 설치되는 것이 일반적입니다.  php는 apache를 통해 브라우저로 정보를 전송하고 MySql을 이용해 사용자의 정보를 저장하기 때문에 일반적으로 함께 사용되고 설치됩니다. 이를 APM이라 하는데 Window에 설치하는 APM을 WAPM이라 합니다. 이걸 각각 설치 할 수도 있지만 난이도가 있기 때문에 Bitnami를 이용해 한번에 설치해 보도록 하겠습니다. php설치 먼저 https://bitnami.com/stack/wamp 에 접속하여 설치파일을 다운로드 받습니다.  다운로드가 완료되면 설치파일을 실행합니다. 다른 구성요소들은 굳이 필요하지 않으니 체크박스를 해제해줍니다. php에서 쓰는 MySql의 root사용자 비밀번호를 설정해주는 화면입니다. 6자리 이상의 비밀번호를 입력하시면 됩니다. 설치가 되고 있는 화면입니다.  설치가 완료되고 브라우저 주소창에 localhost를 쳤을 때 다음과 같은 화면이 출력되면 제대로 설치가 된것입니다.
자세한 내용 보기

[Digital Signage] Xibo 설치

이미지
 이번에는 Digital Signage용 오픈소스 OS인 Xibo를 설치하는 방법에 대해 알아보겠습니다. Xibo는 php기반이기 때문이 php가 설치되어 있어야 합니다. php 설치가 필요하신 분들은  http://cd4761.blogspot.kr/2016/02/it-php.html 로 가셔서 설치를 하신다음 진행해주시기 바랍니다.   http://xibo.org.uk/  에 접속해서 아래 그림과 같이 표시된 것들을 다운로드 받습니다.  먼저 CMS를 설치해 보도록 하겠습니다. CMS CMS란?  CMS는 Content Management System의 약자로 말그대로 Digital Signage를 통해 보여줄 컨텐츠들을 관리하는 시스템이라 보시면 됩니다. CMS는 PHP/ MySQL 웹 어플리케이션 이며 Apache, nginx 그리고 Microsoft IIS에서 작동 합니다. CMS설치 다운로드 받은 CMS파일을 압축 푼 다음 C:\Bitnami\wampstack-5.5.31-0\apache2\htdocs에 다음과 같이 위치 시켜줍니다. Xibo폴더 내부는 다음과 같습니다. 그 다음 브라우저에 localhost/Xibo를 입력하면 다음과 같은 화면이 출력됩니다. 하지만 사진을 보시면 각 항목이 체크 표시가 된 경우도 있고 x표시가 된 경우도 있을 것 입니다. 그럴 경우 C:\Bitnami\wampstack-5.5.31-0\php 폴더에 있는 php.ini 파일을 열면  위와 같은 부분이 있을 것입니다. 저는 Fileinfo와 SOAP Extension에 문제가 있다고 되어있는데 이럴경우 저 부분에 extension=php_fileinfo.dll과 extension=php_soap.dll을 입력해주시면 해결이 됩니다.  나머지 설치를 진행해주시고 설치가 완료된 후에 로그인을 하면 ...
자세한 내용 보기