비대해진 AGENTS.md 토큰 다이어트: 3단계 서브에이전트 리팩토링 프롬프트

TypeScript 교육자이자 개발자인 맷 포콕(Matt Pocock, @mattpocockuk)이 2026년 10월 6일, 프로젝트의 AI 지침 파일인 AGENTS.md의 비대화와 토큰 낭비 문제를 해결하기 위한 실전 리팩토링 프롬프트(Prompt of the day)를 공개했습니다. AI 코딩 에이전트가 매 대화 턴마다 읽어 들이는 컨텍스트의 과부하를 줄이고 지침의 실행력을 극대화하기 위해, 3단계 서브에이전트를 점진적으로 활용하는 접근법을 제안했습니다.

소프트웨어 개발 프로젝트에서 AI 코딩 어시스턴트(Claude Code, Cursor, Windsurf, Codex 등)를 도입하는 사례가 보편화되면서, 프로젝트 루트의 AGENTS.md는 에이전트의 행동 지침을 정의하는 표준 파일로 자리 잡았습니다. 그러나 프로젝트가 진행됨에 따라 온갖 규칙과 컨벤션, 산발적인 금지 조항이 무분별하게 누적되면서, 이 파일 자체가 시스템 프롬프트의 거대한 병목 구간이자 토큰 낭비의 온상으로 변질되는 현상이 빈번하게 발생하고 있습니다.

1. AGENTS.md의 비대화와 컨텍스트 토큰 낭비 문제

맷 포콕은 해당 포스트에서 "AGENTS.md는 토큰 비효율(token inefficiency)이 발생하는 가장 흔한 원인이며, 이 프롬프트는 이를 근본적으로 해결한다"고 강조했습니다.

에이전트 하네스는 대화 세션이 시작되거나 프롬프트가 주어질 때마다 루트에 위치한 AGENTS.md 전체를 컨텍스트 윈도우에 주입합니다. 이때 문서가 수백 줄 이상으로 비대해지면 다음과 같은 문제가 발생합니다:

• 컨텍스트 윈도우 고갈과 비용 증가: 사소한 질문이나 단일 파일 수정 작업에서도 항상 수천 토큰에 달하는 고정 지침이 소모되어 API 호출 비용이 급증하고 대화 컨텍스트 제한에 빠르게 도달합니다.
• 주의 집중력(Attention) 분산: 거대한 단일 문서에 나열된 수많은 규칙으로 인해, 정작 당장 수행해야 하는 작업과 관련된 핵심 지침에 모델이 온전히 집중하지 못하고 환각이나 지침 누락이 발생합니다.
• 무효 지침의 누적: 린터나 컴파일러가 이미 기계적으로 강제하고 있는 규칙이나 LLM의 기본 추론 능력으로 충분히 처리 가능한 상투적 문구가 중복 기재되어 유효한 정보 밀도가 급격히 떨어집니다.

2. 맷 포콕의 AGENTS.md 리팩토링 프롬프트 전문

맷 포콕이 공유한 영문 프롬프트 전문은 다음과 같습니다. /writing-for-agents 커맨드 또는 스킬 트리거 아래 실행되도록 구성되어 있습니다.

Prompt of the day:

/writing-for-agents my AGENTS.md is a hot mess, propose a series of restructurings that:

- Remove no-ops
- Use progressive disclosure
- Move instructions to CODING_STANDARDS.md

Apply your work over three subagents, each more radical than the last. Create a single PR.

AGENTS.md is the most common source of token inefficiency. This prompt kills it dead.

이 프롬프트는 에이전트에게 단순한 문서 요약을 요청하는 대신, 명확한 3대 리팩토링 축을 설정하고 이를 3개의 서브에이전트에 점진적으로 위임하여 단일 풀 리퀘스트(PR)로 완결하도록 지시합니다.

3. 3대 구조 개선 원칙: 무효 지침 제거, 점진적 공개, 표준 분리

프롬프트에 제시된 핵심 요구사항은 에이전트 지침 아키텍처의 현대적 모범 사례 세 가지를 명문화하고 있습니다.

• 무효 지침 제거 (Remove no-ops): "깨끗하고 가독성 높은 코드를 작성하라", "버그를 만들지 말라", "변수명을 명확히 지어라"와 같은 상투적인 문구는 실제 모델의 코드 생성 품질을 높이지 못하면서 토큰만 낭비하는 대표적인 no-op(무효 연산)입니다. 또한 ESLint, Prettier, TypeScript 컴파일러 등 프로젝트 내 자동화 도구가 이미 감지하는 규칙도 텍스트 지침에서 과감히 삭제 대상이 됩니다.
• 점진적 공개 원칙 적용 (Use progressive disclosure): 백과사전식으로 모든 규칙을 루트 파일 하나에 몰아넣는 대신, 루트 AGENTS.md는 목차이자 가벼운 라우터(Router) 역할만 수행하도록 개편합니다. 상세 아키텍처나 배포 절차, 특정 라이브러리 가이드는 별도의 참조 문서나 온디맨드 스킬로 분리하고, 에이전트가 해당 작업을 실제로 수행할 때만 해당 경로를 탐색해 읽도록 유도합니다.
• 코딩 표준의 별도 파일 분리 (Move instructions to CODING_STANDARDS.md): 에이전트의 동작 환경 규약(예: 테스트 실행 방법, CLI 도구 사용법, 세션 워크플로우)과 순수 코드 스타일 규약(네이밍 규칙, 컴포넌트 분리 원칙 등)을 분리합니다. 코드 스타일과 패턴 규칙을 CODING_STANDARDS.md로 격리하면, 코드 작성 단계가 아닌 환경 설정이나 기획 단계에서 불필요한 토큰 낭비를 줄일 수 있습니다.

4. 3단계 서브에이전트 점진 실행과 단일 PR 통합 워크플로우

이 프롬프트의 독창적인 설계는 리팩토링의 실행 강도를 3단계 서브에이전트로 분할한 점에 있습니다.

• 점진적 급진성 (Each more radical than the last): 프롬프트는 각 서브에이전트의 작업을 사전 고정하는 대신, 회차를 거듭할수록 점진적으로 더 과감한(radical) 리팩토링 안을 도출하도록 지시합니다. 이를 통해 모델이 단순하고 소극적인 문구 정리에 그치지 않고 단계적으로 깊이 있는 구조 개선을 탐색하도록 유도합니다.
  • 초기 단계: 명백한 중복과 무효 지침 정리 등 보수적 정비
  • 중간 단계: 코딩 표준 분리와 지침 간결화 등 실질적 모듈화
  • 최종 단계: 루트 문서를 가벼운 라우터로 압축하고 점진적 공개 체계로 전면 재편하는 적극적 재구조화
• 단일 PR(Single PR)로 결과 도출: 세 서브에이전트의 작업 결과물을 여러 브랜치로 분산시키지 않고 최종적으로 하나의 단일 PR로 묶도록 지시합니다. 이를 통해 작업자는 단계별 제안이 누적 반영된 최종 git diff를 한눈에 검토하고, 맥락의 훼손 없이 안전하게 리팩토링을 반영할 수 있습니다.

비대해진 지침 문서는 에이전트의 지능을 돕는 대신 오히려 모델의 주의력을 갉아먹는 원인이 됩니다. Matt Pocock이 제안한 3단계 서브에이전트 프롬프트는 에이전트 지침 체계를 군더더기 없이 경량화하고자 하는 팀에게 실용적인 리팩토링 템플릿을 제공합니다.

원문 출처

• X (옛 트위터): Matt Pocock (@mattpocockuk) AGENTS.md 리팩토링 프롬프트 포스트