안드레 카파시의 비밀: CLAUDE.md에 절대 쓰면 안 되는 3가지! 😲

클로드 MD, 제대로 쓰고 있니? AI 코딩 도우미를 위한 완벽 가이드

클로드 MD, 이거 진짜 효과 있는 거 맞아? 한국어로 써도 영어로 답하고, 건드리지 말라는데 자꾸 건드리고... 그러다 보면 클로드 MD가 500줄짜리 매뉴얼이 되어버린 경험, 다들 있을 거야. 그런데 말이지, 많은 사람들이 클로드 MD를 잘못 쓰고 있대.

클로드 MD는 사람이 읽는 설명서가 아니야! AI가 똑같은 실수를 반복하지 않도록 막아주는 가드레일인 거지. 이걸 이해하면 클로드 MD를 훨씬 짧고 정확하게 쓸 수 있고, 결과물도 훨씬 좋아질 거야.

클로드 MD, 어디에 써야 할까? (4가지 위치)

클로드 MD는 딱 한 곳에만 있는 게 아니야. 클로드 코드는 네 군데에서 클로드 MD를 가져와.

1. 전역 클로드 MD (~/.config/claude/claude.md): 모든 프로젝트에 공통으로 적용되는 개인적인 노트나 규칙을 적어두는 곳이야. 나만의 코딩 스타일이나 선호하는 소통 방식을 적어두면 좋겠지.
2. 팀 공유 클로드 MD (<repository_name>/claude.md): 팀 전체가 알아야 할 코드 컨벤션, 빌드나 테스트 명령어 같은 규칙을 적어두는 곳이야. 팀원 모두가 같은 규칙을 따르도록 도와줘.
3. 로컬 클로드 MD (claude.local.md): 나만 보는 임시 메모나 비밀 토큰 같은 걸 적어두는 곳이야. 이건 깃에 커밋하거나 푸시할 때 포함되지 않도록 .gitignore에 추가하는 게 좋아.
4. 서브디렉토리 클로드 MD (<subdirectory>/claude.md): 루트 디렉토리의 클로드 MD가 너무 길어질 때, 특정 폴더나 패키지에만 적용되는 규칙을 따로 만들어두는 곳이야. 모노레포에서 패키지별로 다른 규칙이 필요할 때 유용해.

이 네 가지 클로드 MD는 매번 요청마다 자동으로 합쳐져서 클로드에게 전달돼. 위에서 아래로 갈수록 더 우선순위가 높아지니까, 규칙이 충돌하면 아래쪽에 있는 규칙이 이긴다고 생각하면 돼.

클로드 MD, 어떻게 써야 할까? (핵심 원칙)

• 코드로 알 수 있는 건 쓰지 마!: 클로드는 코드를 읽을 수 있어. 그래서 "리액트 사용", "소스 폴더에 컴포넌트 있음" 같은 건 쓰지 마. 대신, 코드로 알 수 없는 함정이나 규칙, 자주 발생하는 실수를 적어주는 게 좋아.
• 구체적으로 써!: "테스트 잘 짜라" 대신, "어떤 걸로 테스트해야 하고, 어떤 건 피해야 하는지"처럼 구체적으로 써야 해.
• 구조화해서 써!: 들여쓰기나 리스트를 사용해서 AI가 쉽게 읽을 수 있도록 만들어.
• 정기적으로 검토하고 업데이트해!: 클로드 MD도 코드처럼 유지보수가 필요해. 한 달에 한 번 정도는 안 쓰는 규칙은 지우고, 새로운 실수는 반영해 주는 게 좋아.
• 간결하게 써!: 엔트로픽에서는 100줄 이하를 권장해. 프로젝트가 크면 서브디렉토리 클로드 MD를 활용해서 길이를 줄이는 게 좋아.

진짜 꿀팁 두 가지!

1. 실수할 때마다 바로바로 반영해!: 클로드가 실수를 하면, "이런 실수는 다시 하지 마. 클로드 MD에 반영해 줘."라고 바로 말해줘. 클로드 MD는 한 번에 완벽하게 쓸 수 없어. 실수가 발생할 때마다 클로드에게 시켜서 업데이트하면, 그 실수는 앞으로 절대 일어나지 않을 거야.
   • 예시: 클로드가 테스트를 "먹"으로 짜버렸다면, "먹은 쓰지 않는다. 이걸 클로드 MD에 반영해라."라고 말하면 돼.
2. 빌드, 테스트, 린트 명령어는 꼭 명시해!: 클로드는 명령어를 추측해야 할 때 시간이 오래 걸리고 비용도 발생해. 빌드, 테스트, 린트 명령어를 명시해주면 바로 정답으로 갈 수 있어서 시간과 토큰을 절약할 수 있어.

자동화 도구 활용하기

• 안드레이 카파시 스킬: 안드레이 카파시가 만든 코딩 워크플로우나 컨벤션을 스킬 형태로 정리한 거야. 이걸 클로드 MD에 넣으면 AI 코딩 실수를 줄이는 데 도움이 돼. (검색: "안드레이 카파시 스킬")
• 엔트로픽 공식 플러그인:
  • revise claude.md: 세션 중에 AI가 실수한 부분을 자동으로 분석하고 개선해 줘.
  • claude.md 리팩토링: 기존 클로드 MD를 분석하고 리팩토링해 줘.

이 플러그인들을 사용하면 직접 클로드 MD를 개선할 필요 없이 훨씬 빠르고 정확하게 관리할 수 있어.

클로드 MD, 절대 이렇게 쓰지 마! (안티 패턴)

• 사람을 위한 설명서처럼 쓰지 마!: AI를 위한 가드레일이야.
• 코드로 알 수 있는 내용은 넣지 마!: 폴더 구조, 디렉토리 설명, "코드를 깨끗하게 해라" 같은 건 낭비야.
• 추상적인 내용은 피하자!: "좋은 코드를 작성해라" 같은 말은 의미 없어.

핵심 정리

클로드 MD는 사람이 읽는 설명서가 아니라, AI가 같은 실수를 반복하지 않도록 만드는 가드레일이야. 작게 유지하고, 실수가 날 때마다 채워나가는 살아있는 문서라고 생각하면 돼.

클로드 MD를 잘 관리하는 것이 결국 하네스 엔지니어링의 핵심이야. AI 코딩 도우미가 발전할수록 클로드 MD의 중요성은 더욱 커질 거야.

오늘 배운 내용들을 바탕으로 여러분의 프로젝트 클로드 MD를 점검해보고, 궁금한 점이나 적용 후기는 댓글로 공유해줘!