모노레포에서 중첩된 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)에 도달하면 병합을 중단합니다. 4개의 서비스를 문서화하는 루트 파일은 매 작업마다 그중 3개 서비스에 대한 예산을 낭비하게 됩니다.

지시 사항이 서로 충돌하기 시작합니다. 웹 디렉터리는 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.

워커 파일도 동일한 형식을 따르지만 내용은 다릅니다. 여기에는 설치 명령, pytest -q, 소비자가 멱등성을 유지해야 하는 이유, 그리고 테스트 통과 전에 실행해야 할 마이그레이션이 포함됩니다. 인프라 파일에는 에이전트가 피해를 입히지 않도록 제한하는 규칙을 작성합니다. 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에서는 symlink 사용 시 관리자 권한이나 개발자 모드가 필요하므로, 해당 환경에서는 @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에 두십시오. 디렉터리 트리나 의존성 목록처럼 에이전트가 코드에서 직접 읽을 수 있는 사실은 어디에도 둘 필요가 없습니다.