anti-patterns

안티패턴 — CLAUDE.md 망치는 법

1. 1000줄짜리 만능 CLAUDE.md

린트 규칙·코딩 컨벤션·이력서·취향까지 다 적는다. 200개 지시문 한계를 넘어 핵심까지 무시당한다.

2. 자동 생성에 맡기기

“/init이 알아서 만들어 주니까 안 봐도 돼.” — HumanLayer는 정반대를 권한다. 손으로 짠 60줄이 자동 생성 600줄보다 강하다.

3. 린터 역할 강요

“세미콜론 빼지 마”, “인덴트 4 스페이스” 같은 결정적 규칙을 모델에게 시킨다. 결정적 도구(prettier, eslint, ruff)로 옮긴다.

4. 같은 사실을 CLAUDE.md와 AGENTS.md에 중복 작성

유지보수가 두 배로 든다. 한 곳에 두고 다른 한 곳에서는 참조한다.

5. 파일 참조 없이 모든 가이드를 인라인

점진적 공개(progressive disclosure)를 안 쓴다. 토큰 예산을 매 턴마다 낭비한다.

6. 부정 규칙을 긍정 규칙 사이에 끼워 넣기

“X 해라. Y 하지 마라. Z 해라” 식. 모델은 부정 규칙을 더 자주 빠뜨린다. ## 절대 금지 절을 따로 만든다.

7. 메타 원칙 누락

“왜 이 규칙들이 있는가”가 없으면 후속 수정자가 규칙을 무력화하는 변경을 한다. 한 줄짜리 메타 원칙을 박는다.