AI 코딩 에이전트가 규칙을 안 지킬 때 — 문서 말고 훅으로 막기

AI 코딩 에이전트를 오래 쓰다 보면 규칙 문서가 점점 길어진다. CLAUDE.md나 AGENTS.md에 “이렇게 해라”, “저건 하지 마라”가 계속 쌓인다.

내 경우도 그랬다. git add -A 금지, 새 브랜치 만들지 말 것, .env는 커밋 금지, 로그는 logs/에 남길 것… 항목이 수십 개가 됐다.

그런데 문서가 길어질수록 지켜지는 비율은 오히려 떨어졌다.

문서로 막는 것의 한계

이유를 생각해보면 당연하다. 지침은 확률적으로 작동한다. 컨텍스트가 길어지면 앞쪽 지침의 영향력이 줄고, 작업이 복잡해지면 규칙보다 당면 문제에 주의가 쏠린다.

특히 이런 패턴이 반복됐다.

• 규칙 문서에 분명히 “새 브랜치 만들지 말 것”이라고 적혀 있는데 브랜치가 생겨 있다
• git add -A 금지라고 썼는데 파일이 통째로 스테이징돼 있다
• 대부분은 지킨다. 그런데 가끔 안 지킨다

문제는 이 “가끔”이다. 열 번에 아홉 번 지키는 규칙은, 열 번째에 사고가 난다. .env가 커밋되는 사고는 한 번이면 충분하다.

방향을 바꿨다: 지침이 아니라 장치로

그래서 접근을 바꿨다. 문서로 부탁하는 대신, 애초에 불가능하게 만든다.

기준은 이렇게 잡았다.

자동으로 강제할 수 있는 규칙은 문서를 늘리지 말고 훅, 테스트, CI, 점검 스크립트로 옮긴다.

문서에 남겨야 할 것은 판단이 필요한 것이다. “파일이 500줄을 넘기면 모듈 분리를 검토한다” 같은 건 기계가 판단할 수 없다. 반면 “main 브랜치가 아니면 커밋을 막는다”는 기계가 할 수 있다.

예시 1: 브랜치 규칙을 git hook으로

“새 브랜치를 만들지 말고 main에서만 작업한다”는 규칙이 있었다. 이건 문서로 부탁할 게 아니라 git이 막아야 한다.

git hook을 설치하는 명령 하나로 정리했다. 저장소에 훅을 걸어두면 main이 아닌 브랜치에서의 커밋 자체가 거부된다. 에이전트가 규칙을 잊어도 git이 거절한다.

핵심은 에이전트의 협조가 필요 없다는 점이다. 지침을 읽었는지, 컨텍스트에 남아 있는지와 무관하게 작동한다.

예시 2: 위험한 명령을 훅에서 가로채기

Claude Code에는 도구 호출을 가로채는 훅 기능이 있다. 명령이 실행되기 전에 검사해서 막을 수 있다.

여기에 걸어둘 만한 것들이 있다.

• git add -A, git add . 같은 광범위 스테이징
• .env 파일이 스테이징에 포함된 커밋
• 프로젝트 밖 경로를 향한 파일 삭제

훅은 지침과 성격이 다르다. 지침은 “하지 마세요”고, 훅은 “할 수 없습니다”다. 이 차이가 실제 결과를 만든다.

예시 3: 매번 확인해야 하는 건 스크립트로

반복적으로 확인해야 하는 항목은 사람도 에이전트도 빠뜨린다. 이건 점검 스크립트로 만들어두는 게 낫다.

이 블로그 저장소에도 같은 방식을 적용했다. 배포 전 점검을 ./run.sh check 하나로 묶었다.

$ ./run.sh check
=== 배포 전 점검 ===
  [문제] SITE_URL 이 설정되지 않았거나 localhost 입니다.
         → .env 에 SITE_URL=https://your-domain.com 추가
  [문제] PUBLIC_CONTACT_EMAIL 이 비어 있습니다.
         → 개인정보처리방침에 문의 연락처가 없으면 심사에서 반려될 수 있습니다.
  [안내] 글 3개 (발행 3개 / 작성중 0개)

“배포 전에 SITE_URL 확인하기”를 문서에 적어두면 언젠가 빠뜨린다. 명령 하나로 만들어두면 빠뜨릴 수가 없다.

그래도 문서에 남겨야 하는 것

전부 자동화할 수 있는 건 아니다. 문서에 남겨야 할 것은 이런 종류다.

• 판단 기준: “파일이 500줄을 넘기면 분리를 검토한다”
• 왜 그렇게 하는지: 이유가 없으면 규칙은 상황이 바뀔 때 잘못 적용된다
• 프로젝트별 함정: “이 서버는 재시작 순서가 중요하다” 같은 것

여기서 하나 더 배운 게 있다. 문서를 읽는 대상에 따라 나누는 것이 효과가 있었다.

• 사람과 팀이 읽어야 하는 요구사항, 완료 기준, 설계 결정 → docs/
• 에이전트만 참고할 운영 지식, 반복되는 함정, 복구 절차 → docs_for_ai/
• 에이전트가 직접 실행하는 디버깅 도구 → tools_for_ai/

섞어두면 양쪽 다 안 읽는다. 사람용 문서에 에이전트용 세부 절차가 섞이면 사람이 안 읽고, 그 반대도 마찬가지다.

정리

규칙이 안 지켜질 때 문서를 더 길게 쓰는 건 대체로 효과가 없다. 오히려 반대다. 문서가 길어질수록 각 항목의 영향력은 희석된다.

• 기계가 검사할 수 있는 규칙은 훅, 테스트, CI, 점검 스크립트로 옮긴다
• 지침(“하지 마세요”)과 장치(“할 수 없습니다”)는 신뢰도가 다르다
• 문서에는 판단이 필요한 것과 이유만 남긴다
• 문서는 읽는 대상별로 나눈다. 섞으면 아무도 안 읽는다

규칙 문서가 계속 길어지고 있다면, 그중 기계가 대신 확인해줄 수 있는 항목이 몇 개인지 세어보면 좋다. 내 경우엔 절반 가까이가 그랬다.