CLAUDE.md 완전 정복 - 코딩 규약 작성법

AI가 팀 컨벤션을 100% 따르게 만드는 법

CLAUDE.md에서 가장 자주 업데이트하게 되는 섹션이 코딩 규약입니다.

"Claude Code에 이렇게 작성해 달라"는 규칙을 하나씩 추가해 나갈수록 출력 품질이 조금씩, 그러나 확실하게 높아집니다.

이 장에서는 언어·프레임워크별로 바로 복붙해서 쓸 수 있는 코딩 규약 예시와, 규약을 잘 작성하는 원칙을 소개합니다.

규약을 작성할 때의 3가지 원칙

원칙 1. 구체적으로 작성한다

"깔끔한 코드를 작성한다"는 너무 모호합니다. AI는 이 문장을 보고 나름의 기준으로 해석하는데, 그 결과가 항상 여러분의 의도와 일치하지 않습니다. 구체적인 수치나 조건으로 풀어서 작성하세요.

# ❌ 모호한 작성 방식
- 깔끔한 코드를 작성한다
- 적절한 에러 핸들링을 한다

# ✅ 구체적인 작성 방식
- 함수는 30행 이내로 작성한다. 초과하는 경우에는 책임에 따라 분할한다
- 외부 API 호출은 try-catch로 감싸고, 에러는 AppError 클래스로 래핑한 뒤 상위로 전파한다

원칙 2. 선택지를 없앤다

"A 또는 B 중 어느 쪽이든 괜찮다"는 식의 모호함을 남기면 AI의 출력이 매 번 달라집니다. 하나를 선택해 강제하세요.

# ❌ 모호한 방식
- interface 또는 type으로 타입을 정의한다

# ✅ 명확한 방식
- 타입 정의에는 type을 사용한다. interface는 사용하지 않는다

팀 내에서 아직 합의가 안 된 사항이라도, 일단 하나를 골라 CLAUDE.md에 명시해 두는 편이 낫습니다. AI의 출력이 일관되어야 코드 리뷰 부담이 줄어듭니다.

원칙 3. 예외를 명시한다

모든 규칙에는 예외가 있습니다. 예외를 명시하지 않으면 AI가 규칙을 기계적으로 적용해 오히려 역효과가 나는 경우가 생깁니다.