Claude Code Codex 같이 쓰기, 같은 저장소에서 역할 나눈 규칙

2026.10.15 · 밥

웹게임 하나를 Claude Code 랑 Codex 로 같이 만들고 있다. 처음엔 둘 다 같은 폴더에서 일하니까 알아서 맞춰 가겠지 했다. 근데 한쪽이 만진 파일을 다른 쪽이 이어받으려면 무엇을, 왜, 어디까지 했는지 바로 알 수 있어야 했다. 이미 정해 둔 걸 깨지 않게 하는 것도 문제였고. 그래서 Codex 가 지킬 작업 규칙을 따로 문서로 만들었다.

Claude Code Codex 같이 쓰기에서 먼저 정할 건 다섯 가지다. 두 도구가 각각 어떤 지침 파일을 읽는지, 누가 무엇을 정하는지, 어느 브랜치에서 일하는지, 한 번에 어디까지 고치는지, 그리고 끝나면 무엇을 적는지. 아래 지침 파일 얘기는 2026년 10월 15일에 연 공식 문서 기준이고, 나머지는 우리 게임 저장소에서 실제로 쓰는 규칙이다.

Claude Code 와 Codex 는 다른 지침 파일을 읽는다

제일 먼저 알아 둘 게 이거다. 둘 다 저장소에 적어 둔 지침을 읽긴 하는데, 기본으로 찾는 파일 이름이 다르다.

Claude Code 메모리 문서를 보면 Claude Code 는 CLAUDE.md 를 읽는다. 내 모든 프로젝트에 걸리는 ~/.claude/CLAUDE.md, 저장소에 같이 올리는 ./CLAUDE.md(또는 ./.claude/CLAUDE.md), 나만 쓰고 git 에는 안 올리는 ./CLAUDE.local.md 가 있다. 작업 폴더와 그 위 폴더들의 파일을 시작할 때 다 읽고, 서로 덮어쓰는 게 아니라 이어 붙인다. 작업 폴더에 가까운 파일이 뒤에 붙는다. 하위 폴더 파일은 그 폴더 일을 할 때 읽는다. 파일 하나는 200줄 아래로 잡으라고 권한다.

Codex 는 AGENTS.md 다. Codex AGENTS.md 문서에 따르면 먼저 Codex 홈 폴더(기본 ~/.codex)의 파일을 읽고, 그다음 프로젝트 루트(보통 git 루트)에서 지금 작업 폴더까지 내려가며 폴더마다 파일을 하나씩 붙인다. 가까운 폴더의 지침이 뒤에 오니까 앞의 지침을 덮는다. 합친 크기가 한도(기본 32 KiB)에 닿으면 더 붙이지 않는다. 지우지 않고 잠깐 바꿔 쓰고 싶으면 AGENTS.override.md 를 쓰면 된다.

헷갈리는 건 둘이 같이 있을 때다. Claude Code 문서에 따르면 Claude Code 도 AGENTS.md 를 읽을 수 있는데(v2.1.277 이상), 기본 설정에선 작업 폴더나 그 위에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md 가 하나도 없을 때만 읽는다. 셋 중 하나라도 있으면 AGENTS.md 는 안 읽는다는 뜻이다. 나만 쓰려고 CLAUDE.local.md 하나 만들어도 걸린다. 둘 다 읽히게 하려면 CLAUDE.md 맨 위에 @AGENTS.md 한 줄을 넣어 가져오면 된다. 문서는 CLAUDE.md 를 AGENTS.md 로 심볼릭 링크하는 방법도 적었는데, 윈도우에선 링크를 만들 때 관리자 권한이나 개발자 모드가 필요하고 git 이 링크를 그냥 글자 파일로 꺼낼 수 있어서 가져오기 쪽을 권한다.

우리 저장소가 딱 이 경우였다. 루트에 CLAUDE.md(25줄)랑 AGENTS.md(11,516바이트)가 따로 있고, CLAUDE.md 는 AGENTS.md 를 가져오지 않는다. 그러니까 기본 설정이면 저장소 루트의 두 파일 중에선 Claude Code 는 CLAUDE.md 만, Codex 는 AGENTS.md 만 본다. 따로 두는 것 자체는 문제가 아닌데, 대신 둘 다 지켜야 하는 규칙은 두 파일에 다 들어가 있어야 한다. 우리는 구현 전에 먼저 읽을 설계 문서 목록을 두 파일에 똑같이 적어 뒀다. 한쪽만 고치면 다른 쪽은 옛 규칙대로 움직인다.

하나 더. Claude Code 문서는 CLAUDE.md 가 강제 설정이 아니라 참고하는 맥락이라고 적었다. 무슨 일이 있어도 막아야 하는 동작은 PreToolUse 훅으로 막으라고 한다. 지침 파일에 "절대 하지 말 것"을 적어 두는 것만으로 다 막힌다고 기대하면 안 된다.

역할 나누기에서 결정 권한부터 정하기

다음은 누가 정하느냐다. 우리 게임은 설계 결정, 그러니까 수치나 규칙이나 정책은 사람이 승인해야 확정된다. Codex 지침에는 Codex 가 구현 방법을 제안할 수는 있어도 게임 설계 결정은 승인을 받은 뒤에 적용한다고 적어 뒀다. 승인 없이 새로 정한 값에는 임시라는 표시를 붙인다.

작업 규칙에는 도구가 스스로 정한 값은 일지의 '제안'에만 적고 결정 문서에는 넣지 말라고 적었다. 실제로 Codex 가 길드 외교 기능을 만들면서 갱신 기한을 언제부터 셀지 같은 기술 선택을 직접 했는데, 그건 일지의 제안 칸에 임시 표시를 달고 남았고 결정 문서에는 들어가지 않았다. 이어받는 쪽은 어디까지가 확정이고 어디부터가 도구가 고른 값인지 일지에서 가려 볼 수 있다.

일을 나누는 방식은 우리 경우 종류별로 딱 자르진 않았다. CLAUDE.md 에는 Claude Code 가 기획, 개발, 시험, 증거, 우선순위를 맡는다고 적었고, 그림은 Claude Code 가 요청서를 쓰고 Codex 가 그리고 Claude Code 가 검수한다. 기능 구현도 묶음 단위로 Codex 에 맡긴다. 그림 쪽 얘기는 Codex 이미지 생성 한도 글에 따로 적었다.

작업 브랜치를 나눠 두기

Codex 규칙에서 시작할 때 할 일 세 번째가 이거다. main 에서 직접 고치지 않고 codex/<날짜>-<주제> 브랜치를 새로 만들어서 일한다. 실제로 쓴 이름은 codex/20261001-war-mvp 같은 식이다. 합치는 건 사람이 승인한 뒤에.

브랜치 이름 앞에 도구 이름을 붙여 두면 git 기록만 봐도 누가 한 일인지 갈린다. 커밋 메시지 첫 줄도 [codex] <영역>: <요약> 으로 맞췄다. 시작할 때 git status 가 깨끗해야 한다는 줄도 같이 넣었다. 다른 도구가 하다 만 변경을 섞어서 커밋하는 걸 막으려는 거다.

영역 하나씩, 새 기능은 새 파일로

한 번에 고치는 범위도 정했다. 저장소를 영역으로 나눈 지도 문서를 두고, Codex 는 한 번에 영역 하나만 고친다. 다른 영역 파일이 꼭 필요하면 연결하는 한 줄만 넣고 일지에 적는다.

새 기능은 큰 기존 파일에 길게 덧붙이지 말고 새 파일로 만든다. 기존 파일엔 불러오고 등록하는 몇 줄만. 길드 외교 묶음이 그렇게 들어갔다. 외교 규칙은 새 파일 두 개(서버 하나, 화면 하나)로 만들었고, 원래 길드 파일의 외교 부분은 새 파일로 넘겨주는 얇은 코드로 바뀌었다. 두 도구의 변경이 같은 큰 파일에 몰리는 걸 줄이려는 규칙이다.

이어받을 수 있게 작업 일지 남기기

솔직히 이게 제일 쓸모 있었다. Codex 는 묶음 하나가 끝날 때마다 그날 일지 파일에 한 절을 덧붙인다. 칸은 정해져 있다.

시험 칸에 실행 안 한 것까지 적게 한 게 컸다. 실제 일지에 이런 절이 있다. 길드 묶음에서 관련 시험 95개를 전부 비UI 시험이라고 적었다가, 그중 하나가 UI 시험 표시가 붙은 거라 비UI 94개에 UI 1개로 바로잡은 기록이다. 통과 수는 같았지만 시험 분류를 바로잡은 기록이 같은 일지에 남았다. 이어받는 쪽은 "전부 돌렸다"는 말 대신 무엇을 돌렸고 무엇을 안 돌렸는지를 받는다.

Claude Code Codex 같이 쓰기 점검표

처음 둘을 같이 쓰기 시작한다면 아래 다섯 줄부터 채워 보면 된다.

다섯 개 다 처음부터 완벽할 필요는 없다. 우리도 지침 파일 차이는 나중에야 문서로 확인했다. 근데 브랜치랑 일지만 먼저 정해 둬도 누가 무엇을 어디까지 했는지는 git 기록과 일지에 남는다. 두 도구의 사용량 한도를 먼저 확인하는 순서는 사용량 한도 글에 따로 적었다.

다음엔 프로세스를 이름으로 한꺼번에 끄지 말고 PID 로 꺼야 하는 이유를 얘기하려고 한다.