실제로 전송되는 내용
일반 지침 콘텐츠는 완전히 전송됩니다. 설정 명령, 코드 스타일, 테스트 지침, PR 규칙, 아키텍처 제약 조건 등 대부분의 CLAUDE.md 파일의 핵심 내용이 이에 해당하며, AGENTS.md도 마찬가지로 필수 프런트매터(frontmatter)가 없는 마크다운 지침 파일입니다.
항상 켜져 있는(Always-on) 범위가 전송되지만, 도구별로 주의할 점이 있습니다. 루트 레벨의 AGENTS.md는 이를 읽는 도구들에 의해 항상 활성화된 상태로 처리됩니다. Codex는 "작업을 시작하기 전에 AGENTS.md 파일을 읽습니다." Zed는 "개인 및 프로젝트 수준의 에이전트 안내를 위한 기본 지침 파일로 AGENTS.md를 지원합니다." Cursor는 중첩된 하위 디렉터리 지원을 포함하여 AGENTS.md를 ".cursor/rules의 간단한 대안"으로 나열합니다. Devin은 "CLAUDE.md 및 AGENTS.md를 포함하여 코드베이스의 특수 파일을 기반으로 지식(Knowledge)을 자동으로 가져오고 업데이트합니다."
디렉터리 범위 지정은 전송되지만, 작동 방식은 다릅니다. 두 포맷 모두 디렉터리별 파일을 지원합니다. Claude Code는 작업 디렉터리에서 트리 위로 올라가며 찾은 파일을 "파일 시스템 루트에서 작업 디렉터리 방향" 순서로 연결합니다. Codex도 같은 방향으로 체인을 구축합니다. "Codex는 루트에서부터 파일을 연결하며 빈 줄로 구분합니다. 현재 디렉터리에 더 가까운 파일은 결합된 프롬프트에서 나중에 나타나므로 이전 지침을 덮어씁니다." Cursor의 중첩된 AGENTS.md 파일은 "상위 디렉터리와 결합되며, 더 구체적인 지침이 우선권을 갖습니다."
형태는 같지만 세 가지 로더가 다르게 작동합니다. 중첩된 지침은 작동하지만, 우선순위 의미론이 동일할 것이라고 가정하지 마십시오.
하나의 파일, 네 개의 서로 다른 로더
통합하기 전에 알아두어야 할 점은, 각 도구에서 "AGENTS.md를 읽는다"는 의미가 약간씩 다르며, 이 차이에 따라 파일을 구성하는 방법이 결정된다는 것입니다.
Codex는 실행할 때마다 지침 체인을 한 번 빌드합니다. Codex 홈 디렉터리의 글로벌 파일에서 시작하여 프로젝트 루트에서 작업 디렉터리 방향으로 이동하며 디렉터리당 최대 하나의 파일을 가져와 루트에서부터 연결합니다. 또한 전체 체인에 제한을 둡니다. "결합된 크기가 project_doc_max_bytes(기본값 32 KiB)로 정의된 제한에 도달하면 파일 추가를 중단합니다."
Cursor는 루트 AGENTS.md를 설정이 필요 없는 .cursor/rules 대안으로 취급하며, 중첩된 파일은 "상위 디렉터리와 결합되고 더 구체적인 지침이 우선권을 갖습니다."
Zed는 개인 및 프로젝트 범위 모두에서 이를 기본 지침 파일로 사용합니다. 개인용은 ~/.config/zed/AGENTS.md이고, 프로젝트 파일은 "충돌할 때 개인 AGENTS.md를 재정의"합니다. 프로젝트 로더는 목록에서 첫 번째로 일치하는 파일을 가져오므로, 오래된 규칙 파일이 남아 있으면 문제가 될 수 있습니다.
Devin은 이를 지침으로 전혀 로드하지 않고, "CLAUDE.md 및 AGENTS.md를 포함하여 코드베이스의 특수 파일을 기반으로 지식(Knowledge)을 자동으로 가져오고 업데이트합니다." 해당 지식이 세션에 도달하는지 여부는 고정(pinning) 및 트리거 설명에 따라 달라집니다.
네 가지 도구 모두에서 실질적으로 얻을 수 있는 교훈은 동일합니다. 루트 파일은 짧게 유지하고 구체적인 내용은 디렉터리 수준 파일로 밀어 넣는 것입니다. 이렇게 하면 Codex의 제한, Cursor의 우선순위, Zed의 재정의 동작을 동시에 만족시킬 수 있습니다.
이를 연결하는 동안 한 가지 다행스러운 점은 @AGENTS.md 가져오기(import)가 Claude Code의 외부 가져오기 승인 대화 상자를 트리거하지 않는다는 것입니다. 이 대화 상자는 가져오기가 "작업 디렉터리 외부에서 확인될 때" 나타나는데, 리포지토리 루트의 AGENTS.md는 내부에 있으므로 확인 요청 없이 로드됩니다.
전송되지 않는 내용 — 다음 세 가지는 CLAUDE.md를 삭제하지 않고 유지해야 하는 이유입니다.
@path 가져오기. Claude Code의 가져오기 구문은 AGENTS.md에 상응하는 기능이 없습니다.
CLAUDE.local.md. 각 디렉터리의 CLAUDE.md 뒤에 추가되는 커밋되지 않은 개인 메모입니다. 대응하는 기능이 없습니다.
Claude Code가 직접 작성한 모든 내용. 자동 생성된 메모리는 정의상 Claude 전용입니다.
수동 마이그레이션
문서화된 두 가지 경로가 있습니다. Claude 전용 콘텐츠가 필요한지 여부에 따라 선택하십시오.
1단계: 공유 콘텐츠를 AGENTS.md로 이동
리포지토리 루트에 AGENTS.md를 생성하고 설정, 테스트, 스타일, 규칙 등 도구에 구애받지 않는 모든 내용을 이동합니다. 그런 다음 CLAUDE.md에 남은 내용을 읽고 분류합니다. 순수하게 Claude 전용인 지침은 남겨두고 나머지는 모두 제거합니다.
이 작업을 하는 김에, 더 이상 사실이 아닌 부분은 마이그레이션하지 말고 삭제하십시오. 통합은 더 이상 사용하지 않는 서비스에 대해 설명하는 단락을 제거할 수 있는 가장 좋은 기회입니다.
리포지토리에 .cursorrules, .windsurfrules 또는 .clinerules도 있는 경우 지금 함께 통합하십시오. 여러 도구가 AGENTS.md를 기본적으로 읽으며, Zed의 프로젝트 지침 로더는 .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md, GEMINI.md가 포함된 목록에서 첫 번째로 일치하는 파일을 가져옵니다. 따라서 오래된 .cursorrules를 그대로 두면 새로운 AGENTS.md가 완전히 가려질 수 있습니다.
2단계: Claude Code를 동일한 파일에 연결
Anthropic은 두 가지 방법을 문서화했습니다. Claude 전용 추가 사항을 유지할 수 있는 가져오기(import) 버전은 다음과 같습니다.
@AGENTS.md
## Claude Code
`src/billing/` 하위의 변경 사항에는 plan 모드를 사용하십시오.문서에 따르면 "Claude는 세션 시작 시 가져온 파일을 로드한 다음 나머지를 추가합니다." 또는 Claude 전용 콘텐츠를 추가할 필요가 없는 경우 심볼릭 링크를 사용할 수 있습니다.
ln -s AGENTS.md CLAUDE.md공식 문서에서 발췌한 두 가지 확인 사항입니다. "성공 시 명령은 아무런 출력을 인쇄하지 않습니다. 다음 세션에서 /context를 실행하고 CLAUDE.md가 Memory files 아래에 나타나는지 확인하십시오." 그리고 Windows의 경우 "심볼릭 링크를 생성하려면 관리자 권한 또는 개발자 모드가 필요하므로 대신 @AGENTS.md 가져오기를 사용하십시오."
직접 분류하고 싶지 않을 때 유용한 단축 방법이 있습니다. /init은 ".cursor/rules/ 또는 .cursorrules에 있는 Cursor 규칙과 .github/copilot-instructions.md에 있는 Copilot 규칙을 읽고 관련 부분을 생성된 CLAUDE.md에 통합합니다. CLAUDE_CODE_NEW_INIT=1이 설정되면 /init은 AGENTS.md, .devin/rules/, .windsurf/rules/ 또는 .windsurfrules, 그리고 .clinerules도 읽습니다." 방향에 유의하십시오. 이는 다른 파일로부터 CLAUDE.md를 생성하는 것으로, 여기서 원하는 방향과는 반대이지만 분류하기 전에 누적된 모든 내용을 한곳에서 확인하는 가장 빠른 방법입니다.
그런 다음 크기 예산을 확인하십시오. Codex는 "결합된 크기가 project_doc_max_bytes(기본값 32 KiB)로 정의된 제한에 도달하면 파일 추가를 중단"하며, 제한에 도달하면 제한을 늘리거나 중첩된 디렉터리로 분할할 것을 권장합니다. Claude Code의 지침에 따르면 파일이 길어질수록 더 많은 컨텍스트를 소비하고 준수율이 떨어집니다. 하나의 통합된 파일이 목표이지, 하나의 거대한 통합 파일이 목표는 아닙니다.
더 나은 방법: 파일은 작게 유지하고 지식은 검색 가능하게 만들기
통합하면 세 개 대신 하나의 파일을 얻게 됩니다. 하지만 파일이 잘하는 역할이 바뀌지는 않습니다. 지침 파일은 프로젝트의 추론 과정을 담는 것이 아니라 방향성을 제시하는 데 적합합니다.
위의 모든 로더는 매 실행마다 항상 켜져 있는 콘텐츠를 컨텍스트에 연결합니다. 이것이 바로 크기 제한이 존재하는 이유입니다. 따라서 에이전트가 가장 잘 알기를 바라는 부분(아키텍처가 왜 그렇게 설계되었는지, 이미 시도했다가 포기한 접근 방식은 무엇인지, 특이한 결정이 옳았던 제약 조건 등)은 매 요청마다 함께 전송되는 파일에 포함되어서는 안 되는 부분들입니다.
이것이 바로 MemoryLake가 보관하는 것입니다. 도구가 읽을 수 있는 레이어에 지속적인 프로젝트 지식을 보관하므로, AGENTS.md는 짧게 유지되고 추론 과정은 계속 사용할 수 있습니다. 설정은 3단계로 진행됩니다.
1단계: API 키 생성
MemoryLake에 로그인하고 API 키를 생성합니다. 연결하는 도구 전체에서 하나의 자격 증명만 사용하면 됩니다.
2단계: 첫 번째 메모리 업로드
CLAUDE.md를 분류하다 보면 두 파일 모두에 속하지 않는 세 번째 묶음을 발견하게 될 것입니다. 이를 하나의 주장당 하나의 짧은 항목으로 작성하십시오.
결정을 내리게 한 제약 조건이 포함된 결정 사항. "결제 대행사가 멱등성 키 없이 재시도하므로 쓰기 작업은 outbox 테이블을 거칩니다." 규칙은 전반부만 명시하지만, 이 버전만이 대안이 다시 제안되는 것을 방지합니다.
이미 배제된 접근 방식. 가장 가치 있는 범주이자 리포지토리 그 어디에도 존재하지 않는 내용입니다.
교차 리포지토리 지식. 소유한 모든 프로젝트에 적용되는 도메인 어휘 및 표준입니다. AGENTS.md는 설계상 리포지토리별로 적용되지만, 이는 그렇지 않습니다.
두 번 이상 수정한 사항. 두 번 이상 언급했다면 누락된 항목이 있는 것이며, 그 이유가 옆에 함께 기재되어야 합니다.
3단계: AI 및 에이전트 연결
사용하는 도구를 연결합니다. MemoryLake는 MCP 및 API를 통해 액세스할 수 있으므로, Claude Code, Codex, OpenClaw를 포함한 MCP 네이티브 에이전트는 MCP 서버를 가리켜 연결하고, 다른 어시스턴트는 API를 통해 동일한 메모리를 읽습니다.
솔직한 세 가지 한계가 있습니다. MemoryLake는 AGENTS.md를 대체하지 않습니다. 여전히 해당 파일이 필요하며, 위의 통합 작업은 그 자체로 가치가 있습니다. 또한 사용자가 직접 또는 에이전트가 작성한 내용만 보관하므로 2단계는 수동으로 진행됩니다. 그리고 지침 파일은 강제된 설정이라기보다는 컨텍스트에 가까우며, 메모리 레이어도 이를 바꾸지는 못합니다.
실제 변화하는 점
하나의 파일로 정확성이 유지됩니다. 서로 어긋나던 세 개의 사본이 하나로 합쳐지고, AGENTS.md를 기본적으로 읽는 도구들이 도구별 연결 작업 없이 이를 자동으로 인식합니다.
Claude Code가 계속 작동합니다. @AGENTS.md 가져오기는 문서화되어 있고, 한 줄이며, 되돌릴 수 있습니다. 표준과 기존 설정 중 하나를 선택해야 하는 고민이 사라집니다.
크기 제한이 더 이상 문제가 되지 않습니다. 32 KiB는 방향성을 제시하기에는 넉넉하지만 지식 베이스를 담기에는 부족합니다. 이러한 역할을 분리함으로써 제한을 넘지 않게 유지할 수 있습니다.
오래된 규칙 파일이 새 파일을 가리는 일이 발생하지 않습니다. Zed가 목록에서 첫 번째로 일치하는 파일을 가져온다는 사실을 알고 나면, .cursorrules를 삭제하는 것이 3주 후에 발생할 미스터리한 문제를 방지하는 마이그레이션의 일부가 됩니다.
새로운 도구를 도입하는 데 비용이 들지 않습니다. 목록에 있는 대부분의 도구는 이미 AGENTS.md를 읽으며, 그렇지 않은 도구는 MCP를 통해 메모리 레이어를 읽습니다. 이 형태는 Cursor와 Claude Code 간에 하나의 메모리 공유하기에서 다루고 있습니다.
통합 지침 파일을 위한 모범 사례
공유 콘텐츠는 AGENTS.md에 넣고, Claude 전용 콘텐츠는 가져오기(import) 아래에 넣으십시오. 이것이 문서화된 패턴이며 diff를 읽기 쉽게 유지해 줍니다.
통합이 완료되면 .cursorrules 및 .windsurfrules를 삭제하십시오. 그렇지 않으면 첫 번째 일치 로더가 오래된 파일을 선택할 수 있습니다.
Claude 전용 지침이 있는 경우 심볼릭 링크 대신 가져오기를 사용하십시오. Windows에서는 지침 유무와 관계없이 가져오기를 사용하십시오.
/context로 확인하십시오. 막연히 가정하지 말고 다음 세션에서 CLAUDE.md가 Memory files 아래에 나타나는지 확인하십시오.
제한 이하로 유지하고, 크기가 커지면 디렉터리별로 분할하십시오. Codex의 기본값은 전체 체인에 걸쳐 32 KiB입니다. 중첩된 파일은 제한 내에 유지하기 위해 문서화된 방법입니다.
문서를 직접 붙여넣지 마십시오. 참조하십시오. 코드가 변경됨에 따라 복사본은 오래된 정보가 됩니다. 이는 에이전트가 작성된 지침 파일을 무시하는 이유의 핵심 논점입니다.
git에 커밋하십시오. 그래야 통합된 파일이 개인의 자산이 아닌 팀의 자산이 됩니다.
이유(reason)는 파일에서 제외하고 검색 가능한 레이어에 보관하십시오. 방향성은 AGENTS.md에, 논거는 메모리에 둡니다. 이러한 분리를 통해 파일을 실제로 준수할 수 있을 만큼 작게 유지할 수 있습니다.
결론
AGENTS.md는 평범함 덕분에 승리했습니다. 6만 개 이상의 리포지토리와 대부분의 주요 에이전트가 이미 읽고 있는, 예측 가능한 이름을 가진 개방형 마크다운 파일입니다. 이 파일로 통합하면 세 파일이 서로 어긋나는 문제를 해결할 수 있으며, AGENTS.md 대신 CLAUDE.md를 읽는 주목할 만한 도구인 Claude Code는 @AGENTS.md 가져오기를 통한 문서화된 한 줄의 연결 방법이 있거나, Claude 전용으로 추가할 내용이 없다면 심볼릭 링크를 사용할 수 있습니다.
통합이 해결하지 못하는 것은 지침 파일의 원래 목적이 아니었던 부분입니다. 모든 로더는 매 요청마다 항상 켜져 있는 콘텐츠를 전송하므로 모두 크기 제한이 있습니다. 따라서 공유 지침은 AGENTS.md로 이동하고, Claude 전용 줄은 가져오기 아래에 유지하며, 오래된 규칙 파일은 삭제하고, 결정 사항, 제약 조건, 거부된 접근 방식은 에이전트가 쿼리할 수 있는 레이어에 두십시오. 실제로 준수되는 하나의 짧은 파일이 잘려 나가는 하나의 긴 파일보다 낫습니다.