Claude Code, CLAUDE.md 없으면 AGENTS.md를 읽는다

Who Should Read

Codex·Cursor 등과 Claude Code를 함께 쓰면서 CLAUDE.md 심볼릭 링크를 따로 관리하던 개발자

Core Mechanics

• CLAUDE.md 없으면 AGENTS.md 읽는다
  • 2.1.277(2026년 9월 18일) 변경 기록에 'AGENTS.md support'로 추가됐다.
  • CLAUDE.md가 없는 프로젝트에서 AGENTS.md를 대신 읽는다.
• 설정에서 바꿀 수 있다
  • /config의 'Project instructions' 항목에서 동작을 바꾼다.
  • Bedrock, Vertex, Foundry에서는 아직 지원하지 않는다고 적혀 있다.
• 이번 페이지는 2.1.304 릴리스 노트다
  • 2.1.304(2026년 10월 19일)에는 /auto-mode-setup 추가, 도구 검색(tool search) 기본값 변경 등이 담겼다.
  • 2.1.302에는 CLAUDE_CODE_AUTO_MODE_MODEL 환경변수가 추가됐다.
• 컨텍스트 관련 수정도 함께 들어갔다
  • 자체 페이스(self-paced) /loop 깨우기가 1시간 프롬프트 캐시 만료 직후에 실행되던 문제를 고쳤다.
  • 압축(compaction) 후 스킬 목록을 다시 보내도록 바꿨고, /reload-skills는 새로 바뀐 스킬만 보낸다.

Community Reactions

• AGENTS.md 실사용 불만이 나왔다
  • Claude Code가 AGENTS.md와 CLAUDE.md를 system-reminder로 감싸고 '관련 있을 때만 반응하라'는 문구를 붙인다는 의견이 있었다.
  • 그래서 Codex가 AGENTS.md를 훨씬 잘 따른다는 경험이 공유됐고, 관련 이슈(anthropics/claude-code#18560)가 Not Planned로 닫혔다고 했다.
• skills 폴더는 아직 안 읽는다
  • 이번 변경에 .agents/skills는 포함되지 않는다는 지적이 여러 번 나왔다.
  • Shopify CEO가 이를 두고 Claude Code 금지를 언급했다는 기사 링크가 공유됐다.
• 기존 우회법이 있었다
  • CLAUDE.md에 '@AGENTS.md' 한 줄만 넣어 쓰면 잘 됐다는 경험이 있었다.
  • CLAUDE.md를 AGENTS.md 심볼릭 링크로 두는 방법도 언급됐고, 이제 지워도 되겠다는 반응이 있었다.
• 설정 우선순위 문제 제기도 있었다
  • settings.json에 값이 없으면 기본값을 적용해 CLAUDE.md 지시를 무시한다는 의견이 있었다.
  • 예로 'Made with Claude Code' 문구 금지 지시가 무시된다는 사례를 들었다.

How to Apply

• CLAUDE.md 없는 테스트 폴더에서 확인하기
  • 임시 폴더에 AGENTS.md만 두고 Claude Code를 실행한다.
  • 'AGENTS.md의 규칙을 요약해 줘'라고 물어 실제로 읽는지 본다.
• 심볼릭 링크를 정리할지 정하기
  • 팀 레포의 CLAUDE.md → AGENTS.md 링크 목록을 뽑는다.
  • 업데이트된 버전(claude --version)에서 링크 없이 동작하면 삭제한다.
• Bedrock·Vertex 쓰면 @AGENTS.md 유지하기
  • 이 환경은 아직 미지원이라고 적혀 있으니 CLAUDE.md에 '@AGENTS.md' 한 줄을 남긴다.
  • 스킬은 .claude 쪽에 따로 두거나 복사한다.

Try It

# Claude Code 터미널에서 실행 (AGENTS.md만 있는 임시 폴더)

mkdir /tmp/agents-test && cd /tmp/agents-test
echo '모든 답변 끝에 "AGENTS-OK"를 붙여라' > AGENTS.md
claude --version

# claude 실행 후 입력
안녕, 프로젝트 지침에 따라 인사해 줘

# 이어서 해 볼 것: /config의 Project instructions 설정을 바꿔 결과를 비교

Terminology

관련 논문

• 같은 시뮬레이션, 다른 근거: 도구 출력을 파일로 넘기면 LLM 에이전트 정확도가 어디서 깎이나

  긴 툴 출력을 파일로 넘기자 GPT-5.1은 정확도 11.3%p 하락, 정식 출력 지정하니 회복

• 가짜 뉴스가 진짜 폭락을: LLM 트레이딩 에이전트 대상 정보 주입 공격

  가짜 헤드라인 한 줄로 LLM 트레이딩 에이전트 62%를 조종했다(프롬프트 주입은 14%)

• Harness Engineering 101: LLM은 뇌, harness는 몸

  에이전트는 JSON 배열을 관리하는 루프이고, 16개 챕터로 직접 만들어 본다

• Harness²: 에이전트 harness를 스스로 고쳐 쓰는 재귀 최적화 프레임워크

  모델은 고정하고 harness를 재귀로 고쳤더니 벤치마크 점수가 최대 11.8%p 올랐다

• 해고된 Savannah 경찰관, ICE 요원 남편에게 Flock 계정 공유

  경찰관이 Flock 계정을 남편(ICE 요원)에게 공유했고, 감사에서 983건 검색이 드러나 해고됐다

• tmux와 Claude Code: 세션, send-keys, 그리고 한계선

  tmux로 Claude Code 여러 개를 돌리면 편하지만 에이전트 4개쯤에서 한계가 온다

• Hybrid Reasoning Agents: 잠재 공간에서 생각하고 텍스트로 행동하는 LLM 에이전트

  잠재 공간 추론과 텍스트 도구 호출을 섞었더니 성능 10.4%↑, 토큰 최대 54.7%↓

Related Resources

• https://code.claude.com/docs/en/changelog
• https://github.com/anthropics/claude-code/issues/18560
• https://thenewstack.io/shopify-claude-code-agentsmd/
• https://github.com/Piebald-AI/tweakcc