내 AI에게 나를 알려주는 한 장 — CLAUDE.md
양식 한 장을 채워 「나는 누구·원칙·금지·말투」를 파일로 만들고, 비밀값은 이 파일 밖에 둔다는 한 가지 규칙만 함께 익힌다.
이 노드가 끝나면 이 노드를 마치면 내 CLAUDE.md 초안 한 장을 가지고, 세션을 새로 열어도 설명을 되풀이하지 않게 된 것을 확인한다.
재방문 키 지도 L3-②, 검색어 ‘claude-md’
유능한 신입사원을 온보딩하듯 AI에게 회사(나)를 알려준다.
글
양식 한 장의 빈칸을 채워 「나는 누구 · 일하는 원칙 · 넘지 말아야 할 선 · 말투」를 파일로 만들고, 비밀값은 이 파일 밖에 둔다는 규칙 하나를 함께 익힙니다. 파일 만들기는 메모장 하나면 누구나 할 수 있고, 새 세션에서 자동으로 읽히는지 보는 확인은 폴더를 읽는 에이전트형 도구가 있을 때 합니다.
어제 자세히 설명했는데, 오늘 새 대화를 열면 AI가 처음 보는 사람처럼 굴지 않습니까? 무능해서가 아니라, 세션을 새로 열면 작업 기억이 리셋되는 구조이기 때문입니다.
이 칸을 마치면 나를 알려주는 CLAUDE.md 초안 한 장이 생깁니다. 그리고 새 세션을 열어도 설명을 되풀이하지 않게 된 것을 확인합니다.
CLAUDE.md는 특별한 프로그램 없이 쓰는 텍스트 한 장입니다. 작업 폴더 맨 위에 이 이름으로 두면, 에이전트형 AI가 그 폴더에서 일을 시작할 때마다 가장 먼저 읽습니다. 신입사원 연수와 같습니다. 연수를 거치지 않은 신입은 자꾸 다른 회사 방식을 가져옵니다.
양식은 네 칸입니다. 나는 누구인가, 일하는 원칙, 넘지 말아야 할 선, 그리고 말투입니다. 칸마다 미리 써 둔 기본 줄이 있어서 빈칸만 채우면 되고, 두세 줄이면 충분합니다.
규칙은 하나만 함께 익힙니다. API 키나 비밀번호 같은 비밀값은 이 파일에 적지 않습니다. 이 파일은 세션마다 읽히고, 남에게 보여 줄 일도 생기기 때문입니다. 필요하면 별도 설정 파일에 있다는 위치만 적습니다.
처음 하는 분이 막히는 곳은 이름과 자리입니다. 파일 이름이 정확히 CLAUDE.md이고, 일을 시작하는 그 폴더 안에 있어야 읽힙니다.
다음 칸에서는 템플릿으로 역할 선언 하나를 오늘 업무에 써 봅니다. 해 보다가 막히면 이 페이지 아래 묻기 칸에 남겨 주십시오.
한 장은 무엇인가
- 텍스트 한 장입니다. MD는 마크다운의 줄임말이고, 「양식 없는 메모장 문서」라고 보면 됩니다.
- 작업 폴더 맨 위에
CLAUDE.md라는 이름으로 두면, 에이전트형 AI가 그 폴더에서 일을 시작할 때마다 가장 먼저, 자동으로 읽습니다. - 그 폴더 안에서만 작동합니다. 다른 폴더를 열고 일을 시작하면 읽히지 않습니다.
- 무엇부터 적을까 막히면 이렇게 묻습니다 — 「지금 내가 매번 말로 반복하는 설명은 무엇인가?」 그것이 1순위입니다.
비유: 신입사원 책상 위의 업무 매뉴얼. 출근하면(세션을 열면) 무조건 이것부터 읽습니다. 다만 유능한 신입일수록 좋은 상사의 확인이 필요합니다 — 도장까지 맡기지는 않습니다.
양식 네 칸
| 칸 | 묻는 것 | 빈칸 |
|---|---|---|
| 나는 누구인가 (정체성) | 나는 누구이고 무엇을 위해 일하는가 | 「나는 ___ 이다」 · 「내가 이 일을 하는 목적은 ___ 이다」 |
| 일하는 원칙 (원칙) | 시간이 없을 때 무엇을 버리고 무엇을 지키는가 | 「시간이 없을 때 나는 을 먼저 버리고, 은 끝까지 지킨다」 |
| 넘지 말아야 할 선 (경계) | 절대 맡기면 안 되는 일 · 반드시 내 승인이 필요한 일 | 두 줄 |
| 말투 | 내 글은 남의 글과 무엇이 다른가 | 존댓말/반말 · 내 글의 특징 |
칸마다 미리 써 둔 기본 줄이 있어서 빈칸만 채우면 됩니다. 두세 줄이면 충분합니다. 양식 전체는 CLAUDE.md 양식 한 장에 있습니다.
경계 칸은 「맡기되, 도장은 사람이 찍는다」를 내 일로 옮긴 칸입니다. 환자에게 나가는 최종 설명, 성적, 사람에 대한 평가처럼 「최종」과 「사람」이 들어간 일이 여기 들어갑니다.
비밀값은 이 파일 밖에 — 이 칸의 규칙 하나
API 키 · 토큰 · 클라이언트 ID · 사용자 ID 같은 인증 정보는 CLAUDE.md에 직접 적지 않습니다. 인증 정보는 별도의 설정 파일에만 두고, CLAUDE.md에는 그 파일의 위치만 적습니다.
| 까닭 | 설명 |
|---|---|
| 세션마다 읽힌다 | AI가 파일을 읽어 답을 만들 때 그 내용은 AI 서비스의 서버로 전송됩니다. 공개 웹에 올라가는 것은 아니지만 서비스 제공자에게는 보입니다. 매 세션 가장 먼저 읽히는 파일에 비밀을 적으면 세션마다 그 값을 보내는 셈입니다. |
| 보여 줄 일이 생긴다 | 이 한 장은 남에게 보이거나 화면에 띄울 일이 생깁니다. 저도 화면에 보일 때는 원본 대신 비밀의 위치와 개인 일정을 뺀 판을 따로 만들어 띄웠습니다. |
| 파일은 같이 간다 | 키를 코드에 적으면 코드를 올리는 저장소에 같이 올라갑니다. 지시 문서도 폴더째 옮기거나 공유하면 같이 갑니다. |
- 그 설정 파일은 노트 폴더 밖, AI에게 연결하지 않은 별도 설정 폴더에 둡니다. 지울 필요는 없습니다 — 연결 범위에서 빼는 것으로 충분합니다.
- 한 번 밖으로 나간 비밀값은 되돌릴 수 없습니다. 그래서 이 규칙 하나만은 처음부터 지킵니다.
- 첫 번째 자물쇠는 붙여넣기 전의 내 손입니다. 규칙은 유출을 막는 것이 아니라 실수를 잡습니다.
경계 칸에 넣을 한 줄(가공 경로):
비밀번호 · API 키 · 토큰 같은 인증 정보는 이 파일에 적지 않는다.
필요하면 ~/.local/share/atlas-demo/config.json 에 있다는 위치만 적는다.
제 실물
화면에 보이려고 따로 깎아 만든 제 한 장도 같은 네 칸이고, 칸마다 3~4줄, 전체 30줄입니다.
## 나는 누구인가
임상의. 진료와 개발 프로젝트를 병행한다.
목적: 도구 자체가 아니라, 모델을 나누고 확산하는 것.
## 일하는 원칙
핵심부터 간결하게. 불필요한 서론·맺음말·반복 요약 금지.
불확실하면 추측하지 말고 질문한다. 가정은 명시한다.
결과는 사실대로 — 실패·생략·미검증을 그대로.
새 최상위 폴더를 만들 때는 먼저 확인한다.
## 넘지 말아야 할 선
인증 정보(API 키·비밀번호·개인 식별번호)는 어떤 문서에도 기재하지 않는다.
개인정보가 담긴 자료는 문서에 평문으로 남기지 않는다 — 경로 참조만.
되돌리기 어려운 일은 사람이 최종 확인한다.
회의록 인용은 원문 그대로만.
## 말투
답변은 항상 존댓말.
한국어로 답하되 코드·파일명·기술 용어는 영어 유지.
표는 짧은 사실 나열에만, 설명은 문장으로.
- 양식의 원칙 기본 줄 두 개(질문하라 · 사실대로)는 제가 모든 작업에 거는 원칙에서 옮겨 온 문장입니다.
- 이 한 장도 처음부터 완성된 것이 아닙니다. 제 전역 지침은 코딩 태도 한 절(약 2KB)에서 시작해, 몇 차례에 걸쳐 절이 붙어 지금은 세 절(약 6KB)입니다.
채팅형만 있을 때
자동으로 읽히는 것은 폴더를 읽는 에이전트형 도구의 일입니다. 채팅형만 있다면 CLAUDE.md를 메모장으로 열어 전체를 복사해 새 대화 맨 앞에 붙입니다. 이때는 「자동으로 먼저 읽힌다」가 아니라 붙인 그 대화 안에서만 읽힙니다.
더 읽기
- 가져갈 자료: CLAUDE.md 양식 한 장 — 네 칸 · 빈칸 · 기본 줄 · 비밀값 한 줄.
- 앞 칸: AI에게 나를 세 줄로 — 역할·환경·말투 — 설치 없이 채팅창 맨 앞에 붙이는 세 줄.
- 다음 칸: 템플릿으로 시작하기 — 역할 선언 하나를 오늘 업무에.
- 같은 칸: 셋업 체크리스트 — 다섯 걸음 — 결제 → 설치 → 첫 설정 → 파일 한 장 → 말 걸기. 이 한 장은 그 넷째 걸음입니다.
- 깊은 칸: 정체성·원칙·경계·말투의 실물 — 어디서 열어도 같은 태도(전역)와 그 폴더의 규칙(프로젝트)을 두 장으로 나누고, 규칙 머리에 「적용 범위」를 먼저 적습니다.
- 늘 지킬 규칙은 이 한 장에, 가끔 시키는 작업의 절차는 다른 자리에 둡니다. 판단 기준은 「항상 지킬 규칙인가, 가끔 시키는 작업인가」입니다.
가져갈 자료
- claude_md_form.md 2 KB
해보기
해보기 (10분)
처음에는 컴퓨터 한 대를 정해 거기서만 합니다. 여러 대에서 맞추는 일은 나중에 필요해질 때 합니다.
① 파일 만들기 — 누구나 (메모장만 있으면 됩니다)
- 폴더 하나 — 컴퓨터에 작업 폴더를 하나 만든다(가공 예:
my-ai-workroom). - 양식 넣기 — CLAUDE.md 양식 한 장을 그 폴더 맨 위에 넣고, 이름을 정확히
CLAUDE.md로 바꾼다. - 빈칸 채우기 — 텍스트 편집기로 열어 네 칸(나는 누구인가 · 일하는 원칙 · 넘지 말아야 할 선 · 말투)의 빈칸을 채운다. 칸마다 두세 줄이면 충분하다. 막히면 「지금 내가 매번 말로 반복하는 설명은 무엇인가?」부터 적는다.
- 비밀값 확인 — 저장하기 전에 파일 전체를 한 번 훑는다. API 키 · 비밀번호 · 토큰 같은 값이 있으면 지우고, 필요하면 「별도 설정 파일에 있다」는 위치만 남긴다.
② 자동으로 읽히는지 확인 — 폴더를 읽는 에이전트형 도구가 있을 때
- 폴더 지정 — 에이전트형 데스크톱 앱에서 1번 폴더를 작업 폴더로 지정하고 새 세션을 연다. (설치와 첫 설정은 셋업 체크리스트 — 다섯 걸음에서 다룬다.)
- 물어보기 — 새 세션에서 아무 설명 없이 이렇게 묻는다.
이 폴더에서 일할 때 내가 누구이고, 무엇을 맡기면 안 되고, 어떤 말투로 답해야 하는지 세 줄로 말해 줘.
에이전트형 도구가 아직 없다면 — 5·6번 대신 CLAUDE.md를 메모장으로 열어 전체를 복사하고, 채팅창의 새 대화 맨 앞에 붙인 뒤 6번 질문을 한다. 이때는 자동으로 먼저 읽히는 것이 아니라, 붙인 그 대화 안에서만 읽힌다.
실물에서는 이렇게 보입니다
- 영상(모션)에서는 「폴더 맨 위의
CLAUDE.md한 장 → 새 세션 → AI가 그 장을 먼저 읽고 답한다」가 한 화면에 나온다. 내 화면에서는 파일을 만드는 곳(폴더 창)과 묻는 곳(에이전트형 앱)이 다른 창이다. - 한 장은 특별한 프로그램 없이 텍스트 편집기로 열리는 텍스트 문서다.
- 맥: Finder에서 폴더를 만든다. 가공 예 위치는
~/atlas/my-ai-workroom/, 한 장은~/atlas/my-ai-workroom/CLAUDE.md. - 윈도우: 탐색기에서 폴더를 만든다. 가공 예 위치는
%USERPROFILE%\atlas\my-ai-workroom\, 한 장은%USERPROFILE%\atlas\my-ai-workroom\CLAUDE.md. 메모장으로 열어 채운다. - 폴더 지정은 두 운영체제 모두 에이전트형 앱의 화면에서 한다.
- 이 칸에는 셸 명령이 없다.
「됐다」
- 폴더 맨 위에
CLAUDE.md한 장이 보이고, 네 칸이 채워져 있고, 그 안에 비밀값이 없다 → 초안은 됐다. - 새 세션에서 내가 설명하지 않았는데도, 6번 질문의 답이 내 양식의 정체성 · 경계 · 말투와 맞게 화면에 나온다 → 됐다.
- 세션을 닫고 한 번 더 열어 같은 질문을 해도 같은 답이 나온다 → 새 세션에서도 설명을 되풀이하지 않게 된 것이다.
- 답이 양식과 어긋나면 함정의 이름과 자리부터 확인한다.
🔴 함정
처음 하는 사람이 겪는 막힘 — 하나.
파일을 만들었는데 AI가 읽지 않는다
이름은 정확히 CLAUDE.md, 자리는 일을 시작하는 그 폴더의 맨 위.
이 한 장은 놓인 작업 폴더에서 일을 시작할 때만 읽힌다. 양식 파일 이름을 그대로 두었거나, 파일을 작업 폴더가 아닌 곳에 두었거나, 다른 폴더를 열고 일을 시작하면 읽히지 않는다. 처음 하는 사람이 묻고도 이해하지 못한 지점이 이 「위치」였다(강의 관찰, 가공).
대응: 폴더 창에서 파일 이름이 CLAUDE.md인지, 폴더 맨 위에 있는지 본다. 에이전트형 앱에서 지정한 작업 폴더가 그 폴더인지 확인하고, 새 세션을 열어 해보기 6번 질문을 다시 한다.
막혔을 때 먼저 볼 것
이 칸에서 막힌 것 묻기
답은 이 칸의 FAQ에 익명으로 올라갑니다(보통 7일 안). 연락처를 남기면 직접도 보냅니다. 이메일 수집·로그인 없음.