CLAUDE.MD & SKILL.MD
AI에게 기억을 심는 방법
CLAUDE.md 와 SKILL.md
매번 같은 설명을 반복하고 있다면, 그건 AI를 제대로 쓰는 게 아니다.
파일 하나로 AI의 기억을 영구화하는 방법을 정리한다.
Claude Code는 강력하다. 코드를 짜고, 서버에 배포하고, 파일을 수정하고, 터미널까지 조작한다. 그런데 치명적인 약점이 있다.
대화가 끝나면 모든 걸 잊는다.
어제 알려준 서버 주소, 어제 합의한 코딩 규칙, 어제 설명한 프로젝트 구조. 오늘 새 대화를 열면 Claude는 완전히 처음 만난 사람처럼 행동한다. 그래서 매번 같은 설명을 반복하게 된다.
이 반복을 끊기 위해 등장한 것이 CLAUDE.md와 SKILL.md다. 파일에 기록해두면, Claude는 매번 그 파일을 읽고 시작한다. 마치 새 직원이 출근할 때마다 업무 매뉴얼을 펼쳐보는 것처럼.
CLAUDE.md는 프로젝트의 신원 증명서다. Claude Code가 실행될 때 자동으로 읽는 파일이며, 여기서 환경·구조·규칙을 파악한다.
CLAUDE.md에는 두 가지 레벨이 있다.
위치: C:\Users\user\CLAUDE.md
서버 접속 정보, 개인 코딩 스타일, SSH 키 경로처럼 모든 작업에 공통으로 필요한 내용. 한 번만 써두면 어떤 프로젝트에서 Claude Code를 열어도 자동으로 읽힌다.
위치: 프로젝트폴더/CLAUDE.md
해당 프로젝트의 폴더 구조, DB 스키마, 배포 명령, 주의사항 등 그 프로젝트만의 내용. 같은 서버에 여러 프로젝트가 있어도 각자 다른 내용을 가질 수 있다.
# **CRM 프로젝트 ## 서버 접속 ssh -i "C:\Users\user\downloads\*******.pem" ubuntu@xx.xx.xx.xx ## 프로젝트 구조 - 경로: /home/ubuntu/*****-crm-web - DB: SQLite (MySQL 아님, 혼동 주의!) - PM2 프로세스명: *****-crm ## 배포 후 필수 실행 pm2 restart *****-crm && pm2 logs *****-crm --lines 20 ## 주의사항 - 한글 포함 파일: cp949 인코딩 주의 - heredoc 대신 sed 명령어 사용
SKILL.md는 작업 전문 매뉴얼이다. CLAUDE.md가 “어디서 일하는지”를 알려준다면, SKILL.md는 “어떻게 일하는지”를 알려준다.
예를 들어 Word 문서(.docx)를 만드는 작업을 생각해보자. Claude는 python-docx 라이브러리를 쓸 줄 안다. 그런데 막상 만들면 한글이 깨지거나, 파일이 엉뚱한 곳에 저장되거나, 설치 명령이 틀려서 실패하는 경우가 생긴다. 이런 시행착오를 겪고 나서 “아, 이 환경에서는 이렇게 해야 되는구나”를 파일로 기록해둔 것이 SKILL.md다.
## Word 문서 생성 SKILL ### 라이브러리 설치 pip install python-docx --break-system-packages # --break-system-packages 옵션 필수 (이 환경 특성) ### 한글 폰트 처리 # 기본 폰트로 하면 한글 깨짐 → 반드시 지정 run.font.name = '맑은 고딕' ### 출력 경로 # 항상 이 경로에 저장해야 사용자가 다운로드 가능 /mnt/user-data/outputs/파일명.docx ### 표준 절차 1. 이 SKILL.md 먼저 읽기 2. 라이브러리 설치 확인 3. 한글 폰트 지정하여 문서 생성 4. outputs 폴더에 저장 5. present_files 로 사용자에게 전달
| 구분 | CLAUDE.md | SKILL.md |
|---|---|---|
| 한 줄 정의 | 환경 · 맥락 전달 | 작업 노하우 전달 |
| 읽히는 시점 | 자동 대화 시작 시 | 수동 해당 작업 시 |
| 담는 내용 | 서버 정보, 폴더 구조, 코딩 규칙, 주의사항 | 라이브러리, 절차, 검증된 예시 코드 |
| 비유 | 회사 입사 안내서 | 작업별 전문 매뉴얼 |
| 적용 범위 | 해당 프로젝트 전체 | 특정 작업 유형 |
| 재사용 | 프로젝트 내 고정 | 여러 프로젝트 공유 가능 |
처음 접하면 낯선 확장자다. .md는 Markdown의 약자로, 특별한 기호 몇 가지로 서식을 표현하는 텍스트 파일이다.
메모장으로 열면 그냥 텍스트 파일이다. 단지 #으로 제목을,
-으로 목록을 표현하는 약속이 있을 뿐이다.
## 소제목
– 항목1
– 항목2
**굵게**
• 항목2
AI가 .md를 선호하는 이유는 단순하다. 구조가 명확하고, 어떤 텍스트 편집기로도 열 수 있고, AI가 파싱하기 쉽기 때문이다. Word처럼 복잡한 바이너리 형식이 아니라 순수 텍스트라서, 읽는 속도도 빠르다.
C:\Users\user\CLAUDE.md로 저장. 이것만 해도 절반은 완성이다.
# **세무회계 Claude 공통 설정 ## 서버 접속 PEM 키: C:\Users\user\downloads\*******.pem # WordPress ssh -i "C:\Users\user\downloads\*******.pem" bitnami@xx.xx.xx.xx # XXCRM ssh -i "C:\Users\user\downloads\*******.pem" ubuntu@xx.xx.xx.xx # NAS — VPN 연결 필수! ssh vxxxxx@192.xxx.x.xxx -p 9*** ## 코딩 규칙 - 주석: 한국어 - 한글 bash: heredoc 대신 sed 사용 - 인코딩: UTF-8 (cp949 주의) ## 절대 주의 - **CRM DB = SQLite (MySQL 아님) - NAS 작업 전 VPN 연결 상태 확인
AI 도구를 쓰면서 “왜 매번 같은 말을 해야 하지?” 싶은 답답함이 생긴다면, 그건 AI의 문제가 아니라 기억을 심어주지 않은 것이다.
이 규칙대로 일해줘”
이렇게 하는 거야”
둘 다 결국 같은 원리다. AI에게 말로 설명하는 대신 파일로 기록한다. 파일은 휘발되지 않는다. 오늘 쓴 내용이 내일도, 한 달 후에도 그대로 읽힌다. 한 번의 기록이 수십 번의 반복 설명을 대신한다.
