Andrej Karpathy는 AI 코딩 도구를 쓸 때 "도구에게 컨텍스트를 반복 설명하는 시간이 가장 큰 낭비"라고 했다. 그가 강조하는 핵심은 단순하다. 한 번 잘 써놓은 가이드가 100번의 프롬프트를 대체한다. Claude Code에는 이걸 실현할 수 있는 세 가지 레이어가 있다.

세 가지 방식 비교

1. CLAUDE.md — 프로젝트 상주 가이드

프로젝트 루트에 CLAUDE.md를 두면 Claude Code가 해당 디렉토리에서 세션을 시작할 때 자동으로 시스템 프롬프트에 주입한다. 매번 설명하지 않아도 된다.

가장 효과적인 경우:

• 프로젝트 구조, 아키텍처, 파일 역할 설명
• "항상 이렇게 해줘" 수준의 행동 규칙 (코멘트 최소화, 추가 기능 금지 등)
• 반복적으로 설명해야 했던 것을 발견했을 때 즉시 추가
• 팀 프로젝트에서 git으로 공유 가능

2. 직접 파일 추가 — .claude/commands/ 커스텀 Skills

.claude/commands/ 폴더에 마크다운 파일을 두면 /파일명으로 호출할 수 있는 슬래시 커맨드가 된다. 특정 작업 패턴을 재사용할 때 쓴다.

# .claude/commands/blog.md
  오늘 작업한 git diff를 분석해서 한국어 개발자 블로그 포스트를 작성해줘.              
  구성: 개요 → 변경 상세 → 회고 → 태그 5개                                             
  형식: Markdown                                                                       
  

이렇게 두면 /blog 한 번으로 위 프롬프트가 실행된다.

가장 효과적인 경우:

• 반복적으로 쓰는 작업 시퀀스 (블로그 작성, 커밋 메시지 생성, 코드 리뷰 등)
• 출력 형식이 정해진 작업 (HTML 블로그, 릴리즈 노트 등)
• 개인 전용이라 git 공유가 필요 없는 워크플로우

3. MCP 서버 — 플러그인 설치 방식

Model Context Protocol(MCP)은 외부 도구를 Claude에 연결하는 표준 프로토콜이다. Figma, Notion, 사내 API, 데이터베이스 등 외부 시스템과 연동할 때 사용한다.

가장 효과적인 경우:

• Claude가 직접 조회해야 하는 외부 데이터가 있을 때 (Linear 티켓, Slack 메시지 등)
• 여러 프로젝트에 걸쳐 공통으로 쓰는 도구 (사내 공통 API 등)
• 파일 시스템 밖에 있는 컨텍스트가 필요할 때

CLAUDE.md를 쓰는 올바른 방법

처음부터 완벽하게 쓰려고 하면 오히려 안 쓰게 된다. Karpathy 식으로 접근하면 이렇다:

"Claude에게 같은 걸 두 번 설명했다면, 그건 CLAUDE.md에 들어가야 한다."

실제 효과 있는 항목 유형:

• 아키텍처 사실 — 타겟 구성, 공유 파일 목록, 데이터 흐름
• 알려진 이슈 — SourceKit false positive처럼 도구 자체의 노이즈
• 행동 규칙 — "코멘트 금지", "요청 범위 밖 리팩터링 금지"
• 금지 사항 — "절대 `.strings` 파일 만들지 말 것, AppStrings 사용"

넣으면 안 되는 것:

• git으로 확인할 수 있는 것 (최근 변경 내역, 누가 뭘 했는지)
• 코드 읽으면 알 수 있는 것 (함수 설명, 변수 역할)
• 자주 바뀌는 임시 상태

성능 저하 구간과 보정 방법

Claude는 코드 작업에 특화되어 있다. 블로그 작성, 마케팅 문구, 감성적인 회고 같은 "창작 업무"에서는 코드 작업 대비 결과물이 밋밋하게 나오는 경우가 있다.

문제 패턴

• 블로그 글이 기술 문서처럼 딱딱하게 나옴
• 회고 섹션이 bullet point 나열로 끝남
• 요청할 때마다 톤이 다름

보정 방법 1 — 커스텀 Skill에 페르소나 고정

# .claude/commands/blog.md
  ## 역할                                                                              
  너는 iOS 독립 개발자다. 기술적으로 정확하지만
  개발 과정의 고민과 결정 이유를 솔직하게 공유하는 스타일로 쓴다.                      
                                                                                       
  ## 형식                                                                              
  - 개요: 왜 이 작업을 했는지 (what이 아니라 why)                                      
  - 상세: 코드 스니펫 포함, 변경 전후 비교                                             
  - 회고: 잘못된 시도 포함, 최종 결론까지의 과정                                       
  - 태그: 5개                                                                          
                                                                                       
  ## 금지                                                                              
  - "~했습니다" 격식체 금지, "~했다" 평어체 사용
  - 변경 사항 단순 나열 금지                                                           
  

보정 방법 2 — CLAUDE.md에 출력 스타일 명시

## 글쓰기 스타일 (블로그, 문서 작성 시)
  - 평어체 사용 (~했다, ~이다)                                                         
  - 결론 먼저, 이유 나중                                                               
  - 실패한 시도도 포함할 것                                                            
  - 기술 용어는 처음 한 번만 설명                                                      
  

보정 방법 3 — 회피: 단순 작업은 분리

블로그처럼 창작 비중이 높은 작업은 Claude Code보다 claude.ai 웹에서 별도 대화로 쓰는 게 나을 수 있다. 코드 컨텍스트 없이 글쓰기 모드로만 집중시킬 수 있기 때문이다. Claude Code는 코드 + 파일 조작에, 웹 Claude는 문서 작성에 역할을 나누는 전략이다.

정리 — 언제 뭘 쓸 것인가

• 프로젝트를 처음 시작할 때 → CLAUDE.md 먼저 작성
• "이걸 두 번 설명했다" 싶을 때 → CLAUDE.md에 즉시 추가
• 반복하는 작업 패턴이 생겼을 때 → 커스텀 Skill로 템플릿화
• 외부 시스템 데이터가 필요할 때 → MCP 서버 연동 검토
• 창작/문서 작업이 밋밋하게 나올 때 → Skill에 페르소나·스타일 고정, 또는 웹 Claude 분리