Claude로 계획하고 Codex로 검증한 저장소 구조 리팩토링

지난 글에서 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가 한 건 문서를 읽는 게 아니었다. 실제 저장소 상태를 뒤졌다.

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

결과로 두 가지 문제를 찾아냈다.

문제 1: docs/images → raw/assets 전환이 publish 계약과 충돌

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

문제 2: 계획 문서 자체가 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가 실제 저장소와 맞닿게 검증했다. 두 가지 문제가 나왔다. 계획을 다시 짰다. Codex가 실행했다.

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

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

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

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

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

---