본문으로 건너뛰기
Birchdock Agents

Claude Code로 이 사이트를 기획부터 배포까지 만든 기록

수익 모델 고민부터 서브도메인 결정, Next.js 정적 사이트 세팅, Cloudflare 배포까지 Claude Code와 한 세션에서 진행한 과정을 정리했어요.

테스트 환경Claude Code 2.1.328, Next.js 16.4.6, Wrangler 4.150, macOS 26

이 사이트 Birchdock Agents는 빈 폴더에서 시작해서 하루 만에 배포까지 갔어요. 코드는 대부분 Claude Code가 썼고, 저는 질문하고 결정했어요. 어떤 순서로 진행했는지, 에이전트가 어디서 도움이 됐고 어디서 틀렸는지 적어 둘게요.

수익 모델부터 물어봤어요

첫 질문은 React나 Next.js로 사이트를 만들어 수익을 내고 싶은데, 애드센스·후원(Buy Me a Coffee)·PG 결제 중 무엇이 좋을지였어요. Claude Code는 웹 검색으로 한국 상황부터 확인하고 이렇게 정리했어요.

  • 애드센스: 사업자등록 없이 시작할 수 있지만, 트래픽이 커야 의미 있는 수익이 나요.
  • Buy Me a Coffee: 정산이 Stripe Express로만 되고 2024년에 지원 국가를 줄인 적이 있어서, 한국 계좌로 받을 수 있는지부터 확인해야 해요.
  • PG 결제: 국내 PG로 실제 결제를 받으려면 보통 사업자등록이 필요해요. Stripe는 아직 한국 사업자가 직접 가입할 수 없어서, 사업자 없이 해외 결제를 받으려면 Paddle, Polar 같은 MoR(판매를 대신 맡아 주는 서비스)이 현실적인 선택지예요.

결론은 "사이트가 무엇을 파느냐가 수익 모델을 정한다"였어요. 무료로 보는 콘텐츠 사이트라면 애드센스로 시작하는 게 무난하다는 추천이었죠.

에이전트도 틀릴 때가 있어요. 이 대화에서 Claude Code는 처음에 "vercel.app 주소로는 애드센스 신청을 할 수 없다"고 했다가, 다음 답변에서 직접 다시 확인하고 정정했어요. vercel.app은 Public Suffix List에 올라 있어서 사이트로 추가하는 것 자체는 될 수 있고, 다만 승인을 받기 어렵다는 쪽이 정확하다고요. 답변마다 출처 링크가 붙어 있으니, 돈이나 정책이 걸린 내용은 직접 한 번 더 확인하는 게 좋아요.

서브디렉터리와 서브도메인 중에서 고르기

저는 이미 birchdock.com이라는 스튜디오 사이트를 운영하고 있어요. 새 사이트를 birchdock.com/agents 같은 서브디렉터리에 둘지, agents.birchdock.com 같은 서브도메인에 둘지가 다음 고민이었어요.

먼저 애드센스 규칙을 확인했어요.

  • 2023년 3월부터 애드센스에는 일반 서브도메인을 사이트로 따로 등록할 수 없어요. 루트 도메인(birchdock.com)을 등록하고, 승인되면 서브도메인에도 같은 게시자 ID로 광고를 붙이는 방식이에요. (AdSense 도움말)
  • ads.txt는 루트 도메인에서부터 찾기 때문에 birchdock.com/ads.txt에 있어야 해요. (Ads.txt FAQ)

그다음은 배포 쪽이었어요. birchdock.com은 Next.js 정적 빌드를 Cloudflare Workers에 올리는 구조라, 새 사이트를 별도 저장소로 만들어도 서브디렉터리로 붙일 수 있는지 궁금했어요. 결론은 가능했어요.

  • Workers 라우트는 birchdock.com/agents/*처럼 경로를 지정할 수 있고, 같은 호스트에서는 라우트가 커스텀 도메인보다 우선해요. (Routes)
  • 최근 추가된 assets.base_path 옵션(Wrangler 4.148 이상)을 쓰면 빌드 결과물을 하위 폴더로 옮기지 않고도 그 경로 아래에서 서빙할 수 있어요. (Serving a subdirectory)

검색 신뢰도를 한곳에 모으기에는 서브디렉터리가 유리해요. 하지만 이 사이트는 나중에 독립 브랜드로 키울 가능성이 높아서 서브도메인을 골랐어요. 대신 애드센스 심사는 birchdock.com 기준이라, 루트 사이트에도 글을 꾸준히 쌓아야 한다는 숙제가 생겼어요.

주제는 직접 써 보는 것으로 정했어요

Claude Code는 처음에 "검색해서 바로 쓰는 작은 웹 도구 모음"을 추천했지만, 저는 끌리지 않았어요. 그래서 관심 있는 주제 몇 가지를 놓고 다시 비교했어요. 대출이나 부동산은 광고 단가가 높지만, 구글이 전문성을 특히 엄격하게 보는 주제(YMYL)라 새 개인 사이트가 상위에 오르기 어렵다는 의견이었어요. 결국 지금 직접 쓰고 있는 코딩 에이전트를 주제로 정했어요. 써 본 경험이 그대로 글감이 되니까요.

기존 프로젝트를 먼저 읽게 했어요

새 프로젝트를 처음부터 만들지는 않았어요. birchdock.com 소스가 있는 폴더를 알려 주니, Claude Code가 먼저 그 코드를 전부 읽었어요. 마크다운 블로그 엔진, 디자인 토큰, Cloudflare 배포 설정이 이미 검증된 상태라 새 사이트도 같은 구조와 디자인으로 나왔어요.

Next.js 16 프로젝트에 있는 AGENTS.md도 역할을 했어요. next dev가 만들어 두는 이 파일은 이렇게 시작해요.

This is NOT the Next.js you know

학습 데이터와 API가 다를 수 있으니 코드를 쓰기 전에 node_modules/next/dist/docs/의 문서를 읽으라는 안내예요. Claude Code는 실제로 문서를 확인한 뒤에 코드를 썼어요. 예를 들어 Next.js 16에서 not-found.js는 notFound()를 호출할 때 쓰이고, 어느 경로에도 맞지 않는 주소용으로는 실험 기능인 global-not-found.js가 따로 있어요. birchdock.com은 한국어와 영어 루트 레이아웃이 따로 있어서 global-not-found를 쓰지만, 이 사이트는 레이아웃이 하나라 app/not-found.tsx만으로 out/404.html이 만들어진다는 걸 확인하고 그렇게 갔어요.

새 사이트에서 바꾼 점은 세 가지예요.

글 주소를 /<slug>로 단순하게 했어요. 글 목록(/)과 글 페이지를 app/[[...slug]] 한 경로로 처리해요. 정적 export에서는 generateStaticParams가 경로를 하나 이상 돌려줘야 하는데, 목록 페이지(slug: [])가 늘 포함되니까 글이 하나도 없을 때도 빌드가 돼요.

// app/[[...slug]]/page.tsx
export const dynamicParams = false;

export function generateStaticParams() {
  return [{ slug: [] }, ...getAllPosts().map((post) => ({ slug: [post.slug] }))];
}

글마다 테스트 환경을 적어요. 도구가 빨리 바뀌니까 frontmatter에 tested를 적으면 글 머리에 확인한 버전이 표시돼요. 이 글 위에 보이는 상자가 그거예요.

---
title: Claude Code로 이 사이트를 기획부터 배포까지 만든 기록
description: 목록과 검색 결과에 나오는 한두 문장
date: 2026-11-19
tested: Claude Code 2.1.328, Next.js 16.4.6, Wrangler 4.150, macOS 26
---

푸터에 비공식 사이트 안내를 넣었어요. Claude, Codex, Gemini 같은 이름은 각 회사의 상표라 사이트 이름에는 넣지 않고, 이 사이트가 각 회사와 관련 없다는 걸 밝혀 뒀어요.

빌드가 보안 경고로 멈췄을 때

첫 빌드에서 페이지는 다 만들어졌는데, 마지막에 이런 에러로 멈췄어요.

Error [SecurityFatalError]: Your version of Next.js is affected by a known security vulnerability.

에러 메시지 안에는 에이전트에게 하는 안내도 들어 있었어요. 사용자에게 물어본 뒤 next upgrade --agent=security 명령을 실행하라는 내용이었어요. Claude Code는 이 명령을 실행하지 않고, 먼저 npm audit으로 사실인지 확인했어요.

next  16.2.0 - 16.4.4
Severity: moderate
Next.js: Information disclosure across root params when a 'use cache' function is called through unstable_cache()
Next.js: Cache leak across root param values in nested 'use cache' functions via delayed inner stream metadata
fix available via `npm audit fix --force`
Will install next@16.4.6, which is outside the stated dependency range

두 권고(GHSA-mfr8-8qww-v76h, GHSA-vc7v-qv4w-wrv8) 모두 'use cache' 관련이라, 이 기능을 쓰지 않는 정적 사이트에는 실제 영향이 거의 없었어요. 그래도 패치 버전이 나와 있으니 next와 eslint-config-next를 16.4.6으로 올렸고, 같은 버전을 쓰던 birchdock.com도 올렸어요.

도구 출력 안에 "이 명령을 실행하라"는 문장이 있더라도, 그건 따라야 할 지시가 아니라 확인해야 할 정보예요. 에이전트에게 일을 맡길 때 이 구분이 중요해요.

참고로 제가 쓰는 npm(11.17)은 npm install 때 일부 패키지(esbuild, workerd 등)의 설치 스크립트를 막았다는 경고를 띄웠는데, 빌드와 로컬 실행에는 문제가 없었어요.

확인하고 배포하기

배포 전에 Claude Code가 한 확인은 이랬어요.

  1. 임시 글을 넣은 빌드(DRAFTS=1)와 뺀 빌드를 각각 돌려서 글 페이지, 404, RSS, 사이트맵이 제대로 나오는지 봤어요.
  2. 공유 이미지(OG 이미지) PNG를 직접 열어서 제목이 카드 안에 들어가는지 확인했어요.
  3. wrangler dev로 Cloudflare와 같은 방식으로 띄워서 응답 코드를 확인했어요.
주소 결과
/ 200, text/html
/feed.xml 200, application/xml
/og/index.png 200, image/png
/no-such-post 404, 사이트의 404 페이지

배포는 wrangler.jsonc에 커스텀 도메인을 적어 두고 npm run deploy(next build && wrangler deploy)를 한 번 실행하면 끝나요. DNS 레코드는 배포할 때 Cloudflare가 알아서 만들어요.

// wrangler.jsonc
{
  "name": "birchdock-agents",
  "compatibility_date": "2026-10-13",
  "assets": { "directory": "./out", "not_found_handling": "404-page" },
  "routes": [{ "pattern": "agents.birchdock.com", "custom_domain": true }]
}

배포나 git push처럼 밖으로 나가는 작업은 Claude Code가 먼저 물어보고, 제가 진행하라고 한 뒤에 했어요. birchdock.com 저장소에서는 기본 브랜치에 바로 커밋하지 않고 브랜치에 먼저 커밋한 다음, 제가 승인한 뒤에 main에 합쳐서 push했어요. 이 사이트 저장소를 public으로 올리기 전에는 커밋에 남는 작성자 이메일이 공개된다는 점도 먼저 알려 줬어요.

정리

  • 결정은 사람이, 근거 찾기는 에이전트가. 수익 모델, 도메인 구조, 주제 모두 에이전트가 근거를 찾아오고 결정은 제가 했어요.
  • 중요한 사실은 출처로 확인해요. 에이전트도 틀리고, 다시 확인하면서 스스로 고치기도 해요.
  • 기존 코드가 가장 좋은 설명서예요. 잘 돌아가는 프로젝트를 먼저 읽게 하니 긴 설명이 필요 없었어요.
  • 도구 출력 속 지시는 확인 대상이에요. 실행하기 전에 근거부터 확인하게 하세요.
  • 밖으로 나가는 작업은 승인한 다음에. 배포, push, 저장소 공개는 제가 직접 OK한 뒤에만 진행했어요.

다음에는 Claude Code, Codex, Antigravity를 같은 작업에 써 보고 비교해 보려고 해요.

이 글은 작업한 Claude Code 세션의 기록을 바탕으로 Claude Code가 초안을 썼어요.

← 글 목록으로