요즘 멀티에이전트 프로젝트를 보다 보면 이상할 정도로 같은 파일이 반복된다. 이름은 조금 달라도 결국 AGENTS.md 같은 운영 문서가 한가운데 자리 잡는다.
근데 재밌는 건, AGENTS.md가 중요하다고 해서 길게 쓰면 오히려 해가 될 수 있다는 점이다. 너무 친절한 문서는 비용만 늘리고, 모델을 앵커링해서 성능을 깎을 수 있다.
그래서 오늘은 “AGENTS.md를 써야 하냐 말아야 하냐”가 아니라, 왜 이 파일이 표준처럼 굳어지는지와 무엇을 넣어야 진짜 도움이 되는지를 정리해본다.
Quick Answer
AGENTS.md가 살아남는 이유는 멀티에이전트 팀이 공유해야 할 비직관적 규칙, 툴 강제, handoff 계약, 예외 처리를 가장 얇게 고정할 수 있기 때문이다. 반대로 디렉토리 설명, 스택 자랑, 너무 긴 배경설명은 오히려 방해가 되기 쉽다.
이 글이 필요한 사람
- AGENTS.md를 길게 써야 하나 짧게 써야 하나 감이 안 오는 사람
- 멀티에이전트 팀 규칙을 어디에 고정해야 할지 고민하는 사람
/init로 만든 긴 운영문서가 오히려 답답했던 사람- README와 운영 계약 문서를 어떻게 나눌지 고민하는 사람
지금 결론
- AGENTS.md는 “친절한 소개문”이 아니라 “발견 불가 규칙집”이어야 한다.
- 에이전트가 스스로 찾을 수 있는 정보는 최대한 줄이는 게 낫다.
- 진짜 가치 있는 건
누가 언제 뭘 하고 어디서 멈추는지다.
왜 표준처럼 굳어지나
멀티에이전트가 많아질수록 공통 언어가 필요하다.
- 어떤 도구를 강제로 쓰는지
- 어떤 경로는 건드리면 안 되는지
- 실패했을 때 누구한테 넘기는지
- 완료를 어디까지로 보는지
이걸 매번 프롬프트에서 다시 설명하면 팀이 느려진다. 그래서 결국 얇은 운영 문서가 필요해지고, 그 역할을 AGENTS.md가 맡는다.
실무에선 이런 줄이 진짜 사람 살린다
말이 추상적으로 들리면 감이 안 온다. 실제로 운영 문서에서 힘이 센 건 이런 종류의 문장이다.
| 문장 종류 | 없는 팀에서 생기는 일 | 들어가 있으면 좋은 점 |
|---|---|---|
테스트는 반드시 pytest만 사용 |
에이전트마다 제각각 다른 검증 명령을 씀 | 검증 루프가 일정해짐 |
배포 전에는 무조건 사람 승인 |
끝까지 밀어붙이다 사고 남 | 중단 조건이 분명해짐 |
실패 시 ops 채널로 handoff |
다들 멍하니 로그만 봄 | 책임이 바로 이동함 |
generated 폴더 수정 금지 |
빌드 산출물까지 건드려서 diff가 지저분해짐 | blast radius가 줄어듦 |
즉 좋은 AGENTS.md는 철학 선언문보다 실패를 줄이는 문장이 많다.
나쁜 예시 vs 좋은 예시
짧게 비교하면 감이 더 빨리 온다.
나쁜 예시
- 이 저장소는 React, FastAPI, Redis를 사용합니다.
- 폴더 구조는 src, docs, scripts로 이뤄져 있습니다.
- 팀은 품질과 협업을 중요하게 생각합니다.
이건 틀린 말은 아니지만, 에이전트가 스스로 찾을 수 있는 정보가 대부분이라 운영 문서로서 효율이 낮다.
좋은 예시
- DB 마이그레이션은 owner 승인 전 실행 금지
- 테스트는 `pnpm test:ci`만 허용
- 배포 실패 시 `#ops-release`에 링크와 로그 5줄 남기기
- generated/ 와 dist/ 는 수정 금지
이쪽은 에이전트가 혼자 발견하기 어려운 규칙이라, 문서에 적어둘 가치가 높다.
근데 왜 자동 생성은 위험할까
여기서 함정이 있다. AGENTS.md가 필요하다고 해서 /init 같은 걸로 자동 생성한 긴 문서를 던져주면, 스스로 찾을 수 있는 정보까지 중복해서 먹게 된다.
이건 두 가지 문제를 만든다.
- 컨텍스트 낭비
- 잘못된 앵커링
즉, 중요한 파일이긴 한데 많이 넣는다고 좋은 파일은 아니다.
넣어야 할 것 vs 빼야 할 것
넣어야 할 것
- 비직관적 제약
- 특정 도구 강제 사용
- 테스트/배포 금지 조건
- handoff 규칙
- 예외 승인 경로
빼야 할 것
- 폴더 구조 길게 설명
- 스택 소개
- README에 이미 있는 내용
- 모델이 스스로 찾을 수 있는 일반 정보
실전 체크포인트 4개
1. 누가 최종 도장을 찍는가
AGENTS.md에 이게 없으면 팀은 금방 흐려진다.
2. 어디서 멈추는가
에이전트가 계속 밀어붙이면 사고난다. 중단 조건은 꼭 있어야 한다.
3. 어떤 툴을 강제로 쓰는가
테스트, 린트, 시트 반영, 퍼블리셔 같은 건 도구 강제가 있어야 안정적이다.
4. 예외가 생기면 어디로 relay 하는가
실패했을 때 다들 멍때리면 그게 제일 비싸다.
내 기준 최소 골격
내가 새 저장소에 AGENTS.md를 붙일 때는 보통 아래 5가지만 먼저 넣는다.
- 절대 건드리면 안 되는 경로
- 강제할 검증 명령 1개
- 멈춰야 하는 조건 2~3개
- 실패 시 handoff 대상
- 완료로 인정하는 기준
이 5개만 있어도 문서는 갑자기 소개글에서 운영 계약으로 바뀐다.
실수 TOP 3
실수 1. README를 복붙한다
그러면 AGENTS.md는 운영문서가 아니라 장황한 소개문이 된다.
실수 2. 규칙보다 설명이 많다
실행 계약이 약해지고, 모델은 길만 잃는다.
실수 3. 실패 패턴을 업데이트하지 않는다
처음 만든 문서가 영원히 맞는 게 아니다. 실제로 틀린 패턴만 남겨야 한다.
FAQ
Q. 꼭 AGENTS.md여야 해?
A. 이름은 달라도 된다. 다만 역할은 필요하다. 팀 공통 운영 계약을 담는 얇은 문서가 있어야 한다.
Q. 길면 더 좋은 거 아냐?
A. 아니다. 오히려 짧고 정확한 게 더 좋다.
Q. 개인 프로젝트에도 필요해?
A. 멀티에이전트나 자동화가 들어가면 개인 프로젝트에도 금방 필요해진다.
다음에 읽을 글
- Claude Code Skills 체크리스트 2026 — hooks·gotchas 쌓아도 팀 생산성이 안 오를 때 보는 운영 실수 7가지
- Claude Code 스킬 만드는 법 2026 — 공식 skill-creator 가이드에서 건질 핵심만
출처
AGENTS.md 문서화 함정요약 메모 (2026-02-26)