AI 에이전트의 비대해진 명령어 파일을 위한 무손실 다이어트

대부분의 AI 코딩 에이전트는 모든 세션에 프로젝트 지침 파일을 로드합니다. 처음에는 규약을 모아놓은 페이지로 시작하지만, 점차 배포 런북, 장애 후속 조치 보고서, 스키마 마이그레이션 노트, 프론트엔드 관련 특이사항 등 팀의 잡동사니 서랍이 되어갑니다. 저희의 파일은 253줄, 67KB, 약 33,000 토큰에 달했으며, 에이전트가 코드 한 줄을 읽기도 전에 주입되었습니다. 이 글에서는 파일을 10KB의 라우팅 허브로 축소한 구조 조정 과정, 남겨둬야 했던 안전 규칙, 그리고 이 전환으로 인해 잃은 것이 없음을 증명한 검증 과정을 설명합니다. 모든 것을 결정한 제약 조건은 어떤 내용도 삭제할 수 없으며, 오직 이동하거나 병합할 수만 있다는 것이었습니다.

명령 파일이 비대해지는 이유: 목적지 없는 규칙

파일이 커진 것은 누군가 부주의해서가 아니었습니다. "정책이나 설정이 변경될 때마다 즉시 명령 파일을 업데이트하라"는 책임감 있게 들리는 규칙 때문에 커졌습니다. 그 규칙에는 라우팅이 없었습니다. 모든 프로젝트는 반드시 읽힐 것이 보장된 하나의 파일에 운영 세부 정보를 추가했습니다. 왜냐하면 그곳이 미래의 에이전트가 반드시 찾아볼 유일한 장소였기 때문입니다.

이것이 바로 여러분의 설정에서도 인지할 가치가 있는 구조적인 원인입니다. 추가만 하는 문화(append-only culture)를 가진, 항상 로드되는 단일 파일은 단조롭게 증가합니다. 모든 경고는 과거의 어떤 사건을 통해 그 자리를 차지했기 때문에, 아무도 경고를 제거할 수 있는 위치에 있지 않습니다. 1년 후, 우리는 테이블 셀 안에 10개 문단의 이력이 담기게 되었고, 에이전트는 해당 문단이 설명하는 하위 시스템을 전혀 건드리지 않는 세션을 포함한 모든 세션에서 토큰 비용을 지불했습니다.

낭비는 단지 돈뿐만이 아닙니다. 33,000 토큰의 서문은 주의를 분산시킵니다. 모델은 긴 컨텍스트 중간에 묻힌 명령을 놓치는 것이 입증되었습니다. 에이전트가 가장 준수해야 할 경고들은 몇 달 전의 크롤러 결함에 대한 문단들과 경쟁하고 있었습니다.

주제별로 분리하되, 스톱 게이트는 유지하기

해결책은 명확합니다. 세부 사항을 필요할 때 읽는 주제 문서로 옮기고, 허브는 작게 유지하는 것입니다. 우리는 결국 8개의 운영 문서(배포, 클라우드 리소스, 관리자 웹, 라이선싱, 음성 파이프라인, 데이터 수집, 크롤링, 야간 배치)와 마이그레이션 파일 자체 옆에 있는 마이그레이션 README를 갖게 되었습니다. 각 문서는 자신의 도메인을 완전히 소유합니다. 허브는 주제당 한 줄과 포인터를 유지합니다.

파일 레이아웃보다 더 중요했던 두 가지 설계 결정이 있었습니다.

첫째, 인덱스는 그저 정중한 링크 목록이어서는 안 됩니다. 시간 압박을 받는 담당자는 목록을 훑어보고 코딩을 시작할 것입니다. 우리는 이를 조건부 라우팅 테이블처럼 작성했습니다. "라이선싱 또는 시트 로직 수정 시: 먼저 docs/ops/license.md를 반드시 읽어야 합니다." 차이가 사소하게 들릴 수 있습니다. 실제로는, 전제 조건으로 표현된 지침은 준수되지만, 참조로 표현된 링크는 건너뛰게 됩니다. 또한 무언가가 어디에 있는지 확실하지 않을 때 파일을 통째로 읽는 대신 docs 디렉터리에서 키워드로 grep하라는 한 줄을 추가했습니다.

둘째, 그리고 이것이 사고를 방지하는 부분인데, 일부 경고는 절대 옮겨서는 안 됩니다. 만약 "배포 전 보류 중인 스키마 마이그레이션을 실행하라"는 내용이 담당자가 열어보지 않을 수도 있는 문서에만 있다면, 언젠가 담당자는 그 문서를 읽지 않고 배포할 것이고, 그 경고가 담고 있던 사고는 다시 발생할 것입니다. 우리는 이러한 경고 중 7개를 스톱 게이트(Stop Gates)라는 제목 아래 허브에 유지했으며, 각각은 세부 사항이 위임된 요약된 불변 사항입니다.

• 모든 배포 전에 마이그레이션 상태를 확인하고, 불분명하면 배포하지 마십시오. 먼저 이미지를 되돌려 롤백하고, 그 다음에 스키마 되돌리기를 고려하십시오.
• 관리되는 런타임 환경 변수를 변경할 때는 추가(additive) 플래그만 사용하십시오. 모든 것을 교체(replace-everything)하는 방식은 관련 없는 구성을 조용히 삭제합니다.
• 사용자 음성 녹취록, 번역 또는 비밀 값을 로그, 문서 또는 커밋에 절대 기록하지 마십시오.
• 데이터베이스 IP 허용 목록 플래그는 전체 목록을 덮어씁니다. 먼저 현재 목록을 읽고 합집합으로 패치하십시오.
• 수집된 오디오에 대한 보존 및 동의 규칙은 불변 사항입니다. 이를 건드리기 전에 데이터 문서를 읽으십시오.
• 프로덕션 저장소에 대한 파괴적이거나 덮어쓰기 방식의 명령어는 먼저 대상, 영향 반경 및 롤백 확인이 필요합니다.
• 유료 엔드포인트 인증, 속도 제한 또는 페일-클로즈(fail-closed) 방식의 평가판 로직을 절대 우회, 삭제 또는 약화시키지 마십시오.

우리가 사용한 선택 규칙은 다음과 같습니다. 경고를 무시했을 때 중단, 데이터 손실, 규정 위반 또는 고객에게 보이는 장애를 유발하면 허브에 남기고, 단지 오후 시간을 낭비하는 정도라면 밖으로 옮깁니다. 사용 빈도가 아니라 무시했을 때의 비용입니다.

허브의 맨 위, 모든 것 위에 한 줄이 더 추가되었습니다. 문서와 코드가 일치하지 않을 때는 코드가 진실입니다. 문서를 업데이트하고, 오래된 문서에 맞추기 위해 작동하는 코드를 "수정"하지 마십시오. 분리된 문서 시스템은 담당자가 모순을 발견하고 잘못된 방향으로 해결할 때 최악의 실패를 겪습니다.

이동으로 인해 손실된 것이 없음을 증명하기

"모든 것을 옮겼으니 믿어주세요"는 검증이 아닙니다. 우리의 첫 번째 계획은 grep으로 몇 가지 독특한 토큰을 무작위로 확인하는 것이었습니다. 한 검토자가 샘플링으로는 잡아낼 수 없는 세 가지 실패 모드를 지적했습니다. 토큰은 살아남았지만 그 주변 문장이 잘려나가는 경우, 텍스트가 이전 파일에 그대로 남아있어도 이전 파일과 새 파일의 합집합은 통과하는 경우, 그리고 텍스트가 잘못된 문서에 들어가는 경우입니다. 샘플링은 샘플만 증명할 뿐, 그 이상은 아무것도 증명하지 못합니다.

대신, 우리는 모두 기계적인 방법을 실행했습니다.

첫째, 편집 전 원본 파일의 스냅샷에서 모든 인라인 코드 스팬을 추출했습니다. 이는 백틱으로 묶인 모든 명령어, 플래그, 경로, 식별자를 의미합니다. 고유한 스팬 583개를 얻었습니다. 각 스팬은 $1::text[]와 같은 스팬이 정규식 메타문자로 가득 차 있기 때문에 정규식이 아닌, 공백 정규화 후 고정된 문자열로 비교하여 새 문서들의 합집합 어딘가에 나타나야 합니다.

둘째, 경고 표시(금지, 필수, 주의를 나타내는 단어 및 문서에서 사용하는 경고 이모지)가 포함된 모든 문장을 추출했습니다. 61개의 문장을 얻었습니다. 마이그레이션은 재작성이 아닌 그대로의 이동이었기 때문에, 각 문장은 정규화 후 글자 하나하나까지 똑같이 어딘가에 존재해야 했습니다. 이것이 바로 이 검사를 강력하게 만드는 비결입니다. 이동된 문장은 그 조건, 심각성, 이유를 함께 가지고 갑니다. 단 세 문장만이 이 검사를 통과하지 못했으며, 각각 문서화된 사유가 있었습니다. 하나는 중복된 문장과 병합되었고, 다른 하나는 표의 여러 행에 걸쳐 분할되었으며, 또 다른 하나는 내부 상호 참조가 의도적으로 재작성되었습니다. 사유가 없는 것은 무엇이든 출시 중단(stop-ship) 사유가 되었을 것입니다.

셋째, 게이트가 아닌 이상 탐지기로서의 바이트 계산입니다. 새 파일들의 합은 원본의 129%였습니다(헤더, 포인터, 그리고 새로운 Stop Gates 섹션이 텍스트를 추가함). 만약 그 수치가 60%로 나왔다면 원인을 찾아 나섰을 것입니다. 우리는 의도적으로 이를 통과/실패 임계값으로 삼지 않았습니다. 왜냐하면 합법적인 중복 제거 과정은 전체 크기를 줄일 수 있는 반면, 잘못된 이동은 잘못된 텍스트가 그대로 있는 상태에서도 임계값을 통과할 수 있기 때문입니다.

스팬 검사는 즉시 그 가치를 증명했습니다. 웹 서버 하위 명령어가 비슷하게 이름 붙여진 실시간 하위 명령어와는 구별된다는 내용의 한 문장이 마이그레이션 맵의 빈틈으로 빠져 있었습니다. 67KB를 두 번 읽는 사람이라도 누락된 절 하나를 찾아내지는 못했을 것입니다. 583개의 스팬에 대한 고정 문자열 비교는 몇 초 만에 이를 잡아냈고, 우리는 출시 전에 이를 복원했습니다.

새 에이전트로 라우팅 스모크 테스트하기

텍스트 검증은 보존을 증명합니다. 하지만 새로운 레이아웃이 작동한다는 것을 증명하지는 않습니다. 이를 위해 새 에이전트 세션에 새로운 10KB 허브만 제공하고 세 가지 질문을 했습니다. 좌석 라이선싱 로직을 수정하기 전에 무엇을 읽어야 하는지, 관리자 웹 서비스를 어떻게 배포하는지, 그리고 프로덕션 환경의 캐시를 삭제해 달라는 것이었습니다.

처음 두 답변은 올바른 문서로 라우팅되었고 마이그레이션 게이트를 인용했습니다. 세 번째 답변이 바로 설계할 가치가 있는 부분이었습니다. 에이전트는 어떤 것도 실행하기를 거부했고, 파괴적인 작업 중지 게이트를 인용했으며, 어떤 환경과 어떤 키 접두사를 사용할지 물었고, 전체 삭제 대신 범위 지정 삭제를 제안했습니다. 이러한 거부가 바로 항상 로드되는 파일에 중지 게이트를 유지하는 핵심 이유였습니다. 만약 스모크 테스트에서 에이전트가 무언가를 거부하도록 만들 수 없다면, 그 테스트는 너무 가벼운 것입니다.

작게 유지하기: 파일만이 아닌 규칙을 수정하세요

마지막 변경 사항은 6개월 후에 전체 작업을 다시 실행하는 것을 방지하는 것이었습니다. 기존의 증가 규칙("항상 지침 파일 업데이트")은 라우팅 규칙으로 대체되었습니다. 즉, 상시 규칙, 좌표, 중단 게이트는 120줄 및 10KB의 하드 캡이 있는 허브로 이동하고, 운영 세부 정보, 플래그, 인시던트 기록은 해당 도메인을 소유하는 주제 문서로 이동하며, 의사결정 근거는 설계 로그로, 코드-로컬 트랩은 보호하는 코드 옆의 코드 주석으로 이동합니다. 허브가 상한선을 초과할 경우, 필요한 대응은 상한선을 협상하는 것이 아니라 콘텐츠를 분리하는 것입니다.

규모를 파악하기 위한 몇 가지 최종 수치입니다. 허브는 67KB에서 10KB 미만으로 줄었으며, 이는 모든 단일 에이전트 실행에서 약 28,000개의 토큰에 해당하는 세션 컨텍스트를 절약한 것입니다. 검증 스위트는 약 40줄의 Python과 셸로 구성됩니다. 세 차례의 검토와 검증 툴링을 포함한 전체 마이그레이션은 하루 분량의 작업이었습니다. 만약 여러분의 에이전트 지침 파일이 수천 토큰을 넘어서고 계속 증가한다면, 이러한 감량은 저렴하고 토큰 절약 효과는 매일 복리로 쌓이며, 스팬 수준 검증을 통해 작은 파일과 안전한 파일 사이에서 선택할 필요가 없습니다.