Claude Code × Codex 실전기 02. 저장소 구조 리팩토링

지난 글에서 Claude Code만 쓰던 프로젝트에 Codex를 넣었습니다. 그때의 결론은 "도구가 프로젝트를 이해하게 만드는 게 아니라, 프로젝트가 스스로를 설명할 수 있게 만드는 것"이었습니다.

이번 글의 핵심은 Claude가 만든 저장소 구조 변경 계획을 Codex가 실제 저장소 기준으로 검증한 과정입니다.

결과는 단순한 폴더 이동이 아니었습니다. raw, wiki, assets, output의 역할을 다시 나누고, Claude Code와 Codex가 같은 경계를 읽을 수 있는 구조로 정리했습니다.

시작 조건은 분명했습니다. ai-survival-log 프로젝트가 커지면서 아티클은 sources/에, 책 스크린샷은 book/에, 이미지는 docs/images/에 흩어져 있었습니다.

이번에는 Claude로 계획을 짜고, Codex로 검증을 맡겼습니다.

계획은 문서 안에서만 완결됐습니다

Claude-Codex 협업 구조를 실제로 써보는 첫 번째 큰 작업이었습니다.

당시 저장소는 이런 모양이었습니다.

ai-survival-log/
├── sources/          ← 외부 아티클 (어중간한 위치)
├── book/             ← 책 스크린샷 (어중간한 위치)
├── wiki/             ← 위키
└── docs/
    └── images/       ← 이미지 (어중간한 위치)

파일들이 계층 없이 흩어져 있었습니다. Claude에게 맡긴 작업은 계획서 작성이었습니다. wiki/projects/repo-structure-refactor.md를 만들었습니다. 골자는 이랬습니다.

ai-survival-log/
├── raw/
│   ├── articles/     ← sources/ 이동
│   ├── books/        ← book/ 이동
│   └── assets/       ← docs/images/ 이동
├── wiki/
└── output/
    ├── blog/         ← 신규
    ├── youtube/      ← 신규
    └── instagram/    ← 신규

문서만 보면 구조가 정리된 것처럼 보였습니다. 문제는 실제 저장소와 맞춰 보는 단계에서 드러났습니다.

Codex는 저장소 상태로 계획을 검증했습니다

Codex에게 계획서를 검증하라고 했습니다.

그런데 Codex가 한 건 문서를 읽는 게 아니었습니다. 실제 저장소 상태를 뒤졌습니다.

디렉토리 현황 확인
→ 계획 문서 라인별 교차 검증
→ 런타임 테스트 실행
→ 운영 계약 문서와 대조

결과로 두 가지 문제가 드러났습니다.

첫 번째 문제는 docs/images → raw/assets 전환이 publish 계약과 충돌한 점이었습니다.

계획서에는 이미지 폴더를 raw/assets/로 옮기는 내용이 있었습니다. 그런데 AGENTS.md와 publishing-contract 문서를 보니 downstream site(ai-survival-log-site)가 이미 특정 경로를 전제하고 있었습니다. 경로를 바꾸면 downstream 계약이 깨집니다.

두 번째 문제는 계획 문서 자체가 lint를 깨고 있었다는 점이었습니다.

python3 -m pytest tests/test_wiki_lib.py → 통과
python3 scripts/wiki lint → 실패

계획서 안에 언급된 경로, 타입이 현재 wiki lint 규칙을 위반하고 있었습니다. 계획 문서 자체가 저장소 무결성 기준을 통과하지 못하는 상태였습니다.

이미지는 raw가 아니라 발행 자산이었습니다

두 가지 문제를 반영해서 구조를 다시 설계했습니다.

핵심 수정은 이미지 경로를 raw/assets/가 아니라 assets/blog/로 분리하는 것이었습니다.

판단 기준은 역할이었습니다. 이미지는 원본 지식 자료(raw)가 아니라 채널별로 발행하는 자산입니다. 그래서 assets/ 계층을 별도로 두고, 채널별로 나누는 쪽이 더 정확했습니다.

최종 구조는 다음과 같았습니다.

ai-survival-log/
├── raw/              ← 불변 원본 자료
│   ├── articles/
│   ├── books/
│   ├── journals/
│   ├── videos/
│   └── podcasts/
├── wiki/             ← 지식 베이스
│   └── ...
├── assets/           ← 채널별 자산 (raw/assets에서 분리됨)
│   ├── blog/
│   ├── youtube/
│   ├── instagram/
│   └── webtoon/
└── output/           ← 재생성 가능한 publish artifact
    ├── blog/
    ├── youtube/
    ├── instagram/
    └── threads/

raw → wiki → output 흐름이 명확해졌습니다. assets/는 이 흐름에서 비텍스트 자산을 관리하는 별도 계층입니다.

대칭 운영 문서가 계층 경계를 설명했습니다

계획이 확정되자 Codex가 실행으로 넘어갔습니다.

파일 이동 자체는 간단했습니다. 중요한 변화는 마지막 단계에 있었습니다.

각 최상위 디렉토리에 운영 문서를 대칭으로 배치했습니다.

raw/CLAUDE.md, raw/AGENTS.md
assets/CLAUDE.md, assets/AGENTS.md
output/CLAUDE.md, output/AGENTS.md

Claude와 Codex가 어떤 계층에 들어와도 그 경계와 규칙을 읽을 수 있도록 하는 구조입니다. 이 항목은 처음 계획에 없었습니다. Codex가 실행하면서 자연스럽게 제안했습니다.

실제 저장소 검증이 문서 충돌을 드러냈습니다

이번 작업에서 가장 중요했던 지점은 검증 방법이었습니다.

처음엔 그냥 계획서를 다른 LLM에게 검토시키는 식으로 생각했습니다. 그런데 그게 아니었습니다.

Codex가 한 건 이거였습니다.

1. 실제 디렉토리 상태 확인
2. 테스트(pytest) 실행
3. 계약 문서(AGENTS.md, publishing-contract) 교차 검토
4. lint 검증

문서를 읽는 게 아니라, 실제 저장소 상태와 계획서를 맞닿게 했습니다. 그래서 계획서 안에서는 보이지 않던 충돌이 드러났습니다.

만약 문서만 검토했다면 docs/images → raw/assets 문제는 발견하지 못했을 것입니다.

구조 정리는 운영 원칙을 더 선명하게 만들었습니다

구조 변경을 실행하면서 자연스럽게 따라온 것들이 있습니다.

Claude의 /wiki:ingest 같은 command와 Codex의 wiki-ingest 같은 skill을 병행 구조로 운용하기로 했습니다. 같은 기능을 두 곳에 구현하면 중복처럼 보이지만, 실제로는 진입점이 다를 뿐입니다. 이전 글에서 "입구는 나눴지만 철학은 통일했다"고 쓴 것의 구체적 실현이었습니다.

raw/ 불변 원칙도 더 강하게 문서화됐습니다. "수정하지 않는다"에서 "절대 직접 수정하지 않는다"로. 말은 비슷한데 의도하는 강도가 달라집니다.

Claude는 계획을 만들고 Codex는 검증과 실행을 맡았습니다

Claude로 계획서를 썼습니다. Codex가 실제 저장소와 맞닿게 검증했습니다. 두 가지 문제가 나왔습니다. 계획을 다시 짰고, Codex가 실행했습니다.

이 패턴을 이름 붙이면 이렇습니다.

Plan(Claude) → Validate(Codex) → Execute(Codex)

Claude가 잘하는 건 맥락을 유지하며 계획을 언어화하는 것입니다. Codex가 잘하는 건 실제 저장소 상태를 바닥까지 확인하며 실행하는 것입니다.

두 도구를 경쟁 관계로 보면 아무것도 안 보입니다. 역할을 나눠서 파이프라인으로 연결하면, 하나가 놓치는 걸 다른 하나가 잡아냅니다.

그리고 하나 더. 혼자 만든 계획서는 자기 문서 안에서만 완결됩니다. 실제 저장소와 맞닿는 검증이 필요하다는 걸, 이번에 확실히 배웠습니다.