AI 코딩 에이전트용 CLAUDE.md 인기 비결

Andrej Karpathy가 지적한 AI 모델의 실패 사례를 해결하기 위해 제작된 CLAUDE.md 파일이 GitHub에서 22만 개 이상의 별을 기록하며 급성장하고 있다.

이 파일은 Claude Code가 세션을 시작할 때 읽는 단순 텍스트 파일로, 모델이 사용자의 기술 스택이나 과거 결정을 기억하지 못해 발생하는 잘못된 가정과 불필요한 리팩토링 문제를 해결하는 데 목적이 있다.

주요 핵심 규칙:

• 가정 대신 질문 (Ask, don't assume): 불확실한 부분이 있다면 코드를 작성하기 전에 반드시 질문하여 의도를 확인한다.
• 최소 기능 구현 (Simplest solution first): 요청하지 않은 추상화를 피하고, 작동하는 최소한의 코드만 구현한다.
• 관련 없는 코드 유지 (Don't touch unrelated code): 현재 작업과 관련 없는 파일은 수정하지 않는다.
• 불확실성 명시 (Flag uncertainty): 확신이 없을 때는 무리하게 진행하지 않고 사용자에게 명확히 알린다.

이 설정은 AI 에이전트가 스스로 혼란을 관리하고, 일관성을 유지하며, 무분별하게 코드를 수정하는 것을 방지하여 개발자의 작업 흐름을 보호한다.