클로드 코드는 작업 폴더에 CLAUDE.md라는 파일이 있으면 일을 시작할 때마다 이 파일을 먼저 읽고 그 내용을 따릅니다. 그리고 Skills는 자주 하는 작업의 방법을 묶어 두었다가 필요할 때 꺼내 쓰게 하는 기능입니다. 둘 다 “매번 같은 말을 반복하지 않게” 해 준다는 점에서 바이브코딩을 오래 할수록 효과가 커지는 기능입니다.
왜 AI는 지난번에 한 말을 잊을까
AI는 대화가 새로 시작되면 이전 대화에서 정한 것을 기억하지 못하는 경우가 많습니다. “글씨를 크게 해 달라고 지난주에도 말했는데, 새 화면은 또 작네” 하는 일이 생기는 이유입니다. 새로 온 직원에게 회사의 업무 매뉴얼을 건네듯, AI에게도 매번 읽을 매뉴얼을 주면 해결됩니다. 그 매뉴얼이 CLAUDE.md입니다.
CLAUDE.md란
CLAUDE.md는 작업 폴더 맨 위에 두는 평범한 글 파일입니다. 특별한 문법이 필요 없고, 사람이 읽는 메모처럼 쓰면 됩니다. 클로드 코드는 그 폴더에서 일을 시작할 때 이 파일을 먼저 읽고 적힌 원칙을 지킵니다.
직접 만들 필요도 없습니다. 이렇게 요청하면 됩니다.
이 폴더에 CLAUDE.md 파일을 만들어 주세요. 지금까지 우리가 정한 원칙(누가 쓰는 앱인지, 글씨 크기, 말투, 조심할 것)을 정리해서 넣고, 앞으로 작업할 때 항상 이 원칙을 지켜 주세요.
CLAUDE.md에 무엇을 적을까
네 가지 묶음으로 나누면 정리하기 쉽습니다.
# 이 앱은 수요 기도 모임의 기도제목 나눔 앱입니다. 쓰는 사람: 모임 참석자 누구나, 60~70대가 많음. 대부분 폰으로 씀. # 화면 원칙 - 본문 글씨는 18px 이상, 버튼은 손가락으로 누르기 쉽게 크게 (어르신이 많아서) - 화면의 모든 말은 한국어 존댓말 - 한 화면에 강조색은 하나만 # 내용 원칙 - 성경 구절은 개역개정 본문 자료에서 가져오고 기억으로 인용하지 말 것 - 예시가 필요할 때 실제 사람 이름을 지어내지 말 것 # 작업 원칙 - 디자인을 바꿀 때는 시안을 먼저 보여 줄 것 - 다 만든 뒤에는 폰 화면 크기로 직접 확인하고 보고할 것 - 사용자 자료를 지우는 작업은 반드시 먼저 물어볼 것
좋은 CLAUDE.md를 쓰는 세 가지 원칙
이유를 함께 적습니다
“글씨를 크게”보다 “어르신이 많아서 글씨를 크게”가 낫습니다. 이유를 알면 AI가 처음 보는 상황에서도 그 뜻에 맞게 판단합니다. 이유를 아는 AI는 글씨뿐 아니라 버튼과 간격도 넉넉하게 만듭니다.
같은 원칙을 두 군데 적지 않습니다
한 파일에는 “글씨 18px”, 다른 파일에는 “글씨 16px”이라고 적혀 있으면 AI는 어느 쪽을 따라야 할지 모릅니다. 원칙은 한 곳에만 두고, 바꿀 때는 그곳만 고칩니다.
실수가 반복되면 원칙으로 만듭니다
AI가 같은 실수를 두 번 하면 원칙으로 만들 때가 된 것입니다. “이런 실수가 다시 생기지 않게 CLAUDE.md에 적어 주세요”라고 말하세요. 시간이 갈수록 매뉴얼이 두꺼워지고, AI는 점점 그 앱을 잘 아는 동료가 됩니다.
Skills란 — 반복 작업을 묶어 두는 방법
CLAUDE.md가 “이 앱에서 늘 지킬 원칙”이라면, Skills는 “특정 작업을 하는 방법”을 묶어 둔 것입니다. 예를 들어 “블로그 글을 올릴 때는 이 순서로, 이 서식으로 한다”, “화면 사진은 이 크기로 찍는다” 같은 작업 절차를 하나의 스킬로 만들어 두면, 클로드 코드가 그 작업을 할 때 꺼내 씁니다.
스킬은 작업 폴더 안의 스킬 폴더에 SKILL.md라는 설명 파일로 들어갑니다. 파일 맨 위에 이 스킬이 무엇을 하는지 한두 줄로 적어 두면, 클로드 코드가 관련된 일을 할 때 알아서 불러 쓰고, 사용자가 이름으로 직접 부를 수도 있습니다. 이것도 직접 만들 필요 없이 요청하면 됩니다.
우리가 방금 한 "블로그 글을 서식에 맞춰 올리는 작업"을 다음에도 같은 방법으로 할 수 있게 스킬로 만들어 주세요. 언제 쓰는 스킬인지 설명도 함께 적어 주세요.
CLAUDE.md는 “늘 지킬 원칙”, Skills는 “가끔 하는 작업의 방법” 이라고 기억하면 구분이 쉽습니다. 처음에는 CLAUDE.md 하나로 충분하고, 같은 작업을 여러 번 반복하게 될 때 스킬을 만들면 됩니다.
자주 묻는 질문
CLAUDE.md는 폴더마다 따로 있어야 하나요?
네, 앱마다 원칙이 다르니 작업 폴더마다 따로 두는 것이 좋습니다. 모든 작업에 공통으로 적용할 원칙(예: 항상 한국어로 답하기)은 사용자 전체 설정 쪽에 두는 방법도 있습니다.
CLAUDE.md가 길어지면 문제가 되나요?
너무 길면 AI가 중요한 원칙을 놓칠 수 있습니다. 지켜지지 않는 원칙이 보이면 중복을 지우고, 중요한 것을 위로 올려 정리해 달라고 요청하세요.
CLAUDE.md를 단계별로 키워 가는 법
처음부터 완벽한 CLAUDE.md를 쓸 필요는 없습니다. 이렇게 자라게 하면 됩니다.
- 첫날 — “이 앱은 무엇이고 누가 쓰는지” 두세 줄만 적습니다.
- 첫 주 — 디자인을 정하면서 글씨 크기, 색, 말투 같은 화면 원칙이 생깁니다. 정해질 때마다 추가합니다.
- 첫 실수 후 — AI가 같은 실수를 두 번 하면 그 실수를 막는 원칙을 넣습니다. 예: “날짜를 영어로 쓰지 말 것”.
- 배포 후 — “자료를 지우기 전에 반드시 물어볼 것”, “비밀 열쇠를 코드에 넣지 말 것” 같은 안전 원칙을 넣습니다.
한 달쯤 지나면 CLAUDE.md만 읽어도 그 앱이 어떤 원칙으로 만들어졌는지 알 수 있게 됩니다. 사람이 이어받아도 도움이 되는 문서가 되는 셈입니다.
여러 앱에 공통 원칙을 쓰고 싶을 때
앱을 여러 개 만들다 보면 “어느 앱이든 한국어로”, “어느 앱이든 글씨는 크게”처럼 모든 앱에 공통인 원칙이 생깁니다. 이런 원칙을 앱마다 복사해 두면 나중에 바꿀 때 여러 곳을 고쳐야 하고, 하나를 빠뜨리면 앱마다 원칙이 달라집니다.
공통 원칙은 사용자 전체에 적용되는 설정 쪽에 한 번만 두고, 각 앱의 CLAUDE.md에는 그 앱에만 해당하는 원칙을 적는 것이 좋습니다. 어디에 두어야 할지 모르겠다면 “이 원칙을 모든 작업에 적용되게 저장해 주세요”라고 요청하면 됩니다.
실수에서 원칙으로 — 이렇게 쌓입니다
CLAUDE.md의 원칙은 대부분 실제 실수에서 나옵니다. 예를 들면 이런 식입니다.
- AI가 날짜를 하루 밀려서 보여 준 일이 있었다면 → “날짜는 한국 시간 기준으로 계산할 것”
- 디자인을 바꾸고 바로 공개했다가 되돌린 일이 있었다면 → “디자인 변경은 시안을 먼저 보여 줄 것”
- 성경 구절이 번역본마다 섞여 나온 일이 있었다면 → “성경은 개역개정 본문 자료에서만 가져올 것”
- 예시 화면에 실제 사람처럼 보이는 이름이 들어갔다면 → “예시에 사람 이름을 지어내지 말 것”
이렇게 실수가 생길 때마다 원칙으로 바꿔 두면, 같은 실수는 두 번 다시 반복되지 않습니다. 원칙을 적을 때는 “무엇을 하지 말 것”과 함께 “왜 그런지”를 한 줄 붙여 두세요. 이유가 있는 원칙은 AI가 비슷한 다른 상황에도 알아서 적용합니다. 반대로 이유 없는 원칙은 글자 그대로만 지켜서, 조금만 상황이 달라지면 같은 종류의 실수가 다시 나옵니다.
CLAUDE.md는 사람에게도 좋은 문서입니다
CLAUDE.md는 AI를 위한 파일이지만, 사람에게도 훌륭한 기록이 됩니다. 몇 달 뒤 앱을 다시 고칠 때, 다른 사람에게 앱 관리를 넘길 때, 이 파일 하나만 읽으면 앱이 어떤 원칙으로 만들어졌는지 알 수 있습니다. 그래서 CLAUDE.md는 짧고 분명하게, 사람이 읽어도 이해되는 말로 쓰는 것이 좋습니다.
새로운 원칙을 더할 때는 날짜를 함께 적어 두는 것도 좋습니다. 언제 왜 생긴 원칙인지 알 수 있어서, 나중에 상황이 바뀌었을 때 지워도 되는 원칙인지 판단하기 쉽습니다.
원칙이 쌓일수록 AI와의 대화는 점점 짧아지고, 결과는 점점 정확해집니다.
함께 읽으면 좋은 글: 클로드 코드 사용법, 바이브코딩 프롬프트 예시
정리
CLAUDE.md는 클로드 코드가 매번 먼저 읽는 원칙 파일이고, Skills는 반복 작업의 방법을 묶어 둔 것입니다. 원칙은 이유와 함께 한 곳에 적고, 같은 실수가 반복되면 원칙으로 옮기세요. 바이브코딩을 오래 할수록 이 두 가지가 시간을 크게 아껴 줍니다.
바이브코딩 가이드 — 함께 읽으면 좋은 글
- 바이브코딩이란? 뜻과 원리, 장단점까지 한 번에 정리
- 바이브코딩 툴 추천 — 클로드 코드 vs 커서 vs 코덱스, 처음이라면 무엇을 쓸까
- 클로드 코드 사용법 — 데스크탑 설치부터 첫 앱 만들기까지
- 바이브코딩 순서 — 아이디어에서 완성까지 6단계
- 바이브코딩 프롬프트 예시 — AI가 한 번에 알아듣는 요청 쓰는 법
- 바이브코딩 디버깅 — 오류가 날 때 AI에게 말하는 법
- 클로드 코드 CLAUDE.md와 Skills 사용법 — AI에게 원칙을 기억시키는 법
- 챗GPT 이미지 생성 프롬프트 작성법 — 앱·블로그에 쓸 그림 만들기
- 바이브코딩 배포 방법과 보안 주의사항 — 만든 앱을 안전하게 공개하기
- 바이브코딩 사례 — 코딩 없이 만든 교회·사역 앱 8가지
