AGENTS.md 실전 작성 패턴, 뭐가 진짜로 에이전트 행동을 바꾸나

AGENTS.md 파일을 만들긴 했는데 에이전트가 여전히 엉뚱하게 행동한다는 분들 계실 텐데요, 실제로 뭐가 효과가 있고 뭐가 없는지 정리한 자료들을 찾아봤어요. 깃허브 블로그가 2,500개 넘는 리포지토리를 분석한 자료랑, ICLR 2026에 발표된 학술 연구까지 같이 정리했어요. 효과 있는 패턴과 효과 없는 패턴을 표로 먼저 보여드릴게요.

효과 있는 패턴 vs 효과 없는 패턴

구분	효과O	효과X
명령어	실제 빌드·테스트·실행 명령어를 정확한 문법으로 명시	"적절한 도구를 사용하세요" 같은 추상적 지시
완료 기준	"pnpm test가 그린이어야 함" 같은 검증 가능한 조건	"제대로 작동해야 합니다" 같은 모호한 목표
지시 형태	성공 기준을 선언 (선언형)	단계를 순서대로 나열 (절차형)
스타일 규칙	린터가 못 잡는 프로젝트 고유 컨벤션	"깔끔한 코드를 작성하세요" 같은 당연한 얘기
모호함 처리	언제 확인 질문을 해야 하는지 명시	아무 언급 없이 에이전트 판단에 맡김
섹션 순서	명령어 → 완료 기준 → 에스컬레이션 → 작업별 섹션 → 스타일	스타일 가이드부터 시작

 

아래에서 표에 나온 항목들이 왜 이런 차이를 만드는지 하나씩 풀어드릴게요.

 

순서가 틀리면 아무리 잘 써도 소용없다

 

가장 확실한 발견은 섹션을 넣는 순서 자체가 효과를 좌우한다는 거예요.

빌드·테스트 명령어를 제일 먼저 넣어야 해요. 에이전트가 뭔가 유용한 일을 하기 전에 반드시 필요한 정보이기 때문이에요.

그다음이 완료 기준인데, 이게 없으면 에이전트가 "다 한 것 같다"는 식으로 스스로 판단하고 끝내버리는 거짓 완료가 자주 발생해요.

그다음은 에스컬레이션 규칙이에요. 에이전트가 막혔을 때 파괴적인 우회 방법을 쓰지 않도록 막아주는 역할이고요.

그 뒤로 작업별로 섹션을 나눠서 불필요한 지침을 매번 파싱하지 않게 하고, 모노레포라면 디렉터리별 스코핑을 마지막에 넣는 순서예요.

 

여기서 중요한 지적이 하나 있는데, 대부분의 AGENTS.md 파일이 실패하는 이유가 스타일 가이드부터 쓰기 시작해서 정작 명령어까지 못 가기 때문이라는 거예요. 스타일 선호는 앞의 네 가지가 제대로 작동한 다음에 넣어도 늦지 않아요.

지시형보다 선언형이 낫다

이 부분이 직관과 좀 어긋나는 부분인데요, 아래 두 방식을 비교해보시면 차이가 명확해요.

# 절차형 (효과 낮음)
1. src/utils/validator.ts 파일을 연다
2. validateEmail 함수를 찾는다
3. 정규식을 RFC 5322 표준에 맞게 수정한다
4. pnpm test를 실행한다

# 선언형 (효과 높음)
이메일 검증 로직을 RFC 5322 표준에 맞게 수정하세요.
완료 조건: pnpm test가 그린이어야 하고, git diff에
console.log가 남아있으면 안 됩니다.

"A를 읽고, B를 수정하고, C를 실행해라" 같은 절차형 지시보다 성공 기준을 선언하는 방식이 훨씬 효과적이라는 지적이 여러 실전 가이드에서 공통적으로 나와요. 절차형 지시는 예상 못 한 상황에서 막다른 길에 부딪히거나 멈춰버리는데, 성공 기준을 선언해두면 에이전트가 스스로 경로를 조직해서 목표에 도달할 수 있다는 거예요. 이건 "순서도부터 그려라"는 전통적인 엔지니어링 본능을 완전히 뒤집는 접근이에요.

모호함을 방치하면 성공률이 뚝 떨어진다

ICLR 2026에 발표된 AMBIG-SWE라는 연구에서는 모호한 버그 리포트를 LLM 에이전트가 어떻게 처리하는지 분석했는데, 명시적으로 확인 절차를 요구하지 않으면 에이전트가 기본적으로 확인 없이 그냥 진행해버리는 경향이 있고, 이 때문에 문제 해결률이 42%까지 떨어진다는 결과가 나왔어요. 그러니까 AGENTS.md에 애매한 요청을 받았을 때 어떻게 확인 질문을 해야 하는지, 언제 진행을 멈추고 물어봐야 하는지에 대한 규칙을 명시적으로 넣어주는 게 성공률에 직결되는 요소예요.

# 모호함 처리 규칙 예시
요청이 다음 중 하나에 해당하면 진행 전에 반드시 확인 질문을 하세요.
- 영향받는 파일이 3개를 초과할 것으로 예상되는 경우
- 기존 공개 API의 시그니처를 변경해야 하는 경우
- 요청에 "적절히", "알아서", "보기 좋게" 같은 모호한 표현이 포함된 경우

로그를 API처럼 쓰는 기법

한 가지 실용적인 팁도 있었는데, 비동기 부작용을 에이전트가 직접 확인할 수 있게 노출시키는 방식이에요. 예를 들어 디버그 모드에서 회원가입 확인 이메일을 표준출력으로 바로 덤프하도록 설정해두고, AGENTS.md에 로그를 읽으라고 지시해두면, 에이전트가 회원가입부터 이메일 확인, 링크 추출, 클릭까지 전체 플로우를 사람의 개입 없이 스스로 완료할 수 있어요.

# 인증 흐름 테스트

디버그 모드(DEBUG=true)에서는 회원가입 확인 이메일이 발송되지 않고
stdout에 JSON 형태로 직접 출력됩니다: {"type": "email", "to": "...", "confirm_url": "..."}

회원가입 플로우를 테스트할 때는 이 로그에서 confirm_url을 추출해서
직접 요청을 보내는 방식으로 이메일 확인 단계를 완료하세요.

이 기법은 이메일 확인뿐 아니라 웹훅이나 백그라운드 작업 결과처럼 에이전트가 직접 관찰하기 어려운 비동기 이벤트 전반에 적용할 수 있어요.

완성된 AGENTS.md 예시

지금까지 말씀드린 순서와 원칙을 다 반영하면 대략 이런 구조가 나와요.

# 빌드 및 테스트
- 설치: pnpm install
- 테스트: pnpm test
- 개발 서버: pnpm dev

# 완료 기준
- 변경 후 pnpm test가 그린이어야 합니다.
- git diff에 console.log나 TODO 주석이 남아있으면 안 됩니다.
- 새로 추가한 함수에는 대응하는 테스트가 있어야 합니다.

# 막혔을 때
- 3번 이상 같은 에러가 반복되면 파일을 되돌리고 다른 접근을 시도하세요.
- 기존 테스트를 삭제하거나 skip 처리해서 통과시키지 마세요.

# 모호함 처리
- 영향 파일이 3개를 초과하거나 공개 API가 바뀌는 요청은 진행 전에 확인하세요.

# 코드 스타일
- 새 컴포넌트는 기존 src/components 구조를 따르세요.
- 상태 관리는 Zustand를 사용하고, 새 전역 상태를 함부로 추가하지 마세요.

정리

정리하면 순서(명령어 → 완료 기준 → 에스컬레이션 규칙 → 작업별 섹션 → 스타일), 절차형보다 선언형 성공 기준, 모호함에 대한 명시적 확인 규칙, 이 세 가지가 실제로 에이전트 행동을 바꾸는 핵심 요소예요. 반대로 "깔끔한 코드를 작성하라" 같은 당연한 얘기나 린터가 알아서 잡아줄 스타일 규칙은 넣어봐야 별 효과가 없다는 게 여러 실전 가이드에서 공통적으로 나오는 결론이에요. 지

금 갖고 계신 AGENTS.md가 스타일 가이드부터 시작하고 있다면, 그 부분을 맨 뒤로 옮기고 명령어와 완료 기준을 앞으로 당기는 것만으로도 눈에 띄는 차이를 보실 수 있을 거예요