Claude Code, 드디어 AGENTS.md 지원 추가

TL;DR Highlight

Claude Code 2.1.277부터 CLAUDE.md가 없으면 AGENTS.md를 읽는다

Who Should Read

여러 AI 코딩 도구를 함께 쓰면서 CLAUDE.md와 AGENTS.md를 따로 관리하느라 번거로운 개발자

Core Mechanics

CLAUDE.md 없으면 AGENTS.md를 읽는다
- Claude Code 버전 2.1.277부터 적용된다.
- 폴더에 CLAUDE.md가 없을 때 Claude가 AGENTS.md를 찾아 사용한다.
/config에서 켜고 끌 수 있다
- 이 동작은 /config에서 토글할 수 있다.
Claude Code mods 기반으로 만들었다
- AGENTS.md 지원은 Claude Code mods를 바탕으로 한다.
- mods는 Claude Code harness(모델을 감싸는 실행 틀)를 커스터마이즈하기 위한 예정된 방식이라고 한다.
내장 mod이고 직접 만들 수도 있다
- AGENTS.md 지원은 built-in mod다.
- 앞으로 프로젝트 지침(project instructions)의 커스텀 버전을 직접 만들 수 있게 된다고 한다.
mod 소스가 공개돼 있다
- 작성자가 GitHub 링크로 해당 mod의 소스를 공개했다.

Community Reactions

How to Apply

Claude Code 버전과 /config 확인하기
- 터미널에서 Claude Code를 2.1.277 이상으로 업데이트한다.
- /config를 열어 AGENTS.md 관련 토글이 켜져 있는지 확인한다.
CLAUDE.md 없는 폴더에서 동작 테스트하기
- AGENTS.md만 있는 저장소에서 Claude Code를 실행한다.
- 규칙을 지키는지 물어 지침이 반영되는지 확인한다.
중복 지침 파일 정리 여부 정하기
- CLAUDE.md와 AGENTS.md 내용이 겹치는 저장소를 찾는다.
- CLAUDE.md가 있으면 AGENTS.md 대신 쓰이므로 둘 중 어느 쪽을 남길지 정한다.

Try It

복사해서 바로 해보기

# Claude Code 터미널에서 실행해서 AGENTS.md 인식 여부 확인 (CLAUDE.md 없는 폴더에서)

{{AGENTS.md에만 적어둔 규칙 1개, 예: 커밋 메시지는 한글로 쓴다}}

지금 이 폴더에서 네가 따르고 있는 프로젝트 지침이 어느 파일에서 왔는지 말하고, 위 규칙을 그대로 인용해줘.

이어서 해 볼 것: /config에서 토글을 끈 뒤 같은 질문을 다시 하고 답이 달라지는지 비교해 본다.

Terminology

AGENTS.mdAI 코딩 에이전트에게 프로젝트 규칙을 알려주는 마크다운 파일이다. 신입에게 주는 온보딩 문서와 비슷하다.

CLAUDE.mdClaude Code가 읽는 프로젝트 지침 파일이다. AGENTS.md의 Claude 전용 버전이라고 보면 된다.

harness모델을 감싸 도구 호출과 지침 로딩을 처리하는 실행 틀이다. 자동차의 엔진이 아니라 차체와 배선에 가깝다.

modsClaude Code harness를 커스터마이즈하기 위해 예고된 방식이다. 플러그인과 비슷하다.