지시서 파일이 두 개가 됐다

무엇이 바뀌었나

확인 Claude Code 2.1.277(9월 18일) 변경 로그에 한 줄로 적혀 있다 — CLAUDE.md 가 없는 프로젝트에서는 AGENTS.md 를 대신 읽는다. 바꾸는 자리는 /config 의 Project instructions 다. (Bedrock · Vertex · Foundry 에서는 아직 안 된다고 같이 적혀 있다.)

확인 공식 문서에 표로 정리돼 있다. 내 폴더에 무엇이 있느냐로 갈린다.

확인 세는 파일과 안 세는 파일이 따로 있다. 이게 제일 헷갈리는 자리다. 작업 폴더나 그 위쪽의 CLAUDE.md · .claude/CLAUDE.md · CLAUDE.local.md 는 센다 — 하나라도 있으면 AGENTS.md 는 안 읽힌다. 반대로 ~/.claude/CLAUDE.md(내 전역 지시서), 조직 관리 CLAUDE.md, .claude/rules/ 는 안 센다 — 이것들은 AGENTS.md 와 같이 올라온다.

확인 읽혔는지 눈으로 볼 수 있는 줄이 있다. 대화창에 이렇게 뜬다 — no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md. 이 줄이 사실상 유일한 확인 수단이다. 문서에 따르면 AGENTS.md 는 /memory 목록에도, /context 의 Memory files 목록에도 안 뜬다.

확인 안 읽는 파일도 못 박혀 있다. AGENTS.local.md, AGENTS.override.md, .agents/ 폴더 아래는 읽지 않는다. 하위 폴더의 AGENTS.md 는 Claude 가 그 폴더의 파일을 열 때 같이 올라온다.

확인 AGENTS.md 자체는 Anthropic 이 만든 형식이 아니다. 코딩 에이전트용 공개 형식이고, 지금은 리눅스 재단 산하 Agentic AI Foundation 이 관리한다. 공개 저장소 6만 개 이상이 쓰고 있고 도구 30종 이상이 읽는다. 정해진 항목은 없다 — 그냥 마크다운이다.

추정 그래서 이번 변경의 실제 수혜자는 도구를 두 개 이상 번갈아 쓰는 사람일 것이다. 한 도구만 쓰는 사람에게는 파일 이름이 하나 늘어난 것에 가깝다. 문서에 그런 구분은 없다. 써 보고 판단할 일이다.

확인 못 함 데스크톱 앱과 VS Code 확장에서도 같은 규칙으로 도는지는 문서에서 찾지 못했다. 한국어 화면에서 Project instructions 가 어떤 말로 표기되는지도 확인하지 못했다. 여기는 적지 않고 비워 둔다.

왜 중요한가

교육 과정 L2 · 06 에서 고칠 자리가 하나면 틀릴 자리도 하나라고 적었다. 지시서 파일은 그 원칙이 제일 잘 깨지는 자리다. CLAUDE.md 에 한 번, AGENTS.md 에 한 번 적어 두고 한쪽만 고치는 일이 반복된다.

이번 변경은 그 두 개를 하나로 줄일 수 있게 해 준다. 다만 저절로 하나가 되는 건 아니다. 위 표대로 내 폴더 상태에 따라 읽히는 쪽이 달라진다. 그래서 줄이기 전에 지금 무엇이 읽히고 있는지부터 봐야 한다 (L2 · 04).

확인 Claude Code 는 터미널에서 돌리는 도구다. 처음이면 STEP 15 부터 보는 쪽이 빠르다. 무료 플랜에서는 안 된다 — Pro 이상이 필요하다.

직접 해 보기 — 10분

1. 버전을 본다. 이 기능은 2.1.277 부터다.

   claude --version

   낮게 나오면 claude update. 올린 직후 첫 세션은 아직 안 읽는다 — 문서에 그렇게 적혀 있다. 한 번 끄고 다시 켠 세션부터 읽는다.
2. 지금 무엇이 있는지 센다. 작업 폴더에서 한 줄이면 된다.

   ls -a CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md AGENTS.md 2>/dev/null
   
   # Windows PowerShell
   dir CLAUDE.md, .claude\CLAUDE.md, CLAUDE.local.md, AGENTS.md -ErrorAction SilentlyContinue

   위쪽 폴더도 본다. 상위 폴더에 하나 있으면 그게 이긴다.
3. 읽혔는지 화면에서 확인한다. claude 를 띄우고 대화창 위쪽에 AGENTS.md loaded: 줄이 뜨는지 본다. 안 뜨면 이렇게 물어보면 된다.

   지금 네 프로젝트 지시서에 무엇이 들어 있는지
   그대로 적어 줘. 어느 파일에서 온 것인지도 같이.

4. 둘 다 읽게 바꾼다. /config → Project instructions → claude-md-and-agents-md. 같은 폴더의 CLAUDE.md 가 먼저, AGENTS.md 가 그 뒤에 올라온다. 이미 불러온 것은 두 번 안 읽는다.
5. 파일로 고정한다. 매번 /config 를 누르기 싫으면 ~/.claude/settings.json 에 적어 둔다.

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

   고치기 전에 그 파일을 복사해 둔다 — L2 · 05. 프로젝트 설정 파일에 적으면 무시된다. 사용자 설정에 적어야 한다.

한 줄 정리

1. 2.1.277 부터, CLAUDE.md 가 없으면 AGENTS.md 를 읽는다.
2. 확인은 AGENTS.md loaded: 줄 하나뿐이다 — /memory 에는 안 뜬다.
3. 둘 다 읽히게 하려면 /config → Project instructions → claude-md-and-agents-md.