AI 요약
Claude Code는 강력한 AI 코딩 에이전트이지만, 명확한 행동 제약이 없으면 기존 코드베이스에서 불필요한 리팩터링을 수행하거나 무관한 파일까지 수정하여 거대한 변경사항(diff)을 만드는 폭주 문제를 일으키기 쉽습니다. 이를 해결하기 위해 개발자 사노 키신은 GitHub에서 16만 개 이상의 스타를 기록한 multica-ai/andrej-karpathy-skills 리포지토리의 CLAUDE.md 운영 노하우를 소개했습니다. CLAUDE.md는 Claude Code가 프로젝트의 맥락과 행동 규칙을 기억하도록 돕는 영구적 지침 파일로, 일종의 AI용 README 역할을 합니다. 안드레이 카파시(Andrej Karpathy)가 지적한 LLM 코딩의 전형적인 실패 패턴을 극복하기 위해 이 파일은 구체적인 네 가지 행동 원칙을 정의하고 있습니다. 코딩 전 생각하기, 단순성 우선, 외과 수술식 변경, 목표 지향적 실행 등의 원칙을 통해 개발자는 AI 에이전트의 불필요한 코드 수정을 억제하고 안전하게 코딩 작업을 자동화할 수 있습니다.
핵심 인사이트
- 16만 스타 리포지토리 기반: GitHub에서 16만 개 이상의 스타를 획득한
multica-ai/andrej-karpathy-skills리포지토리는 Claude Code의 거동을 개선하기 위한 단일 지침 파일인CLAUDE.md를 핵심으로 삼고 있습니다. - 안드레이 카파시의 지적 해결: 전 테슬라 AI 디렉터 안드레이 카파시가 경고한 LLM 코딩의 대표적인 실패 패턴인 '독단적 전제하에 진행하기', '과도한 복잡성 추가', '무관한 코드 수정'을 차단하는 가이드를 제공합니다.
- AI용 README인 CLAUDE.md: 이 파일은 단순한 강제 설정이 아니라 AI 코딩 에이전트에게 지속적인 프로젝트 컨텍스트를 제공하여 인간 개발자가 의도치 않은 변경을 하지 않도록 방어벽 역할을 합니다.
- 외과 수술식 변경(Surgical Changes): 의뢰와 무관한 코드나 주석, 포맷을 AI가 임의로 수정하는 '하는 김에 수정(ついで修正)'을 철저히 금지하여 리뷰하기 편한 변경 최소화(diff)를 지향합니다.
주요 디테일
- Think Before Coding (구현 전 생각하기): 애매한 요구사항이 있을 때 AI가 임의로 판단해 구현하지 않도록, 구현 전에 달성 목적, 수정 파일, 전제 조건 및 애매한 부분을 먼저 정의하게 유도합니다.
- Simplicity First (단순함 최우선): 필요 이상의 일반화나 미래를 대비한 과도한 추상화를 지양하고, 요구사항에 명시된 기능만을 기존 코드 스타일에 맞추어 단순하게 해결합니다.
- Surgical Changes (외과 수술식 변경): 요청과 무관한 파일의 수정을 원천 차단하며, 사용하지 않는 코드(Dead Code)가 발견되더라도 지시가 없었다면 임의로 삭제하지 못하게 제약합니다.
- Goal-Driven Execution (목표 지향 실행): AI에게 단순한 지시 대신 "버그를 재현하는 테스트를 먼저 작성하고 이를 통과하는 코드를 작성하라"는 식의 검증 가능한 목표와 범위를 명확히 제시합니다.
- 작성 요령:
CLAUDE.md를 길고 모호하게 작성하는 것보다 짧고 명확하게 구체적인 행동 원칙 위주로 기술하는 것이 제어 효율성이 높습니다.
향후 전망
- AI 코딩 도구의 평가는 단순한 '코드 작성 능력'에서 '기존 설계를 파괴하지 않고 안전하게 제어 가능한가'의 운영 및 통제 능력으로 전환될 것입니다.
- 향후 기업의 개발 환경에서 개발자 협업 규칙뿐만 아니라 AI 에이전트의 거동을 제어하기 위한 표준
CLAUDE.md가이드라인과 이를 검증하는 자동화 파이프라인 도입이 늘어날 것으로 예상됩니다.