AGENTS.md가 뭔지 몰라도 괜찮다, 외주 개발팀이 알아야 할 것만 정리했다

한줄 요약

AI 코딩 에이전트에 규칙을 전달하는 컨텍스트 파일, 이제 도구마다 따로 관리할 필요 없다.

AI 코딩 에이전트를 실무에 쓰는 개발팀이라면 컨텍스트 파일 관리 문제를 한 번쯤은 겪는다. 에이전트는 프로젝트 사정을 전혀 모른 채 작업을 시작하기 때문에, 빌드 방법이나 코드 규칙, 건드리면 안 되는 영역 같은 정보를 어딘가에 적어 두고 자동으로 읽히게 해야 한다. 문제는 도구마다 이 파일의 이름과 위치가 제각각이라는 점이다. 외주 개발사나 여러 에이전트를 동시에 운용하는 팀일수록 이 문제가 더 빠르게 불거진다.

왜 컨텍스트 파일이 흩어지는가

도구가 늘면 파일도 늘어난다. 특정 에이전트는 루트에 고유한 이름의 파일을 읽고, 다른 에이전트는 .설정폴더 안의 파일을 읽는다. 담긴 내용은 사실상 같은데, 파일은 여러 개로 쪼개진다.

이 상태에서 규칙 하나를 바꾸면 나머지 파일도 같이 수정해야 한다. 바쁜 스프린트 중에 한두 개를 빠뜨리면, 에이전트마다 다른 규칙으로 코드를 생성한다. 규칙이 어긋난 코드가 리뷰를 통과해 병합되기 전까지는 아무도 눈치채지 못하는 경우도 많다.

외주 개발 프로젝트에서는 이 문제가 더 두드러진다. 개발사와 클라이언트가 각자 다른 도구를 쓰는 상황이 흔하고, 인수인계 시점에 컨텍스트 파일이 어디에 몇 개 있는지 정리조차 안 된 경우도 적지 않다.

AGENTS.md가 해결하는 것

이 혼란을 정리하기 위해 등장한 것이 AGENTS.md다. 코딩 에이전트용 컨텍스트 파일의 개방형 표준 형식으로, 특정 회사가 소유하지 않고 중립 재단이 관리한다. "에이전트를 위한 README"라고 이해하면 충분하다.

현재 30개가 넘는 도구가 이 파일을 지원하고, 지원 수준은 세 가지로 나뉜다.

• 네이티브 지원: 별도 설정 없이 자동으로 읽는다.
• 우선 지원: 도구 고유 파일이 없을 때 대신 읽는다.
• 호환 지원: 설정을 추가하면 읽는다.

중요한 점은 벤더 전용 파일은 해당 도구가 사라지면 함께 쓸모를 잃지만, 표준 파일은 도구가 바뀌어도 그대로 유지된다는 것이다. 외주 개발 완료 후 운영 도구가 바뀌거나, 협력사가 교체되는 상황에서도 팀의 규칙은 한 파일에 살아남는다.

현재 가장 많이 쓰는 도구와의 연결 방법

현재 한국 개발 현장에서 가장 많이 쓰이는 AI 코딩 도구는 아직 AGENTS.md를 직접 읽지 않는다. 대신 두 가지 방법으로 연결할 수 있다.

첫 번째는 기존 컨텍스트 파일 안에 @AGENTS.md 한 줄을 넣어 불러오는 방식이다. 공통 규칙은 AGENTS.md에 적고, 해당 도구에만 필요한 규칙은 기존 파일에 남긴다. 역할 분리가 명확하고, 나중에 다른 도구를 추가할 때도 AGENTS.md 하나만 관리하면 된다.

두 번째는 기존 컨텍스트 파일을 AGENTS.md를 가리키는 심볼릭 링크로 바꾸는 방식이다. OS가 링크를 해석해 주기 때문에 도구 입장에서는 차이가 없다. 다만 도구 전용 규칙을 따로 적을 공간이 없고, 운영 환경에 따라 제약이 생길 수 있다. 그래서 실무에서는 첫 번째 방식이 더 유연하다.

이 두 방식이 속도나 비용에서 손해를 주는지 궁금할 수 있다. 컨텍스트 파일은 세션을 시작할 때마다 로드되기 때문에, 한 단계를 더 거치면 토큰 비용이 쌓이지 않을까 하는 걱정이다. 결론부터 말하면, 실제로 여러 모델에 걸쳐 측정해 봤을 때 전달 방식에 따른 비용 차이는 없었다. 측정에서 나타난 소폭의 편차는 에이전트가 매 실행마다 조금씩 다르게 추론하는 실행 노이즈였지, 파일을 불러오는 경로에서 비롯된 것이 아니었다.

외주 개발팀이 지금 바로 할 수 있는 것

전환 자체는 단순하다.

1. 기존 컨텍스트 파일의 이름을 AGENTS.md로 바꾼다. 파일을 새로 만드는 게 아니라 이름을 바꿔야 변경 이력이 유지된다.
2. 기존 파일 이름으로 새 파일을 만들고, 첫 줄에 @AGENTS.md만 적는다.
3. 에이전트에 PING처럼 임시 확인용 키워드를 심어 파일이 실제로 읽히는지 검증한다.

이 세 단계를 같은 커밋으로 묶으면 컨텍스트 파일이 비어 있는 공백 상태가 생기지 않는다.

한 가지 더 챙길 것이 있다. 전달 방식을 정리하는 것보다 파일 내용을 다듬는 일이 훨씬 중요하다. 코드를 읽으면 알 수 있는 내용, AI가 자동 생성한 장황한 설명, 오래전에 바뀐 규칙의 잔재 같은 것들이 쌓이면 에이전트 성능은 오히려 떨어진다. 에이전트가 코드만 봐서는 알 수 없는 것, 즉 팀 고유의 빌드 방법, 배포 제약, 절대 건드리면 안 되는 영역 같은 정보만 남기는 것이 원칙이다. 200줄 안쪽이 실무적으로 적당한 기준이다.