Claude Code 사용 시 직면했던 문제점
-
일관성 없는 코드 스타일: AI가 생성하는 모델이나 컨트롤러 코드가 매번 달라 프로젝트의 컨벤션을 따르지 않았습니다. 서비스 객체 사용 여부나 비즈니스 로직 배치 방식 등에서 혼란이 발생했습니다.
-
바퀴를 재발명: 기존에 구축된 인증 서비스나 표준화된 오류 처리 클래스를 무시하고 새로운 시스템을 생성하여 비효율을 초래했습니다.
-
비효율적인 패턴 및 초점 상실: Rails 안티 패턴(모델에 비즈니스 로직 포함, 비대한 컨트롤러, 뷰에 데이터베이스 쿼리 등)을 생성하고, 단순한 변경 요청에도 관련 없는 아키텍처 재설계를 제안하는 등 초점을 잃는 경향이 있었습니다.
해결책: CLAUDE.md 파일
CLAUDE.md 파일은 코드베이스 내에 전략적으로 배치되는 마크다운 문서로, AI가 해당 디렉토리의 코드를 처리하기 전에 읽는 “실행 가능한 사양” 역할을 합니다.
구조 및 구성 요소
-
구조:
project_root/CLAUDE.md는 프로젝트 개요와 일반적인 규칙을 담고,app/models/CLAUDE.md와 같이 하위 디렉토리별 파일은 해당 코드에 대한 구체적인 규칙을 정의합니다. AI는 작업 시 상위 디렉토리의 모든 CLAUDE.md 파일을 읽습니다. -
주요 구성 요소:
- 긍정적 예시: 올바른 구현 방식을 실제 코드 예시로 보여줍니다. (예: 얇은 모델)
- 안티 패턴: 피해야 할 구현 방식을 명시적으로 보여줍니다. (예: 모델에 비즈니스 로직 포함 금지)
- 컨텍스트별 규칙: 패턴 적용 시기, 예외 처리 방법 등을 정의합니다.
실제 적용 예시
CLAUDE.md 지침이 없을 때 Post 모델에 비즈니스 로직이 혼재되어 있던 코드를, 지침 적용 후 Post 모델은 데이터, 유효성 검사, 연관 관계에만 집중하고 PublishPostCommand와 같은 명령 객체에서 비즈니스 로직을 처리하도록 분리하여 코드의 응집도를 높이고 유지보수성을 향상시켰습니다.
구현 과정 및 결과
-
구현 과정: 기존 코드 분석, 문서 계층 구조 생성, AI가 따를 수 있는 명확한 의도 설정, 지속적인 개선 과정을 거칩니다.
-
결과 및 영향: 예측 가능한 결과물, 개발 속도 향상, 팀 지식 보존, 코드 품질 개선, 그리고 궁극적으로 고급 자동화를 위한 견고한 기반을 마련합니다.