새 세션을 열 때마다 같은 말을 반복하고 있었습니다. "커밋은 명시적으로 요청받았을 때만 해줘", "테스트는 변경된 모듈만 돌려줘", "새 파일 대신 기존 파일을 수정하는 쪽을 우선해줘" 같은 규칙을 대화 초반에 매번 다시 입력했습니다. 세션이 끝나면 이 맥락도 함께 사라지기 때문에, 다음 세션에서 또 같은 문장을 타이핑하는 일이 반복됐습니다.
어떤 작업이었나
여러 저장소를 오가며 작업하다 보니 저장소마다 지켜야 할 규칙이 조금씩 달랐습니다. 한 저장소는 커밋 메시지에 이슈 번호를 꼭 붙여야 했고, 다른 저장소는 린트 도구가 달라서 포맷 명령어 자체가 달랐습니다. 세션을 새로 열 때마다 "이 저장소에서는 ~~" 하고 규칙을 설명하는 데 첫 몇 턴을 소모했고, 가끔은 설명을 빼먹어서 이전 세션과 다른 방식으로 처리되는 일도 있었습니다.
AI를 어떻게 활용했나
Claude Code는 세션을 시작할 때 프로젝트 루트의 CLAUDE.md 파일을 자동으로 읽어 컨텍스트에 포함시킵니다. 매번 대화로 설명하던 규칙을 이 파일로 옮겼습니다.
# CLAUDE.md
## 커밋
- 사용자가 명시적으로 요청하기 전에는 커밋하지 않는다.
- 커밋 메시지는 간결한 한 줄 요약 + 이슈 번호(`#123`) 형식을 따른다.
## 테스트
- 변경한 모듈에 해당하는 테스트만 실행한다 (`./gradlew :feature:xxx:test`).
- 전체 테스트는 명시적으로 요청받았을 때만 실행한다.
## 코드 스타일
- 새 파일을 만들기보다 기존 파일을 수정하는 쪽을 우선한다.
- 주석은 "왜"가 드러나지 않는 이상 추가하지 않는다.
세션을 새로 열 때마다 이 파일이 자동으로 로드되면서, 대화 초반에 규칙을 다시 설명할 필요가 없어졌습니다. 하위 디렉터리로 이동해서 작업할 때는 그 디렉터리에 있는 CLAUDE.md도 함께 읽히기 때문에, 공통 규칙은 루트에 적고 모듈별 예외는 해당 디렉터리에 따로 적어 나눴습니다.
처음에 걸렸던 부분
처음에는 규칙을 전부 프로젝트 루트 CLAUDE.md 한 파일에 몰아넣었습니다. 항목이 늘어나면서 파일이 길어지자, 뒤쪽에 적어둔 규칙일수록 실제로 지켜지지 않는 경우가 잦아졌습니다. 예를 들어 맨 위에 적힌 커밋 규칙은 매번 지켜졌지만, 파일 아래쪽에 있던 세부 규칙은 종종 무시됐습니다.
규칙을 카테고리별 짧은 섹션으로 나누고, 정말 항상 지켜야 하는 것만 남기고 나머지는 지웠습니다. "가능하면 ~", "웬만하면 ~" 같은 애매한 표현으로 적힌 항목도 실제로는 거의 지켜지지 않아서, 조건 없이 항상 적용되는 규칙만 단정적인 문장으로 남겼습니다.
결과와 얻은 팁
CLAUDE.md는 매 세션 대화 맥락과 별개로 항상 로드되므로, 세션이 바뀌어도 잊히지 않아야 할 규칙을 적어두기에 적합합니다.- 파일이 길어질수록 뒤쪽 규칙의 준수율이 떨어졌습니다. 항목 수를 늘리기보다 정말 매번 지켜야 하는 규칙만 추리는 편이 효과적이었습니다.
- 저장소 전체에 적용되는 규칙은 루트에, 특정 모듈에만 해당하는 규칙은 그 하위 디렉터리의
CLAUDE.md에 나눠 적으니 파일 하나가 비대해지는 것도 막을 수 있었습니다. - "가능하면", "웬만하면" 같은 조건부 표현은 실제로는 지켜지지 않는 경우가 많아서, 예외 없이 지켜야 하는 규칙만 단정문으로 적는 편이 낫습니다.