/init으로 생성한 AGENTS.md가 오히려 비용을 20% 늘리는 이유와 올바른 컨텍스트 설계 전략

AI 코딩 에이전트를 도입하면서 “AGENTS.md를 만들어두면 성능이 더 좋아지지 않을까?”라고 생각해본 적 있으신가요? 실제로 많은 팀이 /init 명령으로 AGENTS.md를 자동 생성해 에이전트의 이해도를 높이려 합니다.

하지만 최근 연구 결과는 정반대의 사실을 보여줍니다. 자동 생성된 AGENTS.md는 작업 성공률을 낮추고, 비용을 20% 이상 증가시킬 수 있습니다. 반대로, 잘 설계된 컨텍스트 파일은 실행 시간과 토큰 사용량을 줄이는 효과를 보이기도 합니다.

이 글에서는 AGENTS.md가 언제 도움이 되고, 언제 오히려 해가 되는지, 그리고 정적 파일을 넘어서는 더 나은 컨텍스트 설계 전략은 무엇인지 정리합니다.

반응형

---

AGENTS.md, 도움이 될까? 해가 될까?

1. 개발자가 작성한 AGENTS.md는 성능을 개선한다

Lulla et al. (ICSE JAWs 2026)의 연구에서는 GitHub PR 124개를 대상으로 AGENTS.md의 유무만 바꾼 페어드 실험을 진행했습니다.

그 결과:

• 실행 시간 28.64% 감소
• 출력 토큰 16.58% 감소

이 실험에서 사용된 AGENTS.md는 개발자가 직접 유지보수하던 파일이었습니다. 즉, 코드만 읽어서는 알 수 없는 프로젝트 고유의 지식이 포함돼 있었습니다.

핵심은 “정보의 질”입니다.

---

2. LLM이 자동 생성한 AGENTS.md는 오히려 성능을 떨어뜨린다

ETH Zurich 연구에서는 4개 에이전트를 SWE-bench 등에서 테스트하며 다음을 비교했습니다.

• LLM 자동 생성 컨텍스트 파일
• 개발자가 직접 작성한 파일

결과는 분명했습니다.

• LLM 자동 생성 파일:
  • 작업 성공률 2~3% 하락
  • 비용 20% 이상 증가
• 단, README 등 기존 문서를 모두 제거한 환경에서는 오히려 2.7% 성능 향상

반면,

• 개발자 작성 파일:
  • 성공률 약 4% 향상
  • 비용 최대 19% 증가

결론은 단순합니다.

자동 생성이 문제라기보다, 중복이 문제입니다.
에이전트가 이미 알 수 있는 정보를 다시 제공하면 노이즈만 늘어납니다.

---

왜 자동 생성 AGENTS.md는 해로울까?

자동 생성된 AGENTS.md에는 대개 다음이 포함됩니다.

• 코드베이스 개요
• 디렉토리 구조
• 기술 스택 설명
• 모듈 구조

하지만 최신 코딩 에이전트는 이미 전체 코드베이스를 탐색할 수 있습니다.

Sonnet 4.5 출력의 100%, GPT-5.2 출력의 99%가 코드베이스 개요를 스스로 생성합니다.

이미 알고 있는 정보를 또 주면 어떻게 될까요?

• 토큰만 추가 소비
• 컨텍스트 길이 증가
• 주의력 분산
• 성능 저하

여기에 앵커링 효과까지 더해집니다.
예를 들어 “이 프로젝트는 레거시 패턴을 사용한다”는 문장이 있으면, 더 나은 대안이 있어도 그 패턴에 고착될 수 있습니다.

“Lost in the Middle” 연구(Liu et al., 2024)에서도 긴 컨텍스트는 주의 분산을 유발해 성능을 떨어뜨린다고 지적합니다.

---

AGENTS.md에 반드시 넣어야 할 것 vs 넣지 말아야 할 것

넣어야 할 것: 에이전트가 코드로 알 수 없는 정보

다음은 반드시 문서화할 가치가 있습니다.

• 도구 지정
  예: “패키지 관리는 uv를 사용할 것”
• 비직관적 실행 규칙
  예: “테스트는 반드시 --no-cache로 실행. 그렇지 않으면 fixture가 false positive 발생”
• 시스템 제약
  예: “auth 모듈은 커스텀 미들웨어 사용 중. 표준 Express로 리팩토링 금지”

흥미로운 점은, 문서에 명시된 도구는 작업당 1.6~2.5회 사용되지만, 문서에 없으면 0.05회 미만으로 급감합니다.
문서화는 실제 행동을 바꿉니다.

---

넣지 말아야 할 것: 에이전트가 스스로 발견 가능한 정보

• 디렉토리 구조
• 모노레포 레이아웃
• 기술 스택 개요
• 표준 아키텍처 패턴

이 정보는 사람에게는 친절하지만, 에이전트에게는 중복일 가능성이 높습니다.

---

정적 AGENTS.md의 구조적 한계

잘 작성된 AGENTS.md라도 한계가 있습니다.

문서는 정적(static)이고, 작업은 동적(dynamic)입니다.

예를 들어:

• 문서 수정 작업에도 “커밋 전 전체 테스트 실행” 지시가 적용
• CSS 리팩토링에 DB 마이그레이션 경고가 로드
• 보안 수정에 성능 최적화 힌트가 함께 포함

모든 작업에 모든 지침이 적용되면서 토큰과 시간이 낭비됩니다.

ACE 프레임워크(ICLR 2026)는 정적 파일 대신 generator / reflector / curator 파이프라인을 사용하는 Agentic Context Engineering 접근법을 제안합니다.
이 방식은 정적 파일 대비 12.3% 높은 성능을 기록했습니다.

핵심은 컨텍스트를 동적으로 진화시키는 것입니다.

---

더 나은 구조: 계층형 컨텍스트 설계

여러 연구와 실무 사례는 공통된 결론에 도달합니다.

단일 AGENTS.md 파일이 아니라, 라우팅 계층 + 선택적 로드 구조가 더 적합합니다.

Layer 1 – 프로토콜 파일

• 사용 가능한 페르소나
• 호출 조건
• 스킬과 담당 작업 유형
• MCP 연결과 용도

여기에는 최소한의 “발견 불가능한 정보”만 포함합니다.

---

Layer 2 – 페르소나/스킬 파일

• UX 에이전트는 UX 컨텍스트만 로드
• 백엔드 에이전트는 백엔드 컨텍스트만 로드

불필요한 정보는 아예 읽지 않도록 설계합니다.

---

Layer 3 – 유지보수 서브에이전트

문서는 부패합니다.

6개월 방치된 AGENTS.md가 이미 교체된 의존성이나 변경된 구조를 설명하고 있다면, 그 자체가 리스크입니다.

정확성을 유지하는 전담 에이전트가 필요합니다.

현재 주요 코딩 에이전트는 이 구조를 완전하게 지원하지 않으며, 아직 도구 공백이 존재합니다.

---

자동 최적화 루프의 가능성

Arize AI는 CLAUDE.md 지시문을 수동 작성하지 않고 자동 최적화 루프를 사용합니다.

프로세스는 다음과 같습니다.

1. 학습용 작업에 에이전트 실행
2. 결과 평가
3. 실패 원인에 대한 LLM 피드백 생성
4. 메타프롬프팅으로 지시문 개선
5. 반복

그 결과:

• cross-repo 테스트 +5.19%
• in-repo 테스트 +10.87%

여기서 드러난 중요한 사실이 있습니다.

사람에게 유용한 정보와 LLM에게 필요한 정보는 다릅니다.

• “이 서비스는 repository 패턴 사용” → 사람에게 유용
• 특정 import 경로 구분, 비직관적 파일 명명 규칙 → 모델에게 더 중요

수동 작성은 “개발자가 필요한 걸 알고 있다”는 가정 위에 서 있습니다.
경험적 증거는 그렇지 않을 가능성을 시사합니다.

---

AGENTS.md를 바라보는 올바른 마인드셋

AGENTS.md는 영구 설정이 아닙니다.
진단 도구입니다.

한 줄을 추가할 때마다 이렇게 생각해볼 수 있습니다.

“왜 에이전트가 이걸 헷갈렸을까?”

예:

• 유틸리티를 엉뚱한 디렉토리에 넣음 → 디렉토리 구조가 혼란스러움
• 폐기된 의존성을 계속 사용 → import 구조가 잘못 설계됨
• 타입 검사를 빠뜨림 → 빌드 파이프라인에서 자동 검증해야 함

정답은 파일을 키우는 것이 아니라, 코드베이스를 고치는 것입니다.

실험해볼 수 있는 방법도 있습니다.

AGENTS.md를 거의 비운 상태에서
“이 프로젝트에서 놀랍거나 혼란스러운 점을 발견하면 코멘트로 남겨라”
라는 지시 하나만 두는 것입니다.

에이전트가 제안하는 내용은 영구 보관용 문서가 아니라, 코드베이스의 문제 지점을 알려주는 신호일 수 있습니다.

---

실용적 권장사항

1. /init 실행을 중단하십시오.
   문서가 전혀 없는 레포가 아니라면 중복 가능성이 높습니다.
2. 한 줄 추가 전 자문하십시오.
   “에이전트가 코드를 읽으면 알 수 있는가?”
   그렇다면 쓰지 마십시오.
3. 반복 실패 시 문서보다 코드베이스를 먼저 수정하십시오.
   • 구조 개선
   • 린터 규칙 추가
   • 테스트 커버리지 확대
4. 대규모 CI/CD 환경에서는 15~20% 비용 오버헤드가 복리로 누적됩니다.
5. 에이전트는 신입 사원이 아닙니다.
   사무실 투어는 필요 없습니다.
   필요한 것은 지도(map)가 아니라 지뢰의 위치(mines)입니다.

---

728x90

AGENTS.md는 설정 파일이 아니라 문제 탐지기다

자동 생성된 AGENTS.md는 편리해 보입니다.
하지만 대부분의 경우 중복 정보로 인해 성능을 낮추고 비용을 높입니다.

반대로, 코드로는 알 수 없는 제약과 규칙만 정제해 담으면 분명한 효과가 있습니다.

더 나아가, 정적 파일이 아닌 동적 컨텍스트 설계와 자동 최적화 루프가 미래 방향일 가능성이 높습니다.

결국 핵심은 이것입니다.

AGENTS.md를 키우는 대신, 코드베이스를 더 명확하게 만드십시오.
에이전트가 헷갈리는 지점은, 사람도 헷갈릴 가능성이 높습니다.

AGENTS.md는 답이 아니라 신호입니다.
그 신호를 따라가면 더 단단한 코드베이스와 더 효율적인 AI 협업 구조에 도달할 수 있습니다.

300x250

https://addyosmani.com/blog/agents-md/

Stop Using /init for AGENTS.md