AGENTS.md 룰 하나로 Codex 토큰 사용량 약 50% 줄인 후기

AGENTS.md에 미지의 명령 출력을 4000바이트로 자르는 규칙을 더해 작성자 평가 기준 컨텍스트가 약 50% 줄어든 기록.

요약

Codex 같은 코딩 에이전트가 명령으로 파일을 읽을 때 출력이 너무 커지지 않도록 AGENTS.md에 규칙 한 줄을 넣었더니, 작성자 본인이 돌린 평가 기준으로 컨텍스트 사용이 약 50% 줄었다는 개인 적용 사례.

작성자는 작업 종류에 따라 절감 폭이 더 크거나 더 적다는 단서를 본인이 직접 붙였다.

내용

작성자가 추가한 핵심 규칙은 한 줄이다.

• 출력이 얼마나 클지 알 수 없거나, 클 가능성이 있는 명령은 바이트 단위로 자른다.
• 기본 패턴은 COMMAND 2>&1 | head -c 4000 형태로, 표준출력과 표준오류를 합쳐 앞쪽 4000바이트만 남기는 식이다.

작성자는 줄 수 제한만으로는 안전하지 않다고 적었다. head -n 20처럼 줄 수만 제한해도 한 줄이 길면 컨텍스트가 그대로 터질 수 있다는 이야기다. 본인은 개행이 없는 5MB 이상 SQLite 파일에서 그런 상황을 겪었다고 했다.

두 번째로 큰 절감 포인트로는 매 작업마다 테스트, 타입 체크, 전체 검증을 돌리지 않도록 "언제 검증을 돌릴지"에 대한 규칙을 따로 추가한 점을 들었다.

평가는 작성자가 직접 돌린 몇 가지 작업 — 파일 탐색, 웹 개발, "이 저장소부터 파악해 줘" 같은 저장소 파악 작업 — 기준이고, 절감 폭은 약 50%, 작업에 따라 더 많거나 더 적다고 본인이 단서를 붙였다.

AGENTS.md에는 명령 출력 규칙 외에도 서브에이전트 사용, 복잡도 줄이기, 검증 시점 같은 규칙이 함께 들어 있고, Codex 시스템 프롬프트도 GPT-5 베이스에서 게임/웹 디자인 같은 무관한 부분을 덜어낸 버전으로 바꿨다고 적었다. AGENTS.md 본문 전체와 시스템 프롬프트 수정본 자체는 원문 참고.

댓글에서 남긴 점

• 유저1: 비슷하게 명령 출력을 자르거나 다시 쓰는 도구를 도입한 뒤, 디버깅에 필요한 정보까지 함께 빠져 코딩 에이전트 품질이 떨어졌고, 한참 뒤에야 그 도구 때문이라는 걸 알아챘다는 사례. 출력 잘라내기가 문제 원인 파악에 필요한 신호까지 빼버릴 수 있다는 부작용 신호다.
• 유저2 → 작성자: Codex가 작은 작업에도 테스트와 Xcode 빌드/시뮬레이터를 자주 돌렸다는 관찰에 대해, 작성자는 시스템 프롬프트에서 테스트 실행 부분을 제거하고 "테스트는 가끔만, 돌릴 때는 바이트 캡과 함께"라는 규칙을 넣었다고 답했다. Playwright나 vitest 같은 테스트 도구가 큰 출력을 뱉는다는 점이 이유였다.

범위와 한계

• 50% 절감 폭은 작성자 본인이 돌린 평가 기준이다. 어떤 저장소·모델·세션 길이에서 돌린 평가인지, 표본 크기가 얼마인지는 본문에 자세히 적혀 있지 않다.
• 시스템 프롬프트도 함께 바꿨기 때문에, 절감 폭이 명령 출력 규칙 하나로 나온 것인지 시스템 프롬프트 변경까지 합쳐서 나온 것인지는 본문에 분리되어 있지 않다.

댓글에서 나온 의문

• 출력을 잘라내는 방식이 캐시 동작과 캐시 가격에 영향이 있는지.
• Codex 앱과 CLI 양쪽에서 같은 방식이 동작하는지.
• 두 의문 모두 작성자가 본문에서 답하지 않았다.