Claude Code와 Codex가 같은 저장소를 쓸 때, 규칙은 AGENTS.md 한 곳에 둡니다

이 블로그 저장소는 기계 세 곳에서, 여러 AI 코딩 도구가 번갈아 씁니다. 주로 Claude Code가 쓰고, Codex 기반 도구(oh-my-codex, 줄여서 OmX)도 가끔 들어옵니다.

도구가 여럿이면 곤란한 게 하나 있습니다. 규칙을 어디에 적어 둬야 모든 도구가 같은 규칙을 따를까? 이 글은 그 답으로 저장소 루트에 AGENTS.md 하나를 두게 된 과정입니다.

규칙이 한 기계에만 있었습니다

이 저장소는 커밋 메시지 끝에 Constraint:, Rejected: 같은 git 트레일러를 붙입니다. 무엇을 왜 골랐는지를 커밋에 남겨 두면 나중에 git log로 찾을 수 있어서입니다.

문제는 이 규칙이 제 맥의 전역 설정에만 있었다는 겁니다. 이 맥에서 도는 Claude Code는 규칙을 봤지만, 다른 기계의 에이전트는 볼 방법이 없었습니다.

7월 말에 세어 보니 커밋 91건 중 Co-Authored-By가 붙은 커밋은 52건이었습니다. 값은 셋으로 갈렸습니다. Claude Opus 5가 47건, OmX가 6건, Claude Fable 5가 5건이었습니다. 어느 도구가 커밋했는지는 남았지만, 트레일러 형식을 지키는지는 기계마다 제각각일 수밖에 없는 구조였습니다.

기계마다 설정하는 대신 저장소에 넣었습니다

처음 떠오른 방법은 기계마다 같은 규칙을 설치하는 것이었습니다. 금방 접었습니다. 기계가 늘 때마다 같은 일을 반복해야 하고, 셋 중 하나가 어긋나도 아무도 모릅니다.

그래서 규칙을 저장소 안으로 옮겼습니다. 저장소 파일은 git pull만 하면 모든 기계로 따라가니까요. 남은 질문은 파일 이름이었습니다.

• CLAUDE.md는 Claude Code가 읽는 파일입니다. Codex 계열은 읽지 않으니 OmX 커밋이 빠집니다.
• AGENTS.md는 Codex가 읽는 파일입니다. 그리고 제 환경에서는 Claude Code도 이 파일을 읽었습니다.

결국 AGENTS.md로 정했습니다. 이 저장소에는 CLAUDE.md가 없습니다. 그런데도 Claude Code(2.1.235)가 세션을 시작할 때 AGENTS.md 내용을 프로젝트 지침으로 받아 왔습니다. 두 도구가 같은 파일 하나를 보는 셈입니다.

파일에는 이렇게 적었습니다

지금 이 저장소의 AGENTS.md는 맨 위에 누구에게 적용되는 파일인지부터 밝힙니다.

이 저장소는 여러 기계에서 여러 에이전트가 함께 쓴다. 이 파일은 그 전부에게
적용된다 — Claude Code, Codex 계열(OmX) 모두 이 파일을 읽는다.

그 아래에 규칙이 두 덩어리 있습니다. 하나는 커밋 트레일러 형식이고, 다른 하나는 블로그 글을 고칠 때 한국어 문장 검토를 반드시 거치라는 규칙입니다. 두 번째 규칙은 이번 주에 더했습니다. 어느 도구가 글을 고치든 같은 검토 절차를 거치게 하려는 겁니다.

일부러 적지 않은 것도 있습니다. Co-Authored-By에 들어갈 값은 파일에 고정하지 않았습니다. 이 트레일러는 어느 에이전트가 커밋했는지 가리려고 붙이는 것이라, 도구마다 자기 이름을 적어야 맞습니다. 예시에 특정 이름을 박아 두면 모두가 그 이름을 베껴 쓰게 됩니다.

전역 파일과 저장소 파일은 역할이 다릅니다

AGENTS.md가 저장소에 생겼다고 전역 설정이 필요 없어지지는 않습니다. 둘은 담는 내용이 다릅니다.

위치	담는 것	예
도구의 전역 파일 (~/.codex/AGENTS.md 등)	그 기계에서 그 도구를 어떻게 쓸지	응답 언어, 작업 방식, 자주 쓰는 스킬
저장소의 AGENTS.md	이 저장소에서 지킬 약속	커밋 형식, 글 검토 절차, 금지 사항

기준은 간단합니다. 이 저장소를 새 기계에서 처음 클론한 에이전트도 알아야 하는 규칙이라면 저장소 파일에 둡니다. 제 취향이나 그 기계에서만 의미 있는 설정이라면 전역 파일에 둡니다.

강제할 방법은 없습니다

AGENTS.md는 지침일 뿐 강제 장치가 아닙니다. 에이전트가 읽고 따르기를 기대하는 파일입니다.

강제하려면 git의 commit-msg 훅을 쓰는 방법이 있습니다. 그런데 훅은 .git/hooks 안에 있어서 저장소를 클론해도 따라오지 않습니다. 기계마다 core.hooksPath를 따로 설정해야 하니, 결국 처음 문제로 돌아갑니다. 그래서 훅은 아직 넣지 않았습니다.

대신 규칙이 지켜졌는지는 커밋 기록으로 확인할 수 있습니다. 이 저장소에서 어떤 도구가 몇 번 커밋했는지는 이렇게 봅니다.

git log --format="%(trailers:key=Co-Authored-By,valueonly)" | sort | uniq -c | sort -rn

Codex가 이 파일을 받는지는 따로 물어서 확인했습니다. 저장소에서 Codex에게 파일을 열지 말고 이미 받은 지침만으로 트레일러 규칙을 말해 보라고 했더니, 이렇게 답했습니다.

커밋 트레일러 블록은 메시지의 마지막 문단 하나로 두고, `Co-Authored-By:`를 포함한 모든 트레일러 사이에 빈 줄을 넣지 않아야 한다.

AGENTS.md에 적은 그대로입니다. 다만 지침을 받는 것과 실제 커밋에서 지키는 것은 다른 문제입니다. AGENTS.md를 넣은 뒤로 이 저장소의 커밋은 전부 Claude Code가 했기 때문에, Codex가 규칙대로 커밋하는지는 다음 Codex 커밋이 생겨야 알 수 있습니다.

한 번 밟은 함정: 트레일러 앞의 빈 줄

규칙을 쓰는 세션에서 실제로 밟은 함정이 있어서, AGENTS.md 한가운데에 적어 뒀습니다.

git은 커밋 메시지의 마지막 문단만 트레일러로 읽습니다. 그래서 트레일러 사이에 빈 줄이 하나라도 들어가면 그 위쪽 트레일러는 전부 평범한 본문이 됩니다.

Not-tested: 맥미니 쪽 동작

Co-Authored-By: <이 커밋을 쓴 에이전트>

이렇게 쓰면 Co-Authored-By만 트레일러로 남고 Not-tested는 사라집니다. 더 곤란한 건 git log --grep="^Not-tested:"로 찾으면 여전히 찾아진다는 점입니다. --grep은 원문 텍스트를 훑을 뿐이라, 트레일러 블록이 깨졌는지는 알려 주지 않습니다.

그래서 커밋한 뒤에는 git의 트레일러 파서에 직접 물어봅니다.

git log -1 --format="%(trailers)"

기대한 트레일러가 목록에 없다면 블록이 깨진 겁니다. git commit --amend로 빈 줄을 지우면 됩니다.

정리하면

• 여러 AI 도구가 같이 쓰는 저장소라면 규칙은 저장소 루트의 AGENTS.md에 둡니다. 클론하는 곳이면 어디든 따라갑니다.
• 도구마다 달라야 하는 값(누가 커밋했는지 등)은 파일에 고정하지 않습니다.
• AGENTS.md는 강제하지 않습니다. 지켜졌는지는 커밋 기록으로 확인합니다.
• 트레일러를 쓴다면 블록 안에 빈 줄을 넣지 말고, 확인은 %(trailers)로 합니다.