AGENTS.md 패턴: 실제로 에이전트 행동을 바꾸는 것들

저의 첫 번째 AGENTS.md는 팀 스타일 가이드를 200줄에 걸쳐 붙여넣은 것이었습니다. 네이밍 컨벤션, 코드 리뷰 체크리스트, 배포 절차, 아키텍처 원칙이 모두 포함되어 있었습니다. 에이전트는 대부분을 무시했습니다. 지침이 틀려서가 아니라 — 그것이 운영 지침이 아닌 문서였기 때문입니다.

이 구분은 이 글의 어떤 특정 패턴보다 더 중요합니다. AGENTS.md는 AI 에이전트를 위한 운영 정책이지, 사람을 위한 README가 아닙니다. 에이전트는 왜 컨벤셔널 커밋을 사용하는지 이해할 필요가 없습니다. 정확히 어떤 명령어를 실행해야 하는지, 그리고 “완료”가 어떤 상태인지만 알면 됩니다.

TL;DR

대부분의 AGENTS.md 문제는 에이전트 운영 지침이 아닌 사람을 위한 문서를 작성하는 데서 비롯됩니다. 효과적인 파일은 명령어 중심(설명이 아닌 정확한 실행 구문), 작업별 구성(코딩, 리뷰, 릴리스 섹션), 그리고 완료 조건 정의(명시적인 “완료” 기준)로 이루어져 있습니다. 확실하게 무시되는 안티패턴은 산문 단락, 모호한 지시(“조심하세요”), 그리고 상충하는 우선순위입니다. AGENTS.md는 60,000개 이상의 프로젝트에서 채택된 개방형 표준이며 ¹, Codex, Cursor, Copilot, Amp, Windsurf 등에서 작동합니다 ².

맥락: AGENTS.md는 Linux Foundation 산하 Agentic AI Foundation에 의해 관리됩니다 ³. 플래티넘 멤버로는 Anthropic, Google, Microsoft, OpenAI가 있습니다. 이 글에서는 실용적인 패턴을 다룹니다. Codex 전용 설정은 Codex 가이드를, Claude Code의 동등한 시스템(CLAUDE.md)은 Claude Code 가이드를 참조하세요.

무시되는 것들

아래 패턴들은 에이전트 행동에 관측 가능한 변화를 만들어내지 못합니다. 각 패턴을 해당 지침이 있는 경우와 없는 경우에 동일한 작업을 실행하고, 패턴당 10회 이상의 실행에서 작업 완료 정확도를 비교하여 식별했습니다. GitHub의 2,500개 이상의 AGENTS.md 파일이 포함된 저장소 분석도 같은 결론에 도달했습니다: “대부분의 에이전트 파일은 기술적 한계 때문이 아니라 너무 모호해서 실패합니다” ¹¹. 아래 패턴들은 어떤 측정에서도 정확도를 개선하지 못했습니다.

명령어 없는 산문 단락

<!-- BAD: Agent skips this -->
We value clean, well-tested code. Our team follows TDD principles
and believes in comprehensive test coverage. Please ensure all
changes are properly tested before submitting.

에이전트는 이것을 읽고, 모호한 선호사항으로 표현한 다음, 테스트 없이 코드를 작성합니다. 실행할 명령어도, 충족할 임계값도, “적절히 테스트된”의 정의도 없기 때문에 실행 가능한 지시가 없습니다.

모호한 지시

<!-- BAD: "Careful" means nothing to an agent -->
- Be careful with database migrations
- Optimize queries where possible
- Handle errors gracefully

“조심하세요”는 제약이 아닙니다. “가능한 경우”는 트리거 조건이 아닙니다. “우아하게”는 행동 명세가 아닙니다. 이것들은 사람 간 안내처럼 읽히지, 에이전트 지시로는 읽히지 않습니다. 효과적인 예와 비교해 보세요: “alembic check를 마이그레이션 적용 전에 실행하세요. 다운그레이드 경로가 없으면 중단하세요.”

상충하는 우선순위

<!-- BAD: Which one wins? -->
- Move fast and ship quickly
- Ensure comprehensive test coverage
- Keep the runtime budget under 5 minutes
- Run the full integration test suite before every commit

에이전트는 네 가지를 동시에 충족할 수 없습니다. 명시적인 우선순위 없이 지시가 충돌하면, 모델은 검증 단계를 건너뛰고 코드 생성을 서두릅니다. ICLR 2026 연구(AMBIG-SWE)에 따르면 에이전트는 “명시적인 격려 없이 비대화형 행동으로 기본 설정됩니다” — 명확화 질문을 하지 않고 조용히 진행하여 해결률이 48.8%에서 28%로 떨어졌습니다 ¹². 충돌하는 지시는 우선순위에 번호를 매겨 해결하세요: “우선순위 1: 테스트 통과. 우선순위 2: 5분 이내. 우선순위 3: 빠르게 배포.”

강제 수단 없는 스타일 가이드

<!-- BAD: No way to verify compliance -->
Follow the Google Python Style Guide for all code.
Use numpy-style docstrings for public functions.

스타일을 강제하는 정확한 린팅 명령어(ruff check --select D 또는 pylint --rcfile=.pylintrc)를 포함하지 않으면, 에이전트는 자신의 준수 여부를 검증할 방법이 없습니다. 여기서의 패턴은 보편적입니다: 검증 명령어 없는 지시는 규칙이 아니라 제안입니다.

효과적인 것들

아래 패턴들은 에이전트 행동에 일관되고 측정 가능한 변화를 만들어냅니다.

명령어 중심 지시

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

명령어는 모호하지 않습니다. 에이전트는 정확히 무엇을 실행할지, 어떤 인수를 전달할지 알고, 종료 코드를 확인하여 성공을 검증할 수 있습니다. AGENTS.md의 모든 지시는 “이것이 올바르게 완료되었음을 증명하는 명령어는 무엇인가?”라는 질문에 답해야 합니다.

완료 조건 정의

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

명시적인 완료 조건 정의는 가장 흔한 실패 모드를 제거합니다: 에이전트가 검증 없이 “완료”를 보고하는 것입니다. “완료”가 특정 종료 코드로 정의되면, 에이전트는 완료를 보고하기 전에 각 검사를 실행합니다. 이 정의가 없으면 “완료”는 “완료된 것 같습니다”를 의미하게 되며 — 이는 에이전트가 도입하는 버그의 흔한 원인입니다.

작업별 구성 섹션

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions
- Test command: `pytest tests/ -v -k "test_<module>"`

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`
- List changed files: `git diff --name-only HEAD~1`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`
- Tag: `git tag -a v<version> -m "Release v<version>"`

작업별로 구성된 파일은 에이전트가 현재 수행 중인 작업에 따라 관련 지시를 선택할 수 있게 합니다. 평면 목록은 에이전트가 맥락과 관계없이 모든 지시를 파싱하도록 강제합니다. “When…” 접두사는 에이전트가 작업 맥락에 대해 추론하는 방식과 직접적으로 매핑됩니다.

에스컬레이션 규칙

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- If you encounter merge conflicts: stop and show the conflicting files
- Never: delete files to resolve errors, force push, or skip tests

에스컬레이션 규칙이 없으면, 에이전트는 막혔을 때 점점 더 창의적인 우회 방법으로 기본 설정됩니다 — 잠금 파일 삭제, 검사 우회, 또는 실패의 조용한 무시. “Never” 목록은 에스컬레이션 경로만큼 중요합니다. 파괴적인 복구 패턴을 명시적으로 금지하면 최악의 실패 모드를 방지할 수 있습니다.

모노레포를 위한 디렉토리 범위 지정

AGENTS.md는 명세의 핵심 기능으로 계층적 범위 지정을 지원합니다 ². 작업 디렉토리에 더 가까운 파일이 우선권을 가집니다:

/repo/AGENTS.md                        ← Project-wide rules
  └─ /repo/services/AGENTS.md          ← Service defaults
      ├─ /repo/services/api/AGENTS.md  ← API-specific rules
      └─ /repo/services/web/AGENTS.md  ← Frontend-specific rules

루트 수준의 지시는 더 깊은 파일과 연결됩니다. 도구들은 프로젝트 루트에서 현재 작업 디렉토리까지 탐색하며, 경로에서 발견된 모든 AGENTS.md를 결합합니다 ⁴. OpenAI 자체 Codex 저장소는 모노레포에 88개의 별도 AGENTS.md 파일을 사용합니다 — 서비스와 패키지당 하나씩입니다 ⁴.

Codex에서는 어떤 수준에서든 AGENTS.override.md를 사용하여 상위 지시를 확장하는 대신 대체할 수도 있습니다 ⁴. 오버라이드 메커니즘은 Codex 전용이며 — 다른 도구에서는 구현되지 않습니다.

<!-- /repo/services/payments/AGENTS.override.md (Codex only) -->
# Payment Service Rules (OVERRIDE)

This service has additional security requirements.
All changes require: `bandit -r . -ll` passing with zero findings.
No dependency updates without explicit approval.
Test with: `pytest -v --tb=long -x` (fail fast, full tracebacks)

오버라이드를 사용할 때: 릴리스 동결, 인시던트 모드, 또는 프로젝트 전체 기본값을 대체해야 하는 보안 제약이 있는 서비스에서 사용하세요.

도구 간 호환성

AGENTS.md는 60,000개 이상의 프로젝트에서 채택되었으며 ¹, 모든 주요 AI 코딩 도구에서 인식됩니다. 동일한 파일이 각 생태계에서 어떻게 작동하는지 살펴보겠습니다:

팀에서 여러 도구를 사용하는 경우: AGENTS.md를 표준 소스로 작성하세요. 도구별 파일(CLAUDE.md, .cursorrules)을 추가하여 관련 섹션을 가져오거나 반영하세요. 따로 분리된 지시 세트를 유지하면서 서로 달라지는 상황을 만들지 마세요.

작성 순서: 먼저 추가할 것

AGENTS.md를 처음부터 작성한다면, 다음 우선순위 순서로 섹션을 추가하세요. 각 단계는 이전 단계 위에 구축됩니다:

1. 빌드 및 테스트 명령어 — 에이전트가 어떤 유용한 작업을 하기 전에 이것이 필요합니다
2. 완료 조건 정의 — “완료된 것 같습니다”라는 잘못된 완료 보고를 방지합니다
3. 에스컬레이션 규칙 — 에이전트가 막혔을 때 파괴적인 우회를 방지합니다
4. 작업별 구성 섹션 — 작업당 불필요한 지시 파싱을 줄입니다
5. 디렉토리 범위 지정 (모노레포만 해당) — 서비스별 규칙이 전역 지시를 오염시키지 않도록 합니다

처음 네 가지가 작동하기 전까지는 스타일 선호사항을 건너뛰세요. 대부분의 AGENTS.md 파일은 스타일 안내로 시작하고 명령어에는 도달하지 못하기 때문에 실패합니다.

AGENTS.md 테스트하기

에이전트가 실제로 지시를 읽고 따르는지 검증하세요:

# Codex: Show the full instruction chain
codex --ask-for-approval never "Summarize your current instructions"

# Codex: Generate a scaffold (slash command inside an active session)
# Type /init at the Codex prompt, not as a shell command
codex  # then type: /init

# Claude Code: Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
codex --ask-for-approval never "What is your definition of done?"

핵심 테스트: 에이전트에게 빌드 명령어를 설명해 달라고 요청하세요. 명령어를 그대로 재현하지 못하면, 지시가 읽히지 않고 있거나 컨텍스트에 유지하기에 너무 장황한 것입니다. 긴 AGENTS.md 파일은 컨텍스트 윈도우에 의해 잘립니다 — 각 섹션을 50줄 이하로 유지하고 가장 중요한 지시를 앞에 배치하세요.

FAQ

AGENTS.md 파일은 얼마나 길어야 하나요?

각 섹션을 50줄 이하로, 전체 파일을 150줄 이하로 유지하세요 ¹³. Codex는 기본 32 KiB 제한(project_doc_max_bytes)을 적용합니다 ⁴. 긴 파일은 컨텍스트 윈도우에 의해 잘리므로, 가장 중요한 지시 — 명령어와 완료 조건 정의를 스타일 선호사항보다 앞에 배치하세요.

AGENTS.md가 도구별 지시 파일을 대체하나요?

아닙니다. AGENTS.md는 CLAUDE.md, .cursor/rules 및 기타 도구별 파일과 함께 작동합니다. AGENTS.md를 표준 소스로 작성하고, 관련 섹션을 도구별 파일에 반영하세요. AGENTS.md의 패턴(명령어 중심, 완료 조건 정의)은 도구와 관계없이 모든 지시 파일에서 작동합니다.

에이전트가 AGENTS.md를 무시하면 어떻게 하나요?

에이전트에게 빌드 명령어를 설명해 달라고 요청하여 테스트하세요. 명령어를 그대로 재현하지 못하면, 파일이 너무 장황하거나(내용이 컨텍스트 밖으로 밀려남), 너무 모호하거나(에이전트가 실행 가능한 지시를 추출할 수 없음), 검색되지 않고 있는 것입니다(파일 위치와 도구 문서를 확인하세요). GitHub의 2,500개 저장소 분석에 따르면 기술적 한계가 아닌 모호함이 대부분의 실패 원인입니다 ¹¹.

핵심 요약

개인 개발자를 위해:

• 산문을 명령어로 대체하세요. 모든 지시는 무언가를 실행하여 검증 가능해야 합니다.
• 완료 조건을 명시적으로 정의하세요. “완료”는 느낌이 아닌 특정 종료 코드를 의미합니다.
• 에이전트에게 AGENTS.md를 암송하게 하여 테스트하세요. 암송하지 못하는 것은 따르지 않을 것입니다.

팀을 위해:

• AGENTS.md를 단일 진실 공급원으로 사용하세요. 도구별 파일에 반영하되, 병렬 사본을 유지하지 마세요.
• 카테고리별(스타일, 테스트, 배포)이 아닌 작업별(코딩, 리뷰, 릴리스)로 구성하세요.
• 에스컬레이션 규칙을 포함하세요. 이것이 없으면 막힌 에이전트가 원치 않는 방식으로 즉흥적으로 행동합니다.
• 모노레포에서는 디렉토리별로 범위를 지정하세요. 서비스별 규칙이 전역 지시를 오염시켜서는 안 됩니다.

참고 자료