AGENTS.md 실전전략 - 헤매지 않는 에이전트를 만드는 컨텍스트 설계

백과사전이 아닌 목차로 — 컨텍스트 오염 없이 에이전트를 지휘하는 설계법

1. 왜 거대한 AGENTS.md는 역효과를 낳는가

예전에는 AGENTS.md에 모든 것을 담았다.

코딩 표준, 아키텍처 결정, 프로젝트 컨텍스트, 팀 문화.

 

OpenAI 팀조차도 처음에 이 접근을 시도했고, 예측대로 실패하였다.

 

실패 원인은 네 가지였다.

• 컨텍스트 밀어냄(Context Pollution):
  거대한 지침 파일이 실제 작업과 코드, 관련 문서를 밀어낸다.
  에이전트는 중요한 제약 조건을 놓치거나 잘못된 제약 조건을 최적화한다.
• 지침의 역설:
  모든 것이 "중요"하면 중요한 것은 없다.
  에이전트는 의도적 탐색 대신 로컬 패턴 매칭으로 후퇴한다.
• 급속한 부패:
  획일적인 거대 매뉴얼은 낡은 규칙들의 무덤이 된다.
  무엇이 여전히 유효한지 에이전트도, 사람도 판단하기 어렵다.
• 기계적 검증 불가:
  단일 블롭(blob)은 커버리지 검사, 신선도 확인, 교차 링크 검증이 불가능하여 드리프트가 불가피하다.

게다가 Spillwave Solutions의 기술 분석에 따르면,
장시간 세션에서 AGENTS.md는 컨텍스트 압축(compaction)으로 인해 요약되거나 소실된다.
세션 시작 1분에는 있던 지침이 45분 후에는 사라져 있는 것이다.

▲ AGENTS.md는 Codex, Claude Code, Cursor 등 주요 AI 코딩 에이전트에서 공통으로 지원되는 오픈 표준 포맷이다

---

2. 해결책: 목차 패턴 (Table of Contents Pattern)

AGENTS.md를 백과사전이 아닌 목차(Table of Contents)로 취급하라.

.
├── AGENTS.md          ← 약 100줄, 지도 역할
└── docs/
    ├── architecture/  ← 도메인별 아키텍처 맵
    ├── design/        ← 설계 문서 및 검증 상태
    ├── quality/       ← 품질 등급 및 기술 부채 추적
    └── plans/         ← 진행 중·완료된 실행 계획

 

AGENTS.md는 컨텍스트에 항상 삽입되는 약 100줄의 파일로, 주로 맵 역할을 한다.

 

"인증 관련 작업이면 docs/architecture/auth.md를 참조하라"는 식으로
에이전트를 더 깊고 신뢰할 수 있는 정보 소스로 안내한다.

 

이 구조를 점진적 공개(Progressive Disclosure) 라고 한다.
에이전트가 처음부터 모든 것을 로드하는 대신, 필요한 시점에 필요한 깊이의 정보만 접근하게 한다.

---

3. 좋은 AGENTS.md가 담아야 할 것들

약 100줄의 AGENTS.md가 담아야 할 최소한의 내용은 다음과 같다.

# 프로젝트 이름

## 빠른 시작
- 개발 서버 실행: `npm run dev`
- 테스트 실행: `npm test`
- 린트 검사: `npm run lint`

## 아키텍처 지도
- 전체 도메인 구조: [docs/architecture/overview.md](docs/architecture/overview.md)
- 의존성 방향 규칙: [docs/architecture/layering.md](docs/architecture/layering.md)
- 데이터 흐름: [docs/architecture/data-flow.md](docs/architecture/data-flow.md)

## 개발 규칙 (기계적 강제)
- 모든 경계에서 Zod로 데이터 파싱 필수
- 파일당 최대 300줄 제한 (린터 강제)
- 구조화된 로깅만 허용 (console.log 금지)

## 작업별 가이드
- 새 기능 추가: [docs/plans/feature-guide.md](docs/plans/feature-guide.md)
- 버그 수정: [docs/plans/bugfix-guide.md](docs/plans/bugfix-guide.md)
- 인프라 변경: 반드시 사람에게 에스컬레이션

## 품질 현황
- 도메인별 품질 등급: [docs/quality/grades.md](docs/quality/grades.md)
- 알려진 기술 부채: [docs/quality/tech-debt.md](docs/quality/tech-debt.md)

 

핵심 원칙은

• 에이전트에게 무엇을 하라고 가르치지 말고,
• 어디서 찾을지를 가르치는 것 이다.

---

4. 린터 오류 메시지를 에이전트 교육 도구로 활용하라

OpenAI 팀이 발견한 강력한 전술 중 하나는 린터 오류 메시지 자체에 수정 지침을 포함시키는 것이다.

 

여기서 린터 오류메시지란
소스 코드를 분석하여

• 잠재적인 프로그램 오류, 버그,
• 스타일 위반,
• 의심스러운 구조체 등을
  찾아내어 개발자에게 알려주는 경고를 말한다.

// 나쁜 린트 오류 메시지
❌ Error: Dependency violation detected

// 좋은 린트 오류 메시지 (에이전트가 읽고 자가 수정 가능)
❌ Error: Direct import from 'service' layer in 'repo' layer detected.
   Dependency rule: repo → service imports are not allowed.
   Architecture guide: docs/architecture/layering.md#dependency-rules
   Fix: Move the logic to a service layer file, or use a Providers interface.
   See example: src/providers/example.ts

 

에이전트는 이 오류 메시지를 읽고 무엇을 어떻게 고쳐야 하는지 스스로 파악할 수 있다.
수정 지침이 오류와 함께 에이전트 컨텍스트에 자동 주입되는 구조이다.

팁
AGENTS.md 목차 패턴과 린터 오류 메시지를 개선할 경우,
도입 전 Codex 에이전트가 아키텍처 위반을 포함한 PR을 생성하는 비율을 비약적으로 줄일 수 있다.
이를 위한 시간과 노력은 얼마 들지 않는다.

---

5. 문서 최신화를 자동화하라 — doc-gardening 에이전트

AGENTS.md와 docs/ 디렉토리의 가장 큰 적은 문서 부패이다.
코드는 빠르게 변하는데 문서는 그 속도를 따라가지 못한다.

 

이를 해결하기 위해서는 기계적 시행 체계를 구축해야 한다.

1. 전용 린터 및 CI 작업:
   지식 베이스가 최신 상태인지,
   교차 링크가 유효한지,
   올바르게 구성되어 있는지 자동 검증
2. doc-gardening 에이전트:
   주기적으로 오래되거나 유효하지 않은 문서를 검토하여 수정용 PR을 자동 생성
3. 품질 등급 시스템:
   각 도메인의 문서 품질에 등급을 매기고 시간에 따른 격차를 추적

문서를 최신 상태로 유지하는 것은 사람의 작업이 아니라 에이전트의 작업이 된다.

 

 

▲ AI 코딩 에이전트

워크플로 및 성능 분석의 예시

---

6. 계획을 일급 아티팩트로 취급하라

마지막으로 계획을 일급 아티팩트(first-class artifact) 로 취급하라.

• 단순한 변경에는
  간단한 임시 계획
• 복잡한 작업에는
  진행 상황과 의사결정 로그를 포함한 실행 계획을 리포지토리에 저장
• 진행 중인 계획, 완료된 계획, 알려진 기술 부채를
  모두 버전화하여 같은 위치에 배치

이를 통해 에이전트가 작은 안정적인 진입 지점에서 시작하여 다음 단계로 나아가는 점진적 공개가 가능해진다.

---

마치며

AGENTS.md는 에이전트에게 모든 것을 가르치려 하면 실패한다.
에이전트에게 어디서 찾아야 하는지를 알려주는 지도가 되어야 한다.

 

지금 당장 시작할 수 있는 것은 이것이다.
현재 AGENTS.md(또는 CLAUDE.md)를 열어보라.

그것이 지도인가, 백과사전인가?

만약 백과사전이라면,

• 오늘 100줄짜리 목차로 줄이고
• 나머지를 docs/ 디렉토리로 분리하는 것부터 시작하면 된다.

---

📎 참고 출처

• OpenAI 공식 블로그: https://openai.com/index/harness-engineering/
• engineering.fyi 분석: https://www.engineering.fyi/article/harness-engineering-leveraging-codex-in-an-agent-first-world
• Harness Engineering 8 Rules: https://www.vibesparking.com/en/blog/ai/agent-orchestration/2026-03-05-harness-engineering-openai-8-rules-agent-first-world/
• Spillwave — Context Engineering: https://pub.spillwave.com/context-engineering-agents-injecting-the-right-rules-at-the-right-moment-5df91dc215ab