커뮤니티 입장하기

클로드 코드 AGENTS.md 공식 지원(v2.1.277): 읽는 조건과 읽지 않는 조건 정리

AGENTS.md는 여러 AI 코딩 도구가 함께 읽는 프로젝트 지침 파일입니다. Claude Code의 기본 선택 조건과 버전별 차이, 기존 규칙을 지우지 않고 읽힌 파일을 확인하는 순서를 정리했습니다.

게시 수정 약 28분
지금까지 100명 넘게 읽었어요, 63%가 끝까지 읽었어요
#AI#바이브코딩#자동화
Share
클로드 코드 AGENTS.md 공식 지원(v2.1.277): 읽는 조건과 읽지 않는 조건 정리 대표 이미지
목차
  1. AGENTS.md 공식 지원 발표 내용 한눈에 보기
  2. 클로드 코드가 AGENTS.md를 읽는 조건
  3. 상위 폴더의 CLAUDE.md 하나 때문에 팀의 AGENTS.md가 올라오지 않는 구조
  4. Project instructions 설정값 네 가지
  5. AGENTS.md로 읽을 때 CLAUDE.md와 달라지는 곳
  6. 설정 항목이 없거나 파일이 읽히지 않을 때
  7. 1년 넘게 쌓인 요청과 공개 직후 반응
  8. 쓰던 우회법을 정리하는 방법
  9. 기존 파일을 지우지 않고 확인하는 연습
  10. 자주 묻는 질문
  11. Sources
  12. 3줄 요약

세 줄로 먼저 읽기

이번 방문에서 한 편은 바로 볼 수 있습니다.

AGENTS.md는 여러 AI 코딩 도구가 함께 읽도록 만든 프로젝트 지시 파일입니다. 예를 들어 “글을 수정한 뒤 맞춤법을 확인한다”처럼 반복해서 지킬 작업 규칙을 적습니다. .md는 제목과 목록을 간단한 기호로 적는 마크다운 파일의 확장자입니다. 앤트로픽은 현지 시간 2026년 9월 18일 내놓은 클로드 코드 v2.1.277부터 이 파일을 직접 읽기 시작했습니다. 한국 시간으로는 9월 19일 새벽에 배포됐습니다.

클로드 코드를 써 본 분이라면 CLAUDE.md는 익숙할 것입니다. 프로젝트 규칙을 적어 두면 세션이 열릴 때마다 클로드가 읽어 가는 파일이고, 준이아빠블로그에서도 CLAUDE.md 세팅과 공식 문서 대조로 한 번 다뤘습니다. 코덱스나 커서, 깃허브 코파일럿을 같이 쓰는 팀은 같은 내용을 AGENTS.md에도 적어 두 벌로 관리해 왔습니다.

이번 변화로 두 벌을 한 벌로 줄일 수 있게 됐는데, 클로드가 AGENTS.md를 읽어 주는 조건이 생각보다 까다롭습니다. 조건을 모르고 파일부터 정리하면 팀 규칙이 빠진 채로 작업이 진행될 수 있습니다. 아래 직접 실행 기록과 화면은 2026년 9월 19일의 v2.1.277 자료입니다. 사용 조건은 2026년 10월 4일 공식 문서에 맞춰 설명합니다. v2.1.280에서 로딩 목록 표시가, v2.1.281에서 일부 실행 환경 제한이 바뀌었습니다.

AGENTS.md 공식 지원 발표 내용 한눈에 보기

항목내용
적용 버전클로드 코드 v2.1.277. 현지 시간 2026년 9월 18일, 한국 시간 9월 19일 새벽에 배포됐습니다
기본 동작작업 폴더와 그 위쪽에 CLAUDE.md가 없을 때만 AGENTS.md를 대신 읽습니다
바꾸는 방법세션에서 /config를 열고 Project instructions 값을 고릅니다
세션 시작에 읽는 것작업 폴더와 상위 폴더의 AGENTS.md, .claude/AGENTS.md
하위 폴더그 폴더에 CLAUDE.md가 없고 클로드가 그 폴더의 파일을 열 때 그 폴더의 AGENTS.md를 추가로 읽습니다
읽지 않는 것AGENTS.local.md, AGENTS.override.md, .agents/ 아래 전부
현재 안 될 수 있는 경우v2.1.277 미만, 내장 agents-md 플러그인 비활성화, 일부 업그레이드 직후 첫 세션

위 첫 문서 화면의 제3자 제공자 관련 안내는 출시 당시 내용입니다. v2.1.281 이상에 그대로 적용하지 않습니다.

표에서 먼저 볼 것은 기본 동작입니다. 두 파일을 합쳐 읽는 것이 아니라 CLAUDE.md가 없을 때만 대신 읽는 방식이라, 이미 CLAUDE.md를 쓰던 프로젝트에서는 아무것도 달라지지 않습니다.

그다음은 하위 폴더입니다. 세션이 열릴 때 한꺼번에 올라오는 것은 작업 폴더와 그 위쪽 파일이고, 하위 폴더의 AGENTS.md는 클로드가 그 폴더의 파일을 실제로 열 때 뒤늦게 올라옵니다. 이때도 그 하위 폴더에 CLAUDE.md가 없어야 합니다. 여러 프로젝트를 한 저장소에 모은 모노레포에서 하위 프로젝트마다 규칙을 나눠 둘 수 있다는 뜻입니다.

.agents/ 폴더를 읽지 않는다는 항목도 함께 봐야 합니다. 다른 도구들이 스킬이나 하위 에이전트를 그 폴더에 모아 두는 경우가 있는데, 이 프로젝트 지침 자동 로딩 기능은 그 폴더를 대상으로 삼지 않습니다. 사용자가 요청해 파일 도구로 읽는 일까지 불가능하다는 뜻은 아닙니다.

클로드 코드가 AGENTS.md를 읽는 조건

현관에 우리 집 전용 안내문이 붙어 있으면 기사가 그 옆의 공용 안내문은 읽지 않듯, 기본 설정의 클로드는 해당 경로에서 CLAUDE.md를 찾으면 AGENTS.md를 자동 로딩하지 않습니다. 공식 문서가 조합 세 가지로 정리한 내용입니다.

저장소에 있는 파일클로드가 읽는 것
AGENTS.md만 있고 위쪽에도 CLAUDE.md가 없음AGENTS.md
AGENTS.md와 CLAUDE.md가 함께 있음CLAUDE.md만
CLAUDE.md 안에 @AGENTS.md가 적혀 있음CLAUDE.md, 불러온 AGENTS.md 포함

여기서 CLAUDE.md로 세는 파일은 세 가지입니다. 작업 폴더나 그 위쪽의 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md입니다. 반대로 개인 설정인 ~/.claude/CLAUDE.md와 회사가 배포한 관리 정책 파일, .claude/rules/ 파일은 여기서 세지 않으며 AGENTS.md와 함께 올라옵니다.

문서만으로는 상위 폴더 조건이 어디까지 걸리는지 가늠하기 어려워서, v2.1.277을 설치한 맥에서 폴더 네 개를 만들어 직접 확인했습니다. 파일마다 다른 확인 코드를 적어 두고 클로드에게 그 코드를 물어봤습니다. 2026년 9월 19일에 돌린 결과입니다.

폴더 구성클로드가 답한 코드응답 코드가 있던 파일
AGENTS.md 하나만 둠AAA-111AGENTS.md
AGENTS.md와 CLAUDE.md를 같이 둠CCC-333CLAUDE.md
상위 폴더에 CLAUDE.md, 작업 폴더에 AGENTS.mdDDD-444상위 폴더의 CLAUDE.md
AGENTS.md와 CLAUDE.local.md를 같이 둠GGG-777CLAUDE.local.md

네 줄 모두 문서와 맞아떨어졌습니다. 두 번째 폴더에서 claude-md-and-agents-md 설정으로 한 번 더 돌리자, 클로드가 CLAUDE.md의 코드를 먼저 대고 AGENTS.md에 적어 둔 코드를 뒤이어 말했습니다. 두 코드가 응답에 포함된 점은 두 지침의 내용이 전달됐다는 정황입니다. 응답 순서만으로 내부 로딩 순서까지 입증하는 것은 아니며, 파일을 읽는 순서는 공식 문서 설명을 따릅니다.

상위 폴더의 CLAUDE.md 하나 때문에 팀의 AGENTS.md가 올라오지 않는 구조

앞 표의 세 번째 줄은 다음처럼 생각하면 됩니다. work/CLAUDE.md가 있고 work/blog/AGENTS.md가 있을 때, blog에서 시작해도 기본 설정은 위쪽 work/CLAUDE.md를 우선합니다. 여기서 상위 폴더란 현재 폴더를 담고 있는 폴더를 뜻합니다. 기본 설정은 파일이 가까운지만 비교하는 방식이 아닙니다.

여러 프로젝트를 한 저장소에 모은 모노레포에서도 이 조건을 확인해야 합니다. 저장소 루트에 예전에 만든 CLAUDE.md가 남아 있고 패키지 폴더마다 AGENTS.md를 새로 만들어 두었다면, 패키지 폴더에서 세션을 열어도 루트의 CLAUDE.md만 올라옵니다. AGENTS.md로 옮기는 작업을 폴더 단위로 나눠서 하기 어렵다는 뜻이기도 합니다.

더 조용히 걸리는 것은 CLAUDE.local.md입니다. 공식 문서도 이 파일을 따로 경고하고 있는데, 팀이 AGENTS.md를 쓰기로 한 저장소라도, 한 사람이 개인 메모용으로 만든 파일 하나면 팀 지시문이 통째로 빠집니다. 커밋되지 않는 파일이라 다른 사람 화면에서는 멀쩡하게 동작하고, 그 사람 화면에서만 규칙이 빠진 채로 작업이 진행됩니다.

개인 메모를 유지하면서 AGENTS.md도 자동으로 읽게 하려면 다음 절의 claude-md-and-agents-md나 명시적 가져오기를 사용합니다.

Project instructions 설정값 네 가지

세션에서 /config를 열면 Project instructions 항목이 있고, 값은 네 가지입니다.

값클로드가 읽는 것
claude-md-or-agents-md기본값입니다. CLAUDE.md가 있으면 그것만, 없으면 AGENTS.md를 읽습니다
claude-md-and-agents-md둘 다 읽습니다. 폴더마다 CLAUDE.md를 먼저, AGENTS.md를 나중에 올립니다
claude-mdCLAUDE.md만 읽습니다
managed-only시작할 때 관리 정책 지침과 자동 메모리만 읽습니다. 이후 하위 폴더 파일을 읽을 때 일부 CLAUDE.md와 경로별 규칙은 추가될 수 있습니다

claude-md-and-agents-md를 골라도 같은 파일이 두 번 올라오지는 않습니다. CLAUDE.md가 @AGENTS.md로 불러오거나 다른 파일을 가리키는 심볼릭 링크로 연결해 둔 경우, 클로드 코드가 이미 읽은 AGENTS.md를 건너뜁니다.

처음에는 /config에서 현재 값을 확인하는 편이 간단합니다. 사용자 범위로 저장한 변경은 다른 프로젝트에도 영향을 줄 수 있으므로 원래 값을 기록해 둡니다. 설정은 다음 메시지와 새 세션에 적용됩니다.

설정 파일을 직접 편집할 수도 있습니다. 아래 JSON으로 기존 파일 전체를 덮어쓰지 않고 해당 항목만 합칩니다. AGENTS.md 지원이 내장 플러그인으로 들어가 있어서 pluginConfigs의 agents-md@builtin 아래에 적습니다.

{ "pluginConfigs": { "agents-md@builtin": { "options": { "instructionFiles": "claude-md-and-agents-md" } } } }

여기서 놓치기 쉬운 것은 이 값을 프로젝트 폴더의 .claude/settings.json에 적으면 무시된다는 점입니다. 사용자 설정 파일인 ~/.claude/settings.json이나 --settings로 넘기는 파일, 회사 관리 설정에만 적용됩니다. 팀 전체에 같은 값을 적용하고 싶어서 저장소에 커밋하는 방법은 통하지 않습니다.

AGENTS.md로 읽을 때 CLAUDE.md와 달라지는 곳

설정을 켰어도 CLAUDE.md와 똑같이 동작하지는 않습니다. 파일을 읽는 경로와 버전에 따라 다음 차이를 확인합니다.

  • 목록 표시는 버전에 따라 다릅니다. v2.1.280부터는 직접 읽은 AGENTS.md를 /memory 목록에서 확인할 수 있습니다. 그보다 이전에는 /memory와 /context에 표시되지 않았으므로 시작 안내와 규칙을 물었을 때의 응답을 함께 봅니다.
  • 직접 로딩한 AGENTS.md는 InstructionsLoaded 훅을 실행하지 않습니다. 훅은 정해진 이벤트에 맞춰 명령을 실행하는 기능입니다. 지시문이 올라올 때 훅으로 검증하거나 기록을 남기던 설정은 아무 말 없이 동작하지 않게 됩니다. CLAUDE.md가 불러온 AGENTS.md에서는 평소대로 실행됩니다.
  • --add-dir로 추가한 폴더에서는 AGENTS.md가 빠집니다. CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD를 켜 두면 그 폴더의 CLAUDE.md는 올라오지만 AGENTS.md는 올라오지 않습니다.
  • 작업 폴더 밖의 파일을 @경로로 불러올 때 승인을 묻지 않습니다. CLAUDE.md를 쓸 때는 외부 파일을 불러오기 전에 승인을 묻는데, AGENTS.md는 그 프로젝트에서 외부 가져오기를 이미 승인한 경우에만 추가 질문 없이 불러옵니다. 승인한 적이 없어도 모든 외부 파일이 자동 로딩되는 것은 아닙니다.

두 번째와 네 번째는 보안이나 운영 규칙을 훅으로 강제하던 팀에서 확인해 볼 만합니다. 하위 에이전트 쪽은 달라지지 않습니다. 프로젝트 지시문으로 올라온 AGENTS.md는 CLAUDE.md와 마찬가지로 하위 에이전트에게도 전달되고, Explore와 Plan 에이전트는 두 파일을 모두 건너뜁니다.

설정 항목이 없거나 파일이 읽히지 않을 때

PowerShell이나 맥 셸에서 claude --version을 확인하고, Claude Code 대화 안에서는 /config의 Project instructions를 봅니다. 두 명령의 입력 위치가 다릅니다.

현재 공식 안내는 v2.1.277 미만, 내장 agents-md 플러그인 비활성화, 일부 구버전 업그레이드 직후 첫 세션을 확인하도록 합니다. /plugin에서 해당 내장 플러그인이 꺼져 있는지도 봅니다.

출시 초기의 제3자 제공자나 텔레메트리 관련 제한은 v2.1.281 이전 버전에 해당합니다. 현재 버전에서 기능이 안 된다는 이유로 텔레메트리를 켜거나 조직의 훅 정책을 해제하지 않습니다. 업데이트가 제한된 환경이면 같은 폴더의 CLAUDE.md에서 @AGENTS.md로 가져오는 방법을 검토합니다.

1년 넘게 쌓인 요청과 공개 직후 반응

이 기능은 깃허브 이슈 하나에 1년 넘게 요청이 쌓인 끝에 나왔습니다. 2025년 8월 21일에 올라온 6235번 이슈는 "코덱스와 앰프, 커서가 AGENTS.md로 표준을 잡아 가는데 CLAUDE.md는 클로드 코드에만 너무 맞춰져 있어서, 클로드 코드를 쓰지 않는 개발자와 협업할 때 잘 맞지 않는다"는 짧은 글로 시작했습니다.

2026년 9월 19일 기록에는 엄지 반응 5,168개와 댓글 399개가 있었습니다. 지원을 미루는 이유는 기술이 아니라 브랜드 노출이라고 보는 댓글이 여러 개 달렸고, CLAUDE.md에 AGENTS.md를 읽으라는 문장을 넣고 Git 기록에서 제외하는 우회법도 공유됐습니다. 이는 당시 반응이며 현재 연습에서 기존 CLAUDE.md를 덮어쓸 이유는 없습니다. 공개 당일에는 앤트로픽 쪽 공지 게시글을 그대로 옮겨 붙이고 "Finally!!"를 덧붙인 댓글이 올라왔습니다.

그사이 AGENTS.md를 쓰는 곳도 크게 늘었습니다. 공식 사이트는 6만 개가 넘는 오픈소스 프로젝트가 쓰고 있다고 적고 있고, 지금은 리눅스 재단 산하 Agentic AI Foundation이 관리합니다. 위 화면과 당시 기록에는 여러 지원 도구가 소개되어 있습니다. 목록에 이름이 있거나 없다는 사실만으로 현재 세부 지원 조건을 판단하지 않고 각 도구의 문서를 확인합니다.

쓰던 우회법을 정리하는 방법

공식 지원 전에 직접 만들어 둔 설정이 있다면 지금 정리해야 할 것과 그대로 둬도 되는 것을 먼저 구분해야 합니다.

쓰던 방법지금 할 일
CLAUDE.md에 @AGENTS.md를 적어 둠그대로 둬도 됩니다. 어느 설정값에서도 두 번 읽지 않습니다
CLAUDE.md에 "AGENTS.md를 읽어라"라고 문장으로 적어 둠기존 규칙을 보존하며 명시적 @AGENTS.md 가져오기로 바꾼 뒤 확인합니다
CLAUDE.md를 AGENTS.md로 심볼릭 링크다른 파일을 가리키는 연결입니다. 연결 대상과 팀 환경을 확인하고 유지 여부를 정합니다
SessionStart 훅으로 AGENTS.md를 출력직접 로딩이 확인되면 중복 출력 부분만 제거합니다. 훅의 다른 동작은 보존합니다

마지막 줄은 자동 로딩이 실제로 확인된 뒤 적용합니다. 같은 내용을 출력하는 훅이 남아 있으면 클로드가 직접 읽은 AGENTS.md 위에 훅이 출력한 사본이 한 벌 더 올라옵니다. 그 규칙의 본문이 중복으로 들어가면서 클로드가 같은 규칙을 두 번 읽습니다.

심볼릭 링크를 쓰던 팀은 두 가지를 같이 확인하는 편이 좋습니다. 클로드는 링크를 따라 읽지만 Edit와 Write 도구는 링크로 연결된 파일에 쓰지 못하고, 윈도우에서는 관리자 권한이나 개발자 모드 없이 링크를 만들지 못합니다. 링크가 평범한 텍스트 파일로 체크아웃되면 그 컴퓨터에서는 한 줄짜리 CLAUDE.md가 지시문을 대신하게 됩니다.

가져오기 방식은 AGENTS.md와 같은 폴더의 CLAUDE.md에 아래 한 줄을 넣는 방법입니다. 기존 파일이 있다면 원래 내용을 보존하며 추가하고, 이미 같은 줄이 있는지 먼저 봅니다.

@AGENTS.md

이 경우 Claude Code는 CLAUDE.md의 가져오기 구문으로 공통 규칙을 불러옵니다. AGENTS.md를 직접 자동 로딩하는 경로와 구분합니다.

기존 파일을 지우지 않고 확인하는 연습

먼저 자신이 만든 빈 연습 폴더에서 진행합니다. 그 폴더 안에 VS Code 같은 편집기로 AGENTS.md를 만들고 다음처럼 짧게 적습니다.

# 연습 규칙 - 작업 결과는 한국어로 설명한다. - 이 프로젝트의 확인 표시는 BOOK-731이다.

파일 이름이 AGENTS.md.txt로 저장되지 않았는지 봅니다. 위쪽 폴더에 CLAUDE.md 계열 파일이 있다면 지우지 말고 현재 기본 조건에 영향을 준다는 점을 기록합니다. 두 파일을 읽어야 한다면 원래 설정값을 기록한 뒤 /config에서 claude-md-and-agents-md를 선택합니다.

Claude Code에서 /exit로 나온 뒤 같은 연습 폴더의 셸에서 claude로 새 세션을 엽니다. v2.1.280 이상이면 /memory로 AGENTS.md 경로를 확인합니다. 그보다 이전 버전에서는 목록 표시가 없어도 실패로 단정하지 않고 시작 안내와 아래 응답을 함께 봅니다. 이어서 “추가 파일 검색 없이 현재 전달받은 프로젝트 규칙의 확인 표시를 말해 줘.”라고 요청합니다. 목록과 BOOK-731 응답을 함께 확인합니다. 확인 요청 뒤 파일 읽기 도구로 AGENTS.md를 새로 열었다면 시작 시 자동 로딩을 확인한 것과 다릅니다. AI의 대답 하나만으로 모든 규칙이 항상 지켜진다고 판단하지 않습니다.

값이 안 나오면 버전, 실제 파일 이름, 시작 폴더와 상위 규칙, 현재 설정값을 순서대로 확인합니다. 해결하려고 여러 규칙 파일을 한꺼번에 지우지 않습니다.

다음에는 편집기로 확인 표시를 BOOK-842로 바꾸고 저장한 뒤 새 세션에서 같은 확인을 반복합니다. 바뀐 값이 나오면 저장과 새 세션 로딩을 확인한 것입니다. 연습 때문에 사용자 설정을 바꿨다면 원래 값으로 되돌리고 실제 프로젝트의 규칙을 다시 확인합니다.

자주 묻는 질문

CLAUDE.md를 지우면 AGENTS.md를 바로 읽나요?

기본 설정이며 기능을 사용할 수 있는 환경에서, 작업 폴더와 상위 경로에 해당 CLAUDE.md 계열 파일이 없다면 AGENTS.md를 읽습니다. 기존 파일을 지우기 전에 가져오기 방식으로 유지할 수 있는지 먼저 봅니다. .claude/CLAUDE.md와 CLAUDE.local.md도 함께 확인해야 하고, 일부 구버전 업그레이드 직후 첫 세션에서는 아직 동작하지 않을 수 있습니다.

두 파일을 함께 쓰면 규칙이 충돌하지 않나요?

올라오는 순서는 정해져 있습니다. 폴더마다 CLAUDE.md가 먼저 올라오고 그 뒤에 AGENTS.md가 올라옵니다. 충돌 자체를 막아 주는 장치는 없으므로, 공통 규칙은 AGENTS.md에 두고 클로드에만 해당하는 내용만 CLAUDE.md에 남기는 방법이 무난하다고 봅니다.

아마존 베드록에서도 쓸 수 있나요?

현재 공식 문서는 베드록 등에서 직접 로딩이 제한됐던 조건을 v2.1.281 이전으로 구분합니다. 구버전이면 업데이트 여부를 확인하고, 업데이트할 수 없으면 CLAUDE.md의 @AGENTS.md 가져오기를 사용합니다.

Sources

3줄 요약

  1. Claude Code는 v2.1.277부터 AGENTS.md를 직접 읽으며 기본 설정에서는 상위 경로의 CLAUDE.md 계열 파일을 먼저 확인합니다.

  2. 두 파일을 함께 사용하려면 명시적인 가져오기나 Project instructions 설정을 사용하고 기존 규칙을 보존합니다.

  3. 버전과 설정을 확인한 뒤 새 세션의 로딩 목록과 실제 응답을 함께 검사하며 출시 당시 제한을 현재 버전에 그대로 적용하지 않습니다.

Share

제대로 이해했는지 한 문제로 확인해 볼까요?

답을 고르면 바로 풀이가 나와요.

기본 claude-md-or-agents-md 설정이며 별도 가져오기가 없을 때, 상위 폴더에 CLAUDE.md가 있고 작업 폴더에 AGENTS.md가 있으면 무엇을 읽을까요?

이 글이 도움이 되었나요?

이 글 다음 배우기AI 에이전트 중급: 원리와 설계중급 코스 · 12편

도구에 상관없이 통하는 에이전트 원리와 설계 규칙을 정리했습니다

  1. 1AI 에이전트(AI Agent) 뜻과 챗봇, 워크플로의 차이
  2. 2에이전트 루프와 도구 호출(Tool Calling) 원리
  3. 3AGENTS.md와 CLAUDE.md(에이전트 지침 파일) 뜻과 작성법
코스 전체 보기 →
이어서 읽기 좋은 글클로드 코드(Claude Code) CLAUDE.md 세팅, 알려진 노하우들과 공식 문서 업데이트 정리 →

CLAUDE.md에 짧은 프로젝트 규칙을 적고 새 세션에서 읽혔는지 확인하는 방법을 안내합니다. 200줄 권장, 훅과 권한 설정의 역할, 스킬로 옮길 내용과 비용의 차이도 공식 문서에 맞춰 정리했습니다.

함께 읽으면 좋은 글

관련 개념