챕터별 상세
CLAUDE.md의 등장 배경과 인기
안드레 카파시의 메시지를 요약한 65줄짜리 CLAUDE.md 텍스트 파일이 깃허브에서 10만 개 이상의 스타를 받았다. 이 파일은 복잡한 프레임워크나 라이브러리가 아님에도 불구하고 Claude Code와 같은 AI 도구의 성능을 드라마틱하게 향상시킨다. 카파시가 지적한 AI의 한계를 극복하기 위한 실전 지침을 담고 있다.
안드레 카파시는 OpenAI의 공동 창업자이자 테슬라의 전 AI 디렉터로 AI 분야의 권위자이다.
안드레 카파시가 짚은 AI의 3가지 고질병
AI는 사용자에게 묻지 않고 멋대로 해석하여 잘못된 가정을 바탕으로 작업을 시작하는 경향이 있다. 또한 간단한 문제를 수천 줄의 복잡한 코드로 부풀리거나 사용하지 않는 코드를 방치하는 문제를 보인다. 마지막으로 요청하지 않은 부분까지 수정하거나 주석을 삭제하는 등 코드를 임의로 변경하여 예기치 않은 오류를 발생시킨다.
원칙 1: Think Before Coding (코딩 전 사고)
AI가 모호한 요청을 받았을 때 즉시 코딩을 시작하지 않고 사용자에게 되묻도록 강제한다. 추측하지 말고 혼란스러운 지점이나 트레이드오프를 명확히 드러내어 사용자에게 선택지를 제공해야 한다. 예를 들어 로그인 기능 추가 요청 시 JWT, 세션, OAuth 중 어떤 방식을 사용할지 먼저 확인하도록 설정한다.
트레이드오프는 어느 한쪽을 얻으려면 다른 한쪽을 희생해야 하는 경제적/기술적 상충 관계를 의미한다.
원칙 2: Simplicity First (단순함 최우선)
문제를 해결하는 데 필요한 최소한의 코드만 작성하도록 지시하며 불필요한 추상화를 금지한다. 요청하지 않은 유연성이나 설정 가능성을 추가하지 않도록 하여 코드의 가독성과 유지보수성을 높인다. 200줄의 코드를 50줄로 줄일 수 있다면 항상 더 단순한 방식을 선택하도록 가이드라인을 제시한다.
원칙 3: Surgical Changes (수술적 수정)
꼭 필요한 부분만 정밀하게 수정하고 본인이 작성하지 않은 기존 코드는 건드리지 않도록 한다. 멀쩡한 코드를 리팩터링하거나 주석 스타일을 바꾸는 행위를 제한하여 코드 리뷰 범위를 최소화한다. 불필요한 코드를 발견하더라도 직접 지우지 말고 사용자에게 먼저 알리도록 하여 안전성을 확보한다.
수술적 수정(Surgical Changes)은 비유적인 표현으로, 최소한의 절개로 병변만 제거하듯 필요한 코드만 정확히 고치는 것을 의미한다.
원칙 4: Goal-Driven Execution (목표 기반 실행)
단순히 무엇을 하라고 명령하는 대신 성공 기준을 정의하고 검증될 때까지 반복하게 한다. 버그 수정 시 먼저 실패하는 테스트 케이스를 작성하여 문제를 확인한 후 코드를 수정하고 다시 테스트를 통과하는지 검증하는 절차를 밟는다. 모든 변경 사항이 사용자의 요청과 직접 연결되는지 확인하는 단계를 포함한다.
테스트 주도 개발(TDD)의 개념을 AI 에이전트의 작업 방식에 이식한 원칙이다.
프로젝트에 직접 적용하는 방법
VS Code 터미널에서 curl 명령어를 사용하여 CLAUDE.md 파일을 프로젝트 루트에 다운로드할 수 있다. 전역적으로 적용하거나 특정 프로젝트 단위로 적용하는 두 가지 방식을 지원한다. 파일이 생성되면 Claude Code와 같은 에이전트가 컨텍스트가 시작될 때마다 이 지침을 자동으로 로드하여 원칙에 따라 동작한다.
마크다운(.md) 파일은 AI 에이전트가 시스템 프롬프트나 가이드라인으로 읽어들이기 매우 적합한 형식이다.
언급된 리소스
AI 분석 전체 내용 보기
AI 요약 · 북마크 · 개인 피드 설정 — 무료
출처 · 인용 안내
원문 발행 2026. 05. 01.수집 2026. 05. 01.출처 타입 YOUTUBE
인용 시 "요약 출처: AI Trends (aitrends.kr)"를 표기하고, 사실 확인은 원문 보기 기준으로 진행해 주세요. 자세한 기준은 운영 정책을 참고해 주세요.
