서론

지난 기사에서는 비누 브랜드 사이트의 기술 선정(Astro + microCMS + Cloudflare Pages)에 대해 작성했습니다. 이번에는 그 내용, 즉 "실제로 어떻게 만들었는가"에 대한 이야기입니다.

이번 사이트는 모두 Claude Code로 구현했습니다. 사용한 것은 superpowers 플러그인의 subagent-driven-development(이하 sdd)라는 스킬입니다.

이 구성을 시도하게 된 계기는 "Claude Code가 변했다. 현재 사용 중인 3가지 플러그인 + 표준 기능 활용법"이라는 기사였습니다. Status line, genshijin, dig, superpowers와 같은 확장 기능의 조합이 소개되어 있었고, 이를 자신의 프로젝트에서도 시도해 보고 싶다고 생각한 것이 출발점입니다. 본 기사에서는 그중에서도 subagent-driven-development에 집중하여, 실제 브랜드 사이트 구축에서 어떻게 기능했는지를 기록합니다.

subagent-driven-development란

sdd는 한마디로 말하면, "구현 계획을 태스크 단위로 분할하고, 태스크마다 서브 에이전트(sub-agent)에게 구현을 맡기며, 그때마다 리뷰하여 진척 대장에 기록하는" 개발 플로우입니다. 하나의 거대한 세션에 전부 몰아넣는 것이 아니라,

• 구현 계획(plan)을 태스크로 분해한다
• 태스크마다 "brief"(지시서)를 만든다
• 서브 에이전트가 brief에 따라 구현하고, "report"(완료 보고)를 반환한다
• 직전 태스크와의 차이(diff)를 별도로 리뷰한다
• 결과를 "progress ledger"에 기록하고 다음 태스크로 진행한다

라는 단위로 루프를 돌립니다. 태스크 하나마다 구현·확인·기록이 종결되므로, 나중에 "어느 태스크에서 무엇이 일어났는지" 추적하기 쉽다는 것이 특징입니다.

실제 운용 사례

이번 사이트는 사전에 작성한 구현 계획(docs/superpowers/plans/2026-07-20-soap-ec-site-phase1.md)을 바탕으로 다음과 같이 9개의 태스크로 분할했습니다.

코드가 포함된 Task 1~7은 모두 sdd로 진행하였고, Task 8·9는 Cloudflare 대시보드 조작을 동반하기 때문에 수동 작업으로 분리했습니다. "어디까지를 AI에게 맡기고, 어디서부터 인간이 할 것인가"를 태스크 단위로 명확하게 선을 그을 수 있는 것도, 세세하게 태스크를 분할해 두었을 때의 장점이라고 느꼈습니다.

brief의 내용

각 태스크의 brief에는 생성/변경할 파일, 구현해야 할 인터페이스, 그리고 구체적인 구현 코드와 단계가 적혀 있습니다. 예를 들어 Task 6(NewsCard + news 목록 페이지)의 brief는 다음과 같은 입도입니다.

### Task 6: NewsCard + news 목록 페이지
**Files:**
- Create: `src/components/NewsCard.astro`
...

코드 자체가 brief에 거의 작성되어 있기 때문에 구현의 자유도는 높지 않습니다. 뒤집어 말하면, "설계 판단은 계획 단계에서 끝내두고, 구현 페이즈에서는 고민하게 만들지 않는다"라는 역할 분담이 되어 있습니다.

report의 내용

구현 후에는 서브 에이전트가 completion report를 반환합니다. Task 6의 report는 다음과 같은 구성이었습니다.

# Task 6: NewsCard + news 목록 페이지 — Completion Report
## Status: DONE
### Files Created
...

빌드 결과·QA 체크리스트·커밋 해시(commit hash)까지 세트로 반환되므로, 리뷰 담당자(본인)는 report를 읽는 것만으로 "무엇을 확인해야 하는지" 알 수 있습니다.

리뷰 메커니즘

sdd의 또 다른 기둥은 태스크별 차이(diff) 리뷰입니다. 각 태스크 완료 후, 직전 커밋으로부터의 diff만을 잘라낸 리뷰 패키지(review-<from>..<to>.diff)가 만들어지며, 이를 보고 좋고 나쁨을 판단합니다.

판단 결과는 progress.md라는 진척 대장에 한 줄씩 축적됩니다. 실제 로그는 다음과 같은 느낌이었습니다.

## Task 3: BaseLayout + Header + Footer — COMPLETE
commits: fa58b5e..4c92f64, review clean
Minor notes:
...

「review clean(문제 없음)」으로 끝나는 태스크도 있었고, Task 3처럼 경미한 지적 사항(og:url 설정 누락 등)이 기록되는 태스크도 있었습니다. 이 지적 사항들은 최종적으로 모든 태스크가 완료된 후의 최종 브랜치 리뷰 (Final Branch Review) (커밋 8cdc5a2)에서 한꺼번에 확인하여 수정했습니다.

## 최종 브랜치 리뷰 — COMPLETE
commits: b17bbdb..8cdc5a2
수정 완료: mock-3 404, og:url, nav active state, news meta description

태스크 단위 리뷰에서 "현재 범위에서는 문제없음"이라며 넘겼던 경미한 지적 사항이, 후속 공정에서 제대로 포착되어 해소됩니다. 이러한 2단계 체크 체제는 실제로 실행해 보았을 때 좋았다고 느낀 포인트입니다.

좋았던 점 · 어려웠던 점

좋았던 점

• 태스크의 경계가 명확하여, 도중에 작업을 중단하더라도 progress.md를 보면 "어디까지 끝났는지"를 한눈에 알 수 있었습니다.
• diff만 리뷰하는 운영 방식 덕분에, 9개 태스크 분량의 변경 사항을 하나의 거대한 PR (Pull Request)로 읽을 필요가 없어 리뷰 부하가 적었습니다.
• 수동 작업 (Task 8·9의 Cloudflare 설정)을 계획 안에 명시적으로 포함할 수 있었기에, "AI가 수행할 범위"와 "사람이 수행할 범위"의 경계가 모호해지지 않았습니다.

어려웠던 점

• Brief (지시서)의 입도를 어디까지 세밀하게 작성할지 판단하는 것이 처음에는 어려웠습니다. Task 2 (MicroCMS 클라이언트)는 TDD (테스트 주도 개발)로 작성한 테스트 코드까지 Brief에 포함했으나, 코드를 너무 많이 작성하면 서브 에이전트 (Subagent)의 재량이 거의 제로가 되어 "지시서를 그대로 받아 적게 하는 것"에 가까워지는 상황도 있었습니다.
• 태스크 단위 리뷰에서 "현재 문제없음"이라며 넘긴 지적 사항(Header의 활성화 상태 판정 등)이 최종 리뷰까지 밀리게 됩니다. 미결 리스트 자체는 progress.md에 남기 때문에 실질적인 피해는 없었지만, 건수가 많은 프로젝트라면 최종 리뷰의 부담이 커질 수 있다는 우려가 있습니다.

요약

subagent-driven-development는 구현 계획만 제대로 세워져 있다면, "태스크 전달 → 구현 → diff 확인 → 기록"이라는 루프를 담담하게 돌리는 것만으로도 규모가 있는 사이트를 기능별로 착실히 쌓아 올릴 수 있는 개발 플로우였습니다. 특히 이번과 같은 "페이지 수는 많지만 페이지당 복잡도는 그리 높지 않은" 타입의 프로젝트(LP, 기업 사이트, 문서 사이트 등)와 궁합이 좋다고 느꼈습니다.

반대로, 태스크 간의 의존 관계가 복잡하여 "구현하면서 설계를 조정"해야 하는 필요성이 큰 프로젝트에서는 Brief를 작성하는 단계의 비용(≒설계 비용)이 상대적으로 무거워질 것이므로, 그 경우에는 다른 워크플로우(brainstorming을 통해 미리 사양을 확정하는 방식 등)와 조합하는 것이 좋아 보입니다.

Discussion