YDMmobile / oss

AGENTS.md는 README가 아니라 범위를 가진 설정입니다

2026-09-26

저장소 루트에 AGENTS.md를 하나 만들고 모든 규칙을 넣으면 마음이 편합니다.

테스트 명령, 커밋 규칙, 모바일 폴더 주의사항, 문서 문체, 배포 금지, 생성 파일 취급까지 한 장에 모입니다. 에이전트도 한 파일만 읽으면 되니 완벽해 보입니다.

그러다 문서 수정 하나를 맡겼는데 iOS 빌드 규칙까지 읽고, 스크립트 한 줄을 고치는데 앱 전체 테스트를 돌립니다. 규칙은 많지만 지금 작업에 필요한 경계는 흐립니다.

AGENTS.md를 긴 README로 보기보다 디렉터리 트리에 적용되는 범위 설정으로 보면 구조가 선명해집니다. 공통 계약은 위에 두고, 특정 폴더의 차이만 가까운 위치에 둡니다.

파일마다 적용되는 규칙 집합이 다릅니다

예를 들어 구조가 이렇다고 해 봅시다.

repo/
├── AGENTS.md
├── app/
│   ├── AGENTS.md
│   └── src/feature.ts
└── docs/
    └── guide.md

어떤 지침이 적용되는지는 도구의 로딩 규칙과 현재 작업 위치에 따라 달라집니다. 현재 Codex 공식 문서에 따르면, Codex는 프로젝트 루트에서 현재 작업 디렉터리까지 내려가며 지침을 결합합니다. 따라서 루트에서 작업하면 루트 지침이 기본이고, app/를 작업 디렉터리로 삼으면 루트 계약 뒤에 app/AGENTS.md가 더해집니다.

이 규칙은 모든 에이전트에 동일하게 적용되지 않습니다. 예를 들어 제가 관리하는 한 저장소의 Claude 어댑터는 편집 대상 파일에 가장 가까운 AGENTS.md를 따르라고 별도로 규정합니다. 핵심은 파일명만 보고 범위를 추측하지 않고, 사용하는 도구와 저장소가 정한 로딩 규칙을 먼저 확인하는 데 있습니다.

확인 순서는 다음과 같습니다.

  1. 사용하는 도구가 AGENTS.md를 어떤 경로로 읽는지 확인합니다.
  2. 현재 작업 디렉터리와 편집 대상 파일을 함께 확인합니다.
  3. 도구가 실제로 로드한 루트 및 하위 지침을 읽습니다.
  4. 하위 지침에서는 해당 범위의 차이만 구체화합니다.
  5. 충돌하면 도구와 저장소가 정한 우선순위 규칙을 따릅니다.

핵심은 “어느 문서가 우승하나?”가 아니라 “이 파일에 어떤 규칙들이 적용되나?”입니다.

루트에는 모두가 지켜야 할 것만 둡니다

루트 지침에 어울리는 내용은 저장소 어디를 고쳐도 유지되는 계약입니다.

  • 비밀 정보와 업무 자료를 커밋하지 않습니다.
  • 변경 전 관련 지침을 찾습니다.
  • 검증 실패를 숨기지 않습니다.
  • 사용자 요청 밖의 파일을 함부로 정리하지 않습니다.

반면 app/AGENTS.md에는 앱 전용 테스트 명령, 생성 코드 정책, 아키텍처 경계가 어울립니다. docs/AGENTS.md에는 맞춤법 검사나 링크 규칙을 둘 수 있습니다.

판별 질문은 간단합니다.

이 규칙을 다른 폴더의 파일에도 적용하면 여전히 자연스러운가?

아니라면 가까운 폴더로 내립니다.

모든 내용을 루트에 두면 지침이 강해지는 것이 아니라 잡음이 커집니다. 고양이 화장실 청소 규칙을 냉장고 문에 붙여도 중요도는 올라가지 않습니다. (집 전체의 문서 검색 성능만 떨어집니다.)

하위 문서는 차이만 적습니다

가장 관리하기 어려운 구조는 루트 규칙을 하위 파일마다 복사한 뒤 한두 줄만 바꾸는 방식입니다.

처음에는 각 파일이 독립적이라 편합니다. 시간이 지나 루트의 테스트 명령이 바뀌면 복사본 일부만 갱신됩니다. 이제 에이전트보다 사람이 먼저 어느 문서를 믿어야 할지 모릅니다.

하위 지침은 상위 계약을 반복하지 말고 이 범위에서 달라지는 것만 적는 편이 좋습니다.

# app/ instructions

- Run `pnpm test:app` for behavior changes in this directory.
- Do not edit generated files under `src/generated/`.
- UI state belongs in the feature store, not module globals.

이 문서는 짧지만 적용 대상과 행동이 분명합니다. “좋은 코드를 작성하세요”보다 훨씬 쓸모 있습니다.

규칙을 추가하기 전에 위치부터 고릅니다

새로운 실패를 겪으면 지침 한 줄을 추가하고 싶어집니다. 그 전에 세 가지를 물어보세요.

  • 이 규칙은 어떤 파일을 바꿀 때 발동하나요?
  • 사람과 에이전트가 지켰는지 관찰할 수 있나요?
  • 기존 상위 규칙과 겹치지 않나요?

범위가 한 폴더라면 그 폴더 가까이에 둡니다. 저장소 전체라면 루트에 둡니다. 특정 작업에서만 필요한 절차라면 상시 지침보다 별도 스킬이나 작업 문서가 나을 수 있습니다.

좋은 AGENTS.md 구조는 문서 수가 적은 구조가 아닙니다. 편집할 파일을 골랐을 때 필요한 규칙만 자연스럽게 모이는 구조입니다.

오늘 루트 지침을 열고 폴더 이름이 들어간 규칙을 찾아보세요. 그 규칙이 정말 모든 파일에 필요한지 묻고, 아니라면 적용 대상 가까이 옮긴 뒤 도구가 그 범위를 실제로 로드하는지 확인해 보세요. 에이전트가 덜 읽는 것이 목표가 아니라, 읽은 규칙이 지금 작업에 정확히 맞는 것이 목표입니다.