AGENTS.md vs CLAUDE.md — 같은 레포 다른 시점
두 도구에 같은 레포를 다르게 설명해서 작성자/리뷰어 분담을 컨텍스트 레벨에서 강제해요.
이 챕터를 끝내면 두 컨텍스트 파일을 어디까지 겹치고 어디서부터 분리할지 기준이 생겨요.
두 파일이 따로 있는 이유
각 도구가 자동으로 읽는 컨텍스트 파일이 달라요.
CLAUDE.md— Claude Code가 워크스페이스 루트에서 자동 로드AGENTS.md— Codex가 워크스페이스 루트에서 자동 로드
둘 다 "이 레포에 대해 알아야 할 것"을 적는 자유 형식 마크다운이에요. 형식상 같은 파일을 복사해도 동작은 해요. 그런데 그렇게 두면 두 도구를 같은 시점으로 굴리는 셈이라 이중 구조의 의미가 없어져요.
분담 기준 — 작성자 vs 리뷰어
같은 레포를 두 관점으로 나눠 적어요.
CLAUDE.md (메인 작성자용)
- 코드 컨벤션 (네이밍, 폴더 구조, 임포트 순서)
- 자주 쓰는 라이브러리와 패턴 (선호 → 비선호)
- 도메인 용어 사전 (이 레포에서 X는 Y를 의미한다)
- 자주 하는 실수와 회피법
- 새 기능을 어디부터 짜기 시작해야 하는지
AGENTS.md (advisory 리뷰어용)
- 검토 우선순위 (보안 > 타입 안정성 > 성능 > 스타일 같은 순서)
- 절대 금지 패턴 (예: 시크릿 하드코딩,
any캐스팅,--forcepush) - 도메인 무결성 룰 (예: 결제 흐름은 트랜잭션으로 감싸야 한다)
- 리뷰 출력 형식 (예:
[SEVERITY] file:line — description) - "이런 건 무시해도 된다" — 작성자 컨벤션과 충돌하는 일반론은 컷
핵심은 작성자에게는 만드는 법, 리뷰어에게는 의심하는 법을 알려주는 거예요.
겹쳐야 하는 부분
분리만 강조하면 두 도구가 서로 다른 우주를 보고 있는 꼴이라 협업이 깨져요. 다음 세 가지는 두 파일 상단에 같은 텍스트를 그대로 복붙해요. 두 도구는 각자 자기 파일만 읽으니 "한 곳에 두고 참조"는 동작 안 해요.
- 레포 한 줄 소개 — 이 레포가 뭐 하는 곳인지
- 빌드/테스트 명령 — 두 도구 모두 같은 게이트를 알고 있어야 함
- 금지된 액션 최상위 — 시크릿 커밋 금지,
--forcepush,--no-verify등
겹치는 부분은 짧게, 한 화면(10~20줄)으로 끝내요. 양쪽 컨텍스트의 80% 이상이 겹친다면 분담이 작동 안 하고 있다는 신호예요. 실제 양식은 8장 보일러플레이트의 CLAUDE.md/AGENTS.md 템플릿을 그대로 가져다 쓰면 돼요.
자동 동기화는 비추
처음엔 "두 파일이 같은 정보를 따로 쓰면 두 번 일하잖아" 싶어 동기화 스크립트를 짜고 싶어져요. 권장하지 않아요.
- 두 파일이 각자 자기 도구의 사용 양상에 맞춰 진화해야 분담이 살아 있어요
- 동기화하면 한쪽 변경이 다른쪽 의도와 충돌하는데 자동으로 덮어써져요
- 작성자가 새로 발견한 컨벤션과 리뷰어가 새로 잡아야 할 패턴은 시점이 달라요
대신 분기마다 한 번씩 양쪽을 같이 열어서 겹치는 부분만 동기화하는 수동 검토를 권장해요.
분량 가이드
처음부터 길게 쓰지 말고, 실제 협업 중 발견되는 마찰을 한 줄씩 추가하는 식으로 키워요. 시작 분량 기준:
CLAUDE.md— 200~400줄. 도메인 용어 사전이 무거울수록 길어짐AGENTS.md— 80~150줄. 룰은 적을수록 좋음 (많으면 리뷰가 노이즈로 묻힘)
AGENTS.md가 CLAUDE.md보다 길어지기 시작하면 리뷰어한테 너무 많은 걸 주문하는 중이에요. 핵심 룰 5~10개로 줄여요.
다음 챕터 예고
컨텍스트 분리는 끝났어요. 다음 챕터에서 advisory 리뷰어를 실제로 호출하는 래퍼 스크립트를 만들어요. 핵심은 Codex가 없어도 메인 파이프라인이 깨지지 않는 graceful degradation이에요.