GitHub 100k+ 스타 받은 AI 코딩 지침 : claude.md에 직접 적용해서 비교해보기

🤔 시작하며

Claude나 ChatGPT 같은 AI 코딩 어시스턴트를 쓰다 보면 이런 경험 있으신가요?

• "간단한 함수 하나만 만들어달라고 했는데 왜 클래스를 만들어?"
• "이 함수만 수정하면 되는데 왜 전체 파일을 리팩토링해?"
• "묻지도 않은 에러 처리랑 로깅을 왜 추가해?"

저도 마찬가지였습니다. 특히 기존 프로젝트를 수정할 때 AI가 "친절하게" 추가한 코드들 때문에 오히려 더 복잡해지는 경우가 많았죠.

그러던 중 이 아티클에서 흥미로운 걸 발견했습니다.

 

📋 CLAUDE.md: AI의 나쁜 습관을 고치는 지침서

Andrej Karpathy의 GitHub 레포에 있는 CLAUDE.md는 LLM이 코딩할 때 흔히 저지르는 실수를 줄이기 위한 행동 지침입니다.

핵심 원칙 4가지:

1. Think Before Coding: 추측하지 말고, 불확실하면 질문하라
2. Simplicity First: 요청받은 것만, 최소한의 코드로
3. Surgical Changes: 필요한 부분만 수정, 관련 없는 건 건드리지 마라
4. Goal-Driven Execution: 검증 가능한 목표를 세우고 달성할 때까지 반복

좋은 내용이지만 문제가 있습니다. 개발자가 매번 이걸 인지하고 지시할 수 없다는 것.

 

💡 해결책: claude.md에 지침 명시하기

그래서 이 원칙들을 Claude가 자동으로 따르도록 프로젝트 루트의 claude.md 파일에 넣어봤습니다.

원본은 길어서 토큰 효율을 위해 4줄로 압축했습니다:

## 코딩 가이드라인
- **구현 전 확인**: 파일 형식, 저장 방식, 에러 처리 범위 등 핵심 결정사항을 '이 부분은 X가 맞나요?' 형태로 먼저 질문
- **최소 구현**: 단일 사용 코드는 추상화하지 말 것. 클래스/설정/히스토리 등 요청 없는 기능 추가 금지
- **변경 범위 제한**: 요청된 함수/파일만 수정. 주변 코드 포맷팅, 네이밍, 리팩토링 금지. 본인이 추가한 미사용 import만 제거
- **검증 계획**: 구현 전 '1) 테스트 작성 2) 구현 3) 수동 확인' 같은 2-3단계 계획 제시 후 각 단계 완료 시 결과 보고

 

🧪 실험: 날씨 대시보드 만들기

"날씨 데이터를 가져와서 옷차림을 알려주는 대시보드"를 만들어달라고 요청했습니다.

 

방법 1: Auto 모드 (지침 없음)

Claude에게 그냥 자유롭게 작업하도록 했습니다.

결과:

• ⏱️ 소요 시간: 6m
• 📏 코드 라인: 약 500줄
• ✨ 특징:
  
  • 다양한 날씨 아이콘
  • 반응형 디자인

 

방법 2: Plan 모드 (지침 있음)

claude.md에 위 가이드라인을 추가하고 Plan 모드로 실행했습니다.

 

결과:

• ⏱️ 소요 시간: 4m
• 📏 코드 라인: 약 57줄
• ✨ 특징:
  • 구현 전 계속 질문 ("날씨 API는 어떤 걸 쓰시나요?", "옷차림 기준은 온도만 볼까요?")
  • 요청한 기능만 정확히 구현
  • 간결한 코드
  • 명확한 검증 단계 제시

 

📊 결과 비교

항목 Auto 모드 (지침 없음) Plan 모드 (지침 있음)

코드 라인	~500줄	~57줄
소요 시간	기준	1.5배 빠름
사전 질문	없음	5-6번 질문
추가 기능	로딩, 히스토리, 애니메이션 등	없음
디자인	풍성하고 화려함	간결하고 실용적
코드 이해도	복잡함	명확함

 

🎯 언제 어떤 방식을 써야 할까?

Auto 모드 (지침 없음)를 추천하는 경우:

• ✅ 신규 토이 프로젝트: 빠르게 프로토타입이 필요할 때
• ✅ 초기 구축: 어떤 기능이 필요한지 아직 모를 때
• ✅ 탐색 단계: "일단 뭔가 만들어봐" 수준의 요청
• ✅ 디자인 중요: 시각적 완성도가 우선일 때

Plan 모드 (지침 있음)를 추천하는 경우:

• ✅ 기존 프로젝트 수정: 특정 기능만 추가/수정
• ✅ 리팩토링: 코드 정리가 목적일 때
• ✅ 명확한 요구사항: 정확히 뭘 원하는지 알 때
• ✅ 코드 학습: 구현 과정을 이해하고 싶을 때
• ✅ 팀 프로젝트: 일관된 코드 스타일 유지가 중요할 때
•  

💭 개인적인 소감

처음엔 "지침 줘봤자 무슨 소용이야?"라고 생각했는데, 실제로 써보니 확실히 차이가 있었습니다.

특히 Plan 모드에서 Claude가 계속 질문하는 과정에서 제가 놓쳤던 부분들을 발견하게 되더라고요. "아, 에러 처리 어떻게 할지 생각 안 해봤네?" 같은 것들이요.

Auto 모드는 빠르게 뭔가를 만들고 싶을 때, Plan 모드는 정확하게 원하는 걸 만들고 싶을 때. 상황에 맞게 선택하면 될 것 같습니다.

---

참고 링크:

• 원본 아티클
• CLAUDE.md GitHub