모노레포에서 중첩된 AGENTS.md 관리 방법

모노레포에서 중첩된 AGENTS.md가 의미하는 것

모노레포에서 중첩된 AGENTS.md는 저장소 루트에 작은 파일 하나를 두고, 각 서비스 디렉터리 내부에 파일을 하나씩 더 두는 방식을 의미합니다. 루트 파일에는 모든 곳에 적용되는 몇 가지 규칙과 다른 파일들이 어디에 위치하는지에 대한 지도가 포함됩니다. 각 서비스 파일에는 해당 디렉터리에만 적용되는 명령과 관례가 담겨 있습니다. 따라서 services/worker/queue.py을 편집하는 에이전트는 루트 파일과 해당 작업 파일만 읽으면 되며, 전혀 건드릴 일이 없는 프론트엔드에 대해서는 문맥을 전혀 소비하지 않습니다.

별도로 설치할 것은 없습니다. AGENTS.md는 하나의 관례이며, 업스트림 프로젝트에서도 이를 명확히 밝히고 있습니다.

AGENTS.md는 표준 Markdown일 뿐입니다. 원하는 제목을 자유롭게 사용하십시오. 에이전트는 사용자가 제공한 텍스트를 단순히 파싱할 뿐입니다.

이 기술을 제대로 익혀둘 가치가 있는 이유가 바로 이것입니다. 형식은 변경되지 않습니다. 문제가 발생하는 지점은 파일의 배치와 유지보수이며, 이 두 가지는 모두 사용자의 몫입니다.

루트 디렉터리에 위치한 거대한 AGENTS.md 파일이 작동을 멈추는 이유는 무엇입니까?

웹 애플리케이션, 백그라운드 워커, Terraform 디렉터리를 포함하는 저장소의 루트에 600줄짜리 AGENTS.md 파일 하나를 두면 네 가지 문제가 발생합니다.

관리 주체가 없어 정보가 낡게 됩니다. apps/web에서 테스트 스크립트 이름을 변경하는 엔지니어는 apps/web 하위의 파일들만 수정합니다. 루트의 AGENTS.md는 해당 변경 사항(diff)에 포함되지 않으므로 리뷰어는 불일치를 발견할 수 없습니다. 6주가 지나면 해당 파일은 더 이상 존재하지 않는 빌드 단계를 설명하게 되며, 이를 변경한 당사자는 이미 해당 내용을 잊어버린 상태가 됩니다.

모든 작업에서 컨텍스트 비용이 발생합니다. 이러한 파일은 에이전트가 사용자의 질문을 파악하기 전, 세션 시작 시점에 로드됩니다. Claude Code 문서에서는 이를 다음과 같이 수치화합니다. "CLAUDE.md 파일당 200줄 미만으로 유지하십시오. 파일이 길어질수록 더 많은 컨텍스트를 소모하며 지시 사항 준수율이 떨어집니다." Codex는 지시 파일의 총 크기가 기본값인 project_doc_max_bytes(32 KiB)에 도달하면 병합을 중단합니다. 네 가지 서비스를 문서화하는 루트 파일은 매 작업마다 그중 세 가지 서비스에 대한 예산을 낭비하게 됩니다.

지시 사항이 서로 충돌하기 시작합니다. 웹 디렉터리는 pnpm test를 요구하고, 워커는 pytest -q을 요구합니다. 하나의 파일에 작성된 각 규칙은 특정 상황에서만 올바르기 때문에 에이전트는 어떤 규칙을 적용해야 할지 추측해야 합니다. Claude Code 문서에서는 그 결과를 다음과 같이 설명합니다. "두 규칙이 서로 충돌하면 Claude는 임의로 하나를 선택할 수 있습니다." 디렉터리별 파일을 사용하면 두 규칙 중 하나만 컨텍스트에 포함되므로 이러한 추측이 필요 없습니다. 명확하게 작성했다고 확신하는 규칙이 계속 무시된다면, 문구를 네 번째로 다시 쓰기보다 지시 사항이 적용되지 않는 이유를 살펴보는 것이 더 효과적입니다.

에이전트가 코드에서 읽을 수 있는 사실들로 파일이 가득 찹니다. 디렉터리 트리, 의존성 목록, 각 패키지의 요약 등이 이에 해당합니다. Claude Code의 /doctor 검사는 정확히 이러한 내용을 제거하기 위해 존재합니다. 이 기능은 "디렉터리 구조, 의존성 목록, 아키텍처 개요와 같이 Claude가 코드베이스에서 직접 파악할 수 있는 내용을 삭제"하고 "도구의 기본 설정과 다른 함정, 근거, 관례"만을 남깁니다. 이 문장은 특정 내용이 파일에 포함될 자격이 있는지 판단하는 가장 좋은 기준입니다.

에이전트가 루트 파일을 읽습니까, 아니면 가장 가까운 파일만 읽습니까?

많은 사용자가 이 모델을 잘못 이해하고 있으므로, 의역하는 대신 업스트림 관례를 그대로 인용하겠습니다.

각 패키지 내부에 AGENTS.md를 추가하십시오. 에이전트는 디렉터리 트리에서 가장 가까운 파일을 자동으로 읽으므로, 가장 가까운 파일이 우선순위를 가지며 모든 하위 프로젝트는 맞춤형 지침을 포함할 수 있습니다.

충돌 발생 시:

편집 중인 파일과 가장 가까운 AGENTS.md가 우선합니다. 명시적인 사용자 채팅 프롬프트가 모든 것에 우선합니다.

"우선순위를 가진다(Takes precedence)"는 표현을 "루트 파일은 무시된다"는 뜻으로 받아들이는 사람이 많습니다. 그렇지 않습니다. 이 관례를 구현하는 도구에서는 저장소 루트부터 작업 디렉터리까지의 경로에 있는 모든 파일을 읽어 하나로 합칩니다. 가장 가까운 파일이 우선하는 경우는 두 파일이 동일한 주제에 대해 서로 다른 내용을 담고 있을 때뿐입니다.

Codex는 이 메커니즘을 명확히 밝히고 있습니다. "Codex는 루트부터 아래로 파일을 연결하며, 빈 줄로 구분합니다. 현재 디렉터리에 더 가까운 파일이 이전 지침을 덮어씁니다." Claude Code도 자체 파일명에 대해 동일한 경로를 따릅니다. 작업 디렉터리 상위의 디렉터리 계층에 있는 파일들은 "시작 시 전체가 로드"되며, "발견된 모든 파일은 서로를 덮어쓰는 대신 컨텍스트로 연결됩니다." 작업 디렉터리 하위의 디렉터리는 다르게 동작합니다. Claude Code는 "Claude가 해당 디렉터리의 파일을 읽을 때" 요청에 따라 파일을 로드합니다.

여기서 두 가지 실질적인 결과가 도출됩니다. 루트 파일은 저장소 내 모든 세션의 접두사 역할을 하므로, 그곳의 각 줄은 매주 수백 번씩 비용을 지불하는 줄로 간주해야 합니다. 반면 디렉터리별 파일은 에이전트가 다른 곳에서 작업할 때는 아무런 비용이 들지 않으므로, 상세한 내용은 그곳에 작성하는 것이 효율적입니다.

이 동작은 2026년 8월 기준 Codex 및 Claude Code 문서를 통해 확인되었습니다. 도구마다 관례를 구현하는 방식이 조금씩 다르고 변경될 수도 있으므로, 팀에서 사용하는 에이전트의 로딩 규칙을 반드시 확인하십시오.

세 가지 서비스를 포함하는 저장소의 구성 예시

repo/
  AGENTS.md                   rules true everywhere, plus the map
  apps/web/AGENTS.md          TypeScript client, Vite, Vitest
  services/worker/AGENTS.md   Python queue consumer, pytest
  infra/AGENTS.md             Terraform and the deploy scripts

루트 파일은 의도적으로 짧게 작성합니다. 이 파일은 어디를 참조해야 하는지 알려주며, 모든 디렉터리에 공통으로 적용되는 규칙만 포함합니다.

# AGENTS.md

This is a monorepo. Each top-level directory ships its own AGENTS.md.
Read this file and the AGENTS.md nearest the code you are editing
before you change anything.

- `apps/web` browser client
- `services/worker` queue consumer
- `infra` Terraform and deploy scripts

## Rules for the whole repository

- The package manager is `pnpm`. `npm install` writes a second lockfile
  that CI ignores, so the install you tested is not the install that ships.
- Any `generated/` directory is build output. Edit the schema in
  `schemas/` and run `pnpm codegen` instead.
- `.env.local` holds real credentials. Do not read it and do not print it.
- If you change code in a directory, update that directory's AGENTS.md
  in the same commit.

디렉터리별 파일에는 세부 사항을 기술하며, 해당 디렉터리의 규모에 맞춰 필요한 만큼 길게 작성할 수 있습니다.

# apps/web

Browser client. Vite and React, TypeScript with `strict` on.

## Commands

- `pnpm dev` serves on port 5173.
- `pnpm test` runs Vitest once and exits.
- `pnpm typecheck` runs `tsc --noEmit`.

## Conventions

- One component per file under `src/components/`.
- All HTTP goes through `src/api/client.ts`. Do not call `fetch` directly,
  because the client attaches the auth header and retries on 429.

## Traps

- `pnpm build` does not type check. Vite strips the types instead of
  checking them, so a broken type still produces a green build.
  Run `pnpm typecheck` as a separate step.

워커(worker) 파일은 내용은 다르지만 형식은 동일합니다. 여기에는 설치 명령, pytest -q, 소비자가 멱등성을 유지해야 하는 이유, 그리고 테스트 통과 전에 실행되어야 하는 마이그레이션이 포함됩니다. 인프라(infra) 파일에는 에이전트가 피해를 입히지 않도록 제한하는 규칙을 작성합니다. terraform apply는 절대 실행하지 마십시오. terraform plan을 실행하고 거기서 멈추며, 에이전트가 새로운 상태 백엔드를 초기화하지 않도록 이미 구성된 상태 백엔드 이름을 명시하십시오.

이 파일들 어디에도 각 서비스의 용도에 대한 설명이 없다는 점에 주목하십시오. 그것은 사람이 담당할 영역입니다. Upstream에서도 같은 기준을 적용하여 "README.md 파일은 사람을 위한 것으로, 퀵 스타트, 프로젝트 설명, 기여 가이드라인을 담는다"고 명시하며, AGENTS.md는 "빌드 단계, 테스트, 관례 등 코딩 에이전트가 필요로 하는 추가적이고 상세한 맥락"을 담도록 합니다. AGENTS.md와 사람이 읽는 README의 분리에서는 이 경계를 문장 단위로 상세히 다루며, 코드가 왜 현재와 같은 형태인지 기록하는 DESIGN.md는 명령이 아닌 의사결정의 이유를 설명하는 세 번째 파일의 역할을 다룹니다.

코드 변경 시 누가 파일을 업데이트합니까?

규칙은 단 하나이며, 루트 파일에 적용됩니다. 디렉터리 내 코드를 변경하는 사람은 누구나 동일한 커밋에서 해당 디렉터리의 AGENTS.md를 업데이트해야 합니다.

이 방식은 문화적인 이유가 아니라 기계적인 이유로 작동합니다. 디렉터리별 파일은 코드와 동일한 diff에 포함되므로, 풀 리퀘스트 검토자는 두 내용을 동시에 확인할 수 있습니다. 루트 파일은 모두의 것이지만, 이는 곧 누구의 것도 아니라는 의미이며, 그 누구도 읽고 있는 diff에 포함되지 않습니다.

풀 리퀘스트에 검사 기능을 추가하여 이 규칙을 뒷받침하십시오. 변경된 각 파일에서 가장 가까운 상위 AGENTS.md를 찾은 다음, 해당 파일이 수정되지 않았을 때 이를 보고합니다.

#!/usr/bin/env bash
# Warn when code changed but the nearest AGENTS.md above it did not.
changed=$(git diff --name-only origin/main...HEAD)

nearest_doc() {
  d=$(dirname "$1")
  while [ "$d" != "." ]; do
    if [ -f "$d/AGENTS.md" ]; then echo "$d/AGENTS.md"; return; fi
    d=$(dirname "$d")
  done
  echo "AGENTS.md"
}

printf '%s\n' "$changed" | while read -r f; do
  [ -n "$f" ] || continue
  case "$f" in AGENTS.md|*/AGENTS.md) continue ;; esac
  doc=$(nearest_doc "$f")
  printf '%s\n' "$changed" | grep -Fqx "$doc" && continue
  echo "note: $f changed but $doc was not updated"
done

문서 수정 없이 API 클라이언트를 재작업한 브랜치에서의 출력 결과는 다음과 같습니다.

note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updated

이를 실패 처리가 아닌 경고로 유지하십시오. 강제적인 차단은 사람들이 CI를 통과시키기 위해 파일에 빈 줄을 추가하게 만들 뿐이며, 로봇을 만족시키기 위해 편집된 파일은 아예 없는 것보다 가치가 없습니다. 경고는 검토자에게 질문을 던질 기회를 제공하며, 실제로 효과가 있는 부분은 바로 이 지점입니다.

AGENTS.md 파일이 최신 상태가 아닌지 어떻게 확인합니까?

현재 실행할 수 있는 두 가지 확인 방법과 세션 내에서 나타나는 한 가지 증상이 있습니다.

각 파일의 생성 시점과 해당 파일이 설명하는 코드의 생성 시점을 비교하십시오. %cs은 커밋 날짜를 YYYY-MM-DD로 출력합니다.

for f in $(git ls-files '*AGENTS.md'); do
  d=$(dirname "$f")
  printf '%s  doc:%s  code:%s\n' "$f" \
    "$(git log -1 --format=%cs -- "$f")" \
    "$(git log -1 --format=%cs -- "$d")"
done

apps/web/AGENTS.md          doc:2026-02-11  code:2026-08-07
services/worker/AGENTS.md   doc:2026-07-29  code:2026-08-09
infra/AGENTS.md             doc:2026-08-01  code:2026-08-01

문서의 날짜가 코드보다 6개월 뒤처져 있다고 해서 해당 파일이 반드시 잘못된 것은 아닙니다. 이는 어떤 파일을 먼저 읽어야 할지 알려줄 뿐이며, 1초 만에 수행할 수 있는 확인 작업으로서는 충분합니다.

더 이상 존재하지 않는 경로를 찾으십시오. 문서는 매우 구체적인 방식으로 부패합니다. 즉, 삭제된 코드를 계속해서 설명하게 됩니다. 이 파일들에 포함된 모든 경로는 백틱(`)으로 작성되어 있으므로 쉽게 추출하여 테스트할 수 있습니다.

grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
  [ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
done

이 작업을 CI에 통합하기보다는 출력 결과를 직접 읽어보십시오. 이 방식은 src/**/*.ts과 같은 글로브(glob) 패턴이나 인용된 URL도 함께 표시하는데, 이는 두 경우 모두 슬래시(/)를 포함하고 있으며 디스크상의 파일이 아니기 때문입니다.

세션에서 나타나는 증상. 에이전트가 파일을 읽고 파일의 지시에 따라 src/api/client.ts를 열려고 시도하면, 도구는 다음과 같은 결과를 반환합니다.

No such file or directory

따라서 에이전트는 합리적인 판단에 따라 자체적인 fetch 래퍼를 작성하게 됩니다. 이것이 바로 최신 상태가 아닌 파일로 인해 발생하는 실질적인 비용입니다. 에이전트는 귀하의 문서를 무시하지 않습니다. 문서를 그대로 따르다가 3개월 전에 삭제된 경로에 도달하게 되고, 이미 존재하는 코드를 다시 빌드하게 됩니다. Ponytail, 에이전트가 가장 작은 단위의 변경 사항만 적용하도록 제한하는 도구와 같은 기술은 이러한 재빌드 본능을 줄여줄 수는 있지만, 파일이 잘못된 위치를 가리키고 있는 보조 도구까지 찾아낼 수는 없습니다.

Claude Code는 AGENTS.md 파일을 읽습니까?

아니요, 중첩된 레이아웃이 이 파일에 의존하기 때문에 명확히 짚고 넘어갈 필요가 있습니다. 2026년 8월 기준 문서에 따르면 "Claude Code는 CLAUDE.md을 읽으며, AGENTS.md은 읽지 않습니다." 이 패턴은 여전히 유효하지만, 각 AGENTS.md 옆에 CLAUDE.md이 있어야 합니다.

공유 설정 위에 도구별 설정을 추가하려는 경우 import 형식이 적합합니다. services/worker/CLAUDE.md에 다음을 입력하십시오:

@AGENTS.md

## Claude Code

Use plan mode for changes under `services/worker/migrations/`.

도구별로 추가할 내용이 없다면 심볼릭 링크(symlink) 형식이 적합합니다.

git ls-files '*AGENTS.md' | while read -r f; do
  ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.md

ln은 성공 시 아무것도 출력하지 않으므로 apps/web/CLAUDE.md -> AGENTS.md로 목록을 확인하십시오. 그 후 세션을 시작하고 /context을 실행하면 로드된 파일이 Memory files 아래에 나타납니다. Windows에서는 심볼릭 링크를 생성하려면 관리자 권한이나 개발자 모드가 필요하므로, 해당 환경에서는 @AGENTS.md import를 사용하십시오.

이와 관련하여 주의할 점이 하나 있습니다. /compact 이후 루트 파일은 디스크에서 다시 읽히지만, 하위 디렉터리에 있는 중첩 파일은 다시 주입되지 않습니다. 이 파일들은 에이전트가 해당 디렉터리의 파일을 읽을 때 다시 로드됩니다. 긴 세션 도중 특정 디렉터리의 규칙이 적용되지 않는 것처럼 보인다면 보통 이 때문이며, 해당 디렉터리의 파일을 아무거나 수정(touch)하면 다시 적용됩니다.

이 방식은 에이전트 메모리나 스킬과 어떻게 다른가?

이 메커니즘들은 비슷해 보이지만 실패하는 방식이 완전히 다르므로, 어떤 것을 사용해야 할지 정확히 구분할 필요가 있습니다.

AGENTS.md는 사용자가 직접 작성하여 git에 커밋하고 풀 리퀘스트를 통해 검토받으며, 저장소를 복제하는 모든 사람에게 동일하게 적용됩니다. 반면 에이전트 메모리는 에이전트가 직접 작성하여 저장소 외부의 특정 머신에 로컬로 저장합니다. Claude Code의 문서도 이와 같은 기준을 제시합니다. CLAUDE.md는 사용자가 작성한 "지침과 규칙"을 담고, 자동 메모리는 Claude가 학습한 "학습 내용과 패턴"을 담으며, 메모리 디렉터리는 머신 간에 공유되지 않습니다. 판단 기준은 간단합니다. 새로운 환경에서 저장소를 복제한 동료에게도 반드시 적용되어야 하는 사실이라면, 그것은 메모리에 저장될 수 없습니다. 에이전트 메모리가 세션 간에 유지되는 방식에서 이 부분의 절반을 다룹니다.

스킬은 세 번째 요소입니다. AGENTS.md는 모든 세션에서 로드되는 컨텍스트인 반면, 스킬은 필요할 때 로드되는 절차입니다. Claude Code 문서에서는 다음과 같은 유용한 규칙을 제시합니다. "항목이 다단계 절차이거나 코드베이스의 특정 부분에만 관련이 있다면, 스킬이나 경로 범위 규칙으로 옮기십시오." 이 문장의 후반부는 중첩된 AGENTS.md가 해결하는 문제이며, 전반부는 에이전트 스킬이 담당합니다. 동일한 절차가 여러 저장소에서 필요하다면, 10개의 서로 다른 AGENTS.md 파일에 같은 내용을 복사해 넣는 대신 저장소 간에 스킬을 공유하십시오.

Upstream에서는 "작성 시점 기준으로 메인 OpenAI 저장소에 88개의 AGENTS.md 파일이 존재한다"고 언급합니다. 이 숫자가 모든 것을 설명합니다. 거대한 저장소라고 해서 더 큰 파일이 필요한 것은 아닙니다. 코드 옆에 위치하며 해당 코드를 마지막으로 수정한 사람이 관리하는, 더 많은 작은 파일들이 필요할 뿐입니다.

FAQ

중첩된 AGENTS.md는 루트 파일을 대체합니까, 아니면 추가합니까?

추가합니다. 업스트림에서는 "가장 가까운 파일이 우선한다"고 설명하는데, 이는 충돌 시 발생하는 현상일 뿐 로드되는 방식과는 다릅니다. Codex는 "루트부터 아래로 파일을 연결하며 빈 줄로 구분"하며, Claude Code는 작업 디렉터리에서 상위로 이동하며 발견되는 모든 파일을 연결합니다. 가장 가까운 파일이 우선하는 경우는 두 파일이 동일한 주제에 대해 서로 다른 지침을 제공할 때뿐입니다. 공통 규칙은 루트에 한 번만 작성하고, 모든 디렉터리에 반복하지 마십시오.

루트 AGENTS.md는 어느 정도 크기가 적당합니까?

해당 저장소에서 요청을 보낼 때마다 파일 내용이 상단에 붙어도 괜찮을 정도로 작아야 합니다. 실제로 그렇게 동작하기 때문입니다. Claude Code 문서에서는 파일당 200줄 미만을 권장하며, 파일이 길어질수록 "준수율이 떨어진다"고 경고합니다. Codex는 기본적으로 총 32 KiB가 넘어가면 지침 파일 병합을 중단합니다. 루트 파일에 4개의 서비스가 기술되어 있다면, 특정 작업을 수행할 때는 대부분이 불필요한 정보가 됩니다. 세부 사항은 디렉터리별 파일로 옮기고 루트에는 지도를 남기십시오.

이 파일들이 최신 상태를 유지하게 하려면 어떻게 해야 합니까?

루트 파일에 규칙을 하나 추가하십시오. 디렉터리의 코드를 변경하는 사람이 동일한 커밋에서 해당 디렉터리의 AGENTS.md도 업데이트해야 한다는 규칙입니다. 코드가 있는 곳에 파일을 두면 규칙이 잘 지켜지는데, 이는 변경 사항이 사람이 이미 검토 중인 풀 리퀘스트 diff에 포함되기 때문입니다. 변경된 경로를 상위의 가장 가까운 AGENTS.md와 매핑하는 CI 경고를 추가하고, 주기적으로 각 파일의 git log -1 --format=%cs를 해당 파일이 기술하는 디렉터리에서 실행한 동일한 명령 결과와 비교하십시오.

Claude Code가 AGENTS.md 파일을 읽습니까?

아니요. 2026년 8월 기준 문서에 따르면 "Claude Code는 AGENTS.md이 아닌 CLAUDE.md을 읽습니다." 같은 디렉터리에 첫 줄에 @AGENTS.md가 포함된 CLAUDE.md을 만드십시오. 이렇게 하면 공유 파일을 로드하고 그 아래에 Claude 전용 지침을 추가할 수 있습니다. 추가할 내용이 없을 때는 ln -s AGENTS.md CLAUDE.md으로 생성한 심볼릭 링크도 작동하지만, Windows에서는 관리자 권한이나 개발자 모드가 필요합니다. 세션에서 /context을 실행하여 Memory 파일 목록에 해당 파일이 나타나는지 확인하십시오.

가끔씩만 적용되는 규칙은 어디에 두어야 합니까?

AGENTS.md에는 두지 마십시오. 해당 파일은 모든 세션에서 로드되므로, 파일의 모든 줄이 사용자가 실제로 입력한 요청과 경쟁하게 됩니다. 가끔 필요한 여러 단계의 절차는 필요할 때 로드되는 스킬(skill)에 두어야 합니다. 특정 디렉터리에만 적용되는 규칙은 해당 디렉터리의 AGENTS.md에 두십시오. 디렉터리 트리나 의존성 목록처럼 에이전트가 코드에서 직접 읽을 수 있는 사실은 어디에도 둘 필요가 없습니다.