저장소에 AGENTS.md와 CLAUDE.md가 모두 있는 경우, Claude Code가 AGENTS.md를 무시할 수 있습니다

저는 이 문제를 발견했는데, 기존에 Cursor와 Codex용으로 사용하던 AGENTS.md 옆에 짧은 CLAUDE.md 파일을 추가한 후였습니다. Claude Code 세션에서 공유 명령과 '먼저 질문하기(ask first)' 목록을 더 이상 인식하지 못했습니다. 파일 자체는 문제가 없었습니다. 단지 로드되지 않았던 것입니다.

Claude Code의 메모리 문서(https://code.claude.com/docs/en/memory)에 따르면, 기본적으로 작업 디렉토리 또는 그 상위 디렉토리에 CLAUDE.md, .claude/CLAUDE.md, 또는 CLAUDE.local.md가 없는 경우에만 AGENTS.md를 읽는다고 합니다. 개인적이며 종종 gitignore되는 CLAUDE.local.md도 포함되므로, 팀원들은 괜찮더라도 자신을 위해 파일을 숨길 수 있습니다.

한 줄짜리 해결책은 CLAUDE.md의 1번째 줄에 @AGENTS.md를 넣는 것입니다. 이것은 실제 임포트(import)입니다. 단순히 "please also read AGENTS.md"라고 적는 문장은 아닙니다. Claude가 스스로 결정할 때만 열기 때문입니다. 그런 다음 /memory 또는 /context all을 실행하여 두 파일이 모두 표시되는지 확인하십시오.

제가 공유된 AGENTS.md에 넣고, Claude의 스텁(stub)에서는 제외하는 내용들은 다음과 같습니다:

• 실제 명령 (예: "테스트를 실행하라"가 아닌 pnpm test path/to/file)
• 완료 정의(Definition of done): 타입 체크(/lint / tests) 또는 테스트가 실제로 실행되었는지 여부
• 먼저 질문해야 하는 경계(Ask-first boundaries): 인증(auth), 결제(payments), 배포(deploy) 등 프로덕션에 영향을 주는 모든 것
• 주의사항 목록(Gotchas list): 에이전트가 같은 실수를 두 번 할 때만 제가 추가하는 항목들

저는 다단계 작업(PR 검토, 불안정한 테스트 탐색, 인계 메모)은 AGENTS.md에서 제외하고 있습니다. 그래야 모든 세션에 주입되지 않기 때문입니다. Cursor는 여전히 파일 범위 규칙을 위해 .mdc 규칙을 사용하며; Codex는 AGENTS.md만 보기 때문에, 이 세 가지 도구가 모두 필요로 하는 것은 그곳에 존재해야 합니다.

Cursor, Claude Code, 그리고 Codex 사이를 오갈 때 어떻게 하나의 진실 공급원(source of truth)을 유지하는지 다른 분들은 궁금합니다. 임포트하고 계신가요, 심링크(symlinking)를 사용하시나요, 아니면 단순히 두 파일을 유지하고 계신가요?