AI 에이전트 규칙 파일 — 늘릴수록 망가지는 이유
지난 5월, Claude Code가 내 코드 컨벤션을 무시하는 걸 보고 CLAUDE.md에 규칙을 추가했다. 두 줄짜리 간단한 지시였는데, 다음 날부터 출력이 정확히 내 스타일을 따랐다. 신기했어요. 그래서 일주일 동안 규칙을 열두 개 더 넣었죠. 3개월이 지난 지금, 제 CLAUDE.md는 40줄에서 210줄로 늘었습니다. 그런데 출력 품질은 오히려 떨어졌어요. 저는 규칙 팽창을 멈춰야 한다고 생각합니다. 늘릴수록 좋아지는 게 아니라, 일정 지점을 넘으면 시스템이 무너지기 때문입니다.
규칙을 늘렸더니 실제로 일어난 일
5월 초, 제 CLAUDE.md는 핵심 규칙 5개만 담고 있었습니다. 파일 구조, 네이밍, 에러 핸들링, 테스트 커버리지, 커밋 메시지 형식이요. 한 달 동안 AI 코딩 도구가 이 규칙을 96% 정확도로 지켰어요. 출력 한 번에 원하는 코드가 나왔습니다.
6월부터 욕심이 생겼어요. "로깅 레벨은 이렇게", "주석은 JSDoc 형식으로", "변수명은 동사+명사 조합" 같은 세부 규칙을 추가했죠. 한 주에 두세 개씩 늘렸더니 7월 말엔 규칙이 23개가 됐습니다. 그때부터 이상한 일이 벌어졌어요. AI가 규칙 A를 지키려다 규칙 B를 어기기 시작한 거예요.
구체적으로 세어봤더니, 7월 한 달간 생성된 코드 120건 중 67건에서 최소 한 가지 규칙 위반이 발견됐습니다. 5월의 4%에서 56%로 급증한 겁니다. 더 놀라운 건 제가 추가한 신규 규칙 12개 중 실제로 일관되게 지켜진 건 5개뿐이었다는 거예요. 나머지 7개는 AI가 무시하거나 잊어버렸습니다.
8월 초, 규칙 파일을 다시 읽어보니 상충하는 지시가 세 쌍 있었어요. "간결하게 작성하라"와 "모든 엣지케이스를 명시하라"가 충돌했고, "한 함수는 한 가지 일만"과 "유틸 함수 남발 금지"도 모순이었습니다. 제가 규칙을 추가할 때마다 기존 맥락을 확인하지 않았던 거죠.
규칙을 계속 늘려야 하나요?
"규칙을 안 고치면 AI 출력 품질이 떨어지지 않나요?" 이런 질문을 자주 받습니다. 제 경험은 정반대예요. 초기 핵심 규칙 5개만으로도 3개월간 안정적으로 작동했거든요. 문제는 규칙을 늘리면서 생겼습니다.
실제로 8월 10일, 저는 210줄짜리 CLAUDE.md를 44줄로 줄였어요. 핵심 규칙 5개만 남기고 나머지는 전부 지웠죠. 그날부터 일주일간 생성된 코드 35건을 검사했더니 규칙 준수율이 91%로 회복됐습니다. 7월의 44%와 비교하면 두 배 이상 개선된 거예요.
"나쁜 출력이 나오면 규칙을 추가해야죠." 이것도 함정입니다. 제가 7월에 추가한 규칙 12개 중 8개는 일회성 문제를 해결하려고 만든 거였어요. 예를 들어, AI가 한 번 async 함수에 await를 빼먹었다고 "모든 async 함수는 반드시 await 키워드 확인"이라는 규칙을 넣었죠. 그런데 그 문제는 그 후로 다시 안 일어났어요. 일시적 오류를 영구 규칙으로 만든 겁니다.
"계속 진화해야 더 좋아지죠." 맞아요, 하지만 진화보다 안정성이 더 중요한 시점이 있습니다. 제 경우엔 규칙 10개를 넘어가는 순간부터 AI가 맥락을 놓치기 시작했어요. 프롬프트 길이 제한 때문인지, 우선순위 혼란인지는 모르겠지만 확실한 건 "더 많은 규칙 = 더 나은 결과"가 아니라는 겁니다.
커뮤니티에서도 비슷한 고민이 나오더라고요. CLAUDE.md 업데이트 피로를 호소하는 글이 여럿 보였습니다. 규칙 파일이 점점 무거워지면서 관리 자체가 부담이 되는 거죠.
규칙 팽창을 멈출 때는 언제인가요?
저는 이제 규칙을 추가하는 대신 삭제하는 쪽으로 방향을 틀었습니다. 8월 17일 기준 제 CLAUDE.md는 38줄이에요. 5월 초의 40줄과 거의 같죠. 차이가 있다면 규칙이 더 명확해졌다는 겁니다.
핵심은 "이 규칙이 없으면 시스템이 망가지는가?"를 묻는 거예요. 답이 "아니오"면 지웁니다. 실제로 제가 지운 규칙 중 70%는 삭제 후에도 AI 출력에 아무 영향이 없었어요. 필요 없는 규칙이었던 거죠.
규칙 팽창의 숨은 비용도 무시 못 합니다. CLAUDE.md가 길어질수록 AI가 규칙을 읽는 데 토큰을 더 쓰고, 그만큼 실제 작업에 쓸 컨텍스트 용량이 줄어들어요. 7월에 제 프롬프트 평균 길이가 5월 대비 34% 늘어났는데, 그중 절반은 규칙 파일 크기 증가 때문이었습니다.
지금 제 기준은 명확합니다. 규칙은 5개에서 10개 사이로 유지하고, 새 규칙을 추가하려면 기존 규칙 하나를 반드시 삭제합니다. 한 달에 한 번, 각 규칙의 준수율을 측정해서 70% 미만이면 지워요. 진화가 아니라 안정성을 선택한 겁니다.
당신의 CLAUDE.md는 지금 몇 줄인가요? 규칙을 추가하기 전에 한번 세어보세요. 40줄을 넘어가고 있다면, 늘리기보다 줄이는 게 답일 수 있습니다.
자주 묻는 질문
Q. 규칙이 너무 적으면 AI 출력이 일관성 없지 않나요?
A. 제 실측으론 규칙 5개일 때 준수율이 96%, 23개일 때 44%였습니다. 규칙이 적을수록 AI가 더 집중해서 각 규칙을 확실히 지켰어요. 많으면 우선순위가 흐려집니다.
Q. 새 프로젝트마다 CLAUDE.md를 처음부터 만들어야 하나요?
A. 핵심 규칙 5개는 프로젝트 간 재사용합니다. 프로젝트 특수 규칙은 2~3개만 추가하고, 프로젝트 종료 후엔 삭제해요. 영구 규칙과 임시 규칙을 구분하는 게 중요합니다.
Q. 규칙 파일 크기의 적정선은 얼마인가요?
A. 제 경험상 50줄 이하가 안전합니다. 그 이상 가면 상충 규칙이 생기고, AI가 놓치는 지시가 늘어나요. 토큰 절약 측면에서도 짧을수록 유리합니다.
Q. 규칙을 지우면 이전 출력 품질로 돌아가지 않나요?
A. 8월 10일 규칙을 44줄로 줄인 뒤 일주일간 준수율이 91%로 회복됐습니다. 오히려 품질이 개선됐어요. 규칙이 적으면 AI가 각 규칙에 더 집중합니다.