Claude Code로 288페이지 SEO 구현 계획을 63번의 tool call로 완성한 방법
코드를 단 한 줄도 짜지 않고 20시간, 63번의 tool call을 썼다. 그리고 이게 맞는 접근이었다.
TL;DR writing-plans 스킬로 먼저 구현 계획을 문서화하고, subagent-driven development로 실행 준비를 마쳤다. 코딩 없이 설계에만 집중하는 세션은 이후 실행 속도를 극적으로 끌어올린다.
문제: 288페이지, 어디서부터 시작하나
사주 앱(saju_global)에 SEO 궁합 랜딩 페이지 288개를 추가하는 작업이었다. 12간지 × 12간지 = 144개 조합, 남녀 반전 포함 288페이지. 스펙 문서는 있었지만, 바로 코딩을 시작하면 어떤 일이 생기는지 잘 안다 — 중간에 막히고, 방향이 틀어지고, 뒤늦게 설계를 바꾼다.
그래서 먼저 writing-plans 스킬을 호출했다.
writing-plans 스킬: 코딩 전에 계획을 문서로 만든다
/writing-plans → saju_global SEO 궁합 랜딩 288페이지
이 스킬의 전제는 하나다: 실행 에이전트가 코드베이스를 처음 보는 신입이라고 가정하고 계획을 쓴다. 파일 경로, 기존 패턴, 스키마까지 전부 명시한다.
계획을 쓰기 전에 먼저 코드베이스를 읽었다. Read 13회, Glob 4회. 현재 라우팅 구조, 기존 SEO 메타 태그 패턴, i18n 설정, Content Collection 스키마를 직접 읽어서 확인했다. 기억이나 추측으로 계획을 쓰지 않는다 — CLAUDE.md에도 명시된 규칙이다.
첫 시도에서 스펙 파일 경로가 맞지 않았다. 멈추지 않고 Glob으로 docs/superpowers/specs/ 디렉토리를 직접 스캔해서 실제 파일을 찾아냈다. 에러가 났을 때 사용자에게 묻는 대신 스스로 해결한 케이스다.
결과물: docs/superpowers/plans/2026-04-10-seo-compatibility-pages.md
이 파일 하나에 다음이 모두 들어간다:
- 건드려야 할 파일 목록과 변경 이유 (경로 포함)
- 태스크별 실행 순서
- 테스트 방법
- 커밋 단위 분리 기준
계획 문서가 없으면 에이전트를 여러 개 돌릴 수 없다. 스코프가 겹치면 충돌이 나기 때문이다.
Agent 16회: 탐색과 태스크 설계의 도구
총 63회 tool call 중 Agent가 16회로 가장 많다. 이건 코드를 짜기 위한 게 아니었다. 두 가지 목적이었다:
1. 코드베이스 탐색 위임. 기존 SEO 구현 패턴, 라우팅 구조, i18n 설정을 파악하는 작업을 Explore 에이전트에게 넘겼다. 메인 컨텍스트를 탐색 결과물로 채우지 않기 위해서다.
2. 계획 검토. 계획 초안을 쓰고 나서 독립적인 에이전트로 리뷰를 돌렸다. 계획을 쓴 컨텍스트와 다른 시선이 필요하다.
TaskCreate 7회, TaskUpdate 13회 — 서브에이전트 실행을 위한 태스크 트래킹이다. 구현 세션에서 각 에이전트가 어떤 태스크를 맡을지 미리 정의해둔 것이다.
subagent-driven development 준비
계획이 완성되면 그 다음은 실행 방식 선택이다. 두 가지 옵션이 있었다:
- Subagent-driven: 태스크별로 독립 에이전트 디스패치 → 중간 리뷰 → 반복
- Inline: 현재 세션에서 순차 실행
288페이지라는 규모를 감안하면 답은 하나였다. 서브에이전트로 분산해야 속도가 나온다.
실행 전에 워크트리부터 만들었다. main 브랜치에서 직접 작업하면 실험적인 변경이 섞인다. 워크트리를 쓰면 main은 깨끗하게 유지된다.
git worktree add ../saju-seo-pages feature/seo-compat-pages
이후 구현 세션에서는 계획 문서를 그대로 태스크로 쪼개서 에이전트에게 하나씩 넘긴다. 에이전트별 스코프가 계획 단계에서 이미 정해져 있으니 충돌이 없다.
계획만 20시간을 쓰는 게 맞는가
처음엔 이 질문이 든다. 코드 한 줄 없이 세션을 끝내는 게 맞는 건지.
계획 없이 구현을 시작하면 태스크 하나가 끝날 때마다 방향을 재조정한다. 에이전트가 스코프를 벗어나거나, 기존 패턴을 무시하거나, 파일 충돌이 생긴다. 수정하는 데 계획보다 더 많은 시간이 든다.
288페이지짜리 작업을 계획 없이 에이전트에게 넘기면 — 절반쯤에서 멈추고 처음부터 다시 해야 할 가능성이 높다. writing-plans → subagent-driven development로 세션을 분리하면 각 세션이 단일 책임을 갖는다. 계획 세션은 계획만, 실행 세션은 실행만.
정리
- 스케일이 큰 작업일수록 계획 문서를 먼저 만든다. 코드베이스를 직접 읽고, 파일 경로와 패턴을 계획에 명시한다.
- 탐색은 Explore 에이전트에게 위임한다. 메인 컨텍스트는 판단과 조율에만 쓴다.
- 태스크 트래킹은 구현 전에 세팅한다. 에이전트별 스코프를 미리 정의하지 않으면 병렬 실행에서 충돌이 난다.
- 워크트리는 기본값이다.
main을 깨끗하게 유지하는 비용은 0이고, 롤백 비용은 크다.
이번 세션 통계: 63 tool calls — Agent(16), Read(13), TaskUpdate(13), TaskCreate(7), Bash(5), Glob(4), Skill(2), Write(1). 생성 파일 1개. 수정 파일 0개.
Comments 0