CLAUDE.md 작성 가이드 — AI 팀원 매뉴얼 쓰는 법
CLAUDE.md가 무엇이고, 무엇을 담아야 하며, 어떻게 작성해야 AI가 일관된 '팀원'으로 행동하는지를 정리한 작성 가이드
한 줄 요약
CLAUDE.md는 "AI 팀원에게 매번 말하지 않아도 지켜야 할 것" 을 한 곳에 모은 파일입니다. 역할·톤·금지·선호·컨텍스트가 여기 들어가면 모든 Skill이 같은 성격으로 일합니다.
CLAUDE.md 가 뭐고 왜 필요한가
문제 상황
같은 Skill을 두 번 돌렸는데 결과가 다릅니다:
- 첫 번째: "안녕하십니까, 고객님." (딱딱한 공식체)
- 두 번째: "안녕하세요~" (친근체)
Skill 본문에는 분명 "정중한 톤으로 답변"이라 써 있는데 왜 바뀔까요? "정중"이라는 단어가 사람마다 해석이 다르기 때문입니다. 공식 문서에서 정중 ≠ 친근 채팅에서 정중.
해결: CLAUDE.md
CLAUDE.md 는 조직의 "정중함"이 구체적으로 무엇인지 정의하는 문서입니다. 일단 한 번 써두면 Claude는 모든 Skill 실행에서 이 파일을 읽고 일관되게 행동합니다.
비유: 신입 직원에게 매번 "우리 회사 말투는 이렇고, 이런 단어는 쓰지 마세요, 외부에는 이렇게 답하세요"라고 말하는 대신 직원 매뉴얼 한 권을 주는 것.
무엇을 담는가 — 7 섹션 템플릿
flowchart LR C[CLAUDE.md] --> I[1. 정체성·역할] C --> T[2. 톤·말투] C --> P[3. 페르소나 금지 규칙] C --> V[4. 우리 도메인 용어] C --> F[5. 선호 양식] C --> X[6. 컨텍스트 출처] C --> E[7. 예외·에스컬레이션]
1. 정체성·역할
당신의 AI가 누구인지를 한 문장으로.
나는 [조직명] [부서명]의 AI 팀원이다.
내 주된 업무는 [예: 회원 문의 응대 초안 작성과 일일 시장 브리핑 정리].
나는 사람의 판단을 대체하지 않고 **초안**을 만들며, 최종 결정은 담당자가 한다.2. 톤·말투
## 톤
- 공식체를 기본으로 한다. (~습니다, ~입니다)
- 회원·고객에게는 공감 1문장을 먼저 쓴다.
- 내부 동료 대상 메모는 반말 허용.
- 이모지 사용 금지.
- 느낌표 남발 금지 (한 답변에 1개 이하).3. 페르소나 금지 규칙
## 금지
- 법적 해석은 단정하지 않는다. "세무사·변호사 확인 권장"을 덧붙인다.
- 수치·날짜는 원문 확인 없이 생성하지 않는다. 모르면 "확인 필요"로 표시.
- 고객사 실명 노출 금지. 대신 {{company}} 플레이스홀더 사용.
- "죄송"의 남발 금지. 문제 상황에서만 사용.4. 우리 도메인 용어
## 용어
- "회원" = 공제회 가입자. 외부 "고객" 과 구분.
- "급여" = 공제급여 (월급 아님).
- "팔로업" = 후속 대응. "F/U" 축약 가능.
- "AS 방식" = 우리 내부 분류명. 외부에 이 단어 쓰지 않음.5. 선호 양식
## 양식
- 회신 메일: 제목 / 인사 1줄 / 요지 1줄 / 본문 3~5줄 / 서명
- 요약: 한 장 1000자 이내. 소제목 있는 불릿.
- 표: 정렬은 항상 의미 있는 순서 (날짜·금액·우선순위)6. 컨텍스트 출처
## 컨텍스트
- FAQ: /faq.md
- 응대 매뉴얼: /ops/response-manual.md
- 법적 면책 표현: /ops/disclaimers.md
- 고객사 DB: env:CLIENT_DB_PATH (환경변수)AI가 "근거가 어디에 있는지" 알아야 스킬이 그 파일을 자동으로 읽어 컨텍스트에 넣을 수 있습니다.
7. 예외·에스컬레이션
## 에스컬레이션
- 긴급도가 '높음' 이상이면 담당자에게 즉시 알림
- 법령 해석이 모호하면 '법무팀 검토 필요' 태그를 달고 전달
- 고객이 반복 불만을 제기하면 자동 응답 대신 사람에게 전달좋은 CLAUDE.md vs 나쁜 CLAUDE.md
나쁜 예 (추상적)
- 정중하게 답변한다
- 고객을 존중한다
- 실수하지 않는다→ Claude는 "정중"이 무엇인지 알 수 없습니다. 결과는 매번 다릅니다.
좋은 예 (구체적)
- 회신은 "안녕하세요, {{name}}님." 으로 시작한다. "고객님" 단독 호칭 금지.
- 첫 문장은 공감 표현: "불편을 겪으셨다니 죄송합니다" / "문의 주셔서 감사합니다"
- 수치·날짜가 들어갈 때는 항상 출처 링크 또는 FAQ 번호를 본문 끝에 붙인다.
- 마무리는 "추가로 궁금하신 점이 있으시면 회신 주세요." 로 통일.→ Claude는 정확히 이 규칙을 따릅니다. Before/After 비교에서 즉시 차이가 보입니다.
어디에 두는가
| 상황 | 위치 |
|---|---|
| 개인 PC(Desktop) | 작업 폴더 루트에 CLAUDE.md |
| Cowork 팀 공유 | Cowork 프로젝트의 루트에 업로드 |
| 프로젝트별로 다르게 | 프로젝트 폴더 각각에 별도 파일 |
| 전사 공통 + 부서 추가 | 상위 CLAUDE.md + 하위 CLAUDE.md (하위가 상위를 오버라이드) |
첫 CLAUDE.md 만들기 — 15분 워크숍
- 정체성 1문장 쓰기 (2분)
- 톤 규칙 3개 고르기 (3분). 기존 좋은 답변 1개를 예시로 붙여 넣기
- 금지 규칙 3개 정하기 (3분). 실제로 당했던 실수에서 뽑기
- 용어 5개 정의 (2분). 우리만 쓰는 단어 위주
- 양식 1개 만들기 (3분). 가장 자주 쓰는 문서 형식
- Skill 1개에 연결해 테스트 (2분). Before/After 차이 체감
자주 묻는 질문
Q. CLAUDE.md가 너무 길어지면 어떻게 되나요?
A. 매 Skill 호출마다 Claude의 컨텍스트 창 일부를 차지합니다. 일반적으로 1000~3000자 사이가 적정입니다. 그 이상 필요하면 여러 파일로 쪼개고 Skill에서 필요한 것만 지정해 읽도록 합니다.
Q. SKILL.md 랑 CLAUDE.md는 어떻게 다르죠?
A. SKILL.md = 이 스킬이 무엇을 어떻게 하는가(작업 지시서). CLAUDE.md = 모든 스킬이 공통으로 지켜야 할 태도(직원 매뉴얼). Skill은 바뀌지만 매뉴얼은 안정적입니다. 팀이 같으면 CLAUDE.md는 한 벌, Skill은 수십 벌.
Q. 담당자마다 톤 취향이 달라요. 어떻게 합치나요?
A. 톤은 "취향"이 아니라 "조직 규칙"으로 결정해야 합니다. 두 톤이 대립하면 실제 고객 피드백 데이터(몇 건이 좋았고 나빴는지)를 기준으로 합치세요. 합의가 안 되면 임시로 한 톤을 2주간 운영 후 리뷰 방식이 가장 빠릅니다.
다음 읽을거리
변경 이력
- v1 (2026-04-11): 최초 작성 — Claude@IGM Cohort 1 교재용