AGENTS.md 지원, 코딩 에이전트 지침이 표준화된다

작은 변경이지만 표준의 냄새가 난다

Claude Code 2.1.277 changelog는 CLAUDE.md가 없는 프로젝트에서 Claude Code가 AGENTS.md를 대신 읽는다고 적었다. 사용자는 /config의 Project instructions에서 이를 바꿀 수 있고, Bedrock, Vertex, Foundry 경로에는 아직 적용되지 않았다. 릴리스 노트 한 줄이지만 의미는 작지 않다. 에이전트형 개발 도구가 점점 "이 저장소에서 어떻게 일해야 하는가"를 파일 계약으로 읽기 시작했기 때문이다.

기존에는 도구마다 기억 파일 이름이 달랐다. 어떤 도구는 CLAUDE.md, 어떤 도구는 AGENTS.md, 어떤 팀은 README나 docs 안의 운영 규칙을 썼다. 이번 변화는 Claude Code가 자기 파일만 고집하지 않고 더 넓은 생태계의 지침 파일을 받아들이기 시작했다는 신호다. Claude Code memory 문서, features overview, OpenAI Agents SDK 문서, Aider의 CONVENTIONS 안내를 함께 보면 코딩 에이전트의 공통 질문이 보인다. 모델 성능보다 먼저, 모델이 읽어야 할 현장 규칙을 어디에 둘 것인가가 문제다.

지침 파일은 프롬프트가 아니라 운영 계약이다

AGENTS.md 같은 파일은 "친절한 설명"이 아니다. 테스트 명령, 린트 규칙, 금지된 리팩터링, 보안 경계, PR 작성 방식, 배포 전 확인 목록이 들어가는 운영 계약이다. 사람이 온보딩 문서로 읽고, 에이전트는 작업 전후의 판단 기준으로 읽는다. 따라서 이 파일의 가치는 모델별 최적화가 아니라 도구 간 호환성에서 나온다.

한국 개발팀에는 특히 중요하다. 여러 IDE 플러그인, CLI 에이전트, 사내 자동화가 같은 저장소를 건드릴 때 지침이 흩어지면 자동화의 품질도 흩어진다. OpenAI Agents API, 에이전트 운영을 API로 묶다, async/await도 언어마다 다른 계약이다, Real-SWE, 사내 코드 벤치마크의 반격에서 다룬 흐름과 같다. 에이전트 시대의 생산성은 "더 똑똑한 모델"과 "더 분명한 작업 계약"이 같이 움직일 때 오른다.

엔터프라이즈에는 감사 가능성이 중요하다

기업 도입에서 지침 파일의 장점은 감사 가능성이다. 누가 언제 테스트 명령을 바꿨는지, 어떤 보안 예외가 추가됐는지, 릴리스 브랜치에서 다른 규칙을 쓰는지 Git 히스토리로 볼 수 있다. 반대로 채팅창에만 있는 지시는 재현하기 어렵고, 에이전트가 바뀌면 사라진다.

Claude Code 2.1.277에는 AGENTS.md 외에도 gateway proxy egress boundary, upstream static headers, headless session error reporting 같은 운영성 개선이 여럿 들어갔다. 코딩 에이전트가 개인 생산성 도구에서 조직 인프라로 넘어갈 때 필요한 항목들이다. 지침 파일 표준화는 그중 가장 눈에 잘 띄는 개발자 경험의 변화다.

한국 팀의 실무 체크리스트

첫째, 저장소 루트에 AGENTS.md를 두고 공통 규칙만 적는다. 빌드, 테스트, 포맷, 보안 금지선, 리뷰 기준처럼 도구와 무관한 내용을 넣는다. 둘째, 도구별 파일은 보조 파일로 둔다. Claude 전용 기능, 특정 IDE 단축 명령, 사내 플러그인 설정은 별도 파일이 맞다. 셋째, 지침 파일을 길게 만들지 않는다. 에이전트가 매번 읽는 문서는 짧고 강해야 한다.

자주 묻는 질문

Q1: 이제 CLAUDE.md를 지워야 하나요?

A: 아닙니다. Claude 전용 지침이 있으면 CLAUDE.md를 유지하고, 여러 도구가 공유해야 하는 기본 규칙은 AGENTS.md로 옮기는 방식이 현실적입니다.

Q2: AGENTS.md에는 무엇을 넣어야 하나요?

A: 테스트 명령, 빌드 명령, 코드 스타일, 금지 작업, 배포 전 확인 항목처럼 모든 에이전트가 알아야 하는 운영 규칙이 적합합니다.

Q3: 왜 README가 아니라 별도 파일인가요?

A: README는 사람에게 넓은 설명을 주는 문서입니다. AGENTS.md는 자동화가 반복해서 읽는 짧은 작업 계약으로 쓰기 좋습니다.

Q4: Bedrock이나 Vertex 사용자도 바로 적용되나요?

A: changelog 기준으로 해당 경로에는 아직 적용되지 않았습니다. 조직 배포 환경에서는 실제 지원 여부를 별도로 확인해야 합니다.

Q5: 한국 기업에 가장 큰 시사점은 무엇인가요?

A: 에이전트 품질 관리가 프롬프트 개인기에 머물지 않고 저장소에 버전 관리되는 운영 규칙으로 이동한다는 점입니다.