테스트가 중요한 이유

AI 기반 코드 어시스턴트는 종종 팀이 저장소에 "규칙(rules)" 파일을 넣어두면 모델이 모든 요청에서 그 지침을 따를 것이라고 기대하곤 합니다. 실제로 모델은 파일을 전혀 보지 못하거나, 파일을 보더라도 내용을 무시할 수 있습니다. 최근 Claude Code를 이용한 실험에서 이 두 가지 문제가 모두 나타났습니다. 해당 도구는 72KB 크기의 AGENTS.md 파일을 조용히 건너뛰었습니다. 하지만 동일한 파일의 이름을 CLAUDE.md로 변경하자 어시스턴트가 이를 로드했고, 각 요청당 토큰 수가 증가했습니다. 이러한 추가 토큰 예산은 지연 시간과 비용을 늘리고, 요청이 모델의 제한 범위를 초과하게 만들 수 있습니다.

"파일이 존재한다"는 것이 곧 "모델이 규칙을 따른다"는 뜻이라고 가정하는 개발자는 숨겨진 비효율성과 예측 불가능한 결과라는 위험을 감수하게 됩니다. 3단계 테스트는 구성(configuration), 로드(loading), 유용성(usefulness)의 각 단계에서 구체적인 증거를 요구합니다.

확인해야 할 세 가지 질문

  1. 구성(Configured) – 파일이 어시스턴트가 찾는 위치에 배치되어 있는가? 도구마다 경로 또는 파일 이름 규칙이 하드코딩되어 있을 수 있으며, 이 규칙이 일치하지 않으면 파일은 프롬프트 파이프라인에 전혀 포함되지 않습니다.
  2. 로드(Loaded) – 어시스턴트가 파일을 받았다는 증거를 보여주는가? 해시(hash)를 통해 디스크에 있는 파일의 정체성을 확인할 수는 있지만, 모델이 실제로 파일을 확인했음을 증명하는 것은 전달 추적(예: 로그 라인 또는 토큰 수)뿐입니다.
  3. 유용성(Useful) – 파일의 존재가 작업 결과의 품질을 향상시키는가? 토큰만 추가하고 결과에는 변화를 주지 못하는 로드된 파일은 결국 손해입니다.

테스트 실행하기

이 절차는 어떤 플랫폼에서도 반복할 수 있도록 의도적으로 최소화되었습니다.

  1. 눈에 보이는 규칙 생성 – 간단하고 관찰 가능한 지침을 작성합니다. 예를 들어, "편집하기 전에 정확히 두 개의 파일만 나열하라"와 같은 규칙입니다. 규칙의 효과는 어시스턴트의 응답을 통해 확인할 수 있습니다.

  2. 도구 버전 및 모델 확인 – 새로운 세션을 열고 버전 문자열과 모델 식별자를 기록합니다. 버전에 따라 인식하는 파일 이름이 달라질 수 있습니다.

  3. 두 번의 실행 수행 실행 A: 도구가 인식하지 않는 파일 이름을 사용합니다 (예: AGENTS.md). 실행 B: 도구의 기본 파일 이름을 사용합니다 (예: CLAUDE.md).

    기록 사항:

    • 파일의 소스 해시 (디스크 콘텐츠가 변경되지 않았음을 증명하기 위함)
    • 사용된 정확한 경로
    • 어시스턴트가 파일을 로드하면서 남긴 증거 (토큰 수 증가, "loaded X.md"와 같은 명시적 메시지 등)
    • 각 요청의 토큰 수
    • 작업 결과 (어시스턴트가 정확히 두 개의 파일을 나열했는가?)

실행 B에서 규칙이 준수되고 토큰 수가 예상만큼 증가했다면, 파일이 성공적으로 로드되었으며 유용하다는 뜻입니다. 만약 토큰 수는 늘어났는데 규칙이 무시된다면, 파일은 읽히고 있지만 모델의 프롬프트 파싱 과정에서 지침이 버려지는 것입니다. 이 경우 파일에 텍스트를 더 추가하는 것은 도움이 되지 않습니다. 대신 규칙을 하드코딩된 정책 게이트(policy gate)나 테스트 하네스(test harness)로 옮기십시오.

데이터가 보여주는 것

Claude Code 사례는 구성과 로드 사이의 극명한 차이를 보여주었습니다. 72KB 파일이 존재하고, 올바른 해시를 가지고 있으며, 저장소와 동기화되어 있었음에도 불구하고 어시스턴트는 이를 전혀 참조하지 않았습니다. 파일 이름을 기본값인 CLAUDE.md로 변경하자 로드가 트리거되었지만, 상당한 토큰 오버헤드도 발생했습니다. 추가되는 각 토큰은 컴퓨팅 자원을 소모하며 요청이 속도 제한(rate limits)을 초과하게 만들 수 있습니다.

3단계 테스트는 이러한 숨겨진 비용이 운영상의 장애물(production blockers)이 되기 전에 드러내 줍니다. 토큰 차이(delta)를 파악함으로써, 팀은 규칙의 이점이 비용보다 큰지 여부를 결정할 수 있습니다.

요약

규칙 파일이 저장소에 있다고 해서 저절로 작동할 것이라고 가정하지 마십시오. 구성, 로드, 유용성 증명이라는 3단계 테스트를 사용하여 그 가정을 측정 가능한 증거로 바꾸십시오. 파일이 단순히 토큰만 잡아먹는 존재(token sink)라는 것이 증명되면, 로직을 프롬프트에서 분리하여 결정론적 게이트(deterministic gate)로 옮기십시오. 그 결과 더 가볍고, 빠르며, 예측 가능한 AI 코딩 워크플로우를 얻을 수 있습니다.