Claude Code, 프로젝트 지침을 위한 AGENTS.md 대체 파일 지원 추가

Claude Code, 이제 CLAUDE.md가 없으면 AGENTS.md를 읽습니다 – 오랫동안 기다려온 표준 준수 업데이트

Claude Code 2.1.277(2026년 9월 18일 출시)은 작지만 영향력 있는 기능을 추가했습니다. 프로젝트 디렉토리에 CLAUDE.md 파일이 없는 경우, CLI는 자동으로 AGENTS.md를 읽어 지침 세트로 사용합니다. 이 변경 사항은 /config의 Project instructions에서 설정할 수 있으며, 아직 Bedrock, Vertex 또는 Foundry 배포 환경에서는 사용할 수 없습니다.

이 업데이트가 중요한 이유

표준 준수 구성 – AGENTS.md는 에이전트, 기술 및 프로젝트 수준의 프롬프트를 설명하기 위한 사실상의 커뮤니티 관례입니다. Claude Code가 이를 기본적으로 지원함으로써, 사용자가 중복 파일이나 심볼릭 링크를 유지해야 했던 독점적인 방식의 불편함이 해소되었습니다.
마찰 감소 – 개발자들은 이제 하위 호환성을 위해 유지해왔던 CLAUDE.md → AGENTS.md 심볼릭 링크를 삭제할 수 있습니다. 이미 AGENTS.md(또는 최신 .agents/ 레이아웃)를 사용하는 프로젝트는 추가 작업 없이 바로 작동합니다.
대응력의 신호 – 이번 업데이트는 더 넓은 AI 도구 표준과의 정렬을 요구하는 커뮤니티의 피드백을 반영한 결과입니다. 이는 Anthropic이 자체적인 파일 명명 규칙을 강요하기보다 개발자의 의견을 경청하고 있음을 보여줍니다.

변경 로그 내용

AGENTS.md 지원 추가: CLAUDE.md가 없는 프로젝트에서 Claude Code는 대신 AGENTS.md를 읽습니다. /config의 “Project instructions”에서 변경 가능합니다(Bedrock, Vertex, Foundry에서는 아직 지원되지 않음)

이 기능은 순수하게 읽기 전용 대체 기능입니다. .agents/skills 또는 기타 사용자 지정 디렉토리에서 기술을 검색하는 방식은 변경되지 않습니다. 단지 CLAUDE.md가 없을 때 시스템 프롬프트의 소스를 교체할 뿐입니다.

Hacker News의 커뮤니티 반응

댓글 작성자	반응	주요 내용
@askonomm	긍정적	“사용자에게 독점적인 워크플로우를 강요하는 대신 드디어 표준을 준수하는 작업을 하네요.”
@neverrroot	긍정적	“고마워요, 올바른 일을 하셨네요.”
@bcorigliano	긍정적	“드디어!! 업계 전반의 표준이 필요합니다.”
@stillpointlab	관찰적	Claude Fable이 이미 `AGENTS.md`와 심볼릭 링크를 생성한다는 점을 언급하며, 이번 변경이 자동 프로젝트 스캐폴딩으로 인해 촉발되었을 가능성을 제기함.
@TomGarden	혼합적	움직임은 높게 평가하지만 “최소한의 기본 조치”라고 평하며 기존 심볼릭 링크를 삭제함.
@mococa	비판적	이번 변경은 개발자를 위한 진심 어린 배려라기보다 커뮤니티의 분노에 대한 반응일 뿐이라고 주장함.
@mitchitized	비판적	최신 로직이 `CLAUDE.md`보다 `settings.json`을 우선시하여 사용자가 제공한 지침을 무시할 가능성이 있다고 주장함.
@aroman	실용적	“드디어 `AGENTS.md`를 `GEMINI.md`와 `CLAUDE.md`로 재귀적으로 심볼릭 링크하던 `sync-agent-docs.sh`를 삭제할 수 있게 되었네요…”
@bluestein	유머러스	“`AGENTS.md`는 새로운 autoexec.bat이군요.”
@chr15m	긍정적	“애플이 USB-C로 전환한 것처럼, 이건 그냥 당연하고 합리적인 일입니다.”
@perganomoly	부정적	“이렇게 기본적인 기능을 추가하는 데 이만큼이나 걸렸다는 사실이 수치스럽네요.”

전반적으로 커뮤니티는 이번 변경을 획기적인 혁신이라기보다는 필요한 수정으로 보고 있습니다. 많은 사용자가 더 이상 심볼릭 링크가 필요 없다는 점에 안도감을 표했지만, 일부는 여전히 Anthropic의 의도에 대해 회의적인 반응을 보이고 있습니다.

새로운 대체 기능 사용 방법

AGENTS.md가 프로젝트 루트에 있는지 확인합니다(또는 Claude Code가 프로젝트 지침을 검색하는 하위 디렉토리에 위치해야 합니다).
이전에 AGENTS.md를 가리키는 포인터로 사용했던 CLAUDE.md 파일이나 심볼릭 링크를 제거합니다.
검색 위치를 사용자 지정해야 하는 경우, /config 파일의 Project instructions 섹션을 편집합니다:
```
{
  "projectInstructions": {
    "fallbackFile": "AGENTS.md"
  }
}
```
claude --version을 실행하여 2.1.277 버전 이상인지 확인합니다.

변경되지 않는 점

기술 로딩 – Claude Code는 여전히 .agents/skills 디렉토리에서 기술을 자동으로 로드하지 않습니다. 이는 별도의 기능 요청으로 남아 있습니다.
Bedrock/Vertex/Foundry – 이 대체 기능은 현재 해당 플랫폼에서 사용할 수 없으며, 여전히 CLAUDE.md가 필요합니다.
기존 프로젝트 – 두 파일이 모두 포함된 프로젝트는 CLAUDE.md를 삭제하지 않는 한 계속해서 CLAUDE.md를 우선시합니다.

결론

Claude Code가 AGENTS.md를 대체 지침 파일로 추가한 것은 오랫동안 지속된 불편함을 해소하고, 도구를 커뮤니티 관례에 맞추며, 개발자 피드백에 기반하여 적응하려는 Anthropic의 의지를 보여줍니다. 이번 변경은 소소하지만, 사용성과 표준 준수 측면에서 확실한 승리입니다.