AGENTS.md가 여러 개라면 AI는 어느 지침을 따라야 할까?

프로젝트를 열었는데 루트에도 AGENTS.md가 있고, 작업할 폴더 안에도 또 AGENTS.md가 있다면 AI는 무엇을 읽어야 할까요?
둘 다 읽다가 갑자기 우왕좌왕하는 것 아닐까요?
사람도 규칙 문서 두 장만 만나면 표정이 복잡해지는데, AI라고 문서 더미 앞에서 초연할 리는 없습니다 (다만 표정 대신 다음 토큰을 낼 뿐입니다).

여기서 가장 흔한 오해는 가까운 문서 하나만 이긴다는 생각입니다.
하위 폴더의 지침이 있으니 루트 지침은 폐기되고, 두 문서가 경쟁하는 결승전처럼 보이는 것이죠.
하지만 유지보수하기 좋은 저장소 패턴에서는 조금 다르게 생각하는 편이 안전합니다.

핵심은 편집할 파일에 가까운 지침은 작업 범위를 구체화하고, 루트 지침은 여전히 기본 계약으로 남을 수 있다는 점입니다.
가까운 문서는 우선 읽되, 위쪽 문서가 말한 공통 제약까지 자동으로 사라진다고 보지 않는 방식입니다.
이 글은 특정 저장소에 기록된 방식을 바탕으로, 여러 AGENTS.md를 관리할 때 쓸 수 있는 패턴을 정리합니다.
모든 AI 도구가 같은 의미로 처리한다고 단정하는 이야기는 아닙니다.

문서가 둘이면 하나를 버리면 될까?

처음에는 이렇게 생각하기 쉽습니다.

루트 AGENTS.md와 scripts/AGENTS.md가 있다면, scripts/ 안의 파일을 고칠 때는 둘 중 하나만 따르면 된다.

문제는 이 생각이 공통 규칙까지 날려 버릴 수 있다는 데 있습니다.
루트 문서에는 저장소 전체에 적용되는 안전 규칙, 검증 원칙, 작업 방식이 있을 수 있습니다.
반면 하위 문서에는 그 폴더에서만 필요한 명령의 출처나 파일 소유 범위처럼 더 좁은 규칙이 있을 수 있죠.
둘은 경쟁자가 아니라 역할이 다른 문서입니다.

아파트를 떠올려 보세요.
건물 전체의 출입 규칙이 있고, 각 시설에는 이용 안내가 따로 있습니다.
헬스장 안내문을 봤다고 해서 건물 출입 규칙이 없어지는 것은 아닙니다.
그 공간에서 운동할 때는 헬스장 안내가 더 직접적이지만, 건물의 기본 약속도 같이 적용됩니다 (엘리베이터에서 러닝머신을 타지는 않으니까요).

AGENTS.md도 비슷하게 나눌 수 있습니다.
루트 문서는 저장소 전체의 기본 계약을, 하위 문서는 특정 디렉터리의 추가 계약을 맡습니다.
이렇게 두면 하위 문서가 루트 문서를 복사하지 않아도 됩니다.
복사본이 많아질수록 언젠가는 한쪽만 고쳐지는 날이 오기 때문입니다.

가까운 지침이 이긴다는 말의 정확한 뜻

여기서 말하는 nearest wins, 즉 “가장 가까운 AGENTS.md가 우선한다”는 표현은 편집 상황에 대한 읽기 순서에 가깝습니다.
어떤 파일을 바꾸려는지 먼저 보고, 그 파일이 속한 디렉터리에서 가장 가까운 지침을 찾습니다.
그 문서가 그 위치에서 필요한 구체적인 제한을 알려 줍니다.

예를 들어 다음처럼 구성된 저장소를 생각해 봅시다.

repo/
  AGENTS.md
  scripts/
    AGENTS.md
    release-check.sh

AI가 scripts/release-check.sh를 수정하려 한다면 먼저 scripts/AGENTS.md를 확인합니다.
이 문서에 “명령 목록은 여기에서 관리한다”거나 “이 폴더의 변경은 특정 검증을 거친다” 같은 추가 규칙이 있다면, 바로 그 파일을 편집하는 순간에는 그 지침이 가장 직접적입니다.
AI가 경로를 따라 필요한 도장을 받으러 다닌다고 생각하면 조금 덜 헷갈립니다 (도장 수집 취미는 없어도 말이죠).

그렇다고 루트 AGENTS.md가 무효가 되는 것은 아닙니다.
기록된 패턴에서는 하위 문서가 루트 계약을 확장하며, 루트와 모순되는 규칙을 두지 않는 전제를 둡니다.
따라서 가까운 문서는 “이 폴더에서는 이것도 지켜라”라고 말하고, 루트 문서는 “어디서 작업하든 이것은 지켜라”라고 말합니다.

이 구분이 없으면 “가까운 문서가 우선”이라는 짧은 문장이 “나머지는 읽지 않아도 됨”으로 오해되기 쉽습니다.
하지만 실제로 필요한 것은 선택이 아니라 합성입니다.
공통 제약 위에 지역 제약을 얹는 방식이죠.

AI에게는 어떤 순서로 시키면 좋을까?

AI에게 지침을 줄 때는 모호한 우선순위보다 작업 순서를 적어 두는 편이 낫습니다.
다음 정도면 충분히 실용적입니다.

1. 편집 대상 파일의 디렉터리와 상위 디렉터리에서 AGENTS.md를 찾는다.
2. 대상 파일에 가장 가까운 문서를 먼저 읽는다.
3. 루트 문서를 기본 계약으로 함께 확인한다.
4. 하위 문서는 루트 규칙을 보완하며, 충돌이 생기지 않게 유지한다.
5. 특정 폴더의 세부 명령이나 소유 규칙은 그 폴더 문서에만 둔다.

여기서 중요한 단어는 작업 대상입니다.
AI가 저장소 전체를 한 번에 바꾸는 것처럼 행동하면, 어느 지침이 가까운지조차 흐려집니다.
반대로 파일 하나와 그 경로를 먼저 정하면 필요한 문서의 범위도 작아집니다.
지침 문서가 AI를 똑똑하게 만드는 마법 주문이라기보다, 작업 경계를 분명하게 만드는 표지판이라는 뜻입니다.

또한 하위 문서에 루트 규칙을 길게 재작성하지 마세요.
루트에는 공통 원칙을, 하위에는 그 위치에서만 알아야 할 차이를 둡니다.
그래야 누군가 규칙을 고칠 때 어디를 수정해야 하는지 분명해집니다.
문서 두 개가 서로 같은 문장을 들고 있으면, 미래의 편집자가 둘 중 어느 쪽을 믿어야 할지 다시 질문하게 됩니다.

정리: 가까운 문서는 확대경, 루트 문서는 지도

여러 AGENTS.md를 두는 목적은 규칙을 복잡하게 만들려는 것이 아닙니다.
오히려 규칙을 필요한 위치에만 작게 배치하려는 것입니다.
가까운 문서는 지금 고칠 파일을 위한 확대경이고, 루트 문서는 저장소 전체를 잃지 않게 해 주는 지도입니다.

다음에 하위 폴더의 지침을 만들 때는 한 문장을 먼저 확인해 보세요.
“이 내용은 모든 폴더에 필요한가, 아니면 여기에서만 필요한가?”
전자라면 루트에, 후자라면 가까운 폴더에 두면 됩니다.
그리고 AI에게는 가까운 문서를 먼저 읽되 공통 계약도 함께 적용하라고 알려 주세요.

문서가 많다고 반드시 복잡한 것은 아닙니다.
역할이 겹치지 않으면, 오히려 AI도 사람도 덜 헤맵니다.
지침 파일들이 서로 팔꿈치로 자리를 차지하는 대신, 각자 맡은 자리에서 조용히 일하게 만들어 봅시다.
다음 편집에서 필요한 규칙만 또렷하게 찾을 수 있다면, 문서 구조는 이미 제 몫을 하고 있는 셈입니다.