클로드 코드, CLAUDE.md 없으면 AGENTS.md를 읽는다 — 에이전트 지침 파일 표준화의 신호 | 뉴스

클로드 코드가 2026년 9월 18일 v2.1.277부터, 프로젝트에 CLAUDE.md가 없을 때 AGENTS.md를 프로젝트 지침 파일로 읽는다. 여러 코딩 에이전트를 같은 저장소에서 돌리는 팀이 동일한 규칙을 파일마다 복사해 두던 부담이 줄어든다.

판정 대상은 세 파일이다. 작업 디렉터리나 그 상위의 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md 중 하나라도 있으면 기존대로 그쪽을 쓰고, 셋 다 없을 때 AGENTS.md로 떨어진다.

사소해 보이는 변경이지만, 이 한 줄이 실무에서 없애는 마찰은 꽤 크다. 나는 한동안 같은 내용을 세 파일에 복붙하며 살았다. 빌드 명령, 테스트 실행법, 커밋 규칙, 건드리면 안 되는 디렉터리 — 내용은 같은데 도구마다 파일 이름이 달랐다. 그리고 예외 없이 한 파일만 갱신하고 나머지를 잊었다.

무엇이 어떻게 바뀌나

상황	이전	v2.1.277 이후
CLAUDE.md 있음	CLAUDE.md 사용	동일 (변화 없음)
CLAUDE.md 없고 AGENTS.md 있음	프로젝트 지침 없음	AGENTS.md를 지침으로 사용
둘 다 있음	CLAUDE.md 사용	CLAUDE.md 우선 (설정에서 변경 가능)
둘 다 없음	지침 없음	지침 없음

어떤 파일을 프로젝트 지침으로 취급할지는 설정의 "Project instructions" 항목에서 바꿀 수 있다. 다만 모든 세션에 즉시 적용되는 건 아니다. v2.1.277 이전 버전, 기능 플래그를 받아오지 않는 실행 환경(예: 일부 클라우드 경유 구성), 설치·업그레이드 직후 첫 세션은 동작이 다를 수 있다.

왜 AGENTS.md인가 AGENTS.md는 특정 벤더의 파일이 아니라 여러 코딩 에이전트가 공통으로 읽는 관례로 자리 잡아 온 이름이다. 저장소 루트에 하나 두고 모든 도구가 읽게 하자는 발상이고, 이번 변경은 그 관례를 클로드 코드가 받아들인 사례다.

지침 파일에 무엇을 써야 효과가 있나

에이전트 지침 파일을 처음 만들면 대개 장황해진다. 아키텍처 설명, 팀 철학, 코드 리뷰 문화까지 적는다. 경험상 그런 문장은 거의 작동하지 않는다. 실제로 결과를 바꾸는 건 검증 가능한 명령과 금지선이다.

효과 있는 항목

✓빌드·테스트·린트 실행 명령 (복붙 가능한 형태 그대로)

✓패키지 매니저 지정 — npm인지 pnpm인지 헷갈리면 에이전트는 매번 틀린다

✓건드리면 안 되는 경로 (생성 코드, 마이그레이션, 벤더 디렉터리)

✓커밋·브랜치 규칙과 금지 사항 (예: main 직접 푸시 금지)

✓프로젝트 고유의 함정 — "이 서비스는 재시작하면 캐시가 날아간다" 같은 것

✓완료 기준 — 무엇을 돌려서 통과해야 작업이 끝난 것인가

# AGENTS.md (예시 · 짧을수록 좋다)

## 명령
- 설치: pnpm install
- 개발: pnpm dev
- 테스트: pnpm test --run
- 린트: pnpm lint

## 규칙
- 패키지 매니저는 pnpm 고정. npm/yarn 사용 금지.
- prisma/migrations 는 직접 수정하지 말 것.
- src/generated/ 는 생성 파일. 편집 금지.
- 커밋 전 pnpm test --run 과 pnpm lint 가 모두 통과해야 한다.

## 함정
- 개발 서버는 포트 3000 고정. 이미 떠 있으면 죽이지 말고 재사용할 것.
- .env 는 커밋하지 않는다. 예시는 .env.example 에만.

두 파일을 모두 둬야 하는 경우

도구마다 잘 먹는 표현이 다르다고 느껴서 파일을 분리하고 싶을 때가 있다. 그럴 때도 내용의 원본은 하나로 두는 게 낫다. 가장 단순한 방법은 심볼릭 링크이고, 그게 어려운 환경이면 한 파일에서 다른 파일을 참조하는 한 줄만 남기는 방식도 쓸 만하다.

# 방법 1: 심볼릭 링크 (가장 단순)
ln -s AGENTS.md CLAUDE.md

# 방법 2: CLAUDE.md 는 얇게 두고 본문은 AGENTS.md 에
echo "프로젝트 지침은 @AGENTS.md 를 따른다." > CLAUDE.md

# 방법 3: CI에서 동기화 검사
#   두 파일 내용이 다르면 실패시키는 스텝을 넣어 드리프트를 방지

단일 파일 운영의 장점

드리프트 없음
신규 도구 도입 시 추가 작업 없음
리뷰 대상이 하나

주의할 점

도구별 고유 문법(멘션·임포트)이 섞이면 가독성 저하
팀원 중 일부가 특정 도구만 쓰면 불필요한 지침이 섞임
너무 길어지면 어느 도구에서도 효과가 떨어진다

맥락 — 코딩 에이전트 설정의 수렴

2026년 들어 코딩 에이전트 도구는 기능보다 맥락 주입 방식에서 경쟁하고 있다. 어떤 파일을 읽는가, 어떤 규칙을 언제 적용하는가, 스킬·모드 같은 재사용 단위를 어떻게 정의하는가. 파일 이름이 통일되는 흐름은 이 경쟁이 사용자 편에서 정리되고 있다는 신호로 읽힌다. 도구를 바꿀 때 저장소를 다시 손봐야 한다면, 그건 도구의 락인이지 기능이 아니다.

출처

Claude Code 공식 체인지로그 — https://code.claude.com/docs/en/changelog
DEV Community, "Claude Code v2.1.277 Reads AGENTS.md When CLAUDE.md Is Missing" — https://dev.to/cogumellum/claude-code-v21277-reads-agentsmd-when-claudemd-is-missing-53ln
RuntimeWire, "Claude Code adds AGENTS.md fallback for repositories shared across coding agents" — https://runtimewire.com/article/claude-code-adds-agents-md-support

자주 묻는 질문

클로드 코드가 이제 AGENTS.md를 항상 읽나요?

아닙니다. CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md 중 하나라도 있으면 그쪽이 우선입니다. 셋 다 없을 때만 AGENTS.md를 프로젝트 지침으로 읽습니다. v2.1.277 이상에서 적용되며 설정에서 우선순위를 바꿀 수 있습니다.

CLAUDE.md와 AGENTS.md를 둘 다 두면 어떻게 되나요?

기본적으로 CLAUDE.md가 사용됩니다. 두 파일을 모두 유지해야 한다면 심볼릭 링크로 묶거나, 한쪽을 얇게 만들어 다른 쪽을 참조하게 해서 내용의 원본을 하나로 유지하는 방식을 권합니다. 내용이 갈라지면 어느 쪽이 적용됐는지 추적하기 어려워집니다.

지침 파일에는 어느 정도 분량이 적당한가요?

짧을수록 잘 지켜집니다. 빌드·테스트 명령, 패키지 매니저, 금지 경로, 완료 기준 정도면 충분합니다. 아키텍처 설명이나 팀 철학 같은 서술형 문장은 실제 동작을 거의 바꾸지 못하면서 파일만 길게 만듭니다.

업그레이드했는데 동작이 다릅니다. 왜인가요?

v2.1.277 미만 버전이거나, 기능 플래그를 받아오지 않는 실행 환경이거나, 설치·업그레이드 직후 첫 세션인 경우 동작이 다를 수 있습니다. 버전을 확인하고 세션을 다시 시작해 보세요.

AGENTS.md는 표준인가요?

공식 표준 문서라기보다 여러 코딩 에이전트가 공통으로 읽어 온 관례에 가깝습니다. 다만 주요 도구들이 이 이름을 지원하기 시작하면서 사실상 공통 진입점 역할을 하고 있습니다. 새 저장소라면 AGENTS.md 하나로 시작하는 것이 이식성 면에서 유리합니다.