AGENTS.md 운영 가이드: Codex, Copilot, Claude Code가 지시문을 다르게 읽을 때의 레포 설계

AI 코딩 에이전트를 여러 개 쓰는 팀에서 가장 먼저 망가지는 것은 코드가 아니라 지시문이다. Codex는 AGENTS.md를 읽고, Claude Code는 CLAUDE.md를 우선하고, Copilot은 기능별로 다른 규칙을 적용한다. Cursor, Gemini CLI, Antigravity까지 섞이면 “우리 레포의 규칙”이 에이전트마다 다르게 해석될 수 있다.

2026년 10월 3일 공개된 AGENTS.md 비교 글은 이 문제를 잘 보여준다. 같은 디렉터리 구조라도 Codex CLI, Codex code review, GitHub Copilot cloud agent, Copilot CLI, VS Code local agent, Claude Code, Gemini CLI, Antigravity, Cursor, Kiro가 instruction file을 읽는 방식이 다르다. 어떤 도구는 가까운 파일을 우선하고, 어떤 도구는 여러 파일을 이어 붙이고, 어떤 도구는 순서를 보장하지 않는다.

실무에서 중요한 결론은 하나다. “AGENTS.md 하나 두면 모든 에이전트가 같은 규칙을 따른다”는 기대를 버려야 한다. 대신 레포 규칙을 single source로 관리하고, 각 에이전트가 읽는 파일로 안전하게 배포하는 구조가 필요하다.

왜 instruction file 문제가 커졌나

처음에는 코딩 에이전트가 보조 도구였다. 사람이 지시하고, 에이전트는 파일 몇 개를 수정했다. 이제는 PR 리뷰, 이슈 처리, 테스트 보강, 코드 생성, 리팩터링을 여러 에이전트가 동시에 맡는다. 같은 레포에 Codex, Copilot, Claude Code, Cursor가 들어오는 일이 흔해졌다.

문제는 각 도구가 instruction file을 다르게 읽는다는 점이다. 예를 들어 Codex CLI는 프로젝트 루트에서 working directory까지의 AGENTS.md를 연결하고, 가까운 파일이 뒤에 와서 앞선 지시를 덮는 방식으로 동작한다. 반면 Claude Code는 CLAUDE.md 파일들을 concatenation하며, 충돌 시 임의 선택 가능성이 문서에 언급된다. Copilot도 cloud agent, code review, CLI, VS Code local agent마다 문서 설명이 다르다.

이 차이는 작은 스타일 문제로 끝나지 않는다. 한 에이전트는 “테스트 없이 수정 금지”를 읽고, 다른 에이전트는 해당 지시를 못 읽을 수 있다. 한 에이전트는 package 하위 규칙을 우선하고, 다른 에이전트는 root 규칙과 충돌시 애매하게 섞을 수 있다.

레포 규칙은 한 곳에서 관리한다

가장 안전한 패턴은 canonical instruction을 별도로 두는 것이다. 예를 들어 docs/agent-instructions/base.md를 원본으로 관리한다. 그 안에는 모든 에이전트가 공유해야 하는 규칙만 넣는다. 테스트 필수, 보안 파일 수정 금지, 패키지 매니저, 코드 스타일, 리뷰 기준 같은 내용이다.

그다음 각 도구용 파일은 이 원본을 반영한다. AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, GEMINI.md, Cursor rules를 각각 직접 작성하더라도 내용의 출처는 하나여야 한다. 가능하면 생성 스크립트로 동기화한다. 수동 복붙은 시간이 지나면 반드시 어긋난다.

원본 파일에는 도구별 문법을 넣지 않는 것이 좋다. 예를 들어 Claude 전용 slash command나 Codex 전용 sandbox 규칙은 base가 아니라 adapter 파일에 둔다. base는 정책, adapter는 도구별 표현으로 나누는 방식이다.

충돌 가능한 지시는 쓰지 않는다

instruction file에서 가장 위험한 문장은 추상적인 원칙이다. “가능하면 테스트하라”, “필요하면 리팩터링하라”, “적절히 판단하라” 같은 문장은 에이전트마다 다르게 해석한다. 특히 여러 파일이 concatenation될 때 추상 지시는 충돌을 만들기 쉽다.

좋은 지시는 관찰 가능해야 한다. “코드 변경 후 npm test를 실행한다. 실패하면 실패 로그와 원인을 보고하고 수정하지 않은 채 종료하지 않는다”처럼 써야 한다. “보안에 유의하라”보다 “.env, credentials, production dump, private key 파일은 읽거나 수정하지 않는다”가 낫다.

덮어쓰기 규칙도 명확히 한다. “하위 AGENTS.md가 있으면 해당 디렉터리 작업에는 하위 규칙을 우선한다”처럼 사람 기준의 정책을 문서화한다. 단, 모든 에이전트가 이를 자동으로 적용한다고 믿으면 안 된다. 그래서 하위 규칙에는 상위 규칙과 충돌하지 않는 추가 제약만 넣는 편이 안전하다.

모노레포에서는 범위를 작게 나눈다

모노레포에서는 루트 instruction 하나로 충분하지 않다. web, mobile, backend, infra, docs가 서로 다른 명령과 위험을 가진다. 하지만 하위 AGENTS.md를 너무 많이 만들면 에이전트별 탐색 차이 때문에 혼란이 커진다.

실무적으로는 package 단위가 적당하다. apps/web/AGENTS.md, apps/mobile/AGENTS.md, packages/core/AGENTS.md처럼 작업 경계가 명확한 곳에 둔다. 각 파일에는 해당 영역에서만 달라지는 명령과 금지사항을 넣는다. 공통 규칙은 루트에 두고 반복하지 않는다.

하위 파일 첫 줄에는 범위를 명확히 쓴다. “This file applies only to apps/web.”처럼 적는다. 그리고 실행 명령도 구체화한다. “웹 변경 후 pnpm --filter web test 실행”처럼 쓰면 에이전트가 루트 전체 테스트를 무리하게 돌리는 일을 줄일 수 있다.

에이전트별 adapter를 둔다

Codex, Copilot, Claude Code가 모두 같은 파일을 읽는다고 가정하지 말고, adapter 파일을 둔다. 예를 들어 CLAUDE.md에는 “공통 규칙은 AGENTS.md와 동일하며, Claude Code에서는 다음 추가 규칙을 따른다”처럼 쓴다. 단, 실제로 다른 파일을 import하는 기능이 도구별로 다르므로, 단순 참조 문장만으로 충분하지 않을 수 있다.

가능하면 sync script를 만든다. base.md와 tool-specific snippets를 합쳐 AGENTS.md, CLAUDE.md, GEMINI.md를 생성한다. 생성된 파일 상단에는 “DO NOT EDIT DIRECTLY”를 넣는다. PR에서 base와 generated file이 불일치하면 CI가 실패하게 한다.

이 방식은 귀찮아 보이지만, 에이전트가 많아질수록 값어치가 커진다. 특히 외주 개발자, 자동 PR 봇, 코드 리뷰 에이전트가 섞이면 규칙 drift를 사람이 기억으로 관리할 수 없다.

테스트 가능한 규칙을 만든다

instruction도 테스트 대상이다. 예를 들어 “package-lock.json을 직접 수정하지 말 것”이라는 규칙이 있다면, 에이전트가 만든 PR에서 해당 파일 변경을 CI가 감지해야 한다. “마이그레이션에는 rollback을 포함할 것”이라는 규칙이 있다면 migration 파일 패턴을 검사할 수 있다.

모든 규칙을 자동화할 수는 없다. 하지만 핵심 안전 규칙은 CI로 옮겨야 한다. 에이전트 instruction은 모델에게 방향을 주는 장치이고, CI는 실제로 막는 장치다. 둘을 혼동하면 안 된다.

리뷰 체크리스트도 붙인다. PR 템플릿에 “에이전트가 사용한 instruction file”, “실행한 테스트”, “수정 범위”, “건드리지 않은 민감 파일”을 쓰게 한다. 자동 에이전트 PR이라면 이 정보를 본문에 자동으로 넣도록 한다.

실행 체크리스트

• AGENTS.md 하나로 모든 도구가 동일하게 동작한다고 가정하지 않는다.
• canonical instruction을 docs/agent-instructions/base.md처럼 별도 원본으로 둔다.
• AGENTS.md, CLAUDE.md, GEMINI.md, Copilot instructions는 원본에서 생성하거나 동기화한다.
• 공통 정책과 도구별 문법을 분리한다.
• 추상 지시 대신 관찰 가능한 행동으로 쓴다.
• 하위 instruction file은 상위 규칙과 충돌하지 않는 추가 제약만 넣는다.
• 모노레포에서는 package 단위로 범위를 나눈다.
• 생성 파일에는 DO NOT EDIT DIRECTLY를 넣고 CI로 drift를 검사한다.
• 핵심 안전 규칙은 instruction이 아니라 CI에서도 강제한다.
• PR 템플릿에 사용한 에이전트, 읽은 instruction, 실행한 테스트를 기록한다.