![[심층분석] AI 코딩 도구가 맨날 삽질하는 이유, 안드레이 카르파시가 해법을 내놨다](/newsimg/ilAj4eMLF0xoEcMv.png)
AI가 코드를 짜주는 시대, 근데 왜 이렇게 답답할까?
요즘 개발자라면 한 번쯤은 AI 코딩 도구를 써봤을 거예요. Claude Code, GitHub Copilot, Cursor 같은 도구들이 코드를 대신 작성해주는 세상이 됐거든요. 그런데 써보신 분들은 아실 거예요. "이거 왜 이렇게 짰어?" 라는 말이 입에서 절로 나온다는 걸요.
분명 간단한 함수 하나 만들어달라고 했는데, 돌아온 건 수백 줄짜리 코드에 쓸데없는 추상화 레이어가 세 겹이나 덕지덕지 붙은 결과물. 혹은 내가 분명히 건드리지 말라고 한 부분까지 슬쩍 바꿔놓는 바람에 다른 기능이 터져버리는 경험. AI 코딩 도구의 생산성은 분명 매력적인데, 이런 문제들 때문에 오히려 디버깅에 시간을 더 쓰게 되는 아이러니한 상황이 벌어지고 있어요.
이 문제를 정확히 짚어낸 사람이 있어요. 바로 안드레이 카르파시(Andrej Karpathy). 테슬라 AI 총괄을 역임하고, OpenAI 공동 창업 멤버이자, 딥러닝 교육의 전설적인 인물이죠. 이 분이 뭐라고 했냐면요:
> "모델들은 당신을 대신해서 잘못된 가정을 세우고, 확인도 안 하고 그냥 달려버린다. 자기가 뭘 모르는지 관리하지 않고, 명확하게 물어보지도 않고, 불일치를 표면에 드러내지도 않고, 트레이드오프를 제시하지도 않고, 반박해야 할 때도 반박하지 않는다."
이 관찰을 바탕으로 포레스트 장(Forrest Chang)이라는 개발자가 하나의 설정 파일로 AI 코딩 도구의 행동을 근본적으로 개선하는 방법을 공개했어요. CLAUDE.md라는 단일 파일에 네 가지 원칙을 담아서, Claude Code가 코드를 짤 때 사람처럼 생각하고 행동하도록 가이드라인을 만든 거예요.
이게 왜 중요하냐면, 단순히 "프롬프트를 잘 쓰자"는 차원이 아니거든요. AI 코딩 도구와 협업하는 구조적인 방법론을 제시한다는 점에서 의미가 커요.
CLAUDE.md가 뭔데? — AI에게 주는 업무 매뉴얼
먼저 CLAUDE.md라는 게 뭔지부터 설명할게요. Claude Code에서는 프로젝트 루트에 CLAUDE.md라는 파일을 놓으면, AI가 코드를 작성하기 전에 이 파일을 먼저 읽어요. 쉽게 말해서 신입 개발자한테 첫 날 건네주는 팀 컨벤션 문서 같은 거예요. "우리 팀은 이렇게 코드를 짜", "이런 건 하지 마" 같은 규칙을 적어두면, AI가 그걸 따르게 되는 거죠.
보통은 코딩 스타일 가이드(탭 vs 스페이스, 네이밍 규칙 등)를 적어두는 용도로 쓰이는데, 이 프로젝트는 그보다 훨씬 상위 레벨의 사고방식과 작업 태도를 정의해요. AI한테 "코드를 이렇게 포맷팅해"가 아니라 "일을 이렇게 접근해"라고 알려주는 거예요.
네 가지 원칙 심층 분석
이 프로젝트의 핵심은 네 가지 원칙이에요. 하나씩 자세히 뜯어볼게요.
1. 코딩 전에 생각하기 (Think Before Coding)
이게 뭐냐면, AI에게 "모르면 물어봐"라고 가르치는 거예요.
AI 코딩 도구의 가장 큰 문제 중 하나가 뭐냐면, 애매한 요청을 받으면 스스로 "아 이건 이런 뜻이겠지" 하고 가정을 세운 다음 확인도 안 하고 코드를 뚝딱 만들어버리는 거예요. 사람으로 치면, 상사가 "그 기능 좀 고쳐줘"라고 했을 때 뭘 고치라는 건지 안 물어보고 자기 맘대로 바꿔버리는 신입 사원 같은 거죠.
이 원칙은 네 가지 하위 규칙으로 구성돼요:
- 가정을 명시적으로 밝혀라 — 불확실하면 추측하지 말고 물어봐
- 여러 해석이 가능하면 다 제시해라 — 조용히 하나만 골라서 진행하지 마
- 더 단순한 방법이 있으면 반박해라 — 시키는 대로만 하지 말고 더 나은 방법을 제안해
- 혼란스러우면 멈춰라 — 뭐가 불명확한지 이름 붙여서 질문해
- 요청하지 않은 기능은 만들지 마라
- 한 번만 쓰이는 코드에 추상화를 적용하지 마라
- 요청하지 않은 "유연성"이나 "확장성"을 넣지 마라
- 불가능한 시나리오에 대한 에러 핸들링은 넣지 마라
- 200줄이 50줄로 줄어들 수 있다면, 다시 써라
- 변경해야 하는 것만 변경하라 — 주변 코드 정리, 리팩토링은 별도 요청이 없으면 하지 마
- 기존 코드의 패턴과 스타일을 따라라 — 당신이 더 좋은 방식을 안다고 해도, 기존 코드베이스의 일관성이 더 중요해
- 주석과 문서는 당신이 건드린 코드에 대해서만 수정해라
- 이해하지 못하는 코드는 절대 제거하지 마라 — 이건 정말 중요해요
실무에서 이게 어떤 차이를 만드냐면요. 예를 들어 "사용자 인증 기능 추가해줘"라고 요청했다고 해볼게요.
원칙 없는 AI: JWT 토큰 기반 인증을 바로 구현하기 시작해요. OAuth도 넣고, 리프레시 토큰도 넣고, 세션 관리도 넣어요. 근데 사실 당신이 원한 건 단순한 API 키 검증이었을 수 있잖아요.
원칙 있는 AI: "인증 방식을 확인하고 싶어요. JWT, API 키, OAuth 중 어떤 걸 원하시나요? 현재 프로젝트 구조를 보면 API 키 방식이 가장 심플할 것 같은데, 이유는..." 이렇게 먼저 물어보는 거예요.
이 차이가 작아 보일 수 있는데, 실제로 프로젝트에서는 이런 잘못된 가정이 쌓여서 결국 코드를 다 갈아엎어야 하는 상황으로 이어지거든요.
2. 단순함 우선 (Simplicity First)
카르파시가 특히 강하게 지적한 부분이에요. AI가 코드를 짜면 비정상적으로 복잡해지는 현상이 있거든요.
이게 왜 그러냐면, LLM(대규모 언어 모델)이 학습한 데이터에는 각종 디자인 패턴, 엔터프라이즈급 아키텍처, 복잡한 추상화 패턴이 가득하기 때문이에요. 모델 입장에서는 "이런 복잡한 패턴을 쓰는 게 좋은 코드"라고 학습한 셈이죠. 그래서 100줄이면 충분한 코드를 1000줄로 뻥튀기시키는 거예요.
비유하자면 이래요. 동네 분식집에서 떡볶이 레시피를 물어봤는데, 미쉐린 3스타 셰프가 트러플 오일을 넣은 분자요리 떡볶이 레시피를 알려주는 격이에요. 맛은 있을지 몰라도, 당장 필요한 건 그게 아니잖아요.
이 원칙의 핵심 규칙들은:
그리고 가장 인상적인 테스트 기준이 하나 있어요:
> "시니어 엔지니어가 이 코드를 보고 '이거 너무 복잡한데?'라고 말할까? 그렇다면 단순화해라."
이건 사실 AI 코딩 도구에만 해당하는 얘기가 아니에요. 주니어 개발자분들도 종종 디자인 패턴을 과도하게 적용하는 실수를 하거든요. Factory 패턴, Strategy 패턴을 다 배웠으니 써보고 싶은 마음은 이해하지만, 비슷한 코드 세 줄이 조기 추상화보다 낫다는 원칙을 기억하면 좋겠어요.
3. 외과적 수술 같은 변경 (Surgical Changes)
이건 AI 코딩 도구에서 정말 짜증나는 문제를 해결하는 원칙이에요. AI한테 함수 하나 고쳐달라고 했는데, 옆에 있는 주석도 바꾸고, import 순서도 정리하고, 관련 없는 변수명까지 리팩토링해버리는 거예요.
이걸 비유하자면, 치과에 충치 하나 때우러 갔는데 의사가 "이 옆에 이빨도 좀 이상한 것 같으니까 같이 갈아버릴게요" 하는 것과 비슷해요. 한 마디로 "시킨 것만 해" 라는 원칙이에요.
구체적인 규칙을 보면:
4. 목표 중심 실행 (Goal-Driven Execution)
마지막 원칙은 AI가 작업할 때 명확한 성공 기준을 먼저 세우고 시작하라는 거예요.
이건 사실 TDD(Test-Driven Development, 테스트 주도 개발)의 철학과 맥이 닿아 있어요. TDD가 뭐냐면, 코드를 짜기 전에 "이 코드가 성공하려면 어떤 조건을 만족해야 하는가"를 먼저 테스트로 정의하고, 그 테스트를 통과하는 코드를 작성하는 방법론이에요.
이 원칙을 적용하면 AI는 코드를 짜기 전에 "이 작업이 완료되면 이런 결과가 나와야 해"라는 검증 기준을 먼저 제시해요. 그러면 나중에 AI가 만든 코드가 제대로 동작하는지 확인하기가 훨씬 쉬워지죠.
업계 맥락: CLAUDE.md를 넘어선 AI 코딩 가이드라인 전쟁
이 프로젝트가 나온 맥락을 좀 더 넓게 볼 필요가 있어요. 사실 AI 코딩 도구의 행동을 제어하려는 시도는 이것만 있는 게 아니거든요.
Cursor에는 .cursorrules라는 비슷한 개념이 있어요. 프로젝트에 이 파일을 넣으면 Cursor AI가 코드를 생성할 때 참고하게 되죠. GitHub Copilot도 최근 커스텀 인스트럭션 기능을 추가했고요. Windsurf, Cline 같은 도구들도 각자의 방식으로 사용자 정의 규칙을 지원해요.
이 흐름에서 이 프로젝트가 특별한 이유는 뭘까요?
첫째, 권위 있는 출처에서 나온 관찰이에요. 안드레이 카르파시는 AI 분야에서 이론과 실무를 모두 아는 극소수의 인물 중 하나예요. 그가 직접 경험하고 정리한 문제점을 기반으로 만들어졌다는 건 큰 신뢰를 줘요.
둘째, 도구에 종속적이지 않은 원칙이에요. 파일 이름은 CLAUDE.md지만, 여기 담긴 네 가지 원칙은 어떤 AI 코딩 도구에든 적용할 수 있어요. Cursor를 쓰든, Copilot을 쓰든, 이 원칙들을 각 도구의 설정 파일에 옮겨 적으면 돼요.
셋째, 이런 가이드라인을 커뮤니티가 공유하고 발전시킬 수 있는 형태로 제공했어요. GitHub 레포지토리에 올려놓으니까, 포크해서 자기 팀에 맞게 커스텀하기 쉽잖아요. 실제로 이 레포는 이미 1100개 이상의 포크가 만들어졌어요.
비교해보면, 기존의 접근법들은 대부분 "코드 스타일" 레벨에 머물렀어요. "TypeScript를 써라", "함수는 camelCase로 써라" 같은 거요. 하지만 이 프로젝트는 "어떻게 생각하고 일해라" 수준의 메타 가이드라인을 제시한다는 점에서 한 단계 위에 있어요.
한국 개발자에게 주는 시사점
당장 써볼 수 있는 실전 적용법
Claude Code를 쓰고 있다면, 적용하는 데 5분도 안 걸려요.
1. 해당 GitHub 레포에서 CLAUDE.md 파일을 복사해요
2. 자기 프로젝트 루트에 붙여넣으면 끝이에요
3. 필요하면 팀의 상황에 맞게 수정하면 되고요
Cursor를 쓰고 있다면, .cursorrules 파일에 같은 원칙을 옮겨 적으면 돼요. 형식만 좀 다를 뿐, 내용은 그대로 가져다 쓸 수 있어요.
어떤 AI 코딩 도구를 쓰든, 프롬프트에 이 네 가지 원칙을 시스템 메시지로 넣어주면 비슷한 효과를 볼 수 있어요.
팀 단위로 도입할 때 고려할 점
개인 프로젝트에서는 바로 쓰면 되지만, 팀에서 쓸 때는 몇 가지 생각해볼 게 있어요.
1. 팀 컨벤션과의 충돌 관리
이미 팀에서 쓰고 있는 코딩 가이드라인이 있다면, 이 원칙들과 어떻게 조화시킬지 논의가 필요해요. 예를 들어 팀에서 "모든 함수에 에러 핸들링을 넣어라"는 규칙이 있는데, CLAUDE.md에는 "불가능한 시나리오에 대한 에러 핸들링은 넣지 마"라고 돼 있으면 충돌이 생기겠죠. 이런 부분은 팀 상황에 맞게 조율해야 해요.
2. 과도한 의존 방지
이 가이드라인이 AI 코딩 도구의 품질을 높여주는 건 맞지만, 결국 AI가 만든 코드를 사람이 리뷰해야 한다는 본질은 변하지 않아요. 가이드라인이 있으니까 AI 코드를 무조건 신뢰해도 된다고 생각하면 위험해요.
3. 점진적 도입
네 가지 원칙을 한꺼번에 다 적용하기보다, 팀에서 가장 고통받고 있는 문제부터 적용하는 게 현실적이에요. AI가 코드를 너무 복잡하게 짜는 게 문제라면 "Simplicity First"부터, 관련 없는 코드까지 건드리는 게 문제라면 "Surgical Changes"부터 시작하면 돼요.
이것은 더 큰 흐름의 일부다
한 발 물러서서 보면, 이 프로젝트는 "AI 코딩 도구를 어떻게 효과적으로 쓸 것인가"라는 더 큰 질문의 일부예요. AI가 코드를 짜주는 건 이제 당연한 건데, 문제는 그 코드의 품질을 어떻게 보장하느냐는 거거든요.
지금까지는 "좋은 프롬프트를 쓰자"가 주요 접근법이었어요. 하지만 이 프로젝트는 프롬프트 엔지니어링을 넘어서 구조적 가이드라인으로 AI의 행동 패턴 자체를 교정하자는 방향을 보여줘요. 이건 개발 문화에 있어서 중요한 전환점이에요.
한국의 스타트업이나 테크 기업들도 이미 AI 코딩 도구를 도입하고 있는 곳이 많은데, 대부분 "도구를 도입했다"에서 멈춰 있어요. 이 도구를 잘 쓰기 위한 가이드라인과 프로세스까지 갖춘 팀은 아직 드물거든요. 여기서 차별화를 만들 수 있는 기회가 있다고 봐요.
앞으로 어떤 변화가 올까?
이 프로젝트가 시사하는 미래를 몇 가지 전망해볼게요.
1. AI 코딩 가이드라인이 팀 필수 문서가 될 거예요
지금은 README, CONTRIBUTING.md 같은 문서가 프로젝트의 기본 구성이잖아요. 조만간 AI 코딩 가이드라인 파일도 프로젝트의 기본 구성에 포함될 가능성이 높아요. "우리 프로젝트에서 AI가 코드를 짤 때는 이 규칙을 따라야 한다"는 합의가 팀 차원에서 만들어지는 거죠.
2. AI 도구 제공 업체들이 이런 원칙을 내장할 거예요
지금은 사용자가 직접 가이드라인을 작성해야 하지만, 결국 Anthropic, OpenAI, 구글 같은 회사들이 이런 원칙들을 모델 자체에 학습시키거나 기본 설정으로 내장할 거예요. 이 프로젝트가 "사용자가 이런 걸 원한다"는 강력한 신호를 보내고 있으니까요.
3. "AI 코드 리뷰어" 역할이 생길 거예요
사람이 짠 코드를 AI가 리뷰하는 건 이미 있지만, AI가 짠 코드를 전문적으로 리뷰하는 역할이 팀에서 공식적으로 만들어질 수 있어요. AI 코드의 특유한 패턴(과도한 추상화, 불필요한 에러 핸들링 등)을 잡아내는 전문성이 별도로 필요해질 테니까요.
마무리: 도구가 아니라 협업 방식의 문제다
AI 코딩 도구를 두고 "AI가 코드를 잘 짜느냐 못 짜느냐"로 논쟁하는 건 핵심을 놓치는 거예요. 진짜 중요한 건 "AI와 어떻게 협업하느냐"예요. 이 프로젝트는 그 협업의 규칙을 명문화한 첫 번째 의미 있는 시도 중 하나라고 볼 수 있어요.
카르파시의 관찰이 날카로운 이유는, AI 코딩 도구의 문제가 사실 사람 팀에서도 흔히 발생하는 문제와 본질적으로 같다는 걸 보여주기 때문이에요. 가정을 확인하지 않는 것, 과도하게 복잡한 코드를 짜는 것, 범위를 넘어서 이것저것 건드리는 것 — 이건 주니어 개발자나 새로 합류한 팀원한테도 자주 피드백하는 내용이잖아요.
결국 좋은 AI 코딩 가이드라인은 좋은 개발 문화의 연장선에 있어요. AI를 잘 다루는 팀이 코드 품질도 높고, 개발 속도도 빠를 거예요.
여러분은 AI 코딩 도구를 쓰면서 가장 답답했던 경험이 뭐였나요? 그리고 그걸 해결하기 위해 어떤 방법을 쓰고 계신가요? 팀에서 AI 코딩 가이드라인을 만들어 쓰고 있는 분이 계시다면, 어떤 규칙이 가장 효과적이었는지도 궁금해요.
🔗 출처: GitHub
"비전공 직장인인데 반년 만에 수익 파이프라인을 여러 개 만들었습니다"
실제 수강생 후기- 비전공자도 6개월이면 첫 수익
- 20년 경력 개발자 직강
- 자동화 프로그램 + 소스코드 제공
