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가 한 확인은 이랬어요.
- 임시 글을 넣은 빌드(
DRAFTS=1)와 뺀 빌드를 각각 돌려서 글 페이지, 404, RSS, 사이트맵이 제대로 나오는지 봤어요. - 공유 이미지(OG 이미지) PNG를 직접 열어서 제목이 카드 안에 들어가는지 확인했어요.
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가 초안을 썼어요.