AGENTS.md 지원, 코딩 에이전트 운영 바꾸기

[!IMPORTANT] 한 줄 브리핑: Claude Code가 Claude.md가 없을 때 AGENTS.md를 읽도록 바뀌면서, 저장소별 지침 파일을 통합하고 도구 간 규칙 중복을 줄일 기회가 생겼습니다.
분야: IT/AI/Security

30초 요약

Claude Code 변경 로그에는 Claude.md가 없는 경우 AGENTS.md를 읽는 동작이 추가됐다고 기록돼 있습니다. Claude Code 변경 로그
이 변화의 핵심은 파일 하나를 더 읽는다는 데 있지 않습니다. 여러 코딩 에이전트가 공유하는 저장소 지침을 도구별 복사본 대신 공통 파일로 관리할 수 있는지가 핵심입니다.
다만 입력 자료에는 변경 사항의 정확한 적용 버전, 하위 디렉터리 탐색 규칙, 기존 CLAUDE.md와 AGENTS.md가 동시에 있을 때의 우선순위가 충분히 설명돼 있지 않습니다. 조직 표준으로 확정하기 전에는 사용 중인 버전에서 직접 확인해야 합니다.
실무적으로는 기존 지침 파일을 곧바로 삭제하기보다, 작은 저장소에서 AGENTS.md를 기준 파일로 만들고 Claude Code의 실제 읽기 여부를 검증하는 방식이 안전합니다.

확인된 사실

Claude Code 변경 로그에 AGENTS.md 관련 동작이 반영됐다

제공된 원문 제목과 변경 로그에는 Claude Code가 Claude.md가 없을 때 AGENTS.md를 읽는다는 내용이 나타납니다. 이는 적어도 해당 변경 로그 기준으로, AGENTS.md가 존재하더라도 Claude Code가 항상 무시하는 상태에서 벗어났다는 뜻입니다. Claude Code 변경 로그

여기서 주의할 점은 파일 이름 표기입니다. 원문 제목은 Claude.md라고 쓰지만, 개발 현장에서는 CLAUDE.md라는 표기도 널리 사용됩니다. 입력 자료만으로는 두 표기가 동일한 대소문자 규칙을 의미하는지, 문서 원문에서 어떤 정확한 파일명을 기준으로 하는지 단정할 수 없습니다. 저장소에 파일을 만들 때는 사용 중인 Claude Code 문서와 운영체제의 대소문자 처리 방식을 함께 확인해야 합니다.

AGENTS.md는 도구 간 공유 지침 파일로 다뤄지고 있다

Lockstep의 설명은 AGENTS.md를 AI 코딩 에이전트용 핸드북으로 보고, 복사해 실행할 수 있는 명령어, 반드시 지켜야 하는 불변 조건, 작업 경계를 넣으라고 제안합니다. 반대로 유효기간이 짧은 공지나 최신 의사결정은 정적 파일만으로 전달하기 어렵다고 설명합니다. Lockstep의 AGENTS.md 작성 가이드

이 자료는 특정 에이전트의 공식 사양이라기보다 파일을 어떻게 운영할지에 대한 실무 분석입니다. 따라서 AGENTS.md에 무엇을 넣을지 판단하는 참고 자료로는 쓸 수 있지만, Claude Code가 어떤 위치의 파일을 어떤 순서로 읽는지 확인하는 근거로 확대해서는 안 됩니다.

기존 논쟁은 파일 지원보다 운영 부담에 가까웠다

Hacker News의 관련 게시물에는 Claude Code가 AGENTS.md를 기본적으로 읽지 않는 문제에 대한 개발자들의 의견이 모여 있습니다. 댓글에는 다른 코딩 도구와 호환하기 위해 AGENTS.md와 Claude용 지침 파일을 연결하거나 심볼릭 링크로 묶었다는 사례가 등장합니다. Hacker News 토론

이 내용은 커뮤니티 경험과 의견의 기록이지, 모든 환경에서 재현되는 제품 동작의 공식 검증 결과는 아닙니다. 따라서 심볼릭 링크, 파일 내 참조, 특정 도구의 자동 생성 여부를 조직 전체의 기본 정책으로 바로 채택할 근거로 사용해서는 안 됩니다.

정적 지침 파일에는 역할의 한계가 있다

Lockstep는 AGENTS.md에 명령어, 경계, 불변 조건처럼 비교적 오래 유지되는 내용을 넣고, 폐기·동결·새로운 결정처럼 계속 변하는 내용은 별도의 알림 또는 협업 채널에서 다뤄야 한다고 구분합니다. Lockstep의 AGENTS.md 작성 가이드

이 구분은 이번 변화와 직접 연결됩니다. 읽을 수 있는 파일이 늘어나도 에이전트가 최신 정책을 자동으로 이해하거나, 파일에 적힌 오래된 규칙을 스스로 폐기하는 것은 아닙니다. 파일 형식의 통합과 지침의 최신성은 별개의 문제입니다.

실무 판단

1. 이번 변화는 기능 추가보다 표준화 비용을 낮추는 변화다

편집부의 판단으로는 이번 변화의 가장 큰 효과는 에이전트의 추론 능력 향상이 아니라 지침 관리 방식의 선택지를 넓힌 데 있습니다. 팀이 여러 코딩 도구를 번갈아 사용한다면, 도구마다 별도 파일을 유지하는 방식은 다음 문제를 만들기 쉽습니다.

한 도구의 지침만 수정되고 다른 파일은 낡는다.
같은 명령어가 파일마다 조금씩 다르게 적힌다.
새 저장소에 어떤 파일을 먼저 만들어야 하는지 합의하기 어렵다.
에이전트가 서로 다른 규칙을 읽어 작업 결과가 달라진다.

AGENTS.md를 공통 지침의 기준으로 삼을 수 있다면 이 중 일부를 줄일 수 있습니다. 그러나 이것은 자동으로 해결되는 문제가 아닙니다. 팀이 여전히 CLAUDE.md, 도구별 규칙 파일, README에 같은 내용을 중복해서 관리하면 파일 이름만 늘어날 수 있습니다.

2. 공통 규칙과 도구별 규칙을 분리해야 한다

모든 지침을 AGENTS.md로 옮기는 것은 좋은 기본값이 아닙니다. 저장소 구조, 테스트 명령어, 금지된 변경 범위, 생성 파일의 위치처럼 여러 에이전트가 함께 알아야 하는 내용은 공통 파일에 두는 편이 합리적입니다. 반면 특정 에이전트의 호출 방식, 승인 옵션, 세션 운영법처럼 도구에 종속된 내용은 해당 도구의 별도 파일이나 팀 문서가 더 적합할 수 있습니다.

판단 기준은 간단합니다. 다른 코딩 에이전트가 이 지침을 읽어도 같은 결과를 내야 한다면 공통 파일 후보입니다. 특정 도구에서만 의미가 있고 다른 도구가 읽으면 오해할 수 있다면 도구별 파일로 남기는 편이 안전합니다.

3. 파일을 읽는지보다 잘못 읽어도 피해가 작은지가 중요하다

에이전트가 지침 파일을 읽는다는 사실만 확인하고 운영에 투입하면 위험합니다. 지침이 오래됐거나 지나치게 포괄적이면 에이전트가 정상적인 변경까지 막거나, 반대로 위험한 작업을 허용할 수 있습니다. 따라서 도입 기준은 다음 세 가지를 함께 봐야 합니다.

에이전트가 예상한 파일을 실제로 읽는가.
지침에 적힌 명령어와 경계가 현재 저장소와 일치하는가.
지침을 잘못 읽거나 누락해도 테스트와 리뷰에서 오류를 발견할 수 있는가.

이 관점에서 AGENTS.md는 통제 장치가 아니라 작업 맥락을 제공하는 입력값입니다. 권한 관리, 비밀정보 보호, 코드 리뷰, CI 검증을 대신하지 않습니다.

업무에 어떻게 쓸까

단계 1. 저장소의 규칙 파일부터 목록화한다

도입 전에 루트와 주요 하위 디렉터리의 AGENTS.md, CLAUDE.md, README, 도구별 규칙 파일을 목록으로 만드십시오. 각 파일에 같은 내용이 얼마나 반복되는지 확인하고, 마지막 수정일과 담당 팀도 함께 적습니다.

구분	넣을 내용	권장 위치	판단 질문
저장소 공통 명령	설치, 빌드, 테스트, 린트 명령	AGENTS.md	다른 에이전트도 그대로 실행해야 하는가?
변경 경계	수정 금지 디렉터리, 생성 파일 규칙	AGENTS.md	코드 리뷰 전에 반드시 알아야 하는가?
모듈별 규칙	특정 서비스의 테스트와 의존성	해당 디렉터리의 지침 파일	해당 영역 작업에만 필요한가?
도구별 사용법	특정 클라이언트의 호출·승인 방식	도구별 문서	다른 에이전트가 읽으면 혼란스러운가?
최신 공지	일시적 배포 중지, 장애 대응	협업 채널·이슈·런북	만료 시점을 관리해야 하는가?

단계 2. 공통 지침을 작게 옮긴다

첫 버전은 긴 개발 문서가 아니라 에이전트가 작업 직전에 확인할 실행 안내서로 작성하는 편이 좋습니다. 다음 템플릿에서 저장소에 맞는 항목만 채우십시오.

# Repository instructions

## Before changing code
- Read: [관련 디렉터리 또는 문서]
- Do not edit: [생성 파일, 외부 동기화 영역 등]

## Commands
- Install: `[명령어]`
- Test: `[명령어]`
- Lint: `[명령어]`

## Invariants
- [항상 지켜야 하는 데이터·API·보안 조건]
- [변경 시 반드시 함께 갱신할 파일]

## Boundaries
- Ask before: [마이그레이션, 의존성 업그레이드 등]
- Never: [비밀정보 커밋, 운영 데이터 직접 수정 등]

명령어는 설명보다 복사 가능한 형태로 적고, 불변 조건은 검증 가능한 문장으로 작성하십시오. 예를 들어 모든 테스트를 실행하라는 표현보다 npm test를 실행하고 실패 원인을 요약하라는 식이 재사용하기 쉽습니다. 단, 입력 자료만으로 특정 패키지 관리자나 명령어를 권장할 수는 없으므로 실제 저장소의 명령을 넣어야 합니다.

단계 3. Claude Code에서 읽기 여부를 검증한다

작은 테스트 브랜치에서 의도적으로 확인할 수 있습니다.

AGENTS.md에 눈에 띄는 테스트용 규칙을 하나 추가합니다.
CLAUDE.md가 없는 상태에서 Claude Code에 저장소 규칙을 요약하도록 요청합니다.
에이전트가 해당 규칙을 인식했는지 확인합니다.
테스트용 규칙을 제거하고, 실제 명령어를 실행하게 하되 변경 권한은 제한합니다.
AGENTS.md와 기존 도구별 파일을 함께 둔 상태에서 충돌 가능성을 확인합니다.

검증용 규칙은 비파괴적인 문장으로 선택해야 합니다. 파일 삭제, 외부 시스템 호출, 비밀정보 출력 같은 테스트는 피하십시오. 확인되지 않은 환경에서 에이전트의 요약만 믿지 말고, 실제로 테스트 명령을 제안하는지와 변경 범위를 지키는지를 함께 확인해야 합니다.

단계 4. 중단 조건을 먼저 정한다

다음 중 하나라도 발생하면 마이그레이션을 중단하고 기존 지침을 유지하십시오.

사용 중인 Claude Code 버전에서 AGENTS.md 인식 여부가 재현되지 않는다.
기존 CLAUDE.md와 공통 파일의 규칙이 충돌한다.
어떤 파일이 우선되는지 확인할 수 없다.
지침을 읽은 뒤 테스트·린트 명령을 잘못 실행한다.
하위 디렉터리 규칙이 루트 규칙과 충돌해 결과가 일관되지 않는다.
CI나 코드 리뷰에서 에이전트의 잘못된 변경을 잡아낼 수 없다.

이 경우 파일을 하나로 통합하는 대신, 당분간 공통 규칙은 복사하고 변경 시 동기화 검사를 추가하는 방식을 선택할 수 있습니다. 운영상의 번거로움이 있더라도, 읽기 규칙이 불명확한 상태에서 단일 파일을 기준으로 삼는 것보다 안전합니다.

실행 체크리스트

파일 정리

저장소의 모든 에이전트 지침 파일과 위치를 목록화했다.
중복 문장과 서로 다른 명령어를 비교했다.
공통 규칙, 모듈 규칙, 도구별 규칙을 분류했다.
유효기간이 짧은 공지를 정적 지침 파일에서 분리했다.

동작 검증

현재 사용 중인 Claude Code 버전의 변경 로그와 문서를 확인했다. Claude Code 변경 로그
CLAUDE.md가 없는 테스트 저장소에서 AGENTS.md 인식 여부를 확인했다.
두 파일이 동시에 존재할 때 충돌과 우선순위를 확인했다.
읽기 확인뿐 아니라 테스트·린트·변경 범위 준수까지 검증했다.

운영 전환

AGENTS.md의 담당자와 검토 주기를 정했다.
명령어와 경계가 변경될 때 함께 수정할 절차를 만들었다.
에이전트가 지침을 읽지 못해도 피해를 제한할 CI와 리뷰 절차를 유지했다.
한 개 저장소에서 시범 운영한 뒤 여러 저장소로 확대한다.

한계와 주의점

첫째, 제공된 공식 변경 로그 발췌만으로는 정확한 릴리스 버전, 지원되는 파일 경로, 하위 디렉터리의 탐색 방식, 파일 간 우선순위를 모두 확인할 수 없습니다. 이 정보가 필요한 조직은 사용 중인 버전의 공식 문서와 실제 테스트 저장소를 기준으로 별도 검증해야 합니다. Claude Code 변경 로그

둘째, Hacker News 댓글과 외부 분석 글에는 심볼릭 링크나 파일 참조를 이용한 우회 사례가 소개되지만, 이는 환경·버전·운영체제에 따라 달라질 수 있습니다. 커뮤니티 글의 사례를 제품의 보장된 기능으로 해석하지 마십시오. Hacker News 토론 외부 분석 글

셋째, 입력 자료에는 AGENTS.md가 특정 수의 오픈소스 프로젝트에서 채택됐다는 주장이나 대규모 기업의 정책 변화에 관한 내용도 포함돼 있지만, 이번 판단의 핵심 근거로 삼을 만큼 독립적으로 확인된 공식 자료는 제시되지 않았습니다. 따라서 채택 규모, 특정 기업의 실제 차단 여부, 다른 도구의 지원 범위는 이 글에서 사실로 단정하지 않습니다.

넷째, 지침 파일은 보안 경계가 아닙니다. 에이전트가 파일을 읽더라도 권한 상승, 비밀정보 접근, 운영 시스템 변경을 자동으로 막아주지 않습니다. 민감한 저장소에서는 최소 권한, 시크릿 관리, 변경 승인, CI 테스트를 별도로 유지해야 합니다.

결론적으로 이번 변화는 AGENTS.md를 무조건 표준으로 선언하라는 신호라기보다, 저장소 지침을 도구별로 복제해 온 팀이 공통 규칙을 재정리할 계기입니다. 먼저 파일을 작게 만들고, 읽기 여부와 충돌 규칙을 검증한 뒤, 실패해도 복구 가능한 저장소부터 단계적으로 확대하는 것이 현실적인 접근입니다.