Claude Code도 AGENTS.md를 읽습니다, 기존 프로젝트 규칙은 어떻게 옮길까요?

핵심 요약 (TL;DR)

AI 코딩 도구를 바꿀 때마다 같은 프로젝트 설명을 다시 적는 일은 번거롭습니다. Claude Code 2.1.277에는 AGENTS.md를 읽는 지원이 추가됐습니다. 한국시간 9월 19일 공개된 공식 릴리스의 조건은 분명합니다. 프로젝트에 CLAUDE.md가 없을 때 AGENTS.md를 대신 읽으며, 설정은 /config의 Project instructions에서 바꿀 수 있습니다. 두 파일을 자동으로 합쳐 읽는 기능으로 이해하면 안 됩니다.

파일 이름만 바꾸면 모든 도구가 같은 규칙을 따를까요?

그렇지는 않습니다. 이번 변화는 Claude Code가 특정 조건에서 새 지침 파일을 읽는다는 발표입니다. 다른 도구와 파일 탐색 범위, 지침 우선순위, 세부 동작까지 같아졌다는 의미는 아닙니다. 공식 릴리스는 Bedrock, Vertex, Foundry에서는 아직 지원하지 않는다고 명시합니다. 같은 Claude Code라는 이름을 쓰더라도 연결 환경부터 확인해야 합니다.

기존 CLAUDE.md가 있는 프로젝트라면 AGENTS.md를 추가하는 것만으로 전환됐다고 생각하지 마세요. 두 파일에 서로 다른 작업 규칙을 쓰면 사람도 어느 것이 기준인지 헷갈리기 쉽습니다. 파일의 존재와 실제로 선택되는 지침을 따로 확인하는 일이 첫 단계입니다. 이 글은 공식 발표를 읽고 정리한 안내이며, 각 환경에 설치해 비교한 결과는 아닙니다.

기존 프로젝트를 옮기기 전에 무엇을 남겨야 할까요?

먼저 기존 지침을 보관하고, 지금 필요한 규칙과 오래된 작업 메모를 나눠 보세요. ‘고객 데이터는 테스트에 쓰지 않는다’는 계속 남길 원칙이지만, ‘어제 발생한 오류를 고친다’는 현재 작업 티켓에 더 가깝습니다. 파일을 공유하기 전에 무엇을 공유할지 정해야 도구마다 낡은 지시를 반복하는 일을 줄일 수 있습니다.

다음으로 사람이 읽을 기준 원본을 정하세요. 여러 도구를 함께 쓴다면 공통 규칙과 특정 도구에서만 필요한 설정을 구분합니다. 공통 문서에는 프로젝트 목적, 실행·테스트 방법, 변경하면 안 되는 범위처럼 다른 도구에서도 의미가 통하는 내용을 둡니다. 특정 도구의 기능을 일반 규칙처럼 적지는 않는 편이 좋습니다.

초보자의 첫 AGENTS.md에는 무엇이 들어가면 좋을까요?

바이브코딩 시작하는 방법을 찾는다면 긴 규칙집보다 완료 장면부터 적어 보세요. 메모 앱이라면 ‘새 메모를 저장한 뒤 다시 열었을 때 같은 내용이 보여야 한다’가 좋은 기준입니다. 여기에 ‘요청하지 않은 화면은 바꾸지 않는다’, ‘실제 실행하지 않은 테스트를 통과했다고 쓰지 않는다’처럼 검토할 수 있는 약속을 더할 수 있습니다. 이는 제품의 기본 제공 규칙이 아니라 작성 예시입니다.

전환 뒤에는 작은 변경 하나로 확인하세요. AI에게 어떤 지침을 기준으로 작업했는지 설명하게 하고, 실제 변경 파일과 테스트 결과를 대조합니다. 지침을 읽었다는 답변만으로 성공을 판단하지 않는 것이 중요합니다. 결과가 다르면 규칙을 계속 덧붙이기보다 선택된 파일과 설정부터 되짚어 보세요.

FAQ: CLAUDE.md는 지금 지워도 되나요?

발표만 보고 지울 필요는 없습니다. 원본을 보관하고 기존 설정과 필요한 규칙을 확인한 뒤 전환하세요. 이번 릴리스의 기본 설명은 CLAUDE.md가 없을 때 AGENTS.md를 대신 읽는다는 것입니다.

FAQ: 규칙을 적으면 잘못된 수정이 막히나요?

지침 파일은 실행 권한이나 자동 검증 장치와 다릅니다. 파일이 있어도 중요한 데이터 변경과 배포는 별도의 승인·테스트가 필요합니다.

출처: https://github.com/anthropics/claude-code/releases/tag/v2.1.277
발표 시각 확인: https://api.github.com/repos/anthropics/claude-code/releases/tags/v2.1.277
관찰 시점: 2026-09-20 KST.