RSS Feed of JavaPark

AI 에이전트란? 2026년 현재 총정리 — 챗봇과 뭐가 다르고, 뭘 할 수 있나

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

"AI 에이전트가 대세라는데, 그게 ChatGPT랑 뭐가 다른 건가요?"

솔직히 말하면, 저도 처음엔 헷갈렸습니다. 챗봇, 코파일럿, 에이전트 — 다 AI 아닌가? 근데 직접 써보면 완전히 다른 경험입니다.

결론부터 말씀드리면 — 챗봇은 대화하고, 코파일럿은 도와주고, 에이전트는 직접 일합니다. 2026년 현재 AI 에이전트 시장은 $7.6B 규모로, 챗봇 시장 성장률의 2배 속도로 커지고 있습니다. 오늘은 이 모든 것을 한 번에 정리해보겠습니다.

AI 에이전트란? — 30초 정의

AI 에이전트(AI Agent)는 목표를 받으면, 스스로 계획을 세우고, 도구를 사용해서, 여러 단계에 걸쳐 작업을 실행하는 AI 시스템입니다.

비유하자면 이렇습니다:

	챗봇	코파일럿	AI 에이전트
비유	안내 데스크 직원	옆에서 도와주는 동료	업무를 위임받은 대리인
하는 일	질문에 답변	작업을 보조	목표를 받아 자율적으로 실행
자율성	낮음 (반응형)	중간 (제안형)	높음 (실행형)
작업 범위	대화창 안	특정 앱 안	여러 시스템을 넘나듦
인간 개입	매번 필요	승인/거절	최소한의 감독

한 줄로 요약하면:

챗봇 → 대화를 최적화
코파일럿 → 개인 생산성을 최적화
에이전트 → 프로세스 처리량을 최적화

AI 에이전트 실전 예시 — 챗봇·코파일럿과 비교

같은 작업을 세 가지 방식으로 비교해보면 차이가 확 느껴집니다.

"매월 12개 부서 보고서를 합쳐서 경영진 요약 보고서를 만들어라"

방식	실제 작업 과정
챗봇	"보고서를 합치는 방법을 알려줘" → 방법을 텍스트로 설명 → 사람이 직접 실행
코파일럿	엑셀에서 작업 중 "이 수식 추천해줘" → 수식 제안 → 사람이 수락하고 실행
에이전트	"12개 파일 합쳐서 요약 보고서 만들어줘" → 파일 읽기 → 데이터 합치기 → 분석 → 보고서 생성까지 직접 수행

에이전트는 결과물까지 만들어냅니다. 사람은 최종 확인만 하면 됩니다.

2026년 AI 에이전트 주요 플랫폼 — 한눈에 비교

코딩 에이전트

개발자에게 가장 직접적인 AI 에이전트 카테고리입니다.

도구	개발사	특징	작동 방식
Claude Code	Anthropic	서브에이전트, Hook, 1M 컨텍스트, MCP	터미널 / VS Code / 브라우저
Codex CLI	OpenAI	클라우드 샌드박스, 병렬 실행	터미널
Gemini CLI	Google	Gemini 3, 1M 컨텍스트, Extensions	터미널
Cursor	Anysphere	$500M+ ARR, 병렬 에이전트 8개	IDE (VS Code 포크)
Devin	Cognition	가장 자율적, 클라우드 IDE	웹 / Slack
GitHub Copilot	Microsoft	Agent Mode, VM 자동 실행, PR 생성	IDE / 웹

이 블로그에서 다뤄온 Claude Code, Codex CLI, Gemini CLI도 모두 AI 에이전트입니다. 터미널에서 자연어로 지시하면 파일을 읽고, 코드를 작성하고, 테스트를 실행하는 — 그 전체 과정이 "에이전트"입니다.

브라우저 에이전트

2025~2026년 가장 폭발적으로 성장한 카테고리입니다. AI가 직접 브라우저를 조작합니다.

도구	개발사	특징
ChatGPT Agent (Operator)	OpenAI	CUA 모델 기반, 스크린샷으로 화면을 "보고" 마우스/키보드로 "조작"
Project Mariner	Google	Chrome 확장, 동시 10개 작업, WebVoyager 83.5% (SOTA)
Atlas	OpenAI	전용 AI 브라우저, Agent Mode로 다단계 작업

예: "항공편을 검색해서 가격 비교하고, 가장 저렴한 옵션을 정리해줘"
→ AI가 브라우저를 열고, 검색 사이트를 탐색하고, 결과를 표로 정리

워크플로우/비즈니스 에이전트

개발 없이도 업무 프로세스를 자동화합니다.

도구	개발사	규모
Copilot Studio	Microsoft	160,000+ 조직 배포
Agentforce	Salesforce	$540M ARR

이메일 발송, 문서 생성, CRM 업데이트, 회의 예약 등을 로우코드/노코드로 구축합니다.

AI 에이전트를 연결하는 두 가지 표준 — MCP와 A2A

에이전트가 강력한 이유는 외부 도구와 연결할 수 있기 때문입니다. 2026년 현재 두 가지 표준이 자리잡았습니다.

MCP (Model Context Protocol) — AI와 도구를 연결

Anthropic이 만들고, 현재 Linux Foundation 산하로 이관된 오픈소스 표준입니다.

AI 모델 ←→ MCP ←→ 외부 도구 (Slack, Google Drive, Jira, DB 등)

2024년 11월 출시 → 2026년 3월 현재 월간 9,700만 다운로드
5,800+ MCP 서버, 300+ MCP 클라이언트
OpenAI, Google, Microsoft 모두 채택
AI 세계의 "USB-C" — 어떤 모델이든, 어떤 도구든 하나의 표준으로 연결

A2A (Agent-to-Agent) — AI 에이전트 간 통신

Google이 만든 오픈 프로토콜로, 에이전트끼리 대화하고 협업하는 표준입니다.

영업 에이전트 ←→ A2A ←→ 재무 에이전트 ←→ A2A ←→ HR 에이전트

150개 이상 조직 참여 (Atlassian, PayPal, Salesforce, SAP 등)
Agent Card: JSON 형태로 "나는 이런 일을 할 수 있어"를 광고
다른 에이전트가 Agent Card를 보고 최적의 협업 상대를 찾아 통신

MCP vs A2A 차이:

MCP = AI ↔ 도구 (수직적 연결)
A2A = AI ↔ AI (수평적 연결)
둘은 경쟁이 아니라 상호 보완 관계

2026년 AI 에이전트 핵심 트렌드 5가지

1. 멀티 에이전트 시스템의 부상

혼자 일하는 에이전트에서 팀으로 일하는 에이전트로 전환되고 있습니다.

Gartner에 따르면 멀티 에이전트 시스템 관련 문의가 1,445% 급증했습니다. "퍼핏티어(Puppeteer)" 역할의 오케스트레이터가 전문 에이전트들을 조율하는 구조입니다.

오케스트레이터 에이전트
  ├── 코드 작성 에이전트
  ├── 코드 리뷰 에이전트
  ├── 테스트 에이전트
  └── 배포 에이전트

2. 장기 실행 자율 워크플로우

단일 프롬프트 → 단일 응답이 아니라, 며칠간 실행되는 작업 루프가 등장했습니다.

에이전트가 전체 애플리케이션을 구축하고, 인간은 전략적 결정 포인트에서만 개입합니다. Claude Code의 백그라운드 태스크, Devin의 클라우드 실행이 대표적입니다.

3. 비개발자의 에이전트 시대

Microsoft Copilot Studio, Salesforce Agentforce처럼 코드 없이 에이전트를 만드는 플랫폼이 본격화됐습니다. "비즈니스 사용자가 엔지니어가 아닌데도 에이전트를 만들고 있다"는 게 2026년의 현실입니다.

4. 에이전트 프레임워크 통합

각 빅테크가 에이전트 프레임워크를 출시했습니다:

개발사	프레임워크
Anthropic	Claude Agent SDK
OpenAI	Agents SDK
Google	Agent Development Kit (ADK)
Microsoft	Semantic Kernel + AutoGen

커뮤니티에서도 LangGraph, CrewAI, Mastra 등이 경쟁 중입니다.

5. MCP가 인프라 표준으로 확장

2025년이 "채택의 해"였다면, 2026년은 "확장의 해"입니다. Anthropic, OpenAI, Block이 공동 설립한 **Agentic AI Foundation(AAIF)**이 Linux Foundation 산하에서 MCP를 관리합니다.

AI 에이전트의 위험과 한계 — 솔직한 정리

AI 에이전트가 만능은 아닙니다. 알고 쓰는 게 중요합니다.

할루시네이션 — "자신감 있게 틀리는" 문제

에이전트는 자신의 능력 한계를 모릅니다. 전문 지식이 필요한 상황인데도 자신 있게 답을 내놓을 수 있습니다. 고위험 작업에서는 반드시 사람의 검증이 필요합니다.

보안 — 과도한 권한 문제

보고에 따르면 90%의 에이전트가 필요한 것보다 10배 많은 권한을 가지고 있습니다. 도구 연결이 늘어날수록 위험이 곱셈으로 증가합니다. 간접 프롬프트 인젝션(웹페이지에 숨겨진 악의적 지시)도 실제 위협입니다.

비용 — 과소평가되는 현실

Gartner에 따르면 CIO들이 AI 비용을 최대 1,000%까지 과소평가한다고 합니다. 특히 에이전트를 확장하고 유지하는 비용이 예상보다 큽니다.

실패율 — 40% 이상 실패 예상

에이전트 프로젝트의 40% 이상이 2027년까지 실패할 것이라는 Gartner 예측이 있습니다. 기술이 아니라 거버넌스(통제, 소유권, 신뢰 관리)가 가장 큰 장벽입니다.

비개발자용 AI 에이전트 추천 — 지금 바로 시작하기

"에이전트가 뭔지는 알겠는데, 나는 뭘 쓰면 되나요?"

목적	추천 도구	월 비용
파일/데이터 정리	Claude Code	$20 (Pro)
웹 작업 자동화	ChatGPT Agent (Operator)	$20 (Plus)
업무 프로세스 자동화	Copilot Studio	M365 구독
코딩	Claude Code, Cursor	$20~

가장 진입 장벽이 낮은 건 Claude Code입니다. 터미널에서 자연어로 지시하면 파일을 직접 읽고, 수정하고, 생성합니다. 비개발자도 쓸 수 있다는 걸 이전 포스팅에서 다뤘습니다.

자주 묻는 질문 (FAQ)

AI 에이전트가 내 일자리를 대체하나요?

단기적으로는 "대체"보다 "증강"에 가깝습니다. 에이전트는 반복적이고 규칙적인 작업을 처리하고, 사람은 판단·창의·소통에 집중하는 구조입니다. 다만 장기적으로 자동화 가능한 업무 범위가 넓어지는 건 사실입니다.

MCP를 개인이 쓸 수 있나요?

네. Claude Code에서 MCP 서버를 설정하면 Google Drive, Slack, GitHub 등을 연결해서 사용할 수 있습니다. 설정법은 공식 문서에 잘 정리되어 있습니다.

어떤 에이전트 프레임워크를 배워야 하나요?

개발자라면 자신이 사용하는 AI 모델의 공식 SDK부터 시작하세요. Claude 사용자라면 Claude Agent SDK, OpenAI 사용자라면 Agents SDK가 자연스럽습니다. 특정 벤더에 묶이고 싶지 않다면 LangGraph가 가장 범용적입니다.

마무리

AI 에이전트는 "대화하는 AI"에서 "일하는 AI"로의 전환입니다.

2026년 현재:

코딩 에이전트 (Claude Code, Cursor, Devin)는 이미 실전 투입 수준
브라우저 에이전트 (Operator, Project Mariner)는 웹 작업을 자동화
MCP와 A2A로 에이전트끼리 도구를 공유하고 협업하는 시대
하지만 보안, 비용, 거버넌스 문제는 아직 풀어야 할 숙제

에이전트를 "써봐야 하나?"고 고민 중이라면, 답은 간단합니다 — 이미 쓰고 있을 가능성이 높습니다. GitHub Copilot의 자동 완성, ChatGPT의 검색 기능, Claude Code의 파일 편집 — 이 모든 게 에이전트의 일부입니다.

여러분은 어떤 AI 에이전트를 써보셨나요? 댓글로 경험을 공유해주세요!

관련 포스팅:

참고 자료:

AI로 웹서비스 만드는 법 — Claude Code + Supabase 실전 가이드

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

요즘 개발 환경이 빠르게 바뀌고 있습니다. 예전에는 웹서비스 하나 만들려면 프론트엔드, 백엔드, DB, 배포까지 혼자 다 해야 했습니다. 지금은 다릅니다.

"아이디어만 있으면, AI와 함께 웹서비스를 만들 수 있는 시대"

과장이 아닙니다. 실제로 저는 Claude Code + GitHub + Supabase 조합으로 웹서비스를 개발하고 있고, 이 프로세스를 공유합니다.

AI 웹개발 도구 조합 — Claude Code, GitHub, Supabase

먼저 각 도구의 역할을 정리합니다.

도구	역할	비유
Claude Code	AI 코딩 에이전트 — 설계, 구현, 디버깅	24시간 일하는 시니어 개발자
GitHub	코드 저장소 + 버전 관리 + 배포	프로젝트의 금고
Supabase	백엔드 올인원 (DB, 인증, API, 스토리지)	서버 없이 쓰는 백엔드

이 세 가지를 조합하면, 1인 개발자가 풀스택 웹서비스를 만들 수 있는 환경이 됩니다. 서버를 직접 관리할 필요도, 인증 로직을 처음부터 짤 필요도 없습니다.

AI 웹서비스 개발 프로세스 — 5단계

제가 실제로 사용하는 프로세스를 단계별로 정리합니다.

1단계: 기획 — Claude Code와 대화하기

코드를 한 줄도 작성하기 전에, Claude Code에게 아이디어를 설명합니다.

"할 일 관리 웹앱을 만들려고 합니다.
사용자 로그인, 할 일 CRUD, 카테고리 분류 기능이 필요합니다.
기술 스택은 Next.js + Supabase로 가려고 하는데, 어떻게 구조를 잡으면 좋을까요?"

Claude Code는 단순히 코드만 생성하는 게 아닙니다. 프로젝트 구조를 제안하고, 테이블 설계를 잡아주고, 필요한 패키지까지 알려줍니다.

이 단계에서 중요한 건 "무엇을 만들 것인가"를 명확히 하는 것입니다. AI는 방향을 알려주면 알아서 길을 찾지만, 방향이 모호하면 엉뚱한 곳으로 갑니다.

2단계: 프로젝트 셋업 — GitHub + Supabase 초기화

GitHub 저장소 생성

gh repo create my-todo-app --public --clone
cd my-todo-app

Supabase 프로젝트 생성

Supabase 대시보드에서 프로젝트를 만들면 바로 사용할 수 있는 것들이 생깁니다.

PostgreSQL 데이터베이스 — 테이블 만들면 자동으로 REST API 생성
Auth — 이메일, Google, GitHub 로그인 내장
Storage — 파일 업로드/다운로드
Realtime — 데이터 변경 시 실시간 동기화

별도의 백엔드 서버 없이, 프론트엔드에서 직접 Supabase를 호출하는 구조입니다.

환경 변수 설정

# .env.local
NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIs...

3단계: 개발 — Claude Code가 코드를 쓴다

여기서부터 Claude Code의 진가가 발휘됩니다.

DB 테이블 설계

"Supabase에 할 일 관리용 테이블을 만들어줘.
사용자별로 할 일을 관리하고, 카테고리 분류가 가능해야 해."

Claude Code가 SQL을 작성합니다.

-- categories 테이블
create table categories (
  id uuid default gen_random_uuid() primary key,
  user_id uuid references auth.users(id) on delete cascade,
  name text not null,
  created_at timestamptz default now()
);

-- todos 테이블
create table todos (
  id uuid default gen_random_uuid() primary key,
  user_id uuid references auth.users(id) on delete cascade,
  category_id uuid references categories(id),
  title text not null,
  completed boolean default false,
  created_at timestamptz default now()
);

-- RLS(Row Level Security) 활성화
alter table todos enable row level security;
alter table categories enable row level security;

-- 본인 데이터만 접근 가능
create policy "Users can manage own todos"
  on todos for all
  using (auth.uid() = user_id);

create policy "Users can manage own categories"
  on categories for all
  using (auth.uid() = user_id);

Supabase의 RLS(Row Level Security) 는 꼭 설정해야 합니다. 안 그러면 모든 사용자가 다른 사람의 데이터를 볼 수 있습니다.

프론트엔드 구현

"Next.js App Router 구조로 할 일 목록 페이지를 만들어줘.
Supabase에서 데이터 가져오고, 추가/삭제/완료 토글 기능이 필요해."

Claude Code가 컴포넌트, API 호출, 상태 관리까지 한 번에 작성합니다. 저는 결과를 확인하고, 수정이 필요한 부분만 피드백합니다.

"완료된 할 일은 아래쪽으로 내려가게 해줘."
"카테고리 필터 버튼 추가해줘."

이런 식으로 대화하면서 개발을 진행합니다. 코드를 직접 쓰는 시간보다, 원하는 동작을 설명하는 시간이 더 깁니다.

4단계: 버전 관리 — GitHub으로 기록

개발 중간중간 커밋을 남깁니다.

git add .
git commit -m "feat: todo CRUD 기능 구현"
git push origin main

Claude Code에게 /commit 명령어를 사용하면 변경 내용을 분석해서 적절한 커밋 메시지까지 작성해줍니다.

5단계: 배포 — Vercel 또는 GitHub Pages

Next.js 프로젝트라면 Vercel에 연결하는 게 가장 간단합니다.

Vercel에 GitHub 저장소 연결
환경 변수(Supabase URL, Key) 설정
git push만 하면 자동 배포

AI 개발의 핵심 — 사람과 AI의 역할 분담

제가 경험한 AI 기반 개발의 핵심은 역할 분담입니다.

내가 하는 일	Claude Code가 하는 일
무엇을 만들지 결정	어떻게 만들지 설계
요구사항 설명	코드 작성
결과 확인 및 피드백	수정 및 개선
최종 판단	대안 제시

비유하자면, 저는 건축주이고 Claude Code는 건축가입니다. 건축주가 "3층짜리 카페를 짓고 싶어요"라고 말하면, 건축가가 도면을 그리고 시공합니다. 건축주가 벽돌을 쌓을 필요는 없습니다.

Supabase vs Firebase — 백엔드 서비스 비교

백엔드 서비스는 여러 선택지가 있습니다. 비교해봤습니다.

서비스	특징	적합한 경우
Supabase	PostgreSQL 기반, 오픈소스, REST/GraphQL 자동 생성	관계형 데이터, SQL 선호
Firebase	NoSQL(Firestore), Google 생태계	빠른 프로토타이핑, 모바일 앱
PocketBase	Go 기반 단일 바이너리, 셀프호스팅	가벼운 프로젝트, 직접 서버 관리

제가 Supabase를 선택한 이유는 세 가지입니다.

SQL을 쓸 수 있다 — NoSQL보다 익숙하고, 복잡한 쿼리가 가능합니다
무료 티어가 넉넉하다 — 개인 프로젝트에 충분한 용량
Claude Code와 궁합이 좋다 — SQL과 REST API를 AI가 잘 다룹니다

AI 웹개발 실전 팁 3가지

Supabase RLS는 반드시 설정하세요

Supabase는 기본적으로 프론트엔드에서 직접 DB를 호출합니다. RLS 없이 배포하면 누구나 API로 모든 데이터에 접근할 수 있습니다. 이건 실수가 아니라 보안 사고입니다.

Claude Code에게 컨텍스트를 충분히 주세요

# 나쁜 예
"로그인 기능 만들어줘"

# 좋은 예
"Supabase Auth를 사용해서 이메일/비밀번호 로그인 기능을 만들어줘.
Next.js App Router 구조이고, 로그인 후 /dashboard로 리다이렉트해야 해.
미인증 사용자가 /dashboard에 접근하면 /login으로 보내줘."

구체적으로 설명할수록, 수정 횟수가 줄어듭니다.

Git 커밋은 자주 하세요

AI와 개발하면 코드가 빠르게 바뀝니다. 중간중간 커밋하지 않으면, 문제가 생겼을 때 되돌릴 지점이 없습니다. "동작하는 상태"가 확인될 때마다 커밋하는 습관을 들이세요.

자주 묻는 질문 (FAQ)

코딩을 몰라도 AI로 웹서비스를 만들 수 있나요?

기본적인 웹 개념(HTML, API 등)을 이해하면 충분합니다. Claude Code가 코드를 작성하고, 여러분은 "무엇을 만들지" 설명하는 역할입니다. 다만, 결과물을 검토하고 디버깅할 때 기초 지식이 있으면 훨씬 수월합니다.

이 조합으로 개발하면 비용이 얼마나 드나요?

Supabase 무료 티어(500MB DB, 1GB 스토리지), Vercel 무료 플랜, GitHub 무료 저장소를 사용하면 호스팅 비용은 0원입니다. Claude Code 구독 비용만 발생합니다. 개인 프로젝트나 사이드 프로젝트에는 충분한 수준입니다.

Claude Code 말고 다른 AI 코딩 도구도 사용할 수 있나요?

GitHub Copilot, Cursor 등 다른 AI 코딩 도구도 비슷한 프로세스로 활용할 수 있습니다. 다만 Claude Code는 프로젝트 전체 맥락을 이해하고 대화 기반으로 개발을 진행할 수 있다는 점에서 이 프로세스에 가장 잘 맞습니다.

마무리

정리하면, AI를 이용한 웹서비스 개발 프로세스는 이렇습니다.

기획 — Claude Code와 대화하며 구조 설계
셋업 — GitHub 저장소 + Supabase 프로젝트 초기화
개발 — Claude Code가 코드 작성, 나는 피드백
관리 — GitHub으로 버전 관리
배포 — Vercel 연결 후 자동 배포

핵심은 "코드를 직접 쓰는 것"에서 "무엇을 만들지 설명하는 것"으로 역할이 바뀐다는 점입니다.

개발 경험이 많으면 더 정확한 지시를 할 수 있고, 경험이 적어도 AI와 대화하면서 배워갈 수 있습니다. 어느 쪽이든, 혼자 처음부터 끝까지 코딩하던 시대와는 확실히 다릅니다.

여러분은 AI와 함께 어떤 서비스를 만들어보고 싶으신가요? 댓글로 알려주세요!

참고 자료

Claude Code 공식 문서 — Anthropic의 AI 코딩 에이전트 소개 및 사용법
Supabase 공식 문서 — 데이터베이스, 인증, 스토리지 설정 가이드
Vercel 공식 문서 — Next.js 배포 및 환경 변수 설정
Next.js App Router 가이드 — App Router 구조와 라우팅

COKACDIR — 텔레그램으로 Claude Code, Codex CLI를 원격 제어하는 법

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

"Claude Code를 쓰고 싶은데, 항상 컴퓨터 앞에 앉아 있을 수는 없잖아요."

AI 코딩 에이전트를 써보면 한 가지 아쉬운 점이 있습니다. 내 컴퓨터 터미널에서만 쓸 수 있다는 것. 외출 중에 "아 그 버그 고쳐야 하는데" 싶어도, 노트북을 열 수 없으면 답이 없습니다.

결론부터 말씀드리면 — COKACDIR을 쓰면 텔레그램 메시지 하나로 내 컴퓨터의 Claude Code를 원격 조작할 수 있습니다. 새로운 AI를 설치하는 게 아니라, 이미 쓰고 있는 코딩 에이전트를 텔레그램에서 리모컨처럼 조종하는 방식입니다.

저는 실제로 사내에서 봇 2개를 만들어 각각 Claude Code와 Codex CLI를 연결하고, 하나의 그룹에서 "작성 → 검증" 역할을 나눠 운영하고 있습니다. 직접 써본 경험까지 공유합니다.

COKACDIR이 뭔가?

COKACDIR(코칵디르)은 기존 AI 코딩 에이전트를 텔레그램에서 원격 제어하게 해주는 오픈소스 도구입니다.

핵심 컨셉을 정리하면:

항목	내용
정체	AI 코딩 에이전트 원격 제어 도구
지원 에이전트	Claude Code, Codex CLI, Gemini CLI, OpenCode
조작 방식	텔레그램 봇
기술 스택	Rust 74.7%, TypeScript 22.6%
바이너리 크기	15~20MB (단일 바이너리)
라이선스	MIT
GitHub	kstost/cokacdir

비유하자면 — Claude Code가 내 컴퓨터에서 일하는 AI 개발자라면, COKACDIR은 그 개발자에게 텔레그램으로 업무 지시를 보내는 채널입니다. AI 자체가 아니라, 기존 AI에 리모컨을 달아주는 도구입니다.

왜 필요한가?

기존 방식의 한계

Claude Code, Codex CLI 같은 코딩 에이전트는 강력하지만, 내 컴퓨터 터미널에 직접 접속해야 합니다.

상황	기존 방식	COKACDIR
외출 중 긴급 버그 수정	노트북 필요	텔레그램에서 지시
장시간 작업 모니터링	터미널 열어둬야 함	텔레그램으로 실시간 확인
예약 작업 (야간 빌드 등)	별도 CI/CD 구성	cron 표현식으로 예약
팀원과 AI 공유	각자 설치 필요	그룹 채팅에서 공유 사용

특히 스마트폰 하나로 AI 코딩 에이전트를 제어할 수 있다는 점이 핵심입니다.

설치 방법 — 5분 가이드

Step 1: COKACDIR 설치

macOS / Linux:

curl -fsSL https://cokacdir.cokac.com/manage.sh | bash && cokacctl

Windows (관리자 PowerShell):

irm https://cokacdir.cokac.com/manage.ps1 | iex; cokacctl

설치하면 cokacctl이라는 관리 TUI가 열립니다.

Step 2: 텔레그램 봇 생성

텔레그램에서 @BotFather를 검색
/newbot 명령 입력
봇 이름과 아이디 설정
API 토큰을 복사 (예: 123456789:ABCdefGhIjKlmNoPqRsTuVwXyZ)

Step 3: COKACDIR 설정

cokacctl TUI에서:

i 키 — 설치
복사한 텔레그램 봇 토큰 입력
s 키 — 서버 시작

이 3단계면 끝입니다. 이제 텔레그램에서 내가 만든 봇에게 메시지를 보내면, 내 컴퓨터의 코딩 에이전트가 작업을 수행합니다.

주요 기능

1. 텔레그램에서 코딩 에이전트 제어

텔레그램 봇에게 자연어로 메시지를 보내면, 연결된 코딩 에이전트(Claude Code 등)가 실행합니다.

나: src/api/auth.js에서 JWT 만료 시간을 1시간에서 24시간으로 변경해줘

봇: [Claude Code 실행 중...]
     auth.js 파일을 수정했습니다.
     - expiresIn: '1h' → '24h'
     변경 완료.

실시간 스트리밍으로 진행 상황을 확인할 수 있습니다.

2. 멀티 에이전트 지원

하나의 COKACDIR에서 여러 코딩 에이전트를 전환할 수 있습니다.

명령어	설명
`/model`	사용할 에이전트/모델 전환
`/session`	세션 관리
`/start`	세션 시작
`/stop`	세션 중지
`/clear`	대화 초기화

3. 예약 작업

cron 표현식이나 절대 시간으로 작업을 예약할 수 있습니다. 야간 빌드, 정기 코드 점검 같은 반복 작업에 유용합니다.

4. 파일 업로드/다운로드

텔레그램으로 파일을 보내면 서버에 업로드되고, /down 명령으로 서버의 파일을 텔레그램으로 받을 수 있습니다.

5. 보안 기능

기능	설명
AES-256 암호화	설정 가능한 청크 분할로 파일 암호화
접근 제어	`/allowed`로 허용 사용자 관리
도구 제한	`/allowedtools`로 사용 가능한 도구 제어

추가 기능 — 코딩 에이전트 외

COKACDIR은 원격 코딩 제어 외에도 부가 기능을 제공합니다.

기능	설명
터미널 멀티패널	분할 화면으로 여러 작업 동시 수행
20+ 언어 구문 강조	코드 파일 내장 뷰어
이미지 뷰어	Kitty, iTerm2, Sixel 프로토콜 지원
Git 통합	상태, 커밋, 로그, 브랜치 관리
SSH/SFTP	원격 서버 접속
중복 파일 감지	디스크 정리 도구
프로세스 관리자	실행 중인 프로세스 모니터링

지원 플랫폼

OS	아키텍처
macOS	Apple Silicon (ARM64), Intel (x86_64)
Linux	x86_64, ARM64
Windows	x86_64, ARM64

Rust로 작성되어 단일 바이너리(15~20MB)로 배포됩니다. 별도 런타임 설치 없이 바로 실행할 수 있습니다.

실전 활용 — 직접 써본 경험

멀티봇 협업 구조: AI 2대를 한 그룹에서 굴리기

저는 사내에서 COKACDIR 봇 2개를 운영하고 있습니다. 각 봇에 서로 다른 코딩 에이전트를 연결하고, 하나의 텔레그램 그룹에 초대해서 역할을 분리했습니다.

봇	연결 에이전트	역할
Bot A	Claude Code	코드 작성, 아키텍처 설계, 리팩토링
Bot B	Codex CLI / Gemini CLI	코드 리뷰, 테스트 작성, 검증

작업 흐름은 이렇습니다:

[텔레그램 그룹]

나: @BotA 사용자 인증 API를 만들어줘. 
    JWT 기반, refresh token 포함.

Bot A (Claude Code): 
    인증 API를 작성했습니다.
    - POST /auth/login
    - POST /auth/refresh
    - POST /auth/logout
    파일 3개 생성 완료.

나: @BotB 방금 Bot A가 만든 인증 API 코드를 리뷰해줘.
    보안 취약점이 있는지 확인하고, 테스트도 작성해줘.

Bot B (Codex CLI):
    리뷰 완료. 2가지 개선사항:
    1. refresh token 저장 시 해싱 필요
    2. rate limiting 미적용
    테스트 파일 생성 완료 (12 cases).

나: @BotA 리뷰 반영해서 수정해줘.

Bot A: 수정 완료. 모든 테스트 통과.

핵심은 "작성 → 검증 → 수정"을 서로 다른 AI가 맡는다는 점입니다. 한 AI가 만든 코드를 다른 AI가 검증하면, 한 AI에게 모든 걸 맡기는 것보다 완성도가 확실히 올라갑니다. 사람이 하는 코드 리뷰 프로세스와 똑같은 구조를 AI끼리 돌리는 셈입니다.

이 구조의 장점

크로스 체크: AI도 실수합니다. 다른 모델이 검증하면 놓치는 부분을 잡아냅니다
역할 특화: Claude Code는 코드 생성이 강하고, Codex는 테스트 작성에 능합니다. 각자 잘하는 일을 맡기면 효율적입니다
한 그룹에서 관리: 팀원 모두가 대화 흐름을 볼 수 있고, 중간에 개입할 수 있습니다
기록 자동 보관: 텔레그램 채팅 기록이 곧 작업 로그입니다

기타 활용 시나리오

외출 중 긴급 핫픽스:

나: production에서 /api/users 500 에러. 로그 확인하고 수정해줘.
봇: null 참조 에러 확인. 수정 완료. 커밋할까요?
나: 응
봇: 푸시 완료.

야간 자동 작업:

cron 표현식으로 매일 새벽 2시에 테스트를 실행하고 결과를 텔레그램으로 받을 수 있습니다.

팀 공유:

텔레그램 그룹에 봇을 추가하면 팀원 모두가 AI 에이전트를 사용할 수 있습니다. /allowed 명령으로 접근 권한을 관리합니다.

주의할 점

보안: 내 컴퓨터에서 AI가 직접 실행되므로, 봇 토큰 관리와 접근 제어(/allowed)를 반드시 설정하세요
비용: COKACDIR 자체는 무료지만, 연결하는 코딩 에이전트(Claude Code 등)의 사용 요금은 별도입니다
컴퓨터 상태: 내 컴퓨터가 켜져 있고 인터넷에 연결되어 있어야 합니다
MIT 라이선스: 소프트웨어는 "AS IS"로 제공되며, 데이터 손실 등에 대한 책임은 사용자에게 있습니다

정리

항목	내용
한 줄 요약	텔레그램으로 Claude Code/Codex/Gemini를 원격 제어
추천 대상	이동 중에도 AI 코딩을 사용하고 싶은 개발자
비용	COKACDIR 무료, 에이전트 비용 별도
설치 시간	약 5분
GitHub	kstost/cokacdir

"AI 코딩 에이전트는 좋은데 항상 컴퓨터 앞에 있어야 한다"는 불편함을 정확히 해결하는 도구입니다. 특히 Claude Code를 주력으로 쓰는 개발자라면, 텔레그램 봇 하나 만들어두는 것만으로 활용도가 크게 올라갑니다.

FAQ

Q. Claude Code가 설치되어 있어야 하나요?

네. COKACDIR은 새로운 AI가 아니라, 기존에 설치된 코딩 에이전트의 리모컨 역할입니다. Claude Code, Codex CLI, Gemini CLI 중 하나 이상이 설치되어 있어야 합니다.

Q. 컴퓨터를 끄면 어떻게 되나요?

COKACDIR 서버가 꺼지므로 텔레그램에서 제어할 수 없습니다. 항상 접근하려면 클라우드 서버(AWS, GCP 등)에 설치하는 것을 추천합니다.

Q. 보안은 안전한가요?

텔레그램 봇 토큰과 /allowed 명령으로 접근을 제한할 수 있습니다. 다만 내 컴퓨터에서 AI가 직접 명령을 실행하므로, 봇 토큰 유출에 주의해야 합니다. AES-256 파일 암호화도 지원합니다.

여러분은 AI 코딩 에이전트를 어떻게 원격으로 활용하고 계신가요? 다른 방법을 쓰고 계시다면 댓글로 공유해주세요!

AI 코딩 도구 Skill 비교 — Claude Code vs Gemini CLI vs Codex CLI 커스텀 명령어 완전 정리

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

"AI 코딩 도구마다 커스텀 명령어 만드는 방식이 다르던데, 어떤 걸 써야 하죠?"

요즘 Claude Code, Gemini CLI, OpenAI Codex CLI 모두 반복 작업을 명령어 하나로 처리하는 기능을 제공합니다. 이름은 조금씩 다르지만 핵심은 같습니다 — 자주 하는 작업 지시를 파일로 저장해두고, 한 줄로 호출하는 것.

결론부터 말씀드리면, 세 도구 모두 비슷한 목적을 달성하지만 설계 철학과 세부 구현이 꽤 다릅니다. 직접 조사하고 비교해봤습니다.

한눈에 보는 3사 비교표

구분	Claude Code	Gemini CLI	Codex CLI (OpenAI)
커스텀 명령어	Skill (`SKILL.md`)	Custom Command (`.toml`) + Agent Skill (`SKILL.md`)	Skill (`SKILL.md`)
프로젝트 설정 파일	`CLAUDE.md`	`GEMINI.md`	`AGENTS.md`
호출 방식	`/skill-name`	`/command-name`	`$skill-name`
자동 호출	description 기반	Agent Skill만 자동	description 기반
파일 형식	Markdown + YAML	TOML (명령어) / Markdown (스킬)	Markdown + YAML
쉘 명령 주입	!`command`	`!{command}`	미지원
서브에이전트 분리	`context: fork`	미지원	미지원
스킬 배포/공유	Git으로 공유	`.skill` 패키지, Extensions	로컬 공유

1. Claude Code — Skill

이전 포스팅에서 자세히 다뤘지만, 핵심만 짚겠습니다.

파일 구조

~/.claude/skills/blog-post/
├── SKILL.md          # 필수: 프론트매터 + 지시문
├── reference.md      # 선택: 상세 문서
└── scripts/
    └── helper.py     # 선택: 헬퍼 스크립트

SKILL.md 예시

---
name: blog-post
description: 블로그 포스팅 초안을 작성합니다
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, WebSearch
---

# 블로그 포스팅 작성 스킬

주제($ARGUMENTS)를 받으면:
1. 아웃라인을 먼저 잡는다
2. WebSearch로 최신 정보 확인
3. 마크다운 초안 작성

호출

/blog-post Claude Code Skill 소개

Claude Code만의 강점

context: fork — 서브에이전트로 분리 실행해서 메인 대화가 오염되지 않음
allowed-tools — 스킬별로 사용 가능한 도구를 제한 가능
disable-model-invocation — 배포 같은 위험한 작업은 수동 호출만 허용
!`command` — 쉘 명령어 결과를 동적으로 프롬프트에 주입

2. Gemini CLI — Custom Command + Agent Skill

Gemini CLI는 커스텀 명령어 시스템을 두 가지로 분리합니다.

(1) Custom Command — 간단한 슬래시 명령어

TOML 파일로 작성합니다. Claude Code나 Codex와 달리 마크다운이 아니라 TOML입니다.

~/.gemini/commands/commit.toml

description = "Git 커밋 메시지를 자동 생성합니다"
prompt = """
다음 diff를 기반으로 Conventional Commit 메시지를 생성해주세요:

```diff
!{git diff --staged}

"""


호출:
```bash
/commit

핵심 문법:

!{command} — 쉘 명령어 실행 후 결과 주입
{{args}} — 사용자 인자 전달
@{파일경로} — 파일/이미지/PDF 내용 주입 (멀티모달 지원)

하위 폴더로 네임스페이스도 지원합니다:

.gemini/commands/git/commit.toml  →  /git:commit

(2) Agent Skill — 자동 활성화되는 전문 지식

Custom Command와 별도로, 모델이 자동으로 판단해서 활성화하는 스킬 시스템이 있습니다.

.gemini/skills/code-reviewer/
├── SKILL.md
├── scripts/
└── references/

---
name: code-reviewer
description: 코드 리뷰를 수행합니다. 로컬 변경사항과 원격 PR 모두 지원합니다.
---

# Code Reviewer
이 스킬은 체계적인 코드 리뷰를 수행합니다.

## 워크플로우
1. 리뷰 대상 파악 (PR 번호 또는 로컬 변경사항)
2. 코드 분석
3. 리뷰 코멘트 생성

토큰 효율이 좋은 설계:

세션 시작 시 이름+설명만 로드
관련 작업이 감지되면 activate_skill 호출
그때서야 전체 SKILL.md 본문이 컨텍스트에 주입

관리 명령어:

/skills list
/skills disable code-reviewer
gemini skills install https://github.com/...

Gemini CLI만의 강점

TOML 기반 Command — 간단한 명령어는 3줄이면 완성
@{파일경로} — 이미지, PDF 등 멀티모달 파일을 프롬프트에 바로 주입
Progressive Disclosure — Agent Skill은 필요할 때만 전체 로드 (토큰 절약)
Extensions 시스템 — 스킬을 패키지로 묶어 설치/배포 가능

3. Codex CLI (OpenAI) — Skill

Codex CLI의 Skill 시스템은 구조적으로 Claude Code와 가장 비슷합니다.

파일 구조

.agents/skills/fix-issue/
├── SKILL.md          # 필수: 지시문
├── scripts/          # 선택: 실행 스크립트
├── references/       # 선택: 참고 문서
└── agents/
    └── openai.yaml   # 선택: UI 메타데이터

SKILL.md 예시

---
name: fix-issue
description: GitHub 이슈를 분석하고 코드를 수정합니다
---

# Fix Issue

이슈 번호를 받으면:
1. 이슈 내용 분석
2. 관련 코드 탐색
3. 수정 구현
4. 테스트 작성

호출

$fix-issue 42

Claude Code의 / 대신 $ 기호를 사용합니다.

스킬 저장 위치

범위	경로
저장소 (CWD)	`.agents/skills/`
저장소 (루트)	`$REPO_ROOT/.agents/skills/`
사용자	`$HOME/.agents/skills/`
시스템	`/etc/codex/skills/`
번들	Codex 내장

Codex CLI만의 강점

openai.yaml 메타데이터 — 아이콘, 브랜드 색상 등 UI 커스터마이징
MCP 의존성 선언 — 스킬에서 필요한 MCP 도구를 명시적으로 선언
5단계 스코프 — CWD → 저장소 루트 → 사용자 → 관리자 → 시스템까지 세분화
30+ 내장 슬래시 명령어 — /plan, /diff, /compact, /review 등

프로젝트 설정 파일 비교 — CLAUDE.md vs GEMINI.md vs AGENTS.md

스킬과 함께 알아두면 좋은 게 프로젝트 설정 파일입니다. 세 도구 모두 "프로젝트 전체에 적용되는 규칙"을 마크다운 파일로 관리합니다.

구분	Claude Code	Gemini CLI	Codex CLI
파일명	`CLAUDE.md`	`GEMINI.md`	`AGENTS.md`
위치	프로젝트 루트 + 하위 디렉토리	프로젝트 루트 + 하위 디렉토리	프로젝트 루트 + 하위 디렉토리
글로벌 설정	`~/.claude/CLAUDE.md`	`~/.gemini/GEMINI.md`	`~/.codex/AGENTS.md`
동적 발견	작업 디렉토리 기준	JIT 로드 (파일 접근 시)	CWD까지 누적
크기 제한	없음	없음	32KB
자동 생성	없음	`/init` 명령어	`/init` 명령어

비유하자면, CLAUDE.md/GEMINI.md/AGENTS.md는 사무실 공지사항, Skill은 업무 매뉴얼입니다. 하나는 항상 읽히고, 하나는 필요할 때만 꺼냅니다.

어떤 도구를 선택해야 할까?

솔직히 말하면, Skill 기능만으로 도구를 선택하진 않습니다. 하지만 각 도구의 Skill 설계에서 철학의 차이가 보입니다.

Claude Code가 적합한 경우

안전성 제어가 중요할 때 — disable-model-invocation, allowed-tools로 세밀한 제어
서브에이전트 분리가 필요할 때 — context: fork로 긴 작업을 깔끔하게 분리
이미 Claude Code를 주력으로 사용 중일 때

Gemini CLI가 적합한 경우

간단한 명령어를 빠르게 만들고 싶을 때 — TOML 3줄이면 충분
멀티모달 입력이 필요할 때 — @{이미지.png} 같은 파일 주입
토큰 효율을 중시할 때 — Progressive Disclosure 방식

Codex CLI가 적합한 경우

조직 단위 관리가 필요할 때 — 5단계 스코프로 세분화
UI 커스터마이징이 필요할 때 — openai.yaml로 아이콘, 색상 설정
이미 OpenAI 생태계를 사용 중일 때

실전 팁 — 어떤 도구든 공통으로 적용되는 원칙

1. description을 잘 쓰세요. 세 도구 모두 description을 보고 자동 호출 여부를 판단합니다. 모호하면 엉뚱한 타이밍에 호출됩니다.

2. 부작용이 있는 작업은 수동 호출만 허용하세요. 배포, 커밋, 메시지 전송 등은 실수로 자동 호출되면 큰일입니다.

Claude Code: disable-model-invocation: true
Gemini CLI: Custom Command는 기본이 수동
Codex CLI: allow_implicit_invocation: false

3. 스킬 파일은 짧게 유지하세요. 500줄 이내가 권장됩니다. 길어지면 별도 파일로 분리하고 참조하세요.

4. 팀과 공유하려면 프로젝트 디렉토리에 저장하세요.

# Claude Code
.claude/skills/my-skill/SKILL.md

# Gemini CLI
.gemini/skills/my-skill/SKILL.md
.gemini/commands/my-command.toml

# Codex CLI
.agents/skills/my-skill/SKILL.md

Git으로 커밋하면 팀원 모두 같은 명령어를 사용할 수 있습니다.

자주 묻는 질문 (FAQ)

SKILL.md 표준이 통일되어 있나요?

Agent Skills라는 오픈 스탠다드가 있고, Gemini CLI와 Codex CLI가 이를 따르고 있습니다. Claude Code도 비슷한 구조를 사용하지만 프론트매터 옵션에 차이가 있습니다. 완전한 호환은 아니지만, 핵심 구조(YAML 프론트매터 + 마크다운 본문)는 동일합니다.

하나의 Skill 파일을 여러 도구에서 쓸 수 있나요?

기본 구조가 비슷해서 간단한 스킬은 거의 그대로 사용 가능합니다. 하지만 allowed-tools(Claude Code 전용), !{command} vs !`command` 같은 도구별 고유 문법이 있어서 완전한 호환은 어렵습니다.

Skill과 프롬프트 복사-붙여넣기의 차이는 뭔가요?

프롬프트 복사-붙여넣기는 텍스트만 전달하는 거지만, Skill은 도구 사용 제한, 자동 호출 제어, 서브에이전트 분리, 쉘 명령어 동적 주입 같은 제어가 가능합니다. 자동차와 자전거의 차이라고 보시면 됩니다.

마무리

AI 코딩 도구의 Skill/커스텀 명령어 기능은 이제 선택이 아니라 기본입니다.

세 도구 모두 "반복 작업을 파일로 저장하고 한 줄로 호출한다"는 핵심은 같지만:

Claude Code는 안전성 제어와 서브에이전트에 강하고
Gemini CLI는 간결함과 토큰 효율에 강하고
Codex CLI는 조직 관리와 UI 커스터마이징에 강합니다

어떤 도구를 쓰든, 반복하는 작업이 있다면 오늘 바로 Skill 파일 하나 만들어보세요.

여러분은 어떤 AI 코딩 도구를 주로 사용하고 계신가요? 댓글로 알려주세요!

참고 자료

아이디어 검증부터 시작하기 — AI와 함께 기획하는 법

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

"아이디어는 넘치는데, 뭘 만들어야 할지 모르겠다."

1인 개발자라면 한 번쯤 이런 고민을 해보셨을 겁니다. 저도 그랬고, 솔직히 지금도 그렇습니다. 문제는 아이디어가 없는 게 아니라, 어떤 아이디어가 실제로 만들 가치가 있는지 판단하기 어렵다는 점이죠.

결론부터 말씀드리면 — AI를 기획 파트너로 활용하면, 혼자서도 놀라울 정도로 체계적인 기획이 가능합니다. 이번 포스팅에서는 아이디어 발굴부터 PRD 작성까지, AI와 함께하는 1인 개발자의 기획 프로세스를 공유합니다.

1인 개발의 현실 — 왜 기획이 가장 중요한가

1인 개발에서 가장 무서운 건 "3개월 동안 만들었는데, 아무도 안 쓴다"는 상황입니다. 대기업이라면 기획자, 디자이너, PM이 각각의 역할을 맡지만, 1인 개발자는 이 모든 걸 혼자 해야 합니다.

그래서 기획 단계에서의 검증이 더욱 중요합니다.

단계	대기업	1인 개발자
아이디어	기획팀 브레인스토밍	혼자 고민
시장 조사	리서치팀 보고서	구글링 + 감
PRD 작성	PM이 작성	건너뛰기
MVP 정의	스프린트 플래닝	"일단 다 만들자"

이 표를 보면 느끼셨겠지만, 1인 개발자의 기획은 대부분 감에 의존합니다. 하지만 AI를 활용하면 이 격차를 상당 부분 좁힐 수 있습니다.

아이디어 브레인스토밍 — AI와 대화하며 아이디어 발굴하기

첫 번째 프롬프트: 넓게 펼치기

아이디어가 막연할 때는, AI에게 제약 조건과 함께 아이디어를 요청하는 것이 효과적입니다.

나는 1인 개발자야. 아래 조건에 맞는 사이드 프로젝트 아이디어를 10개 제안해줘.

조건:
- 혼자서 2주 안에 MVP를 만들 수 있는 규모
- Next.js + Supabase로 구현 가능
- B2C 또는 개인용 도구
- 월 구독 모델 또는 광고 수익 가능
- 이미 레드오션인 분야는 제외

각 아이디어마다 다음을 포함해줘:
1. 서비스명 (가칭)
2. 한 줄 설명
3. 타겟 사용자
4. 수익 모델
5. 기술적 난이도 (상/중/하)

이렇게 구체적인 제약 조건을 주면, AI가 훨씬 현실적인 아이디어를 제안합니다. "앱 아이디어 추천해줘"라고 물어보면 뻔한 답이 나오지만, 조건을 좁히면 좁힐수록 실용적인 결과가 나옵니다.

두 번째 프롬프트: 깊게 파기

10개 아이디어 중 마음에 드는 2~3개를 골랐다면, 각각에 대해 더 깊이 파봅니다.

"독서 기록 웹앱" 아이디어를 더 구체화해줘.

다음 질문에 답해줘:
1. 기존 서비스(밀리의 서재, 리디 독서노트, 북적북적)와 차별점은?
2. 핵심 기능 3가지는?
3. 사용자가 이 앱을 매일 열어볼 이유는?
4. 기술적으로 가장 까다로운 부분은?
5. 2주 안에 만들 수 있는 MVP 범위는?

이 단계에서 중요한 건, AI의 답변을 그대로 수용하지 않는 것입니다. AI는 아이디어를 정리하고 구조화하는 데 탁월하지만, "이게 정말 사람들이 원하는 건가?"라는 판단은 결국 본인의 몫입니다.

시장 조사 — AI로 경쟁 서비스 분석하고 타겟 사용자 정의하기

경쟁 서비스 분석 프롬프트

한국에서 사용 가능한 독서 기록/관리 서비스를 조사해줘.

각 서비스에 대해 다음을 정리해줘:
- 서비스명과 URL
- 핵심 기능
- 가격 정책
- 장점과 단점
- 사용자 리뷰에서 자주 언급되는 불만 사항

마지막에 이 시장의 전체적인 트렌드와 비어있는 틈새(gap)를 분석해줘.

AI가 제공하는 정보는 학습 데이터 시점까지의 내용이므로, 최신 정보는 직접 확인해야 합니다. 하지만 초기 리서치의 뼈대를 잡는 데는 충분합니다.

타겟 사용자 페르소나 만들기

독서 기록 웹앱의 타겟 사용자 페르소나를 3개 만들어줘.

각 페르소나에 포함할 항목:
- 이름 (가상)
- 나이, 직업
- 독서 습관 (월 몇 권, 선호 장르)
- 현재 독서 기록 방법
- 불편한 점 (Pain Point)
- 우리 앱에서 기대하는 것

페르소나를 만들어두면, 이후 기능 우선순위를 정할 때 "이 기능이 민수(페르소나)에게 정말 필요한가?"라는 기준으로 판단할 수 있습니다.

PRD 작성 — AI가 만들어주는 제품 요구사항 문서

PRD(Product Requirements Document)는 "무엇을 만들 것인가"를 정리한 문서입니다. 1인 개발자에게는 과하게 느껴질 수 있지만, PRD 없이 코딩을 시작하면 중간에 방향을 잃기 쉽습니다.

PRD 생성 프롬프트

독서 기록 웹앱의 PRD를 작성해줘.

서비스 개요:
- 읽은 책을 기록하고, 독서 메모를 남기고, 읽은 책 통계를 볼 수 있는 웹앱
- ISBN 바코드 스캔으로 책 정보 자동 입력
- 월간/연간 독서 통계 대시보드

PRD에 포함할 섹션:
1. 프로젝트 개요 (목적, 배경)
2. 타겟 사용자
3. 핵심 기능 목록 (우선순위 P0/P1/P2)
4. 비기능 요구사항 (성능, 보안)
5. 기술 스택
6. 마일스톤 (2주 스프린트 기준)
7. 성공 지표 (KPI)
8. 리스크 및 대응 방안

AI가 생성한 PRD 예시 (일부)

아래는 실제로 Claude에게 요청해서 받은 PRD의 일부입니다.

# 독서 기록 웹앱 PRD

## 1. 프로젝트 개요
### 1.1 목적
독서 애호가들이 읽은 책을 쉽게 기록하고, 독서 습관을 추적할 수 있는 
웹 애플리케이션을 개발한다.

### 1.2 배경
기존 독서 기록 앱들은 대부분 모바일 중심이며, 
웹에서의 사용 경험이 부족하다. 또한 독서 통계 기능이 
단순 권수 집계에 그치는 경우가 많다.

## 2. 핵심 기능

| 우선순위 | 기능 | 설명 |
|---------|------|------|
| P0 | 책 등록 | ISBN 검색으로 책 정보 자동 입력 |
| P0 | 독서 상태 관리 | 읽는 중/읽은 책/읽고 싶은 책 |
| P0 | 독서 메모 | 책별 메모 및 인용구 저장 |
| P1 | 독서 통계 | 월간/연간 독서량, 장르별 분포 |
| P1 | 바코드 스캔 | 카메라로 ISBN 바코드 인식 |
| P2 | 소셜 공유 | 독서 기록 공개 프로필 |
| P2 | 독서 목표 | 연간 독서 목표 설정 및 추적 |

이 PRD를 기반으로 개발을 진행하면, "다음에 뭘 해야 하지?"라는 고민 없이 체계적으로 진행할 수 있습니다.

MVP 범위 정하기 — "이것만 만들자" 전략

1인 개발자의 가장 큰 적은 **스코프 크리프(Scope Creep)**입니다. "이 기능도 넣으면 좋겠는데..."를 반복하다 보면, 영영 출시하지 못합니다.

MVP 범위 확정 프롬프트

위 PRD 기반으로, 2주 안에 혼자서 만들 수 있는 MVP 범위를 정해줘.

조건:
- P0 기능만 포함
- 디자인은 최소한 (Tailwind CSS 기본 컴포넌트)
- 인증은 소셜 로그인(Google)만
- 배포는 Vercel
- 바코드 스캔은 MVP에서 제외 (수동 ISBN 입력으로 대체)

결과물:
1. MVP 기능 목록
2. 2주 스프린트 일정표 (일별)
3. 각 기능의 예상 소요 시간

AI가 만들어준 일정표를 보면 이런 식입니다.

Week 1:
- Day 1-2: 프로젝트 세팅 + Supabase 연동 + 인증
- Day 3-4: 책 등록 (ISBN 검색 API 연동)
- Day 5: 독서 상태 관리 (읽는 중/완료/위시리스트)

Week 2:
- Day 1-2: 독서 메모 CRUD
- Day 3: 기본 대시보드 (독서 목록 뷰)
- Day 4: UI 다듬기 + 반응형
- Day 5: 배포 + 버그 수정

핵심은 과감하게 빼는 것입니다. 통계 대시보드, 바코드 스캔, 소셜 공유 — 이런 건 다 v2에서 하면 됩니다.

실전 예시: "독서 기록 웹앱" 기획 과정 전체를 AI와 함께

이 시리즈에서는 "독서 기록 웹앱"을 실제로 만들어보겠습니다. 위에서 설명한 프로세스를 그대로 따라가면서, 각 단계에서 AI를 어떻게 활용했는지 보여드리겠습니다.

전체 기획 흐름 요약

1. 아이디어 발굴
   └─ AI에게 사이드 프로젝트 아이디어 10개 요청
   └─ "독서 기록 웹앱" 선택

2. 아이디어 검증
   └─ 경쟁 서비스 5개 분석
   └─ 차별점 정의: "웹 기반 + 깔끔한 통계 + 빠른 기록"

3. 타겟 사용자 정의
   └─ 페르소나 3개 작성
   └─ 핵심 타겟: "월 2-4권 읽는 20-30대 직장인"

4. PRD 작성
   └─ P0/P1/P2 기능 분류
   └─ 기술 스택 확정: Next.js + Supabase + Vercel

5. MVP 범위 확정
   └─ P0 기능만 포함한 2주 스프린트
   └─ v1.0 출시 목표

기획에 소요된 시간

놀라운 건, 이 전체 과정이 약 2시간이면 끝난다는 점입니다. AI 없이 혼자 했다면 최소 1-2일은 걸렸을 겁니다.

단계	AI 없이	AI와 함께
아이디어 브레인스토밍	3시간	20분
경쟁 서비스 조사	4시간	30분
페르소나 작성	2시간	15분
PRD 작성	4시간	30분
MVP 범위 확정	2시간	15분
합계	15시간	약 2시간

물론 AI가 만든 결과물을 검토하고 수정하는 시간은 별도입니다. 하지만 백지에서 시작하는 것과 초안을 수정하는 것은 완전히 다른 난이도죠.

기획 단계에서 AI를 잘 활용하는 팁 3가지

1. 구체적인 제약 조건을 주세요

"앱 아이디어 추천해줘"보다 "Next.js + Supabase로 2주 안에 만들 수 있는 B2C 웹앱 아이디어"가 훨씬 좋은 결과를 냅니다.

2. 대화를 이어가세요

한 번의 프롬프트로 끝내지 말고, AI의 답변에 대해 **"왜?", "좀 더 구체적으로", "다른 관점에서"**라고 계속 질문하세요. 대화가 깊어질수록 결과물의 질이 올라갑니다.

3. AI의 답변을 맹신하지 마세요

AI는 기획의 도구이지, 기획자가 아닙니다. 최종 판단은 항상 본인이 해야 합니다. 특히 시장 데이터는 반드시 직접 확인하세요.

자주 묻는 질문 (FAQ)

Q1. ChatGPT와 Claude 중 기획에는 어떤 걸 쓰는 게 좋나요?

솔직히 말하면 기획 단계에서는 큰 차이가 없습니다. 다만 긴 문서(PRD) 작성에는 Claude가 더 강하고, 아이디어 브레인스토밍에는 ChatGPT가 살짝 더 창의적인 편입니다. 저는 둘 다 번갈아 쓰면서 결과를 비교합니다.

Q2. AI가 만든 PRD를 그대로 써도 되나요?

초안으로는 충분합니다. 하지만 반드시 본인의 상황에 맞게 수정해야 합니다. AI는 "2주 안에 만들 수 있다"고 했지만, 본인의 실력과 가용 시간에 따라 일정은 달라질 수 있습니다.

Q3. 아이디어 검증을 AI로만 해도 충분한가요?

아닙니다. AI를 통한 검증은 1차 필터 정도로 생각하세요. 실제 타겟 사용자에게 직접 물어보는 것이 가장 확실한 검증 방법입니다. 주변 지인이나 온라인 커뮤니티에 "이런 앱 있으면 쓸 건가요?"라고 물어보는 것만으로도 큰 인사이트를 얻을 수 있습니다.

여러분은 사이드 프로젝트 기획할 때 AI를 어떻게 활용하고 계신가요? 댓글로 여러분만의 노하우를 공유해주세요!

다음 포스팅에서는 "설계는 AI에게 맡겨라 — ERD, API, 와이어프레임 자동화"를 주제로, Claude Code를 활용한 설계 프로세스를 다뤄보겠습니다.

AI로 풀스택 개발하기 — Claude Code + Supabase 실전

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

"설계까지 끝났으니, 이제 진짜 코드를 작성할 차례입니다."

지난 두 포스팅에서 AI와 함께 기획하고, ERD/API/와이어프레임까지 설계하는 과정을 다뤘습니다. 이번 포스팅에서는 드디어 실제 코드를 작성합니다. Claude Code와 Supabase를 활용해서 "독서 기록 웹앱"의 핵심 기능을 구현하는 과정을 단계별로 보여드리겠습니다.

개발 환경 세팅 — Next.js + Supabase 프로젝트 초기화

1단계: Next.js 프로젝트 생성

터미널에서 아래 명령어를 실행합니다.

npx create-next-app@latest book-log \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --import-alias "@/*"

2단계: 필수 패키지 설치

cd book-log

# Supabase
npm install @supabase/supabase-js @supabase/ssr

# UI 유틸리티
npm install clsx tailwind-merge

# 아이콘
npm install lucide-react

# 날짜 처리
npm install date-fns

3단계: 환경 변수 설정

.env.local 파일을 생성하고, Supabase 프로젝트의 URL과 anon key를 입력합니다.

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR...

이 값은 Supabase 대시보드 > Settings > API에서 확인할 수 있습니다.

Supabase 셋업 — 프로젝트 생성부터 테이블 생성까지

Supabase 프로젝트 생성

supabase.com에서 회원가입
"New Project" 클릭
프로젝트명: book-log
비밀번호 설정 (DB 접근용, 반드시 기록해두세요)
리전: Northeast Asia (Tokyo) 선택

SQL Editor에서 테이블 생성

Supabase 대시보드 > SQL Editor에서, 이전 포스팅에서 설계한 SQL을 실행합니다. 여기서 핵심 부분만 다시 정리하겠습니다.

-- 커스텀 타입
CREATE TYPE reading_status AS ENUM ('want_to_read', 'reading', 'finished');
CREATE TYPE memo_type AS ENUM ('note', 'quote', 'review');

-- profiles 테이블
CREATE TABLE profiles (
  id UUID REFERENCES auth.users(id) ON DELETE CASCADE PRIMARY KEY,
  username TEXT UNIQUE,
  avatar_url TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- books 테이블
CREATE TABLE books (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  isbn VARCHAR(13) UNIQUE,
  title TEXT NOT NULL,
  author TEXT NOT NULL,
  publisher TEXT,
  cover_image_url TEXT,
  page_count INTEGER,
  published_date DATE,
  description TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- reading_records 테이블
CREATE TABLE reading_records (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id UUID REFERENCES profiles(id) ON DELETE CASCADE NOT NULL,
  book_id UUID REFERENCES books(id) ON DELETE CASCADE NOT NULL,
  status reading_status DEFAULT 'want_to_read',
  start_date DATE,
  end_date DATE,
  rating SMALLINT CHECK (rating >= 1 AND rating <= 5),
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(user_id, book_id)
);

-- memos 테이블
CREATE TABLE memos (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id UUID REFERENCES profiles(id) ON DELETE CASCADE NOT NULL,
  book_id UUID REFERENCES books(id) ON DELETE CASCADE NOT NULL,
  content TEXT NOT NULL,
  page_number INTEGER,
  memo_type memo_type DEFAULT 'note',
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

신규 가입 시 자동 프로필 생성 트리거

사용자가 가입하면 자동으로 profiles 테이블에 레코드가 생성되도록 합니다.

CREATE OR REPLACE FUNCTION public.handle_new_user()
RETURNS TRIGGER AS $$
BEGIN
  INSERT INTO public.profiles (id, username, avatar_url)
  VALUES (
    NEW.id,
    NEW.raw_user_meta_data->>'name',
    NEW.raw_user_meta_data->>'avatar_url'
  );
  RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

CREATE TRIGGER on_auth_user_created
  AFTER INSERT ON auth.users
  FOR EACH ROW EXECUTE FUNCTION public.handle_new_user();

인증 구현 — Supabase Auth로 소셜 로그인

Supabase 클라이언트 설정

// src/lib/supabase.ts
import { createBrowserClient } from '@supabase/ssr';

export function createClient() {
  return createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
  );
}

// src/lib/supabase-server.ts
import { createServerClient } from '@supabase/ssr';
import { cookies } from 'next/headers';

export async function createServerSupabaseClient() {
  const cookieStore = await cookies();

  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll();
        },
        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options)
            );
          } catch {
            // Server Component에서는 쿠키 설정 불가
          }
        },
      },
    }
  );
}

인증 미들웨어

인증되지 않은 사용자가 보호된 페이지에 접근하면 로그인 페이지로 리다이렉트합니다.

// src/middleware.ts
import { createServerClient } from '@supabase/ssr';
import { NextResponse, type NextRequest } from 'next/server';

export async function middleware(request: NextRequest) {
  let supabaseResponse = NextResponse.next({ request });

  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return request.cookies.getAll();
        },
        setAll(cookiesToSet) {
          cookiesToSet.forEach(({ name, value }) =>
            request.cookies.set(name, value)
          );
          supabaseResponse = NextResponse.next({ request });
          cookiesToSet.forEach(({ name, value, options }) =>
            supabaseResponse.cookies.set(name, value, options)
          );
        },
      },
    }
  );

  const {
    data: { user },
  } = await supabase.auth.getUser();

  // 인증되지 않은 사용자 리다이렉트
  if (
    !user &&
    !request.nextUrl.pathname.startsWith('/login') &&
    !request.nextUrl.pathname.startsWith('/auth') &&
    request.nextUrl.pathname !== '/'
  ) {
    const url = request.nextUrl.clone();
    url.pathname = '/login';
    return NextResponse.redirect(url);
  }

  return supabaseResponse;
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

로그인 페이지

// src/app/login/page.tsx
'use client';

import { createClient } from '@/lib/supabase';

export default function LoginPage() {
  const supabase = createClient();

  const handleGoogleLogin = async () => {
    await supabase.auth.signInWithOAuth({
      provider: 'google',
      options: {
        redirectTo: `${window.location.origin}/auth/callback`,
      },
    });
  };

  const handleGithubLogin = async () => {
    await supabase.auth.signInWithOAuth({
      provider: 'github',
      options: {
        redirectTo: `${window.location.origin}/auth/callback`,
      },
    });
  };

  return (
    <div className="flex min-h-screen items-center justify-center bg-gray-50">
      <div className="w-full max-w-md space-y-8 rounded-xl bg-white p-8 shadow-lg">
        <div className="text-center">
          <h1 className="text-3xl font-bold text-gray-900">BookLog</h1>
          <p className="mt-2 text-gray-600">
            나만의 독서 기록을 시작하세요
          </p>
        </div>

        <div className="space-y-4">
          <button
            onClick={handleGoogleLogin}
            className="flex w-full items-center justify-center gap-3 rounded-lg border border-gray-300 bg-white px-4 py-3 text-gray-700 transition hover:bg-gray-50"
          >
            <svg className="h-5 w-5" viewBox="0 0 24 24">
              <path
                fill="#4285F4"
                d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92a5.06 5.06 0 01-2.2 3.32v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.1z"
              />
              <path
                fill="#34A853"
                d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"
              />
              <path
                fill="#FBBC05"
                d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"
              />
              <path
                fill="#EA4335"
                d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"
              />
            </svg>
            Google로 로그인
          </button>

          <button
            onClick={handleGithubLogin}
            className="flex w-full items-center justify-center gap-3 rounded-lg bg-gray-900 px-4 py-3 text-white transition hover:bg-gray-800"
          >
            <svg className="h-5 w-5" fill="currentColor" viewBox="0 0 24 24">
              <path d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385.6.105.825-.255.825-.57 0-.285-.015-1.23-.015-2.235-3.015.555-3.795-.735-4.035-1.41-.135-.345-.72-1.41-1.23-1.695-.42-.225-1.02-.78-.015-.795.945-.015 1.62.87 1.845 1.23 1.08 1.815 2.805 1.305 3.495.99.105-.78.42-1.305.765-1.605-2.67-.3-5.46-1.335-5.46-5.925 0-1.305.465-2.385 1.23-3.225-.12-.3-.54-1.53.12-3.18 0 0 1.005-.315 3.3 1.23.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23.66 1.65.24 2.88.12 3.18.765.84 1.23 1.905 1.23 3.225 0 4.605-2.805 5.625-5.475 5.925.435.375.81 1.095.81 2.22 0 1.605-.015 2.895-.015 3.3 0 .315.225.69.825.57A12.02 12.02 0 0024 12c0-6.63-5.37-12-12-12z" />
            </svg>
            GitHub로 로그인
          </button>
        </div>
      </div>
    </div>
  );
}

OAuth 콜백 처리

// src/app/auth/callback/route.ts
import { createServerSupabaseClient } from '@/lib/supabase-server';
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
  const { searchParams, origin } = new URL(request.url);
  const code = searchParams.get('code');

  if (code) {
    const supabase = await createServerSupabaseClient();
    await supabase.auth.exchangeCodeForSession(code);
  }

  return NextResponse.redirect(`${origin}/dashboard`);
}

CRUD 구현 — Claude Code로 "독서 기록 CRUD 만들어줘"

이제 핵심 기능인 독서 기록 CRUD를 구현합니다. Claude Code에게 아래와 같이 요청하면 됩니다.

reading_records 테이블에 대한 CRUD 서비스 함수를 만들어줘.

- Supabase JS Client 사용
- TypeScript
- 에러 처리 포함
- book 정보도 함께 조회 (join)

서비스 레이어 — 독서 기록 CRUD

// src/services/records.ts
import { createClient } from '@/lib/supabase';
import type { ReadingStatus } from '@/types/database';

const supabase = createClient();

// 내 독서 기록 전체 조회
export async function getMyRecords(status?: ReadingStatus) {
  let query = supabase
    .from('reading_records')
    .select(`
      *,
      book:books(*)
    `)
    .order('updated_at', { ascending: false });

  if (status) {
    query = query.eq('status', status);
  }

  const { data, error } = await query;
  if (error) throw error;
  return data;
}

// 독서 기록 생성
export async function createRecord(
  bookId: string,
  status: ReadingStatus = 'want_to_read'
) {
  const { data: { user } } = await supabase.auth.getUser();
  if (!user) throw new Error('인증이 필요합니다');

  const { data, error } = await supabase
    .from('reading_records')
    .insert({
      user_id: user.id,
      book_id: bookId,
      status,
      start_date: status === 'reading' ? new Date().toISOString() : null,
    })
    .select(`*, book:books(*)`)
    .single();

  if (error) throw error;
  return data;
}

// 독서 상태 변경
export async function updateRecordStatus(
  recordId: string,
  status: ReadingStatus
) {
  const updateData: Record<string, unknown> = { status };

  if (status === 'reading') {
    updateData.start_date = new Date().toISOString();
  } else if (status === 'finished') {
    updateData.end_date = new Date().toISOString();
  }

  const { data, error } = await supabase
    .from('reading_records')
    .update(updateData)
    .eq('id', recordId)
    .select(`*, book:books(*)`)
    .single();

  if (error) throw error;
  return data;
}

// 별점 등록
export async function updateRating(recordId: string, rating: number) {
  const { data, error } = await supabase
    .from('reading_records')
    .update({ rating })
    .eq('id', recordId)
    .select()
    .single();

  if (error) throw error;
  return data;
}

// 독서 기록 삭제
export async function deleteRecord(recordId: string) {
  const { error } = await supabase
    .from('reading_records')
    .delete()
    .eq('id', recordId);

  if (error) throw error;
}

책 검색 및 등록 서비스

// src/services/books.ts
import { createClient } from '@/lib/supabase';

const supabase = createClient();

// 알라딘 API로 ISBN 검색 (서버사이드)
export async function searchBookByISBN(isbn: string) {
  const response = await fetch(`/api/books/search?isbn=${isbn}`);
  if (!response.ok) throw new Error('책을 찾을 수 없습니다');
  return response.json();
}

// 제목으로 책 검색 (DB)
export async function searchBooks(query: string) {
  const { data, error } = await supabase
    .from('books')
    .select('*')
    .or(`title.ilike.%${query}%,author.ilike.%${query}%`)
    .limit(20);

  if (error) throw error;
  return data ?? [];
}

// 책 등록 (DB에 없는 경우)
export async function registerBook(book: {
  isbn?: string;
  title: string;
  author: string;
  publisher?: string;
  cover_image_url?: string;
  page_count?: number;
  description?: string;
}) {
  // ISBN으로 중복 체크
  if (book.isbn) {
    const { data: existing } = await supabase
      .from('books')
      .select('id')
      .eq('isbn', book.isbn)
      .single();

    if (existing) return existing;
  }

  const { data, error } = await supabase
    .from('books')
    .insert(book)
    .select()
    .single();

  if (error) throw error;
  return data;
}

ISBN 검색 API 라우트

// src/app/api/books/search/route.ts
import { NextResponse } from 'next/server';

const ALADIN_API_KEY = process.env.ALADIN_API_KEY;

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const isbn = searchParams.get('isbn');

  if (!isbn) {
    return NextResponse.json(
      { error: 'ISBN이 필요합니다' },
      { status: 400 }
    );
  }

  try {
    // 알라딘 API 호출
    const response = await fetch(
      `http://www.aladin.co.kr/ttb/api/ItemLookUp.aspx?` +
      `ttbkey=${ALADIN_API_KEY}&itemIdType=ISBN13&ItemId=${isbn}` +
      `&output=js&Version=20131101`
    );

    const data = await response.json();

    if (!data.item || data.item.length === 0) {
      return NextResponse.json(
        { error: '책을 찾을 수 없습니다' },
        { status: 404 }
      );
    }

    const item = data.item[0];
    return NextResponse.json({
      isbn: isbn,
      title: item.title,
      author: item.author,
      publisher: item.publisher,
      cover_image_url: item.cover,
      page_count: item.subInfo?.itemPage || null,
      published_date: item.pubDate,
      description: item.description,
    });
  } catch (error) {
    return NextResponse.json(
      { error: '검색 중 오류가 발생했습니다' },
      { status: 500 }
    );
  }
}

UI 구현 — Tailwind CSS로 반응형 대시보드

대시보드 페이지

Claude Code에게 "이전 포스팅의 와이어프레임 기반으로 대시보드를 구현해줘"라고 요청하면 아래와 같은 코드를 생성합니다.

// src/app/dashboard/page.tsx
import { createServerSupabaseClient } from '@/lib/supabase-server';
import { BookList } from '@/components/books/BookList';
import { ReadingStats } from '@/components/records/ReadingStats';
import { redirect } from 'next/navigation';

export default async function DashboardPage() {
  const supabase = await createServerSupabaseClient();

  const { data: { user } } = await supabase.auth.getUser();
  if (!user) redirect('/login');

  // 독서 기록 조회 (책 정보 포함)
  const { data: records } = await supabase
    .from('reading_records')
    .select(`*, book:books(*)`)
    .eq('user_id', user.id)
    .order('updated_at', { ascending: false });

  const reading = records?.filter((r) => r.status === 'reading') ?? [];
  const finished = records?.filter((r) => r.status === 'finished') ?? [];
  const wantToRead = records?.filter((r) => r.status === 'want_to_read') ?? [];

  return (
    <div className="mx-auto max-w-6xl px-4 py-8">
      {/* 독서 통계 */}
      <ReadingStats
        readingCount={reading.length}
        finishedCount={finished.length}
        wantToReadCount={wantToRead.length}
      />

      {/* 탭 기반 독서 목록 */}
      <div className="mt-8">
        <BookList
          reading={reading}
          finished={finished}
          wantToRead={wantToRead}
        />
      </div>
    </div>
  );
}

책 카드 컴포넌트

// src/components/books/BookCard.tsx
'use client';

import Image from 'next/image';
import Link from 'next/link';
import { Star } from 'lucide-react';
import type { ReadingRecord } from '@/types/database';

interface BookCardProps {
  record: ReadingRecord & { book: any };
}

export function BookCard({ record }: BookCardProps) {
  const { book, status, rating } = record;

  const statusLabel = {
    reading: '읽는 중',
    finished: '완료',
    want_to_read: '읽고 싶은',
  }[status];

  const statusColor = {
    reading: 'bg-blue-100 text-blue-800',
    finished: 'bg-green-100 text-green-800',
    want_to_read: 'bg-yellow-100 text-yellow-800',
  }[status];

  return (
    <Link href={`/books/${book.id}`}>
      <div className="group rounded-lg border border-gray-200 bg-white p-4 transition hover:shadow-md">
        {/* 책 커버 */}
        <div className="relative aspect-[3/4] w-full overflow-hidden rounded-md bg-gray-100">
          {book.cover_image_url ? (
            <Image
              src={book.cover_image_url}
              alt={`${book.title} 표지`}
              fill
              className="object-cover transition group-hover:scale-105"
            />
          ) : (
            <div className="flex h-full items-center justify-center text-gray-400">
              No Cover
            </div>
          )}
        </div>

        {/* 책 정보 */}
        <div className="mt-3 space-y-1">
          <span className={`inline-block rounded-full px-2 py-0.5 text-xs font-medium ${statusColor}`}>
            {statusLabel}
          </span>
          <h3 className="line-clamp-2 text-sm font-semibold text-gray-900">
            {book.title}
          </h3>
          <p className="text-xs text-gray-500">{book.author}</p>

          {/* 별점 */}
          {rating && (
            <div className="flex gap-0.5">
              {[1, 2, 3, 4, 5].map((i) => (
                <Star
                  key={i}
                  className={`h-3.5 w-3.5 ${
                    i <= rating
                      ? 'fill-yellow-400 text-yellow-400'
                      : 'text-gray-300'
                  }`}
                />
              ))}
            </div>
          )}
        </div>
      </div>
    </Link>
  );
}

독서 통계 컴포넌트

// src/components/records/ReadingStats.tsx
import { BookOpen, CheckCircle, Bookmark } from 'lucide-react';

interface ReadingStatsProps {
  readingCount: number;
  finishedCount: number;
  wantToReadCount: number;
}

export function ReadingStats({
  readingCount,
  finishedCount,
  wantToReadCount,
}: ReadingStatsProps) {
  const stats = [
    {
      label: '읽는 중',
      count: readingCount,
      icon: BookOpen,
      color: 'text-blue-600 bg-blue-50',
    },
    {
      label: '완료',
      count: finishedCount,
      icon: CheckCircle,
      color: 'text-green-600 bg-green-50',
    },
    {
      label: '읽고 싶은',
      count: wantToReadCount,
      icon: Bookmark,
      color: 'text-yellow-600 bg-yellow-50',
    },
  ];

  return (
    <div className="grid grid-cols-3 gap-4">
      {stats.map((stat) => (
        <div
          key={stat.label}
          className="rounded-lg border border-gray-200 bg-white p-4"
        >
          <div className="flex items-center gap-3">
            <div className={`rounded-lg p-2 ${stat.color}`}>
              <stat.icon className="h-5 w-5" />
            </div>
            <div>
              <p className="text-2xl font-bold text-gray-900">
                {stat.count}
              </p>
              <p className="text-sm text-gray-500">{stat.label}</p>
            </div>
          </div>
        </div>
      ))}
    </div>
  );
}

Claude Code 활용 팁 — 효과적인 프롬프트 작성법

1. CLAUDE.md로 프로젝트 컨텍스트 공유하기

프로젝트 루트에 CLAUDE.md 파일을 두면, Claude Code가 매번 새 대화를 시작할 때 자동으로 읽어서 컨텍스트를 파악합니다.

# BookLog

## 기술 스택
- Next.js 14 (App Router, TypeScript)
- Supabase (PostgreSQL, Auth, RLS)
- Tailwind CSS
- Vercel 배포

## DB 스키마
- profiles: 사용자 프로필 (auth.users 연동)
- books: 책 정보 (ISBN, 제목, 저자)
- reading_records: 독서 기록 (상태, 별점, 날짜)
- memos: 독서 메모 (노트, 인용, 리뷰)

## 코딩 컨벤션
- 컴포넌트: src/components/ 하위 기능별 분류
- 서비스: src/services/ (Supabase 쿼리 로직)
- 서버 컴포넌트 기본, 클라이언트 컴포넌트는 'use client' 명시
- 에러 처리: try/catch + 사용자 친화적 메시지

2. 구체적인 지시를 내리세요

나쁜 예시:

메모 기능 만들어줘

좋은 예시:

memos 테이블에 대한 CRUD를 구현해줘.

- src/services/memos.ts에 서비스 함수
- src/components/memos/MemoEditor.tsx에 작성/수정 폼
- src/components/memos/MemoCard.tsx에 메모 카드
- 메모 타입: note, quote, review (라디오 버튼으로 선택)
- 인용구(quote) 타입은 페이지 번호 입력 필드 추가
- Tailwind CSS, 반응형

3. 단계별로 요청하세요

한 번에 모든 걸 요청하면 결과물의 품질이 떨어집니다. 서비스 함수 -> 컴포넌트 -> 페이지 순서로 나눠서 요청하는 것이 좋습니다.

1단계: "memos 서비스 함수만 만들어줘" -> 검토 -> 확정
2단계: "이 서비스를 사용하는 MemoEditor 컴포넌트 만들어줘" -> 검토 -> 확정
3단계: "대시보드에 메모 섹션 추가해줘" -> 검토 -> 확정

테스트 — AI가 만든 코드를 검증하는 방법

AI가 생성한 코드를 무조건 신뢰하면 안 됩니다. 특히 아래 항목은 반드시 직접 확인하세요.

수동 테스트 체크리스트

항목	확인 사항
인증	로그인/로그아웃 정상 동작
RLS	다른 사용자의 데이터가 보이지 않는지
CRUD	생성/조회/수정/삭제 각각 동작 확인
엣지 케이스	빈 입력, 긴 텍스트, 특수문자
반응형	모바일/태블릿/데스크톱
에러 처리	네트워크 오류, 서버 오류 시 UI

Claude Code로 테스트 코드 생성하기

BookCard 컴포넌트의 단위 테스트를 작성해줘.

- Vitest + React Testing Library 사용
- 테스트 케이스:
  1. 책 제목과 저자가 렌더링되는지
  2. 상태에 따라 올바른 배지 색상이 적용되는지
  3. 별점이 올바르게 표시되는지
  4. 커버 이미지가 없을 때 대체 텍스트가 표시되는지

생성된 테스트 코드 예시:

// src/components/books/BookCard.test.tsx
import { render, screen } from '@testing-library/react';
import { describe, it, expect } from 'vitest';
import { BookCard } from './BookCard';

const mockRecord = {
  id: '1',
  user_id: 'user-1',
  book_id: 'book-1',
  status: 'reading' as const,
  rating: 4,
  start_date: '2026-01-01',
  end_date: null,
  created_at: '2026-01-01',
  updated_at: '2026-01-01',
  book: {
    id: 'book-1',
    isbn: '9788936434267',
    title: '채식주의자',
    author: '한강',
    publisher: '창비',
    cover_image_url: 'https://example.com/cover.jpg',
    page_count: 247,
    published_date: '2007-10-30',
    description: null,
    created_at: '2026-01-01',
  },
};

describe('BookCard', () => {
  it('책 제목과 저자가 렌더링된다', () => {
    render(<BookCard record={mockRecord} />);

    expect(screen.getByText('채식주의자')).toBeInTheDocument();
    expect(screen.getByText('한강')).toBeInTheDocument();
  });

  it('읽는 중 상태 배지가 표시된다', () => {
    render(<BookCard record={mockRecord} />);

    const badge = screen.getByText('읽는 중');
    expect(badge).toHaveClass('bg-blue-100');
  });

  it('별점 4개가 채워져 표시된다', () => {
    render(<BookCard record={mockRecord} />);

    const filledStars = document.querySelectorAll('.fill-yellow-400');
    expect(filledStars).toHaveLength(4);
  });

  it('커버 이미지가 없으면 대체 텍스트가 표시된다', () => {
    const noCoverRecord = {
      ...mockRecord,
      book: { ...mockRecord.book, cover_image_url: null },
    };

    render(<BookCard record={noCoverRecord} />);
    expect(screen.getByText('No Cover')).toBeInTheDocument();
  });
});

RLS 테스트 — 가장 중요한 보안 검증

RLS가 제대로 동작하는지 확인하는 가장 간단한 방법은 Supabase SQL Editor에서 직접 쿼리를 실행하는 것입니다.

-- 특정 사용자로 로그인한 상태를 시뮬레이션
SET request.jwt.claims = '{"sub": "user-id-here"}';

-- 이 쿼리로 해당 사용자의 데이터만 조회되는지 확인
SELECT * FROM reading_records;

개발 결과물 요약

이 세 포스팅에 걸쳐 만든 "독서 기록 웹앱"의 구성을 정리하면 다음과 같습니다.

항목	내용
프론트엔드	Next.js 14 (App Router) + Tailwind CSS
백엔드	Supabase (PostgreSQL + Auth + RLS)
인증	Google, GitHub 소셜 로그인
핵심 기능	책 검색/등록, 독서 기록 CRUD, 메모 CRUD
AI 도구	Claude Code (설계, 코드 생성, 테스트)
개발 기간	약 2주 (기획 포함)

자주 묻는 질문 (FAQ)

Q1. Claude Code 없이 다른 AI 코딩 도구로도 이 과정이 가능한가요?

가능합니다. GitHub Copilot, Cursor 등도 비슷한 작업을 할 수 있습니다. 다만 Claude Code는 프로젝트 전체 컨텍스트를 이해하고 파일 간의 관계를 파악하는 데 강점이 있어서, 이 시리즈에서는 Claude Code를 중심으로 설명했습니다.

Q2. Supabase 무료 플랜으로 실제 서비스 운영이 가능한가요?

사이드 프로젝트 수준이라면 충분합니다. 무료 플랜은 500MB 데이터베이스, 1GB 파일 스토리지, 50,000 월간 활성 사용자를 제공합니다. 다만 프로젝트가 7일간 비활성 상태면 일시 중지되므로, 실제 서비스 운영 시에는 Pro 플랜(월 $25)을 고려하세요.

Q3. AI가 생성한 코드의 품질은 믿을 만한가요?

"초안"으로는 훌륭하지만, 프로덕션에 바로 쓰기에는 부족한 경우가 많습니다. 특히 에러 처리, 엣지 케이스, 보안(RLS 정책) 부분은 반드시 직접 검토하세요. AI를 "주니어 개발자"라고 생각하면 됩니다 — 빠르게 코드를 짜지만, 시니어의 리뷰가 필요한 수준입니다.

여러분도 AI와 함께 사이드 프로젝트를 만들어보고 계신가요? 어떤 도구를 쓰고, 어떤 점이 좋았는지 댓글로 공유해주세요!

다음 포스팅에서는 "Vercel + GitHub Actions로 자동 배포 파이프라인 구축하기"를 주제로, 만든 앱을 세상에 공개하는 과정을 다뤄보겠습니다.

운영과 모니터링 — 출시 후 해야 할 것들

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

드디어 시리즈의 마지막 포스팅입니다. 기획부터 설계, 개발, 배포까지 해냈습니다. 축하합니다! 하지만 여기서 끝이 아닙니다. 출시는 시작일 뿐입니다.

서비스를 세상에 내놓은 순간부터 진짜 게임이 시작됩니다. 사용자가 어떤 에러를 만나는지, 어떤 기능을 많이 쓰는지, 서비스가 얼마나 빠른지 -- 이 모든 것을 파악하고 개선해야 합니다. 이번 포스팅에서는 1인 개발자가 서비스를 안정적으로 운영하기 위해 꼭 해야 할 것들을 정리합니다.

출시는 시작일 뿐 -- 운영의 중요성

많은 1인 개발자들이 출시에만 집중하고, 이후 운영을 소홀히 합니다. 하지만 성공적인 서비스는 출시 이후의 운영에서 결정됩니다.

운영 단계에서 해야 할 핵심 업무는 네 가지입니다.

에러 트래킹: 사용자가 겪는 오류를 실시간으로 감지
사용자 분석: 어떤 기능이 인기 있는지, 어디서 이탈하는지 파악
성능 모니터링: 페이지 로딩 속도, API 응답 시간 관리
피드백 수집: 사용자의 목소리를 듣고 개선에 반영

이 네 가지를 모두 무료 도구로 구축하는 방법을 알려드리겠습니다.

에러 트래킹 -- Sentry 연동

서비스를 운영하다 보면 예상치 못한 에러가 반드시 발생합니다. 사용자가 에러를 직접 알려주기를 기대할 수 없습니다. Sentry를 사용하면 에러가 발생하는 즉시 알림을 받을 수 있습니다.

Sentry 설치

# Sentry Next.js SDK 설치
npx @sentry/wizard@latest -i nextjs

이 명령을 실행하면 Sentry 설정 마법사가 시작됩니다. Sentry 계정 로그인, 프로젝트 생성, 설정 파일 생성까지 자동으로 진행됩니다.

마법사가 완료되면 아래 파일들이 자동 생성됩니다.

sentry.client.config.ts   — 클라이언트 사이드 Sentry 설정
sentry.server.config.ts   — 서버 사이드 Sentry 설정
sentry.edge.config.ts     — Edge Runtime Sentry 설정
next.config.js             — Sentry 플러그인이 자동 추가됨
.env.sentry-build-plugin   — Sentry 인증 토큰

Sentry 기본 설정

// sentry.client.config.ts
import * as Sentry from '@sentry/nextjs';

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,

  // 에러 샘플링 비율 (1.0 = 모든 에러 수집)
  tracesSampleRate: 1.0,

  // 프로덕션에서만 활성화
  enabled: process.env.NODE_ENV === 'production',

  // 사용자 세션 리플레이 (에러 발생 전후 화면 녹화)
  replaysSessionSampleRate: 0.1,  // 전체 세션의 10%
  replaysOnErrorSampleRate: 1.0,  // 에러 발생 시 100%

  integrations: [
    Sentry.replayIntegration(),
  ],
});

// sentry.server.config.ts
import * as Sentry from '@sentry/nextjs';

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 1.0,
  enabled: process.env.NODE_ENV === 'production',
});

커스텀 에러 캡처

자동 에러 수집 외에도 중요한 비즈니스 로직에서 직접 에러를 캡처할 수 있습니다.

// lib/api-client.ts
import * as Sentry from '@sentry/nextjs';

export async function fetchWithErrorTracking(url: string, options?: RequestInit) {
  try {
    const response = await fetch(url, options);

    if (!response.ok) {
      // HTTP 에러도 Sentry에 보고
      Sentry.captureMessage(`API Error: ${response.status} ${url}`, {
        level: 'warning',
        extra: {
          status: response.status,
          statusText: response.statusText,
          url,
        },
      });
    }

    return response;
  } catch (error) {
    // 네트워크 에러 등 캡처
    Sentry.captureException(error, {
      extra: { url, options },
    });
    throw error;
  }
}

Sentry 알림 설정

에러가 발생하면 즉시 알림을 받도록 설정합니다.

Sentry 대시보드 → Settings → Alerts
→ "Create Alert Rule"
→ 조건: "A new issue is created"
→ 액션: 이메일 알림 또는 Slack 알림
→ 빈도: "실시간" 또는 "10분마다 요약"

1인 개발자에게는 Slack 알림을 추천합니다. 에러 발생 시 즉시 알림을 받을 수 있고, 에러 상세 정보로 바로 이동할 수 있습니다.

사용자 분석 -- Google Analytics 4 연동

서비스에 사용자가 어떻게 들어오고, 어떤 페이지를 보고, 어디서 떠나는지 파악하는 것은 서비스 개선의 핵심입니다.

GA4 설치

# Google Analytics 패키지 설치
npm install @next/third-parties

// app/layout.tsx
import { GoogleAnalytics } from '@next/third-parties/google';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="ko">
      <body>{children}</body>
      {process.env.NODE_ENV === 'production' && (
        <GoogleAnalytics gaId={process.env.NEXT_PUBLIC_GA_ID!} />
      )}
    </html>
  );
}

커스텀 이벤트 트래킹

페이지 조회 외에도 사용자의 주요 행동을 추적할 수 있습니다.

// lib/analytics.ts
export function trackEvent(eventName: string, parameters?: Record<string, string | number>) {
  if (typeof window !== 'undefined' && window.gtag) {
    window.gtag('event', eventName, parameters);
  }
}

// 사용 예시
// 회원가입 완료
trackEvent('sign_up', { method: 'email' });

// AI 기능 사용
trackEvent('ai_generate', { feature: 'summary', tokens: 150 });

// 유료 전환
trackEvent('purchase', { value: 9900, currency: 'KRW' });

// components/GenerateButton.tsx
'use client';

import { trackEvent } from '@/lib/analytics';

export function GenerateButton() {
  const handleClick = async () => {
    trackEvent('ai_generate_click', { page: 'dashboard' });

    // AI 생성 로직...

    trackEvent('ai_generate_complete', { duration: 2500 });
  };

  return (
    <button onClick={handleClick}>
      AI로 생성하기
    </button>
  );
}

GA4에서 확인할 핵심 지표

1인 개발자가 꼭 봐야 할 지표입니다.

지표	의미	확인 위치
활성 사용자	실제 서비스를 쓰는 사람 수	홈 > 개요
이벤트 수	핵심 기능 사용 빈도	참여도 > 이벤트
이탈률	첫 페이지에서 바로 떠나는 비율	참여도 > 페이지
사용자 획득	어디서 유입되는지	획득 > 트래픽 소스
전환율	핵심 목표 달성 비율	구성 > 전환

성능 모니터링 -- Vercel Analytics와 Core Web Vitals

서비스가 느리면 사용자는 떠납니다. 성능을 지속적으로 모니터링하고 개선해야 합니다.

Vercel Analytics 활성화

# Vercel Analytics 패키지 설치
npm install @vercel/analytics

// app/layout.tsx
import { Analytics } from '@vercel/analytics/react';
import { SpeedInsights } from '@vercel/speed-insights/next';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="ko">
      <body>
        {children}
        <Analytics />
        <SpeedInsights />
      </body>
    </html>
  );
}

Core Web Vitals 관리

Google이 정한 웹 성능 핵심 지표입니다. SEO에도 영향을 미치므로 반드시 관리해야 합니다.

지표	의미	목표값
LCP (Largest Contentful Paint)	가장 큰 콘텐츠가 보이기까지	2.5초 이하
INP (Interaction to Next Paint)	사용자 입력에 반응하기까지	200ms 이하
CLS (Cumulative Layout Shift)	레이아웃이 갑자기 움직이는 정도	0.1 이하

성능 개선 체크리스트

// 이미지 최적화 — next/image 사용
import Image from 'next/image';

export function HeroSection() {
  return (
    <Image
      src="/hero.webp"
      alt="히어로 이미지"
      width={1200}
      height={630}
      priority  // LCP 대상 이미지에 priority 추가
      placeholder="blur"
      blurDataURL="data:image/jpeg;base64,..."
    />
  );
}

// 동적 임포트로 초기 로딩 최적화
import dynamic from 'next/dynamic';

// 무거운 컴포넌트는 필요할 때만 로드
const HeavyChart = dynamic(() => import('@/components/HeavyChart'), {
  loading: () => <p>차트 로딩 중...</p>,
  ssr: false,
});

사용자 피드백 수집

데이터만으로는 알 수 없는 것들이 있습니다. 사용자의 직접적인 목소리를 듣는 것이 중요합니다.

간단한 피드백 폼 만들기

// components/FeedbackWidget.tsx
'use client';

import { useState } from 'react';
import { createClient } from '@/lib/supabase/client';

export function FeedbackWidget() {
  const [isOpen, setIsOpen] = useState(false);
  const [feedback, setFeedback] = useState('');
  const [type, setType] = useState<'bug' | 'feature' | 'general'>('general');
  const [submitted, setSubmitted] = useState(false);

  const supabase = createClient();

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();

    await supabase.from('feedback').insert({
      type,
      message: feedback,
      page: window.location.pathname,
      user_agent: navigator.userAgent,
      created_at: new Date().toISOString(),
    });

    setSubmitted(true);
    setTimeout(() => {
      setIsOpen(false);
      setSubmitted(false);
      setFeedback('');
    }, 2000);
  };

  if (!isOpen) {
    return (
      <button
        onClick={() => setIsOpen(true)}
        className="fixed bottom-4 right-4 bg-blue-600 text-white px-4 py-2 rounded-full shadow-lg"
      >
        피드백 보내기
      </button>
    );
  }

  return (
    <div className="fixed bottom-4 right-4 w-80 bg-white rounded-lg shadow-xl p-4 border">
      {submitted ? (
        <p className="text-center text-green-600 font-medium">
          소중한 피드백 감사합니다!
        </p>
      ) : (
        <form onSubmit={handleSubmit}>
          <h3 className="font-bold mb-2">피드백 보내기</h3>

          <div className="flex gap-2 mb-3">
            {(['bug', 'feature', 'general'] as const).map((t) => (
              <button
                key={t}
                type="button"
                onClick={() => setType(t)}
                className={`px-3 py-1 rounded text-sm ${
                  type === t ? 'bg-blue-600 text-white' : 'bg-gray-100'
                }`}
              >
                {t === 'bug' ? '버그' : t === 'feature' ? '기능 요청' : '일반'}
              </button>
            ))}
          </div>

          <textarea
            value={feedback}
            onChange={(e) => setFeedback(e.target.value)}
            placeholder="의견을 자유롭게 작성해 주세요"
            className="w-full border rounded p-2 mb-3 h-24 resize-none"
            required
          />

          <div className="flex justify-end gap-2">
            <button
              type="button"
              onClick={() => setIsOpen(false)}
              className="px-3 py-1 text-gray-500"
            >
              취소
            </button>
            <button
              type="submit"
              className="px-3 py-1 bg-blue-600 text-white rounded"
            >
              보내기
            </button>
          </div>
        </form>
      )}
    </div>
  );
}

Supabase 피드백 테이블

-- Supabase SQL Editor에서 실행
CREATE TABLE feedback (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  type TEXT NOT NULL CHECK (type IN ('bug', 'feature', 'general')),
  message TEXT NOT NULL,
  page TEXT,
  user_agent TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  is_resolved BOOLEAN DEFAULT FALSE
);

-- RLS 정책 (누구나 피드백 작성 가능, 읽기는 관리자만)
ALTER TABLE feedback ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Anyone can insert feedback"
  ON feedback FOR INSERT
  TO anon
  WITH CHECK (true);

GitHub Issues 활용

피드백 폼 외에 GitHub Issues를 활용하면 개발자 커뮤니티에서 피드백을 받기 좋습니다.

GitHub 저장소 → Settings → Features → Issues 활성화
→ Issue Template 생성:
  - Bug Report (버그 리포트)
  - Feature Request (기능 요청)

<!-- .github/ISSUE_TEMPLATE/bug_report.md -->
---
name: Bug Report
about: 버그를 신고해 주세요
title: '[BUG] '
labels: bug
---

**버그 설명**
어떤 문제가 발생했나요?

**재현 방법**
1. '...' 페이지에 접속
2. '...' 버튼 클릭
3. 에러 발생

**예상 동작**
어떻게 동작해야 하나요?

**스크린샷**
가능하다면 스크린샷을 첨부해 주세요.

업데이트 전략

서비스를 지속적으로 개선하려면 체계적인 업데이트 전략이 필요합니다.

기능 추가 우선순위 정하기

모든 피드백과 아이디어를 구현할 수는 없습니다. 우선순위를 정하는 간단한 프레임워크입니다.

ICE 스코어링:
- Impact (영향력): 1~10 — 얼마나 많은 사용자에게 도움이 되는가?
- Confidence (확신도): 1~10 — 실제로 효과가 있을 확신이 있는가?
- Ease (난이도): 1~10 — 얼마나 쉽게 구현할 수 있는가?

ICE Score = Impact × Confidence × Ease
→ 점수가 높은 것부터 구현

기능	Impact	Confidence	Ease	Score
다크모드	7	9	8	504
소셜 로그인	8	8	6	384
AI 번역	5	6	4	120

버전 관리

# Semantic Versioning 사용
# MAJOR.MINOR.PATCH

# 버그 수정
npm version patch  # 1.0.0 → 1.0.1

# 새 기능 추가
npm version minor  # 1.0.1 → 1.1.0

# 호환되지 않는 변경
npm version major  # 1.1.0 → 2.0.0

비용 관리 -- 무료 티어로 운영하는 전략

1인 개발자에게 비용 관리는 생존의 문제입니다. 다행히 2026년 현재 대부분의 서비스가 넉넉한 무료 티어를 제공합니다.

무료 티어 한도 정리

서비스	무료 한도	초과 시 비용
Vercel (Hobby)	100GB 대역폭, 무제한 배포	Pro: $20/월
Supabase (Free)	500MB DB, 1GB 스토리지, 50,000 MAU	Pro: $25/월
Sentry (Developer)	5,000 이벤트/월	Team: $26/월
GA4	무제한 (무료)	-
GitHub	무제한 공개 저장소	-
OpenAI API	종량제 (무료 한도 없음)	GPT-4o: ~$5/1M 토큰

비용 절약 팁

// 1. API 호출 최소화 — 캐싱 활용
import { unstable_cache } from 'next/cache';

const getCachedData = unstable_cache(
  async (id: string) => {
    // 비용이 드는 API 호출
    const data = await fetchFromOpenAI(id);
    return data;
  },
  ['openai-cache'],
  { revalidate: 3600 } // 1시간 캐시
);

// 2. Supabase 쿼리 최적화 — 필요한 필드만 조회
// 나쁜 예
const { data } = await supabase.from('posts').select('*');

// 좋은 예
const { data } = await supabase
  .from('posts')
  .select('id, title, created_at')
  .order('created_at', { ascending: false })
  .limit(20);

// 3. 이미지 최적화 — Vercel Image Optimization 활용
// next.config.js
const nextConfig = {
  images: {
    formats: ['image/avif', 'image/webp'],
    minimumCacheTTL: 60 * 60 * 24 * 30, // 30일 캐시
  },
};

비용 모니터링

각 서비스의 사용량을 주기적으로 확인하세요.

매주 월요일 체크리스트:
[ ] Vercel 대시보드 → Usage 탭 확인
[ ] Supabase 대시보드 → Settings → Billing 확인
[ ] Sentry 대시보드 → Settings → Subscription 확인
[ ] OpenAI 대시보드 → Usage 확인

1인 개발자의 AI 스택 시리즈 마무리

5편에 걸친 시리즈를 통해 아이디어 검증부터 운영까지 전체 과정을 다뤘습니다. 처음에는 막막해 보였을 수도 있지만, 하나씩 따라오시면 충분히 할 수 있는 과정입니다.

시리즈 전체 요약 표

편	주제	핵심 내용	주요 도구
1편	아이디어 검증	문제 정의, 시장 조사, MVP 범위 설정	ChatGPT, Notion
2편	AI 기반 설계	UI/UX 디자인, DB 스키마, API 설계	v0, Cursor, Supabase
3편	풀스택 개발	Next.js + Supabase로 MVP 구현	Next.js, Supabase, Tailwind
4편	배포 자동화	Vercel + GitHub 원클릭 배포	Vercel, GitHub
5편	운영과 모니터링	에러 트래킹, 분석, 피드백, 비용 관리	Sentry, GA4, Vercel Analytics

이 시리즈에서 구축한 AI 스택 전체 구조

[사용자] → [Vercel Edge Network]
                    ↓
            [Next.js App Router]
           /        |         \
    [Server]   [Client]   [API Routes]
        ↓          ↓           ↓
  [Supabase]  [React UI]  [OpenAI API]
  (DB/Auth)   (Tailwind)  (AI 기능)
        ↓
  [Sentry]  [GA4]  [Vercel Analytics]
  (에러)    (분석)  (성능)

다음 단계를 위한 제안

시리즈를 마쳤다면 다음 단계를 고려해 보세요.

수익화: Stripe 결제 연동으로 유료 기능 추가
마케팅: Product Hunt 런칭, 기술 블로그 작성
확장: 모바일 앱 (React Native), 크롬 익스텐션
커뮤니티: Discord 서버 운영, 오픈소스 기여

1인 개발자도 AI 도구의 도움을 받으면 기획부터 운영까지 혼자 해낼 수 있는 시대입니다. 이 시리즈가 여러분의 첫 서비스를 만드는 데 도움이 되었으면 합니다.

자주 묻는 질문 (FAQ)

Q1. Sentry 무료 플랜으로 충분한가요?

대부분의 초기 서비스에는 충분합니다. Sentry Developer 플랜은 월 5,000개의 에러 이벤트를 처리할 수 있습니다. 일일 방문자가 수백 명 수준이라면 무료 한도를 넘기기 어렵습니다. 만약 한도에 가까워진다면 tracesSampleRate를 낮춰서 수집 비율을 조절하세요. 예를 들어 0.2로 설정하면 전체 트랜잭션의 20%만 수집합니다.

Q2. Google Analytics 대신 다른 분석 도구를 쓸 수 있나요?

네, 프라이버시를 중시한다면 Plausible Analytics나 Umami를 추천합니다. 둘 다 오픈소스이고, 쿠키를 사용하지 않아서 쿠키 동의 배너가 필요 없습니다. Umami는 Vercel + Supabase에 셀프 호스팅할 수 있어서 비용도 들지 않습니다. 다만 GA4만큼 상세한 분석 기능은 제공하지 않으므로 서비스 규모에 맞게 선택하세요.

Q3. 서비스 사용자가 늘어서 무료 티어를 초과하면 어떻게 하나요?

축하할 일입니다! 사용자가 늘고 있다는 뜻이니까요. 보통 무료 티어를 초과하는 시점이면 이미 수익화를 고려할 단계입니다. 우선순위는 Supabase Pro ($25/월) > Vercel Pro ($20/월) > Sentry Team ($26/월) 순서로 업그레이드하는 것을 추천합니다. Supabase가 가장 먼저 한도에 도달하는 경우가 많기 때문입니다. 총 월 $71이면 안정적인 서비스 운영이 가능합니다.

이것으로 "1인 개발자의 AI 스택" 시리즈를 마칩니다. 기획에서 운영까지, 아이디어를 현실로 만드는 전체 여정을 함께 했습니다. 이 시리즈가 여러분의 서비스 개발에 실질적인 도움이 되었기를 바랍니다. 앞으로도 1인 개발자에게 유용한 콘텐츠로 찾아뵙겠습니다. 감사합니다!

블로그 글을 유튜브 영상으로 만드는 법 — NotebookLM 동영상 변환 가이드

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

블로그에 글을 열심히 써도, 읽는 사람이 한정되어 있다는 걸 느낄 때가 있습니다.

"이 글을 영상으로도 만들 수 있으면 좋겠는데, 촬영도 편집도 할 줄 모르는데..."

결론부터 말씀드리면 — Google NotebookLM을 쓰면 블로그 글 하나로 AI 동영상을 만들 수 있습니다. 촬영 장비도, 영상 편집 기술도 필요 없습니다. 글만 있으면 됩니다.

이 글에서는 제가 실제로 블로그 포스팅을 NotebookLM 동영상으로 변환하고, 유튜브에 업로드한 전체 과정을 공유합니다.

전체 워크플로우 — 3단계

전체 흐름을 먼저 보면 이렇습니다.

블로그 글 작성 → NotebookLM에 업로드 → AI 동영상 생성 → 유튜브 업로드

단계	도구	소요 시간
1. 글 작성	티스토리 / 마크다운	이미 완료
2. 동영상 생성	NotebookLM	5~30분 (자동)
3. 유튜브 업로드	YouTube Studio	5~10분

핵심은 이미 쓴 글을 재활용한다는 것입니다. 새로 콘텐츠를 만드는 게 아닙니다.

1단계: 블로그 글 준비

어떤 글이 동영상으로 적합한가?

모든 글이 영상으로 잘 변환되는 건 아닙니다.

적합한 글	부적합한 글
개념 설명, 비교 분석	코드 위주의 튜토리얼
단계별 가이드	짧은 팁/메모
도구 소개, 후기	코드 스니펫 모음
FAQ, 체크리스트	표만 있는 정리글

예를 들어, "AI로 웹서비스 만드는 법" 같은 글은 동영상으로 만들면 시각적으로 설명이 풍부해져서 효과적입니다. 반면 코드 줄 하나하나를 설명하는 튜토리얼은 텍스트가 더 낫습니다.

글을 준비하는 방법

NotebookLM에 소스를 넣는 방법은 여러 가지입니다.

웹 URL 붙여넣기 — 티스토리 포스팅 URL을 그대로 입력
텍스트 복사/붙여넣기 — 마크다운이나 텍스트를 직접 붙여넣기
Google Docs — 구글 문서로 옮긴 후 연결
PDF 업로드 — 글을 PDF로 변환 후 업로드

가장 간단한 건 블로그 URL을 그대로 넣는 것입니다.

2단계: NotebookLM으로 AI 동영상 생성

NotebookLM 접속 및 노트북 생성

NotebookLM 접속 (구글 계정으로 로그인)
새 노트북 만들기 클릭
소스 추가 > 웹사이트 URL 또는 텍스트 붙여넣기

[이미지: NotebookLM 소스 추가 화면]

Video Overview 생성

소스를 추가하면 오른쪽에 Studio 패널이 나타납니다.

Studio 패널에서 Video Overview 선택
동영상 형식 선택
필요하면 커스텀 프롬프트로 초점을 지정
생성 클릭

[이미지: Video Overview 생성 버튼 클릭 화면]

동영상 형식 — 3가지 비교

형식	특징	가격	추천 용도
Brief	1~2분, 핵심 요약	무료	SNS 공유, 짧은 소개
Explainer	3~5분, 개념 설명	무료	유튜브 업로드, 학습 콘텐츠
Cinematic	5분 이상, 풍부한 애니메이션	Ultra ($250/월)	프로 수준 프레젠테이션

무료 계정으로는 Brief와 Explainer를 사용할 수 있습니다. 블로그 글을 유튜브 영상으로 만드는 용도라면 Explainer가 가장 적합합니다.

커스텀 프롬프트 활용

그냥 생성해도 되지만, 프롬프트를 주면 결과물이 더 좋아집니다.

"이 글의 핵심 내용을 개발자 독자를 위해 설명해줘.
Claude Code와 Supabase의 조합이 왜 효과적인지에 초점을 맞춰줘."

프롬프트로 제어할 수 있는 것들:

초점 — 어떤 부분을 중점적으로 다룰지
톤 — 전문적 / 캐주얼 / 교육적
대상 — 초보자용 / 경험자용

생성 시간

생성 버튼을 누르면 5~30분 정도 걸립니다. 페이지를 닫아도 백그라운드에서 생성이 계속됩니다. 완료되면 노트북에서 확인할 수 있습니다.

3단계: 유튜브에 업로드

동영상 다운로드

NotebookLM에서 생성된 동영상을 다운로드 합니다. MP4 파일로 저장됩니다.

YouTube Studio에서 업로드

YouTube Studio 접속
오른쪽 상단 만들기 > 동영상 업로드 클릭
다운로드한 MP4 파일 선택

메타데이터 설정 — SEO가 여기서도 중요

블로그 SEO와 마찬가지로, 유튜브도 검색 최적화가 중요합니다.

항목	팁
제목	블로그 제목을 그대로 쓰되, "영상 ver." 느낌 추가
설명	블로그 원문 링크 + 핵심 내용 요약 3~5줄
태그	블로그 태그와 동일 + "NotebookLM", "AI 동영상" 추가
썸네일	블로그 대표이미지를 재활용하거나 약간 변형
카테고리	과학/기술 또는 교육

설명란 템플릿

[블로그 원문] https://javapark.tistory.com/entry/글-슬러그

이 영상은 AI JAVAPARK 블로그 포스팅을 Google NotebookLM으로
AI 동영상으로 변환한 콘텐츠입니다.

## 목차
00:00 인트로
00:30 핵심 개념
02:00 실전 예시
04:00 정리

## 키워드
#AI개발 #ClaudeCode #NotebookLM

---
AI JAVAPARK — AI와 함께 만드는 개발 이야기
Blog: https://javapark.tistory.com

블로그 원문 링크를 설명란 맨 위에 넣으면 블로그 유입도 늘어나고, 구글 SEO에서도 상호 연결 효과를 얻을 수 있습니다.

콘텐츠 재활용 전략 — 글 하나로 3가지 만들기

이 워크플로우의 진짜 가치는 하나의 콘텐츠를 여러 형태로 재활용하는 것입니다.

블로그 글 (원본)
  ├── NotebookLM Explainer → 유튜브 영상
  ├── NotebookLM Brief → SNS 숏폼 (인스타, 쇼츠)
  └── NotebookLM Audio Overview → 팟캐스트

콘텐츠 형태	플랫폼	NotebookLM 형식
블로그 글	티스토리	원본
유튜브 영상	YouTube	Explainer / Cinematic
숏폼 영상	YouTube Shorts, 인스타	Brief
팟캐스트/오디오	Spotify, 팟빵	Audio Overview

글 하나 쓰면 4가지 채널에 콘텐츠를 배포할 수 있습니다. 1인 크리에이터에게는 이만한 효율이 없습니다.

주의할 점

AI 생성 콘텐츠 표시

유튜브는 AI로 만든 영상에 대해 AI 생성 콘텐츠임을 표시하도록 권장하고 있습니다. YouTube Studio 업로드 시 "변경되거나 합성된 콘텐츠" 옵션에서 해당 사항을 체크하세요.

무료 계정 제한

무료 NotebookLM 계정은 생성 횟수에 제한이 있습니다. 한 노트북당 생성 가능한 동영상 수가 정해져 있으므로, 프롬프트를 잘 작성해서 한 번에 만족스러운 결과를 얻는 게 중요합니다.

한국어 지원

Video Overview는 한국어를 포함한 여러 언어를 지원합니다. 다만 Cinematic 형식은 현재 영어만 지원됩니다. 무료로 사용하는 Brief/Explainer는 한국어로 생성 가능합니다.

자주 묻는 질문 (FAQ)

NotebookLM Video Overview는 무료인가요?

Brief와 Explainer 형식은 무료로 사용할 수 있습니다. 구글 계정만 있으면 됩니다. Cinematic 형식만 Ultra 구독($250/월)이 필요하지만, 블로그 글을 유튜브 영상으로 만드는 용도라면 Explainer로 충분합니다.

블로그 글 URL을 넣으면 자동으로 전체 내용을 읽나요?

네, NotebookLM이 웹페이지의 텍스트 콘텐츠를 자동으로 추출합니다. 다만 이미지나 코드 블록의 세부 내용은 반영되지 않을 수 있으므로, 중요한 내용이 텍스트로 잘 작성되어 있는지 확인하세요.

생성된 동영상의 저작권은 누구에게 있나요?

NotebookLM으로 생성한 동영상의 저작권은 생성자에게 있습니다. 상업적 사용도 가능합니다. 다만 원본 블로그 글의 내용이 타인의 저작물을 포함하고 있다면 별도로 확인이 필요합니다.

마무리

정리하면, 블로그 글을 유튜브 영상으로 만드는 과정은 이렇습니다.

블로그에 글을 쓴다 — 이미 하고 있는 일
NotebookLM에 URL을 넣고 Video Overview를 생성한다 — 5분 클릭
다운로드해서 유튜브에 업로드한다 — 메타데이터만 잘 채우면 끝

핵심은 새로운 콘텐츠를 만드는 게 아니라, 이미 쓴 글을 다른 형태로 변환하는 것입니다. 글 쓰는 시간은 이미 투자했으니, 추가 10분만 투자하면 유튜브 채널까지 운영할 수 있습니다.

저도 이 블로그의 포스팅을 하나씩 영상으로 변환해볼 예정입니다. 진행 과정도 공유하겠습니다.

여러분은 블로그 글을 다른 형태로 재활용하고 있으신가요? 댓글로 알려주세요!

참고 자료

NotebookLM 공식 사이트 — 구글 AI 리서치 도구
NotebookLM Video Overview 생성 가이드 (공식) — 동영상 개요 생성 방법
Cinematic Video Overviews 출시 발표 (Google 공식 블로그) — 2026년 3월 신기능 소개
YouTube Studio 고객센터 — 동영상 업로드 가이드

설계는 AI에게 맡겨라 — ERD, API, 와이어프레임 자동화

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

"코드부터 짜고 싶은 충동, 이해합니다. 하지만 설계 없이 시작한 프로젝트의 결말은 대부분 같습니다."

지난 포스팅에서 AI와 함께 아이디어를 검증하고 PRD를 작성하는 과정을 다뤘습니다. 이번에는 그다음 단계인 설계를 AI에게 맡기는 방법을 공유합니다. ERD, API 명세, 와이어프레임, 프로젝트 구조까지 — Claude Code 하나로 해결하는 과정을 보여드리겠습니다.

설계를 건너뛰면 생기는 일

1인 개발자가 가장 흔히 하는 실수 중 하나는 "일단 코드부터 짜자"입니다. 저도 수없이 겪었습니다.

테이블 하나 추가하려니 기존 구조와 충돌
API 엔드포인트 네이밍이 중구난방
화면을 만들다 보니 필요한 데이터가 빠져 있어서 DB 수정
결국 전체 리팩토링 — 사실상 처음부터 다시 만들기

설계에 2-3시간만 투자하면, 개발 과정에서 수십 시간을 아낄 수 있습니다. 그리고 이제는 그 2-3시간마저 AI가 크게 줄여줍니다.

ERD 설계 — Claude Code에게 데이터베이스 설계 맡기기

프롬프트: Supabase 테이블 설계 요청

Claude Code에 아래와 같이 요청합니다. 핵심은 지난 포스팅에서 만든 PRD를 컨텍스트로 함께 전달하는 것입니다.

이 PRD를 기반으로 Supabase(PostgreSQL) 데이터베이스를 설계해줘.

요구사항:
- users, books, reading_records, memos 테이블
- Supabase Auth의 auth.users와 연동
- RLS(Row Level Security) 정책 포함
- created_at, updated_at 자동 관리
- 적절한 인덱스 포함

결과물:
1. ERD (텍스트 기반)
2. Supabase SQL (테이블 생성 + RLS + 인덱스)

Claude Code가 생성한 ERD

┌─────────────────┐     ┌──────────────────────┐
│     profiles     │     │        books          │
├─────────────────┤     ├──────────────────────┤
│ id (uuid, PK)   │──┐  │ id (uuid, PK)         │
│ username         │  │  │ isbn (varchar, UQ)     │
│ avatar_url       │  │  │ title                  │
│ created_at       │  │  │ author                 │
│ updated_at       │  │  │ publisher              │
└─────────────────┘  │  │ cover_image_url        │
                      │  │ page_count             │
                      │  │ published_date         │
                      │  │ description            │
                      │  │ created_at             │
                      │  └──────────────────────┘
                      │
                      │  ┌──────────────────────┐
                      │  │   reading_records      │
                      │  ├──────────────────────┤
                      ├──│ user_id (uuid, FK)     │
                      │  │ book_id (uuid, FK)     │
                      │  │ status (enum)          │
                      │  │ start_date             │
                      │  │ end_date               │
                      │  │ rating (1-5)           │
                      │  │ created_at             │
                      │  │ updated_at             │
                      │  └──────────────────────┘
                      │
                      │  ┌──────────────────────┐
                      │  │       memos            │
                      │  ├──────────────────────┤
                      └──│ user_id (uuid, FK)     │
                         │ book_id (uuid, FK)     │
                         │ content (text)         │
                         │ page_number (int)      │
                         │ memo_type (enum)       │
                         │ created_at             │
                         │ updated_at             │
                         └──────────────────────┘

Supabase SQL — 테이블 생성

-- 1. 커스텀 타입 정의
CREATE TYPE reading_status AS ENUM ('want_to_read', 'reading', 'finished');
CREATE TYPE memo_type AS ENUM ('note', 'quote', 'review');

-- 2. profiles 테이블 (Supabase Auth 연동)
CREATE TABLE profiles (
  id UUID REFERENCES auth.users(id) ON DELETE CASCADE PRIMARY KEY,
  username TEXT UNIQUE,
  avatar_url TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- 3. books 테이블
CREATE TABLE books (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  isbn VARCHAR(13) UNIQUE,
  title TEXT NOT NULL,
  author TEXT NOT NULL,
  publisher TEXT,
  cover_image_url TEXT,
  page_count INTEGER,
  published_date DATE,
  description TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- 4. reading_records 테이블
CREATE TABLE reading_records (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id UUID REFERENCES profiles(id) ON DELETE CASCADE NOT NULL,
  book_id UUID REFERENCES books(id) ON DELETE CASCADE NOT NULL,
  status reading_status DEFAULT 'want_to_read',
  start_date DATE,
  end_date DATE,
  rating SMALLINT CHECK (rating >= 1 AND rating <= 5),
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(user_id, book_id)
);

-- 5. memos 테이블
CREATE TABLE memos (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id UUID REFERENCES profiles(id) ON DELETE CASCADE NOT NULL,
  book_id UUID REFERENCES books(id) ON DELETE CASCADE NOT NULL,
  content TEXT NOT NULL,
  page_number INTEGER,
  memo_type memo_type DEFAULT 'note',
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- 6. 인덱스
CREATE INDEX idx_reading_records_user ON reading_records(user_id);
CREATE INDEX idx_reading_records_status ON reading_records(user_id, status);
CREATE INDEX idx_memos_user_book ON memos(user_id, book_id);
CREATE INDEX idx_books_isbn ON books(isbn);

-- 7. updated_at 자동 갱신 트리거
CREATE OR REPLACE FUNCTION update_updated_at()
RETURNS TRIGGER AS $$
BEGIN
  NEW.updated_at = NOW();
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER profiles_updated_at
  BEFORE UPDATE ON profiles
  FOR EACH ROW EXECUTE FUNCTION update_updated_at();

CREATE TRIGGER reading_records_updated_at
  BEFORE UPDATE ON reading_records
  FOR EACH ROW EXECUTE FUNCTION update_updated_at();

CREATE TRIGGER memos_updated_at
  BEFORE UPDATE ON memos
  FOR EACH ROW EXECUTE FUNCTION update_updated_at();

RLS 정책 설정 — 보안의 핵심

Supabase에서 RLS는 선택이 아니라 필수입니다. 각 사용자가 자신의 데이터만 읽고 쓸 수 있도록 정책을 설정합니다.

-- RLS 활성화
ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;
ALTER TABLE reading_records ENABLE ROW LEVEL SECURITY;
ALTER TABLE memos ENABLE ROW LEVEL SECURITY;

-- profiles: 본인만 조회/수정
CREATE POLICY "Users can view own profile"
  ON profiles FOR SELECT
  USING (auth.uid() = id);

CREATE POLICY "Users can update own profile"
  ON profiles FOR UPDATE
  USING (auth.uid() = id);

-- reading_records: 본인만 CRUD
CREATE POLICY "Users can manage own records"
  ON reading_records FOR ALL
  USING (auth.uid() = user_id);

-- memos: 본인만 CRUD
CREATE POLICY "Users can manage own memos"
  ON memos FOR ALL
  USING (auth.uid() = user_id);

-- books: 누구나 조회 가능, 인증된 사용자만 추가 가능
ALTER TABLE books ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Anyone can view books"
  ON books FOR SELECT
  USING (true);

CREATE POLICY "Authenticated users can insert books"
  ON books FOR INSERT
  WITH CHECK (auth.role() = 'authenticated');

API 명세 자동 생성 — RESTful 엔드포인트 설계

Supabase는 테이블 기반으로 자동 REST API를 제공하지만, 프론트엔드에서 사용할 서비스 레이어의 함수 명세를 미리 정의해두면 개발이 훨씬 매끄럽습니다.

API 명세 생성 프롬프트

위 DB 스키마 기반으로 프론트엔드에서 사용할 API 함수 명세를 만들어줘.

조건:
- Supabase JS Client 사용
- TypeScript 타입 정의 포함
- 에러 처리 패턴 포함

카테고리:
1. Auth (로그인, 로그아웃, 프로필)
2. Books (검색, 등록)
3. Reading Records (CRUD, 상태 변경)
4. Memos (CRUD)

생성된 TypeScript 타입 정의

// types/database.ts

export type ReadingStatus = 'want_to_read' | 'reading' | 'finished';
export type MemoType = 'note' | 'quote' | 'review';

export interface Profile {
  id: string;
  username: string | null;
  avatar_url: string | null;
  created_at: string;
  updated_at: string;
}

export interface Book {
  id: string;
  isbn: string | null;
  title: string;
  author: string;
  publisher: string | null;
  cover_image_url: string | null;
  page_count: number | null;
  published_date: string | null;
  description: string | null;
  created_at: string;
}

export interface ReadingRecord {
  id: string;
  user_id: string;
  book_id: string;
  status: ReadingStatus;
  start_date: string | null;
  end_date: string | null;
  rating: number | null;
  created_at: string;
  updated_at: string;
  book?: Book; // join 시
}

export interface Memo {
  id: string;
  user_id: string;
  book_id: string;
  content: string;
  page_number: number | null;
  memo_type: MemoType;
  created_at: string;
  updated_at: string;
}

서비스 함수 명세 예시

// services/books.ts
import { supabase } from '@/lib/supabase';
import type { Book } from '@/types/database';

// ISBN으로 책 검색 (외부 API)
export async function searchBookByISBN(isbn: string): Promise<Book | null> {
  // 1. 먼저 DB에서 검색
  const { data } = await supabase
    .from('books')
    .select('*')
    .eq('isbn', isbn)
    .single();

  if (data) return data;

  // 2. DB에 없으면 알라딘 API로 검색 후 DB에 저장
  const bookInfo = await fetchFromAladinAPI(isbn);
  if (!bookInfo) return null;

  const { data: newBook, error } = await supabase
    .from('books')
    .insert(bookInfo)
    .select()
    .single();

  if (error) throw error;
  return newBook;
}

// 제목으로 책 검색
export async function searchBooksByTitle(
  query: string
): Promise<Book[]> {
  const { data, error } = await supabase
    .from('books')
    .select('*')
    .ilike('title', `%${query}%`)
    .limit(20);

  if (error) throw error;
  return data ?? [];
}

와이어프레임 — AI로 화면 구조 잡기

디자이너 없이 화면을 설계해야 하는 1인 개발자에게, 텍스트 기반 와이어프레임은 매우 실용적인 방법입니다.

와이어프레임 생성 프롬프트

독서 기록 웹앱의 주요 화면 와이어프레임을 텍스트로 만들어줘.

필요한 화면:
1. 대시보드 (내 독서 목록)
2. 책 상세 페이지
3. 책 등록 페이지 (ISBN 검색)
4. 메모 작성 페이지

각 화면에 포함할 것:
- 레이아웃 구조 (ASCII 아트)
- 필요한 컴포넌트 목록
- 사용자 인터랙션 흐름

대시보드 와이어프레임

┌─────────────────────────────────────────────────┐
│  [Logo] BookLog        [검색]    [프로필 아바타] │
├─────────────────────────────────────────────────┤
│                                                  │
│  ┌─ 탭 ──────────────────────────────────────┐  │
│  │ [읽는 중 (3)]  [완료 (12)]  [읽고 싶은 (5)]│  │
│  └───────────────────────────────────────────┘  │
│                                                  │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐         │
│  │ [커버]  │  │ [커버]  │  │ [커버]  │         │
│  │ 제목    │  │ 제목    │  │ 제목    │         │
│  │ 저자    │  │ 저자    │  │ 저자    │         │
│  │ ★★★★☆ │  │ ★★★☆☆ │  │         │         │
│  │ 메모 3  │  │ 메모 1  │  │ [등록]  │         │
│  └─────────┘  └─────────┘  └─────────┘         │
│                                                  │
│              [+ 새 책 등록]                      │
│                                                  │
├─────────────────────────────────────────────────┤
│  올해 읽은 책: 12권 / 목표 24권  [████░░] 50%   │
└─────────────────────────────────────────────────┘

이 와이어프레임을 기반으로 실제 UI를 구현할 때, Claude Code에게 "이 와이어프레임대로 Tailwind CSS로 구현해줘"라고 요청하면 꽤 정확한 결과를 얻을 수 있습니다.

기술 스택 선정 — Next.js + Supabase + Vercel 조합의 이유

1인 개발자에게 기술 스택 선택은 생산성이 최우선입니다. 화려한 스택보다 빠르게 만들고, 쉽게 배포하고, 저렴하게 운영할 수 있는 조합이 중요합니다.

레이어	선택	이유
프론트엔드	Next.js (App Router)	React 생태계, SSR/SSG 지원, Vercel 최적화
백엔드/DB	Supabase	PostgreSQL + Auth + Storage + Realtime 올인원
스타일링	Tailwind CSS	유틸리티 기반, AI가 생성하기 쉬움
배포	Vercel	Git push로 자동 배포, 무료 플랜 충분
AI 개발 도구	Claude Code	코드 생성, 리팩토링, 디버깅

왜 Supabase인가?

솔직히 말하면, Firebase도 좋은 선택입니다. 하지만 Supabase를 선택한 이유는 세 가지입니다.

PostgreSQL — 관계형 DB의 강력함 (JOIN, 트랜잭션)
RLS — 별도 백엔드 서버 없이 보안 처리 가능
무료 플랜 — 사이드 프로젝트에 충분한 무료 티어 (500MB DB, 1GB Storage)

프로젝트 구조 생성 — Claude Code로 보일러플레이트 자동 생성

프로젝트 구조 생성 프롬프트

Next.js 14 (App Router) + Supabase + Tailwind CSS 프로젝트 구조를 만들어줘.

구조 규칙:
- app/ 디렉토리 사용 (App Router)
- 컴포넌트는 components/ 하위에 기능별로 분류
- Supabase 클라이언트는 lib/supabase.ts
- 타입 정의는 types/
- 서비스 로직은 services/

기능:
- 인증 (로그인/회원가입)
- 책 관리 (검색, 등록)
- 독서 기록 (CRUD)
- 메모 (CRUD)

Claude Code가 생성한 프로젝트 구조

book-log/
├── app/
│   ├── layout.tsx              # 루트 레이아웃
│   ├── page.tsx                # 랜딩 페이지
│   ├── globals.css
│   ├── (auth)/
│   │   ├── login/page.tsx      # 로그인
│   │   └── callback/route.ts   # OAuth 콜백
│   ├── (main)/
│   │   ├── layout.tsx          # 인증된 사용자 레이아웃
│   │   ├── dashboard/page.tsx  # 대시보드
│   │   ├── books/
│   │   │   ├── page.tsx        # 책 검색/등록
│   │   │   └── [id]/page.tsx   # 책 상세
│   │   └── memos/
│   │       └── [bookId]/page.tsx # 메모 목록
│   └── api/
│       └── books/
│           └── search/route.ts  # ISBN 검색 API
├── components/
│   ├── ui/                     # 공통 UI 컴포넌트
│   │   ├── Button.tsx
│   │   ├── Input.tsx
│   │   ├── Card.tsx
│   │   └── Modal.tsx
│   ├── auth/
│   │   └── AuthButton.tsx
│   ├── books/
│   │   ├── BookCard.tsx
│   │   ├── BookSearch.tsx
│   │   └── BookList.tsx
│   ├── records/
│   │   ├── StatusBadge.tsx
│   │   └── RecordForm.tsx
│   └── memos/
│       ├── MemoCard.tsx
│       └── MemoEditor.tsx
├── lib/
│   ├── supabase.ts             # Supabase 클라이언트 (브라우저)
│   └── supabase-server.ts      # Supabase 클라이언트 (서버)
├── services/
│   ├── auth.ts
│   ├── books.ts
│   ├── records.ts
│   └── memos.ts
├── types/
│   └── database.ts             # DB 타입 정의
├── middleware.ts                # 인증 미들웨어
└── .env.local                  # 환경 변수

Supabase 클라이언트 설정 코드

// lib/supabase.ts
import { createBrowserClient } from '@supabase/ssr';

export const supabase = createBrowserClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);

// lib/supabase-server.ts
import { createServerClient } from '@supabase/ssr';
import { cookies } from 'next/headers';

export async function createClient() {
  const cookieStore = await cookies();

  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll();
        },
        setAll(cookiesToSet) {
          cookiesToSet.forEach(({ name, value, options }) =>
            cookieStore.set(name, value, options)
          );
        },
      },
    }
  );
}

설계 단계에서 Claude Code를 잘 쓰는 팁

CLAUDE.md 파일 활용하기

프로젝트 루트에 CLAUDE.md 파일을 만들어서 프로젝트 컨텍스트를 미리 정의해두면, Claude Code가 훨씬 일관된 결과를 생성합니다.

# BookLog 프로젝트

## 기술 스택
- Next.js 14 (App Router)
- Supabase (PostgreSQL, Auth, Storage)
- Tailwind CSS
- TypeScript

## 코딩 컨벤션
- 컴포넌트: PascalCase (BookCard.tsx)
- 함수/변수: camelCase
- 타입: PascalCase (interface Book)
- 파일 구조: 기능별 분류

## DB 스키마
- profiles, books, reading_records, memos
- RLS 사용, auth.uid() 기반 권한 관리

자주 묻는 질문 (FAQ)

Q1. Supabase를 처음 쓰는데, RLS 설정이 어렵지 않나요?

솔직히 처음에는 헷갈립니다. 하지만 패턴이 정해져 있어서 한 번 이해하면 쉽습니다. 핵심은 auth.uid() = user_id 하나입니다. "이 행의 user_id가 로그인한 사용자의 id와 같으면 허용"이라는 뜻이죠. 이 포스팅의 SQL을 그대로 사용하셔도 됩니다.

Q2. ERD 설계를 AI에게 맡기면 문제가 생기지 않나요?

AI가 생성한 스키마를 그대로 프로덕션에 쓰면 문제가 될 수 있습니다. 하지만 초기 설계의 출발점으로는 훌륭합니다. 중요한 건 생성된 스키마를 직접 검토하는 것입니다. 특히 인덱스, 제약 조건, 데이터 타입은 반드시 확인하세요.

Q3. 와이어프레임을 텍스트로 만드는 게 Figma보다 나은가요?

"나은가"보다는 "빠른가"의 문제입니다. Figma로 완성도 높은 디자인을 만들 수 있지만, 1인 개발자에게 그 시간은 사치일 수 있습니다. 텍스트 와이어프레임으로 구조를 먼저 잡고, 필요하면 나중에 Figma로 다듬는 순서를 추천합니다.

여러분은 사이드 프로젝트 설계할 때 어떤 도구를 쓰고 계신가요? 댓글로 공유해주세요!

다음 포스팅에서는 "AI로 풀스택 개발하기 — Claude Code + Supabase 실전"을 주제로, 실제 코드를 작성하며 웹앱을 완성하는 과정을 다뤄보겠습니다.

배포 자동화 — Vercel + GitHub 원클릭 배포

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

지난 포스팅에서 Next.js와 Supabase로 풀스택 서비스를 개발했습니다. 이제 만든 서비스를 세상에 내놓을 차례입니다. 하지만 배포라는 단어만 들어도 머리가 아프신 분들이 많을 겁니다. 서버 세팅, SSL 인증서, CI/CD 파이프라인 구성... 과거에는 이 모든 것을 직접 해야 했습니다.

2026년 현재, Vercel을 사용하면 git push 한 번으로 배포가 끝납니다. 이번 포스팅에서는 Vercel과 GitHub를 연동해서 완전 자동 배포 환경을 구축하는 방법을 단계별로 알려드리겠습니다.

왜 Vercel인가?

1인 개발자에게 Vercel이 최적인 이유는 명확합니다.

Next.js 최적화: Vercel은 Next.js를 만든 회사입니다. App Router, Server Components, Edge Runtime 등 Next.js의 모든 기능을 가장 먼저, 가장 잘 지원합니다.
무료 티어가 넉넉합니다: Hobby 플랜으로 월 100GB 대역폭, 무제한 배포, 커스텀 도메인까지 무료로 사용할 수 있습니다.
자동 배포: GitHub에 push하면 자동으로 빌드하고 배포합니다. CI/CD 파이프라인을 따로 구성할 필요가 없습니다.
프리뷰 배포: PR을 올리면 자동으로 프리뷰 URL이 생성됩니다. 코드 리뷰 없이도 변경 사항을 눈으로 확인할 수 있습니다.
글로벌 Edge Network: 전 세계 어디서든 빠르게 접속할 수 있습니다.

Vercel vs Netlify vs GitHub Pages 비교

배포 플랫폼을 고민하시는 분들을 위해 비교표를 준비했습니다.

항목	Vercel	Netlify	GitHub Pages
Next.js 지원	완벽 (공식)	좋음 (플러그인)	정적만 가능
서버리스 함수	지원 (Edge/Node)	지원 (Node)	미지원
무료 대역폭	100GB/월	100GB/월	100GB/월
빌드 시간	6,000분/월	300분/월	2,000분/월
프리뷰 배포	자동	자동	미지원
커스텀 도메인	무료	무료	무료
SSL	자동	자동	자동
Edge Functions	지원	지원	미지원
분석 도구	내장	유료 애드온	미지원

결론: Next.js 프로젝트라면 Vercel이 압도적으로 유리합니다. Netlify도 훌륭하지만, Next.js의 최신 기능을 100% 활용하려면 Vercel이 최선입니다. GitHub Pages는 정적 사이트 전용이므로 풀스택 프로젝트에는 적합하지 않습니다.

Vercel 계정 생성 및 GitHub 연동

1단계: Vercel 가입

vercel.com에 접속해서 Sign Up 버튼을 클릭합니다. GitHub 계정으로 가입하는 것을 추천합니다. 연동이 자동으로 이루어지기 때문입니다.

1. vercel.com 접속
2. "Sign Up" 클릭
3. "Continue with GitHub" 선택
4. GitHub 권한 허용
5. Hobby (무료) 플랜 선택

2단계: GitHub 저장소 권한 설정

가입 후 Vercel이 GitHub 저장소에 접근할 수 있도록 권한을 설정합니다.

GitHub Settings → Applications → Vercel
→ "Repository access" 에서 배포할 저장소 선택
→ 전체 저장소를 허용하거나, 특정 저장소만 선택 가능

보안을 위해 특정 저장소만 선택하는 것을 추천합니다. 필요할 때 저장소를 추가하면 됩니다.

프로젝트 Import -- 첫 배포

3단계: 프로젝트 가져오기

Vercel 대시보드에서 "Add New Project" 를 클릭하고 GitHub 저장소를 선택합니다.

1. Vercel 대시보드 → "Add New Project"
2. "Import Git Repository" 에서 저장소 선택
3. Framework Preset: Next.js (자동 감지됨)
4. Root Directory: ./ (기본값)
5. "Deploy" 클릭

Vercel은 package.json을 분석해서 프레임워크를 자동으로 감지합니다. Next.js 프로젝트라면 별도 설정 없이 바로 배포가 시작됩니다.

4단계: 빌드 설정 확인

대부분의 경우 기본 설정으로 충분하지만, 필요하다면 빌드 설정을 커스터마이징할 수 있습니다.

// vercel.json (프로젝트 루트에 생성)
{
  "buildCommand": "next build",
  "outputDirectory": ".next",
  "installCommand": "npm install",
  "framework": "nextjs"
}

첫 배포가 완료되면 https://프로젝트명.vercel.app 형태의 URL이 자동으로 생성됩니다. 이 URL로 바로 접속해서 서비스를 확인할 수 있습니다.

환경변수 설정

서비스가 정상 작동하려면 Supabase URL, API Key 등의 환경변수가 필요합니다. 로컬에서 .env.local 파일에 넣었던 값들을 Vercel에도 설정해야 합니다.

Vercel 대시보드에서 설정

1. Vercel 대시보드 → 프로젝트 선택
2. Settings → Environment Variables
3. 환경변수 추가

아래 환경변수들을 추가합니다.

# Supabase 연동
NEXT_PUBLIC_SUPABASE_URL=https://xxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIs...

# OpenAI API (서버 사이드 전용)
OPENAI_API_KEY=sk-...

# 기타 설정
NEXT_PUBLIC_APP_URL=https://yourdomain.com

환경변수 스코프 설정

Vercel은 환경변수를 환경별로 분리할 수 있습니다.

환경	용도	예시
Production	실제 서비스	실제 Supabase 프로젝트
Preview	PR 프리뷰	테스트용 Supabase 프로젝트
Development	로컬 개발	로컬 환경변수

Environment Variables 설정 화면에서:
→ 각 변수마다 Production / Preview / Development 체크박스로 스코프 지정
→ OPENAI_API_KEY 같은 민감한 키는 "Sensitive" 옵션 활성화

주의사항: NEXT_PUBLIC_ 접두사가 붙은 변수는 클라이언트에 노출됩니다. API 시크릿 키에는 절대 NEXT_PUBLIC_을 붙이지 마세요.

Vercel CLI로 환경변수 관리

터미널에서도 환경변수를 관리할 수 있습니다.

# Vercel CLI 설치
npm i -g vercel

# 로그인
vercel login

# 환경변수 추가
vercel env add OPENAI_API_KEY production
# 프롬프트에서 값 입력

# 환경변수 목록 확인
vercel env ls

# 환경변수를 로컬 .env.local로 가져오기
vercel env pull .env.local

vercel env pull 명령은 팀원과 환경변수를 공유할 때 매우 유용합니다. .env.local 파일을 직접 주고받을 필요 없이, Vercel에서 바로 가져올 수 있습니다.

커스텀 도메인 연결

프로젝트명.vercel.app 도 좋지만, 자신만의 도메인으로 서비스하면 훨씬 전문적으로 보입니다.

도메인 구매

도메인은 다양한 곳에서 구매할 수 있습니다.

Vercel Domains: Vercel 대시보드에서 바로 구매 가능
Namecheap: 저렴한 가격
Cloudflare: DNS와 함께 관리 편리
가비아: 한국 도메인(.kr) 등록 시

DNS 설정

도메인을 구매했다면 DNS 레코드를 설정합니다.

1. Vercel 대시보드 → 프로젝트 → Settings → Domains
2. 도메인 입력 (예: myapp.com)
3. "Add" 클릭
4. Vercel이 안내하는 DNS 레코드를 도메인 관리 사이트에 추가

일반적으로 아래 두 가지 레코드를 추가하면 됩니다.

# A 레코드 (루트 도메인)
Type: A
Name: @
Value: 76.76.21.21

# CNAME 레코드 (www 서브도메인)
Type: CNAME
Name: www
Value: cname.vercel-dns.com

SSL 인증서 -- 자동 발급

Vercel은 도메인을 연결하면 Let's Encrypt SSL 인증서를 자동으로 발급합니다. 별도의 설정이 필요 없습니다. 인증서 갱신도 자동으로 처리됩니다.

도메인 연결 후 약 1~5분 내에:
→ SSL 인증서 자동 발급
→ HTTP → HTTPS 자동 리다이렉트 설정
→ www → non-www (또는 반대) 자동 리다이렉트

프리뷰 배포 -- PR마다 자동 미리보기 URL

프리뷰 배포는 Vercel의 가장 강력한 기능 중 하나입니다. Pull Request를 올리면 자동으로 해당 변경 사항이 적용된 별도의 URL이 생성됩니다.

작동 방식

1. 새 브랜치 생성: git checkout -b feature/new-ui
2. 코드 수정 후 push: git push origin feature/new-ui
3. GitHub에서 PR 생성
4. Vercel이 자동으로 프리뷰 빌드 시작
5. PR 코멘트에 프리뷰 URL 자동 게시
   → https://프로젝트-git-feature-new-ui-username.vercel.app

프리뷰 배포 활용법

# 기능 브랜치 생성
git checkout -b feature/dark-mode

# 코드 수정
# ...

# 커밋 및 푸시
git add .
git commit -m "feat: 다크모드 추가"
git push origin feature/dark-mode

# GitHub에서 PR 생성 후 Vercel 프리뷰 URL로 확인
# → 모바일에서도 접속해서 테스트 가능
# → 팀원이나 지인에게 URL 공유해서 피드백 받기

1인 개발자라도 프리뷰 배포를 적극 활용하세요. 프로덕션에 바로 머지하기 전에 실제 환경에서 테스트할 수 있어서 실수를 크게 줄일 수 있습니다.

프리뷰 배포 환경변수 분리

프리뷰 배포에서는 테스트용 환경변수를 사용하는 것이 안전합니다.

Vercel 대시보드 → Settings → Environment Variables
→ NEXT_PUBLIC_SUPABASE_URL 변수를 Preview 환경에만 따로 설정
→ 테스트용 Supabase 프로젝트 URL 입력

이렇게 하면 프리뷰 배포에서 실수로 프로덕션 데이터를 건드리는 일을 방지할 수 있습니다.

배포 최적화

빌드 캐시 활용

Vercel은 빌드 캐시를 자동으로 관리합니다. 하지만 next.config.js에서 추가 최적화가 가능합니다.

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  // 이미지 최적화
  images: {
    formats: ['image/avif', 'image/webp'],
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '*.supabase.co',
      },
    ],
  },

  // 헤더 설정 (캐시 최적화)
  async headers() {
    return [
      {
        source: '/api/:path*',
        headers: [
          { key: 'Cache-Control', value: 's-maxage=60, stale-while-revalidate=300' },
        ],
      },
      {
        source: '/:path*.(jpg|jpeg|png|gif|ico|svg)',
        headers: [
          { key: 'Cache-Control', value: 'public, max-age=31536000, immutable' },
        ],
      },
    ];
  },
};

module.exports = nextConfig;

Edge Functions 활용

API 응답 속도를 높이고 싶다면 Edge Functions를 활용합니다. Edge Functions는 사용자와 가장 가까운 서버에서 실행되므로 지연 시간이 크게 줄어듭니다.

// app/api/hello/route.ts
export const runtime = 'edge'; // Edge Runtime 사용

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const name = searchParams.get('name') || 'World';

  return new Response(
    JSON.stringify({ message: `Hello, ${name}!` }),
    {
      headers: { 'Content-Type': 'application/json' },
    }
  );
}

// app/api/og/route.tsx
// OG 이미지 동적 생성 (Edge에서 실행)
import { ImageResponse } from 'next/og';

export const runtime = 'edge';

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const title = searchParams.get('title') || '기본 제목';

  return new ImageResponse(
    (
      <div style={{
        display: 'flex',
        fontSize: 48,
        background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
        color: 'white',
        width: '100%',
        height: '100%',
        alignItems: 'center',
        justifyContent: 'center',
        padding: 48,
      }}>
        {title}
      </div>
    ),
    { width: 1200, height: 630 }
  );
}

빌드 시간 단축 팁

// package.json
{
  "scripts": {
    "build": "next build",
    "vercel-build": "next build"
  }
}

// next.config.js에 추가
const nextConfig = {
  // 빌드 시 불필요한 페이지 제외 (개발용 페이지 등)
  experimental: {
    // 병렬 빌드 최적화
    workerThreads: true,
    cpus: 4,
  },
};

롤백 -- 문제 발생 시 이전 버전 복원

배포 후 문제가 발생했을 때 빠르게 이전 버전으로 되돌리는 것은 매우 중요합니다. Vercel은 이 과정을 매우 간단하게 만들어 줍니다.

대시보드에서 롤백

1. Vercel 대시보드 → 프로젝트 → Deployments 탭
2. 정상 작동하던 이전 배포를 찾기
3. 해당 배포의 "..." 메뉴 클릭
4. "Promote to Production" 선택
5. 즉시 이전 버전으로 복원 완료

CLI로 롤백

# 배포 목록 확인
vercel ls

# 특정 배포를 프로덕션으로 승격
vercel promote [deployment-url]

# 예시
vercel promote myapp-abc123.vercel.app

롤백 전략

1인 개발자에게 추천하는 롤백 전략입니다.

1. 배포 전: 현재 프로덕션 URL 메모
2. 배포 후: 핵심 기능 5분 내 수동 테스트
3. 문제 발견: 즉시 이전 버전으로 롤백
4. 원인 분석: 로컬에서 디버깅 후 수정 배포

자동 배포 워크플로 전체 요약

최종적으로 완성된 배포 워크플로를 정리합니다.

[코드 수정] → [git push] → [Vercel 자동 빌드]
                                    ↓
                            [빌드 성공?]
                           /            \
                        Yes              No
                         ↓                ↓
                  [자동 배포]      [빌드 로그 확인]
                       ↓                  ↓
              [헬스 체크 통과?]    [코드 수정 후 재push]
                     ↓
            [프로덕션 반영 완료]

단계	작업	소요 시간
push	`git push origin main`	즉시
빌드	Next.js 빌드 + 최적화	1~3분
배포	Edge Network 배포	30초
SSL	인증서 확인	자동
완료	프로덕션 반영	총 2~4분

자주 묻는 질문 (FAQ)

Q1. Vercel 무료 플랜으로 실제 서비스 운영이 가능한가요?

네, 가능합니다. Vercel Hobby 플랜은 월 100GB 대역폭, 무제한 배포를 제공합니다. 일일 방문자가 수천 명 수준이라면 무료 플랜으로 충분합니다. 다만, 상업적 용도(팀 프로젝트, 유료 서비스)라면 Pro 플랜을 권장합니다. Hobby 플랜은 비상업적/개인 프로젝트 용도입니다.

Q2. 환경변수를 변경하면 자동으로 재배포되나요?

아닙니다. 환경변수를 변경한 후에는 수동으로 재배포해야 합니다. Vercel 대시보드에서 Deployments 탭의 최신 배포에서 "Redeploy" 를 클릭하거나, 빈 커밋을 push하면 됩니다.

# 빈 커밋으로 재배포 트리거
git commit --allow-empty -m "chore: trigger redeploy"
git push origin main

Q3. 빌드가 실패했을 때 어떻게 디버깅하나요?

Vercel 대시보드에서 실패한 배포를 클릭하면 전체 빌드 로그를 확인할 수 있습니다. 가장 흔한 빌드 실패 원인은 다음과 같습니다.

환경변수 미설정: 로컬에서는 .env.local에 있지만 Vercel에 등록하지 않은 경우
타입 에러: 로컬에서는 무시했지만 next build 시 에러가 발생하는 경우
의존성 문제: package-lock.json이 커밋되지 않은 경우

로컬에서 next build를 먼저 실행해서 빌드 에러를 확인하는 습관을 들이세요.

다음 포스팅에서는 서비스를 출시한 후 반드시 해야 할 운영과 모니터링 에 대해 다룹니다. 에러 트래킹, 사용자 분석, 비용 관리까지 -- 1인 개발자가 서비스를 안정적으로 운영하는 방법을 알려드리겠습니다.

블로그 대표이미지를 코드로 만드는 법 — HTML + Playwright PNG 변환

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

블로그 포스팅을 쓸 때마다 고민되는 게 있습니다 — 대표이미지.

"포토샵은 못 쓰고, Canva는 매번 접속하기 귀찮고, 일관된 스타일을 유지하고 싶은데..."

결론부터 말씀드리면 — HTML+CSS로 이미지를 디자인하고, Playwright로 PNG를 캡처하면 됩니다. 이 블로그의 모든 대표이미지가 이 방식으로 만들어졌습니다.

왜 HTML로 이미지를 만드는가?

방법	장점	단점
포토샵/피그마	자유도 높음	매번 수동 작업, 라이선스 비용
Canva	쉽고 빠름	템플릿 느낌, 일관성 유지 어려움
HTML+CSS	코드로 관리, 재사용, 자동화 가능	CSS 지식 필요

개발자에게 HTML+CSS 방식이 유리한 이유는 세 가지입니다.

코드 = 템플릿 — 한 번 만들면 텍스트만 바꿔서 재사용
버전 관리 — Git으로 이미지 소스를 관리할 수 있음
자동화 — Claude Code에게 "이 포스팅용 대표이미지 만들어줘" 한 마디로 생성 가능

전체 워크플로우

HTML+CSS 작성 → 브라우저에서 확인 → Playwright로 PNG 캡처 → 블로그에 사용

단계	도구	소요 시간
1. HTML 작성	VS Code / Claude Code	5~10분
2. 미리보기	브라우저에서 파일 열기	즉시
3. PNG 캡처	Playwright	즉시

1단계: HTML+CSS로 이미지 디자인

기본 구조 — 썸네일 (1200x630)

블로그 OG 이미지, 유튜브 썸네일용 비율입니다.

<!DOCTYPE html>
<html lang="ko">
<head>
<meta charset="UTF-8">
<style>
  * { margin: 0; padding: 0; box-sizing: border-box; }
  body {
    width: 1200px;
    height: 630px;
    display: flex;
    align-items: center;
    justify-content: center;
    background: linear-gradient(135deg, #0f172a 0%, #1e293b 50%, #0f172a 100%);
    font-family: 'Segoe UI', 'Malgun Gothic', sans-serif;
    overflow: hidden;
    position: relative;
  }

  h1 {
    color: #f1f5f9;
    font-size: 48px;
    font-weight: 800;
    text-align: center;
    line-height: 1.3;
  }

  h1 span {
    background: linear-gradient(90deg, #0ea5e9, #8b5cf6);
    -webkit-background-clip: text;
    -webkit-text-fill-color: transparent;
  }
</style>
</head>
<body>
  <h1>여기에 <span>제목</span>을<br>입력합니다</h1>
</body>
</html>

이것만으로도 다크 배경에 그라데이션 텍스트가 들어간 이미지가 됩니다.

기본 구조 — 대표이미지 (1080x1080)

SNS 공유, 티스토리 대표이미지용 1:1 비율입니다.

<style>
  * { margin: 0; padding: 0; box-sizing: border-box; }
  html { width: 1080px; height: 1080px; overflow: hidden; }
  body {
    width: 1080px;
    height: 1080px;
    /* 나머지는 동일 */
  }
</style>

핵심: 1:1 비율일 때는 html에도 width, height, overflow: hidden을 넣어야 캡처 시 여백이 생기지 않습니다.

2단계: 디자인 요소 추가하기

기본 구조에 시각적 요소를 더하면 완성도가 올라갑니다. 이 블로그에서 실제로 사용하는 패턴을 공개합니다.

그리드 배경

body::before {
  content: '';
  position: absolute;
  inset: 0;
  background-image:
    linear-gradient(rgba(14,165,233,0.06) 1px, transparent 1px),
    linear-gradient(90deg, rgba(14,165,233,0.06) 1px, transparent 1px);
  background-size: 40px 40px;
}

반투명 격자 패턴으로 "기술적인 느낌"을 줍니다. 배경에 깔아두면 단순한 배경이 살아납니다.

글로우 오브(Glow Orb)

.orb {
  position: absolute;
  border-radius: 50%;
  filter: blur(80px);
  opacity: 0.3;
}
.orb-1 { width: 350px; height: 350px; background: #0ea5e9; top: -100px; left: 150px; }
.orb-2 { width: 280px; height: 280px; background: #8b5cf6; bottom: -80px; right: 100px; }

<div class="orb orb-1"></div>
<div class="orb orb-2"></div>

blur 처리된 큰 원이 배경에 깔리면서 자연스러운 색감 변화를 만듭니다. 색상을 바꾸면 포스팅 주제별로 분위기를 다르게 줄 수 있습니다.

주제	오브 색상	느낌
AI / 기술	`#0ea5e9` + `#8b5cf6`	차분한 블루
경고 / 폐지	`#f97316` + `#ef4444`	긴장감 있는 오렌지
YouTube	`#ef4444` + `#8b5cf6`	레드 + 퍼플
Claude Code	`#d4a574` + `#8b5cf6`	브라운 + 퍼플

배지(Badge)

.badge {
  display: inline-block;
  background: rgba(14,165,233,0.15);
  border: 1px solid rgba(14,165,233,0.3);
  color: #38bdf8;
  font-size: 14px;
  font-weight: 600;
  padding: 6px 16px;
  border-radius: 20px;
  letter-spacing: 1px;
  text-transform: uppercase;
}

<div class="badge">SEO Guide</div>

상단에 카테고리 느낌의 라벨을 넣으면 한눈에 주제가 파악됩니다.

그라데이션 텍스트

h1 span {
  background: linear-gradient(90deg, #0ea5e9, #8b5cf6);
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
}

제목의 핵심 단어에만 적용하면 강조 효과가 확실합니다.

3단계: Playwright로 PNG 캡처

HTML 파일을 브라우저에서 열어 확인한 후, Playwright로 캡처합니다.

Playwright MCP 사용 (Claude Code 환경)

Claude Code에서 Playwright MCP를 사용하면 대화 중에 바로 캡처할 수 있습니다.

1. playwright_navigate — HTML 파일 열기 (뷰포트 크기 지정)
2. playwright_screenshot — PNG로 저장

썸네일 (1200x630) 캡처:

navigate: file:///경로/thumbnail.html (width: 1200, height: 630)
screenshot: savePng → thumbnail.png

대표이미지 (1080x1080) 캡처:

navigate: file:///경로/cover.html (width: 1080, height: 1080)
screenshot: savePng → cover.png

Playwright CLI 사용 (수동)

Playwright가 설치되어 있다면 스크립트로도 캡처할 수 있습니다.

// capture.js
const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage({
    viewport: { width: 1200, height: 630 }
  });

  await page.goto('file:///경로/thumbnail.html');
  await page.screenshot({ path: 'thumbnail.png' });

  await browser.close();
})();

node capture.js

캡처 시 주의할 점

문제	원인	해결
이미지가 2:1로 찍힘	뷰포트와 body 크기 불일치	`html`에도 `width`, `height`, `overflow: hidden` 추가
하단에 여백 발생	브라우저가 html에 추가 높이 부여	`html { overflow: hidden }`
한글 깨짐	폰트 미지정	`font-family`에 `'Malgun Gothic'` 추가
그라데이션 텍스트 안 보임	Firefox에서 미지원	Chromium 사용 (Playwright 기본값)

실전 예시 — 이 블로그의 이미지 시스템

이 블로그는 모든 포스팅에 2종류의 이미지를 만듭니다.

유형	비율	크기	용도	파일명
Thumbnail	~2:1	1200x630	OG 이미지, 유튜브 썸네일	`*-thumbnail.png`
Cover	1:1	1080x1080	티스토리 대표이미지, SNS	`*-cover.png`

디자인 일관성 유지 패턴

모든 이미지에 공통으로 적용하는 요소:

배경 — 다크 그라데이션 (#0f172a → #1e293b)
그리드 — 반투명 격자 패턴
글로우 오브 — 주제별 색상 2~3개
배지 — 상단 카테고리 라벨
블로그명 — 우하단 AI JAVAPARK

텍스트와 오브 색상만 바꾸면 일관된 브랜딩을 유지하면서 포스팅별로 구분이 됩니다.

파일 구조

tistory/post/images/
├── post-name-thumbnail.html    ← 썸네일 소스
├── post-name-thumbnail.png     ← 썸네일 이미지
├── post-name-cover.html        ← 대표이미지 소스
└── post-name-cover.png         ← 대표이미지

HTML 소스를 함께 보관하면 나중에 수정이 필요할 때 바로 편집하고 다시 캡처할 수 있습니다.

Claude Code와 함께 쓰면

이 방법의 진짜 장점은 Claude Code와 결합했을 때 나타납니다.

"이 포스팅에 맞는 대표이미지 만들어줘"

이 한 마디면 Claude Code가:

포스팅 내용을 읽고
주제에 맞는 색상과 레이아웃을 결정하고
HTML+CSS를 작성하고
Playwright로 PNG를 캡처합니다

실제로 이 블로그의 포스팅 6개에 대한 썸네일 6개 + 대표이미지 6개, 총 12개의 이미지를 모두 이 방식으로 만들었습니다.

자주 묻는 질문 (FAQ)

Playwright 없이 PNG로 변환할 수 있나요?

브라우저에서 HTML을 열고 개발자 도구의 디바이스 모드에서 해상도를 맞춘 뒤 스크린샷을 찍는 방법도 있습니다. 다만 정확한 크기 제어와 자동화를 위해서는 Playwright가 훨씬 편합니다.

폰트를 웹폰트로 쓸 수 있나요?

네, <link> 태그로 Google Fonts를 불러와서 사용할 수 있습니다. 다만 로컬 파일을 열 때 네트워크 요청이 필요하므로, Playwright 캡처 시 waitUntil: 'networkidle' 옵션을 추가하면 폰트 로딩을 기다립니다.

다크 모드 말고 라이트 모드도 가능한가요?

물론입니다. background를 #ffffff로, 텍스트를 #0f172a로 바꾸면 됩니다. 오브 색상의 opacity를 더 낮추면 라이트 배경에서도 자연스럽습니다.

마무리

정리하면, HTML로 블로그 이미지를 만드는 과정은 이렇습니다.

HTML+CSS로 디자인 — body 크기로 비율 고정, CSS로 시각 요소 구성
브라우저에서 확인 — 파일을 열어 결과 확인
Playwright로 PNG 캡처 — 정확한 크기로 이미지 생성

포토샵 없이, 코드만으로, 일관된 브랜딩의 이미지를 만들 수 있습니다. 한 번 패턴을 잡아두면 새 포스팅마다 텍스트와 색상만 바꾸면 되니, 이미지 제작에 들이는 시간이 크게 줄어듭니다.

여러분은 블로그 이미지를 어떻게 만들고 있나요? 댓글로 알려주세요!

참고 자료

Playwright 공식 문서 — Screenshots — 스크린샷 캡처 옵션 상세 가이드
CSS Gradient Generator — 배경 그라데이션 생성 도구
MDN — background-clip: text — 그라데이션 텍스트 구현 방법
Google Fonts — 무료 웹폰트

Claude Code 입문 가이드 2026 — 설치부터 첫 프로젝트까지 완전 정리

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

"AI 코딩 도구가 너무 많은데, Claude Code는 뭐가 다른 건가요?"

솔직히 말하면 — 직접 써보기 전에는 저도 반신반의했습니다. 터미널에서 AI가 코드를 짠다고? 결국 ChatGPT에 코드 달라고 하는 거랑 뭐가 다르지?

결론부터 말씀드리면 — 완전히 다릅니다. Claude Code는 대화창에서 코드를 복붙하는 게 아니라, 내 프로젝트 폴더 안에서 직접 파일을 읽고, 수정하고, 테스트까지 실행하는 AI 에이전트입니다. 오늘은 설치부터 첫 프로젝트까지 한 번에 정리해보겠습니다.

Claude Code란? — 30초 정의

Claude Code는 Anthropic이 만든 AI 코딩 에이전트입니다. 터미널(또는 IDE)에서 자연어로 지시하면, AI가 프로젝트 전체를 이해하고 직접 코드를 작성·수정·실행합니다.

기존 AI 코딩 도구와의 차이를 정리하면:

	ChatGPT/웹 AI	GitHub Copilot	Claude Code
작동 방식	대화창에서 코드 생성	에디터에서 자동완성	프로젝트 전체를 이해하고 직접 실행
파일 접근	불가 (복붙 필요)	현재 파일 중심	프로젝트 전체 파일 읽기/쓰기
명령 실행	불가	제한적	터미널 명령 직접 실행
컨텍스트	대화 내용만	열린 파일 주변	최대 1M 토큰 (프로젝트 전체)
자율성	낮음	중간	높음 (멀티스텝 작업)

한 줄 요약: "내 컴퓨터에서 일하는 AI 개발자"

설치 방법 — 3분이면 끝

시스템 요구사항

항목	최소 사양
OS	macOS 13+, Windows 10+, Ubuntu 20.04+, Debian 10+
RAM	4GB 이상
필수	Windows: Git for Windows 설치 필요

설치 (권장: 네이티브 설치)

macOS / Linux:

curl -fsSL https://claude.ai/install.sh | bash

Windows (PowerShell):

irm https://claude.ai/install.ps1 | iex

Homebrew (macOS):

brew install claude-code

설치 후 바로 실행:

claude

첫 실행 시 Anthropic 계정 로그인 화면이 나옵니다. 브라우저가 열리면 로그인하고 권한을 승인하면 끝입니다.

IDE 연동 (선택)

CLI 외에 IDE에서도 사용할 수 있습니다.

플랫폼	설치 방법
VS Code	확장 마켓플레이스에서 "Claude Code" 검색 → 설치
JetBrains	플러그인 마켓플레이스에서 "Claude Code" 검색 → 설치
데스크톱 앱	macOS / Windows 전용 앱 (claude.ai에서 다운로드)
웹	claude.ai/code 에서 바로 사용

개인적으로는 터미널(CLI)에서 시작하는 걸 추천합니다. Claude Code의 핵심 경험이 터미널에 있고, IDE 확장은 결국 내부적으로 CLI를 호출하는 구조입니다.

요금제 — 얼마나 드나?

Claude Code는 무료 플랜이 없습니다. 아래 중 하나가 필요합니다.

플랜	월 비용	Claude Code 사용량	추천 대상
Pro	$20	제한적	가볍게 체험
Max 5x	$100	넉넉함	개인 개발자 (추천)
Max 20x	$200	거의 무제한	헤비 유저
Team	$30/인	팀 공유	소규모 팀
Enterprise	별도 문의	커스텀	대규모 조직

실제 비용 감각:

일반적인 개발자 기준 하루 $6~12 정도 사용
/cost 명령으로 현재 세션의 토큰 사용량과 비용을 실시간 확인 가능
Sonnet 모델을 기본으로 쓰면 비용을 크게 줄일 수 있고, 복잡한 작업에만 Opus로 전환하는 전략이 효과적

처음 시작한다면 Pro($20)로 체험 → Max($100)로 전환하는 경로를 추천합니다.

핵심 기능 5가지 — 이것만 알면 시작 가능

1. 자연어로 코딩

> 로그인 API 엔드포인트를 만들어줘. Express.js 기반으로, 
  JWT 토큰 발급까지 포함해서.

Claude Code가 필요한 파일을 만들고, 패키지를 설치하고, 코드를 작성합니다. 사람은 결과를 확인하고 승인하면 됩니다.

2. 프로젝트 전체 이해

> 이 프로젝트의 인증 흐름을 설명해줘

프로젝트 전체 파일을 읽고 구조를 분석합니다. 최대 1M 토큰(약 300만 자)의 컨텍스트 윈도우 덕분에 대규모 프로젝트도 한 번에 이해합니다.

3. Git 통합

> 지금까지 변경사항을 커밋해줘

git add, commit, push, PR 생성까지 자연어로 처리합니다. 커밋 메시지도 변경 내용을 분석해서 자동 생성합니다.

4. CLAUDE.md — AI에게 주는 프로젝트 매뉴얼

프로젝트 루트에 CLAUDE.md 파일을 만들면, Claude Code가 매 세션마다 이 파일을 읽고 프로젝트의 규칙과 컨벤션을 따릅니다.

# CLAUDE.md

## 프로젝트 규칙
- TypeScript strict 모드 사용
- 함수명은 camelCase
- 테스트는 Vitest로 작성
- 커밋 메시지는 한국어로

비유하자면 신입 개발자에게 주는 온보딩 문서입니다. 한 번 작성하면 매번 같은 말을 반복할 필요가 없습니다.

5. MCP 서버 — 외부 도구 연결

MCP(Model Context Protocol)를 통해 Claude Code에 외부 도구를 연결할 수 있습니다.

데이터베이스: Supabase, PostgreSQL 직접 쿼리
브라우저: Playwright로 웹 자동화
API: Slack, GitHub, Jira 등 연동

# 예: Playwright MCP 서버 연결
claude mcp add playwright npx @anthropic-ai/mcp-playwright

연결하면 Claude Code가 브라우저를 직접 조작하거나, DB를 조회하거나, Slack에 메시지를 보낼 수 있습니다.

첫 프로젝트 실습 — React Todo 앱 만들기

실제로 Claude Code를 사용해서 간단한 프로젝트를 만들어보겠습니다.

Step 1: 프로젝트 시작

mkdir my-todo-app
cd my-todo-app
claude

Step 2: 프로젝트 생성 요청

> React + TypeScript로 Todo 앱을 만들어줘. 
  Vite 기반으로 세팅하고, 할 일 추가/완료/삭제 기능을 포함해줘.

Claude Code가 하는 일:

npm create vite 실행
필요한 패키지 설치
컴포넌트 파일 생성
기본 스타일 적용

Step 3: 기능 추가

> 할 일 목록을 localStorage에 저장해서 새로고침해도 유지되게 해줘

Step 4: 확인 및 실행

> dev 서버 실행해줘

이 과정이 5~10분 안에 끝납니다. 물론 프로덕션 품질의 코드는 아니지만, 프로토타이핑이나 학습 목적으로는 압도적으로 빠릅니다.

알아두면 좋은 명령어

명령어	설명
`/help`	도움말
`/cost`	현재 세션 비용 확인
`/compact`	컨텍스트 정리 (긴 세션에서 유용)
`/memory`	프로젝트 메모리 관리
`/review`	코드 리뷰 요청
`Shift+Tab`	모델 전환 (Opus ↔ Sonnet)
`Esc`	현재 작업 중단

실전 팁 5가지

1. CLAUDE.md를 먼저 만들어라

프로젝트 시작 전에 규칙을 정해두면 일관된 코드를 받을 수 있습니다. 없이 시작하면 매번 "TypeScript로 해줘", "테스트도 작성해줘"를 반복하게 됩니다.

2. 작은 단위로 요청하라

"전체 쇼핑몰 만들어줘" 보다 "상품 목록 API 만들어줘" → "장바구니 기능 추가해줘" 식으로 나눠서 요청하는 게 결과물 품질이 높습니다.

3. /compact를 적극 활용하라

긴 세션에서 컨텍스트가 쌓이면 속도가 느려지고 비용이 올라갑니다. 한 작업이 끝나면 /compact로 정리하세요.

4. Sonnet을 기본으로, Opus는 필요할 때만

일상적인 코딩은 Sonnet으로 충분합니다. 복잡한 아키텍처 설계나 대규모 리팩토링에만 Opus를 사용하면 비용을 절반 이하로 줄일 수 있습니다. Shift+Tab으로 전환합니다.

5. Git 커밋을 자주 하라

Claude Code가 코드를 수정하다가 잘못된 방향으로 갈 수 있습니다. 중간중간 커밋해두면 언제든 되돌릴 수 있습니다.

다음 단계

이 글에서 다룬 건 기본 중의 기본입니다. Claude Code를 더 깊이 활용하고 싶다면:

MCP 서버 연결: 데이터베이스, 브라우저, 외부 API를 Claude Code에 연결하는 방법
Hook 활용: 자동 린트, 테스트 실행, 커밋 메시지 검증 자동화
커스텀 스킬: 반복 작업을 슬래시 명령어로 자동화

이 주제들은 후속 포스팅에서 다루겠습니다.

FAQ

Q. Claude Code는 무료로 쓸 수 있나요?

아니요. 최소 Pro 플랜($20/월)이 필요합니다. 무료 체험은 제공되지 않지만, Pro 플랜으로 가볍게 시작한 뒤 필요하면 Max로 업그레이드하는 방식을 추천합니다.

Q. Windows에서도 쓸 수 있나요?

네. Windows 10 이상에서 네이티브로 지원됩니다. 단, Git for Windows가 사전 설치되어 있어야 합니다. PowerShell에서 irm https://claude.ai/install.ps1 | iex 명령으로 설치할 수 있습니다.

Q. 인터넷이 안 되면 사용할 수 없나요?

맞습니다. Claude Code는 Anthropic 서버와 통신해서 작동하므로 인터넷 연결이 필수입니다. 오프라인 모드는 지원하지 않습니다.

여러분은 AI 코딩 도구를 어떻게 활용하고 계신가요? Claude Code를 써보신 경험이 있다면 댓글로 공유해주세요!

비개발자가 Claude Code, Codex CLI 활용하는 법 — 코딩 몰라도 AI 에이전트 쓰는 시대

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

"Claude Code? Codex? 그거 개발자만 쓰는 거 아닌가요?"

솔직히 저도 처음엔 그렇게 생각했습니다. 터미널에 명령어를 치는 도구라니, 당연히 개발자 전용이겠거니 했죠. 그런데 직접 써보니 코딩을 전혀 모르는 사람이야말로 이 도구들의 진짜 수혜자라는 걸 깨달았습니다.

결론부터 말씀드리면 — 비개발자도 충분히 쓸 수 있고, 오히려 반복 업무 자동화에서 엄청난 효과를 볼 수 있습니다. 오늘은 Claude Code와 OpenAI Codex CLI, 이 두 도구를 비개발자 관점에서 설치부터 실전 활용까지 정리해보겠습니다.

먼저, 이 도구들이 뭔가요?

쉽게 비유하자면 이렇습니다.

	ChatGPT / Claude 웹	Claude Code / Codex CLI
비유	카카오톡으로 비서에게 부탁	비서가 직접 내 컴퓨터 앞에 앉아서 작업
할 수 있는 것	텍스트 답변, 조언	파일 읽기/수정, 폴더 정리, 코드 실행, 자동화
작업 범위	대화창 안에서만	내 컴퓨터의 실제 파일과 폴더

Claude Code는 Anthropic이 만든 AI 에이전트 도구이고, Codex CLI는 OpenAI가 만든 도구입니다. 둘 다 터미널(명령 프롬프트)에서 자연어로 지시하면 내 컴퓨터의 파일을 직접 읽고, 수정하고, 생성해줍니다.

핵심은 이겁니다 — 코딩을 해달라고 시키는 게 아니라, 일을 해달라고 시키는 겁니다.

비개발자가 할 수 있는 일 10가지

코딩과 전혀 관련 없는 실전 활용 사례입니다.

업무 자동화

경비 보고서 정리 — 여러 신용카드 명세서(CSV)를 하나로 합치고 카테고리별로 분류
이메일/뉴스레터 초안 — 프로젝트 폴더의 변경사항을 읽고 주간 보고 메일 초안 작성
파일 정리 — 수백 개 파일을 날짜별, 유형별로 자동 분류하고 이름 변경

콘텐츠 & 마케팅

블로그 포스팅 초안 — 주제를 주면 리서치 + 마크다운 초안까지 한 번에
SNS 콘텐츠 배치 생성 — 하나의 긴 글에서 트위터/인스타/링크드인용 요약본 자동 생성
SEO 분석 — 경쟁사 페이지를 분석하고 키워드 리포트 생성

데이터 분석

스프레드시트 가공 — CSV/엑셀 파일에서 특정 조건의 데이터만 추출, 피벗
미사용 구독 감지 — 은행 거래 내역에서 반복 결제를 찾아 리스트업
설문 결과 분석 — 설문 응답 데이터를 요약하고 인사이트 도출

일상

여행 계획 — 날짜, 예산, 취향을 알려주면 일정표 마크다운 파일로 생성

Claude Code 설치 가이드 (비개발자용)

사전 준비

Claude Code를 쓰려면 두 가지가 필요합니다:

Anthropic 유료 구독 — 최소 Pro 플랜($20/월)
Node.js — Claude Code 설치에 필요한 기본 도구

1단계: Node.js 설치

nodejs.org 접속 → LTS 버전 다운로드 → 설치 (모든 옵션 기본값 OK)

설치 확인:

node --version
# v22.x.x 같은 버전이 나오면 성공

2단계: Claude Code 설치

npm install -g @anthropic-ai/claude-code

💡 Windows 사용자: PowerShell 또는 Git Bash에서 실행하세요.

3단계: 실행 및 인증

# 작업할 폴더로 이동
cd ~/Documents/내작업폴더

# Claude Code 실행
claude

처음 실행하면 브라우저가 열리면서 Anthropic 계정 인증을 요청합니다. 로그인하면 바로 사용 가능합니다.

4단계: 첫 번째 대화

> 이 폴더에 있는 파일 목록을 정리해서 summary.md로 만들어줘

이게 끝입니다. 코드를 작성한 게 아니라 한국어로 부탁한 것뿐입니다.

Codex CLI 설치 가이드 (비개발자용)

사전 준비

ChatGPT Plus 이상 구독 — Plus($20/월) 또는 Pro($200/월)
Node.js 18 이상 (위와 동일)

1단계: 설치

npm install -g @openai/codex

2단계: 인증

codex

실행하면 "Sign in with ChatGPT" 옵션이 나옵니다. 브라우저에서 로그인하면 완료.

3단계: 첫 번째 대화

> 이 폴더의 CSV 파일들을 읽고 날짜별로 정렬해서 하나로 합쳐줘

⚠️ Windows 사용자 주의: Codex CLI의 Windows 지원은 아직 실험적입니다. WSL2(Windows Subsystem for Linux) 환경을 권장합니다.

Claude Code vs Codex CLI — 비개발자 관점 비교

항목	Claude Code	Codex CLI
시작 난이도	⭐⭐ 쉬움	⭐⭐ 쉬움 (Windows는 ⭐⭐⭐)
한국어 지원	매우 자연스러움	자연스러움
안전성	변경 전 확인 요청 (감독형)	full-auto 모드 있음 (비감독형 가능)
Windows 지원	네이티브 지원	실험적 (WSL 권장)
최소 비용	$20/월 (Pro)	$20/월 (Plus)
사용량 제한	5시간 제한 (Pro)	모델별 상이
데스크톱 앱	있음 (Mac/Windows)	없음
웹 버전	있음 (claude.ai/code)	없음
VS Code 연동	있음	있음

비개발자에게 추천하는 선택은?

Claude Code를 먼저 추천합니다. 이유는:

감독형 방식 — 파일을 수정하기 전에 항상 확인을 요청합니다. 실수로 중요한 파일을 날릴 걱정이 적습니다.
Windows 네이티브 지원 — WSL 설치 없이 바로 사용 가능합니다.
데스크톱 앱/웹 버전 — 터미널이 어색하면 데스크톱 앱이나 웹에서 시작할 수 있습니다.
VS Code 확장 — VS Code에서 직접 사용하면 터미널을 따로 열 필요도 없습니다.

Codex CLI는 이미 ChatGPT Plus를 구독 중이거나, 터미널 작업에 어느 정도 익숙한 분에게 적합합니다.

비개발자를 위한 실전 팁 5가지

1. CLAUDE.md (또는 AGENTS.md) 파일을 활용하세요

프로젝트 폴더에 CLAUDE.md 파일을 만들어두면, Claude Code가 매번 대화를 시작할 때 이 파일을 읽습니다. 일종의 업무 매뉴얼입니다.

# 이 폴더에 대한 설명

- 이 폴더에는 매월 경비 보고 CSV 파일이 저장됩니다
- 파일 형식: YYYY-MM-expenses.csv
- 카테고리: 교통, 식비, 숙박, 기타
- 월말에 summary.xlsx로 합산 보고서를 만들어야 합니다

이렇게 해두면 매번 같은 설명을 반복하지 않아도 됩니다.

2. 작업 전 백업 습관을 들이세요

AI가 파일을 직접 수정할 수 있으므로, 중요한 파일은 작업 전에 복사본을 만들어두세요.

> 작업 시작하기 전에 이 폴더를 backup 폴더로 복사해줘

이것도 자연어로 시키면 됩니다.

3. 프롬프트는 구체적일수록 좋습니다

❌ "이 파일 정리해줘"
✅ "expenses.csv에서 2024년 3월 데이터만 추출해서 march-report.csv로 저장해줘. 금액 기준 내림차순으로 정렬하고."

4. 모르겠으면 물어보세요

> 이 폴더에 어떤 파일들이 있는지 먼저 알려줘
> 이 CSV 파일의 구조(컬럼)를 설명해줘
> 이걸 엑셀로 변환할 수 있어?

Claude Code와 Codex 모두 대화형이므로, 바로 작업을 시키지 않고 먼저 상황 파악을 요청해도 됩니다.

5. 비용 관리에 신경 쓰세요

사용 패턴	권장 플랜	월 비용
가끔 (주 1~2회)	Pro / Plus	~$20
매일 가볍게	Pro / Plus	~$20
매일 집중적으로	Max	~$100
헤비 유저	Max / Pro (Codex)	$100~200

특히 Claude Code Pro 플랜은 5시간 사용 제한이 있으므로, 가벼운 작업 위주라면 충분하지만 하루 종일 붙잡고 있으면 금방 한도에 도달합니다.

비개발자가 자주 하는 질문 (FAQ)

Q. 터미널(명령 프롬프트)을 한 번도 써본 적이 없는데 괜찮을까요?

괜찮습니다. 필요한 명령어는 딱 세 개입니다:

cd 폴더경로 — 폴더 이동
claude 또는 codex — 도구 실행
exit — 종료

나머지는 전부 자연어로 대화하면 됩니다. VS Code 확장이나 데스크톱 앱을 쓰면 터미널 자체를 건드릴 일이 더 줄어듭니다.

Q. AI가 중요한 파일을 잘못 수정하면 어떡하죠?

Claude Code는 기본적으로 파일을 수정하기 전에 확인을 요청합니다. "이 파일을 이렇게 바꿔도 될까요?"라고 물어보고, 사용자가 승인해야 실행됩니다. Codex CLI도 기본 모드에서는 동일합니다. 다만 Codex의 full-auto 모드는 확인 없이 바로 실행하므로, 비개발자는 기본 모드를 유지하는 것을 권장합니다.

Q. ChatGPT나 Claude 웹에서 하던 작업과 뭐가 다른가요?

가장 큰 차이는 내 컴퓨터의 파일에 직접 접근할 수 있다는 점입니다. 채팅 인터페이스에서는 "이런 코드를 만들어줘"라고 하면 텍스트로 결과를 보여주기만 합니다. Claude Code나 Codex는 실제로 파일을 만들고, 기존 파일을 수정하고, 프로그램을 실행까지 해줍니다.

마무리

"코딩을 모르면 AI 에이전트 도구를 못 쓴다"는 건 이제 옛말입니다. Claude Code와 Codex CLI는 자연어로 지시하면 내 컴퓨터에서 직접 작업을 수행하는 도구이고, 그 지시에 코드가 필요하지 않습니다.

시작이 어렵게 느껴지시면, 딱 하나만 해보세요:

npm install -g @anthropic-ai/claude-code
claude
> 이 폴더에 있는 파일들을 정리해서 목록 만들어줘

이 한 줄이 시작입니다. 한 번 경험하고 나면 "이것도 시킬 수 있지 않을까?" 하는 생각이 자연스럽게 따라올 겁니다.

여러분은 AI 에이전트 도구를 어떤 업무에 활용하고 계신가요? 댓글로 공유해주세요!

관련 포스팅:

AI 코딩 도구 Skill 비교 — Claude Code vs Gemini CLI vs Codex CLI

참고 문서:

Claude Code Skill 사용법 — 슬래시 명령어로 반복 업무 자동화

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

Claude Code를 쓰다 보면 매번 같은 지시를 반복하는 순간이 옵니다.

"블로그 포스팅 써줘. 톤은 친근하게, 마크다운으로, 코드 예시 포함해서, 도입-본문-정리 구조로..."

이 긴 설명을, 이렇게 한 줄로 바꿀 수 있다면 어떨까요?

/blog-post Claude Code Skill 소개

이게 바로 Skill입니다. 실제로 이 글도 제가 만든 블로그 포스팅 스킬로 작성했습니다.

Claude Code Skill이란?

반복되는 작업 지시를 파일로 저장해두고, 슬래시 명령어로 호출하는 기능입니다.

비유하자면, 신입에게 매번 말로 설명하던 업무 절차를 매뉴얼 문서로 만들어둔 것과 같습니다. Claude가 그 매뉴얼을 읽고, 그대로 실행합니다.

Skill vs Hook vs CLAUDE.md 차이점 비교

처음 접하면 헷갈리는 세 가지를 정리합니다.

구분	역할	비유
CLAUDE.md	프로젝트 전체에 적용되는 규칙	사무실 벽에 붙은 공지사항
Skill	특정 작업을 위한 명령어	업무 매뉴얼
Hook	이벤트 발생 시 자동 실행	자동화 봇

핵심 차이를 한 줄로 요약하면:

CLAUDE.md — 항상 적용됩니다
Skill — 내가 호출하거나, Claude가 판단해서 호출합니다
Hook — 특정 이벤트에 자동으로 실행됩니다

SKILL.md 만드는 법 — 3단계

1단계: 폴더와 파일 만들기

~/.claude/skills/blog-post/
└── SKILL.md

이게 끝입니다. SKILL.md 파일 하나만 있으면 됩니다.

저장 위치에 따라 적용 범위가 달라집니다.

위치	적용 범위	용도
`~/.claude/skills/<name>/SKILL.md`	내 모든 프로젝트	개인 스킬
`.claude/skills/<name>/SKILL.md`	해당 프로젝트만	팀 공유 (Git 커밋)

2단계: SKILL.md 작성하기

파일 구조는 YAML 프론트매터 + 마크다운 본문 두 부분으로 되어 있습니다.

---
name: blog-post
description: 블로그 포스팅 초안을 작성합니다
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, WebSearch
---

# 블로그 포스팅 작성 스킬

## 기본 정보
- 블로그명: AI JAVAPARK
- 필명: 자바파커

## 작성 규칙
- 실전 경험 기반의 친근한 문체
- 어려운 개념은 비유나 실제 사례로 설명
- 도입 → 본문 → 정리 구조

## 포맷
- 마크다운 형식
- 코드 블록에는 언어 표기

---로 감싼 윗부분이 프론트매터(설정), 아랫부분이 본문(Claude에게 주는 지시)입니다.

3단계: 호출하기

/blog-post Claude Code Skill 소개

"Claude Code Skill 소개"가 $ARGUMENTS로 전달되어, 스킬에 정의된 규칙대로 포스팅이 만들어집니다.

SKILL.md 프론트매터 옵션 정리

옵션	설명	예시
`name`	슬래시 명령어 이름	`blog-post`
`description`	스킬 설명	`블로그 포스팅 초안을 작성합니다`
`disable-model-invocation`	`true`면 수동 호출만 가능	부작용 있는 작업에 권장
`allowed-tools`	사용할 도구 제한	`Read, Grep, Glob`
`context`	`fork` 시 서브에이전트로 분리 실행	메인 대화 오염 방지
`agent`	`context: fork` 시 에이전트 타입	`Explore`, `Plan`

실전 예시 — 블로그 포스팅 자동화 Skill

실제로 사용 중인 스킬 전체를 공개합니다.

---
name: blog-post
description: 블로그 포스팅 초안을 작성합니다. 주제를 전달하면 구조화된 마크다운 포스팅을 생성합니다.
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, WebSearch, WebFetch, Agent
---

# 블로그 포스팅 작성 스킬

## 기본 정보
- 블로그명: AI JAVAPARK
- 필명: 자바파커
- 플랫폼: 티스토리
- 주요 독자: 개발자, AI/IT에 관심 있는 사람들

## 작성 규칙

### 톤 & 스타일
- 실전 경험 기반의 친근한 문체 ("~합니다" 체)
- 어려운 개념은 비유나 실제 사례로 설명
- 독자가 바로 따라할 수 있는 실용적 내용 중심
- 불필요한 서론 최소화, 핵심부터 진입

### 구조
1. **도입** — 왜 이 주제를 다루는지 (2~3문장)
2. **본문** — 개념 설명 + 실전 예시 + 코드/설정 예시
3. **정리** — 핵심 요약 또는 다음 단계 제안

### 포맷
- 마크다운 형식
- 코드 블록에는 언어 표기
- 적절한 소제목으로 스캔 가능하게 구성
- 긴 설명보다 표, 목록, 코드 예시 활용

## 작업 흐름
1. 주제($ARGUMENTS)를 받으면 먼저 포스팅 아웃라인을 잡는다
2. 필요하면 WebSearch로 최신 정보를 확인한다
3. 프로젝트 내 관련 코드/설정이 있으면 참조한다
4. 마크다운 초안을 작성한다
5. 초안을 프로젝트 루트에 posts/ 디렉토리 아래 저장한다

이 스킬 덕분에 /blog-post 주제 한 줄이면 블로그 톤, 구조, 포맷을 매번 설명하지 않아도 됩니다.

Claude Code Skill 활용 예시 — 코드 리뷰, 이슈 처리

코드 리뷰 스킬

PR을 서브에이전트로 분석합니다. !command`` 문법으로 쉘 명령어 결과를 동적으로 주입하는 게 포인트입니다.

---
name: review
description: PR 코드 리뷰를 수행합니다
context: fork
agent: Explore
allowed-tools: Bash(gh *), Read, Grep, Glob
---

## PR 컨텍스트
- PR diff: !`gh pr diff`
- 변경 파일: !`gh pr diff --name-only`

## 리뷰 기준
1. 버그 가능성이 있는 코드
2. 성능 이슈
3. 보안 취약점
4. 컨벤션 위반

GitHub 이슈 처리 스킬

이슈 번호만 넘기면 분석부터 커밋까지 처리합니다.

---
name: fix-issue
description: GitHub 이슈를 분석하고 수정합니다
disable-model-invocation: true
---

GitHub 이슈 #$ARGUMENTS 를 처리합니다:

1. 이슈 내용을 읽고 요구사항 파악
2. 관련 코드 탐색
3. 수정 구현
4. 테스트 작성
5. 커밋 생성

Claude Code Skill 작성 팁 5가지

disable-model-invocation: true를 습관적으로 쓰세요. 배포, 커밋, 메시지 전송 등 부작용이 있는 스킬에 설정하지 않으면, Claude가 대화 중 알아서 호출할 수 있습니다.

description을 잘 쓰세요. Claude가 자동 호출 여부를 판단할 때 이 설명을 봅니다. 모호하면 엉뚱한 타이밍에 호출됩니다.

SKILL.md는 500줄 이내로. 길어지면 별도 파일로 분리하고 SKILL.md에서 참조하세요. 스킬 디렉토리 안에 examples/, templates/ 같은 하위 폴더를 두면 됩니다.

$ARGUMENTS로 입력값을 받으세요. /skill-name 인자값 형태로 호출하면 $ARGUMENTS에 전달됩니다. $0, $1로 개별 인자도 접근 가능합니다.

context: fork로 대화를 깔끔하게. 리서치나 분석처럼 긴 작업은 서브에이전트로 분리하면 메인 대화가 오염되지 않습니다.

자주 묻는 질문 (FAQ)

Skill과 프롬프트 템플릿은 뭐가 다른가요?

프롬프트 템플릿은 텍스트를 복사-붙여넣기 하는 방식입니다. Skill은 Claude Code가 직접 파일을 읽고 실행하기 때문에, 도구 사용 제한(allowed-tools), 자동 호출 제어(disable-model-invocation), 서브에이전트 분리(context: fork) 같은 세밀한 제어가 가능합니다.

Skill을 팀원과 공유할 수 있나요?

프로젝트 루트의 .claude/skills/ 에 저장하면 Git으로 커밋할 수 있습니다. 팀원이 같은 저장소를 클론하면 동일한 슬래시 명령어를 사용할 수 있습니다.

Skill이 너무 길어지면 어떻게 하나요?

SKILL.md는 500줄 이내로 유지하는 것이 좋습니다. 길어지면 스킬 디렉토리 안에 examples/, templates/ 같은 하위 폴더를 만들고, SKILL.md에서 해당 파일을 참조하도록 작성하세요.

마무리

Skill은 결국 **"Claude에게 주는 업무 매뉴얼을 파일로 저장한 것"**입니다.

SKILL.md 파일 하나 만들고
프론트매터에 이름과 설명 적고
본문에 작업 지시를 마크다운으로 작성하면

그때부터 /name으로 호출할 수 있습니다.

반복하는 작업이 있다면, 오늘 바로 하나 만들어보세요. 한번 만들어두면 다시는 같은 설명을 반복하지 않아도 됩니다.

여러분은 어떤 반복 업무를 스킬로 만들고 싶으신가요? 댓글로 알려주세요!

참고 자료

Gatsby 블로그 스킨 커스터마이징 — 나만의 디자인 만들기

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

지난 포스팅에서 Gatsby 블로그를 설치하고 배포까지 마쳤습니다. 하지만 기본 테마 그대로 사용하기에는 아쉬운 부분이 있습니다. 이번 포스팅에서는 gatsby-starter-hoodie 테마를 기준으로 블로그 디자인을 나만의 스타일로 커스터마이징하는 방법을 알아보겠습니다.

Gatsby 테마 구조 이해

커스터마이징을 시작하기 전에 테마의 폴더 구조를 이해하는 것이 중요합니다.

src/
├── assets/
│   └── theme/
│       └── index.js        # 테마 색상, 크기 등 핵심 설정
├── components/
│   ├── Article/            # 본문 영역 컴포넌트
│   ├── Bio/                # 프로필 영역
│   ├── Header/             # 상단 헤더
│   ├── Layout/             # 전체 레이아웃
│   ├── Sidebar/            # 사이드바
│   └── ...
├── pages/
│   └── index.js            # 메인 페이지
└── templates/
    └── Post.js             # 개별 포스트 템플릿

핵심 파일은 src/assets/theme/index.js입니다. 이 파일에서 색상, 크기, 폰트 등 대부분의 디자인 변수를 관리합니다.

콘텐츠 폭 조정

기본 테마의 콘텐츠 폭이 좁게 느껴진다면 조정할 수 있습니다.

Layout/Body 컴포넌트 수정

src/components/Layout/Body/index.js 파일을 찾아 max-width 값을 변경합니다.

// src/components/Layout/Body/index.js
import styled from "styled-components"

const Body = styled.div`
  margin: 0 auto;
  padding-top: 80px;
  max-width: 680px;  /* 기본값 */

  @media (max-width: 768px) {
    padding: 80px 16px 0;
  }
`

이 값을 필요에 따라 조정합니다.

const Body = styled.div`
  margin: 0 auto;
  padding-top: 80px;
  max-width: 760px;  /* 더 넓은 콘텐츠 영역 */

  @media (max-width: 768px) {
    padding: 80px 20px 0;
  }
`

팁: 너무 넓으면 한 줄에 글자 수가 많아져 가독성이 떨어집니다. 일반적으로 680px~800px 사이가 적당합니다.

테마 변수로 관리하기

반복 사용되는 값은 테마 변수로 관리하면 유지보수가 편리합니다.

// src/assets/theme/index.js 에 추가
const size = {
  maxWidth: "760px",
  mobileBreakpoint: "768px",
  tabletBreakpoint: "1024px",
}

export { size }

타이포그래피 변경

블로그의 분위기를 결정짓는 가장 큰 요소는 폰트입니다.

웹 폰트 추가

Google Fonts나 눈누(Noonnu)에서 원하는 폰트를 선택합니다. gatsby-browser.js에서 웹 폰트를 로드하는 방법이 가장 간단합니다.

// gatsby-browser.js
import "./src/assets/fonts/fonts.css"

/* src/assets/fonts/fonts.css */
@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+KR:wght@400;500;700&display=swap');
@import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500&display=swap');

폰트 적용

전역 스타일 또는 테마 파일에서 폰트를 적용합니다.

// src/assets/theme/index.js
const fonts = {
  body: "'Noto Sans KR', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
  code: "'JetBrains Mono', 'Fira Code', Consolas, monospace",
}

export { fonts }

styled-components에서 사용할 때는 다음과 같이 적용합니다.

import { fonts } from "../../assets/theme"

const Content = styled.div`
  font-family: ${fonts.body};
  font-size: 16px;
  line-height: 1.8;
  letter-spacing: -0.01em;
  word-break: keep-all;
`

글꼴 크기와 행간 조정

가독성을 높이려면 line-height(행간)와 letter-spacing(자간) 조정이 중요합니다.

/* 추천 설정 */
body {
  font-size: 16px;        /* 본문 기본 크기 */
  line-height: 1.8;       /* 행간: 1.6~1.8 추천 */
  letter-spacing: -0.01em; /* 한글은 약간 좁히면 자연스럽습니다 */
  word-break: keep-all;   /* 한글 단어 단위 줄바꿈 */
}

h1 { font-size: 2rem; font-weight: 700; }
h2 { font-size: 1.5rem; font-weight: 700; }
h3 { font-size: 1.25rem; font-weight: 500; }

다크/라이트 테마 색상 커스터마이징

gatsby-starter-hoodie는 다크모드를 기본 지원합니다. 색상 설정은 테마 파일에서 관리합니다.

theme/index.js 수정

// src/assets/theme/index.js

const light = {
  // 배경 색상
  bodyBackground: "#ffffff",
  cardBackground: "#f8f9fa",

  // 텍스트 색상
  text: "#1a1a2e",
  textSecondary: "#6c757d",
  textTertiary: "#adb5bd",

  // 강조 색상
  primary: "#0066cc",
  primaryLight: "#e7f1ff",

  // 경계선
  border: "#e9ecef",
  borderLight: "#f1f3f5",

  // 인라인 코드
  inlineCodeBackground: "#f1f3f5",
  inlineCodeText: "#e74c3c",

  // 헤더
  headerBackground: "rgba(255, 255, 255, 0.85)",
}

const dark = {
  // 배경 색상
  bodyBackground: "#1a1a2e",
  cardBackground: "#16213e",

  // 텍스트 색상
  text: "#e0e0e0",
  textSecondary: "#a0a0a0",
  textTertiary: "#707070",

  // 강조 색상
  primary: "#4dabf7",
  primaryLight: "#1a2744",

  // 경계선
  border: "#2c3e50",
  borderLight: "#233554",

  // 인라인 코드
  inlineCodeBackground: "#2d2d2d",
  inlineCodeText: "#ff6b6b",

  // 헤더
  headerBackground: "rgba(26, 26, 46, 0.85)",
}

export { light, dark }

색상 팔레트 선택 팁

배경색: 순백(#fff)보다 살짝 톤을 줄인 #fafafa나 #f8f9fa가 눈에 편합니다.
다크모드 배경: 순검정(#000)보다 짙은 남색(#1a1a2e)이나 짙은 회색(#1e1e1e)이 부드럽습니다.
강조색(primary): 블로그의 정체성을 나타내는 색상을 하나 정해서 일관되게 사용합니다.
대비: 텍스트와 배경의 명암비가 최소 4.5:1 이상이 되어야 가독성이 보장됩니다. WebAIM Contrast Checker에서 확인할 수 있습니다.

코드 블록 스타일링

기술 블로그에서 코드 블록은 매우 중요한 요소입니다. Gatsby는 기본적으로 Prism.js를 사용합니다.

Prism.js 테마 변경

gatsby-starter-hoodie에서 사용하는 Prism 테마를 변경하려면 gatsby-browser.js에서 import를 수정합니다.

// gatsby-browser.js

// 기본 테마 대신 원하는 테마를 import합니다
// import "prismjs/themes/prism.css"           // 라이트
// import "prismjs/themes/prism-tomorrow.css"  // 다크
// import "prismjs/themes/prism-okaidia.css"   // Monokai 스타일
import "prismjs/themes/prism-vsc-dark-plus.css" // VS Code 스타일

커스텀 코드 블록 스타일

Prism 테마를 직접 오버라이드하면 더 세밀하게 조정할 수 있습니다.

/* src/assets/styles/code.css */

/* 코드 블록 컨테이너 */
.gatsby-highlight {
  margin: 1.5em 0;
  border-radius: 8px;
  overflow: hidden;
}

/* 코드 블록 본문 */
.gatsby-highlight pre[class*="language-"] {
  background: #1e1e2e;
  padding: 1.2em;
  border-radius: 8px;
  font-size: 14px;
  line-height: 1.6;
  overflow-x: auto;
  -webkit-overflow-scrolling: touch;
}

/* 인라인 코드 */
:not(pre) > code[class*="language-"] {
  background: var(--inline-code-bg, #f1f3f5);
  color: var(--inline-code-text, #e74c3c);
  padding: 0.15em 0.4em;
  border-radius: 4px;
  font-size: 0.9em;
}

/* 코드 블록 언어 표시 */
.gatsby-highlight pre[class*="language-"]::before {
  content: attr(class);
  position: absolute;
  top: 0;
  right: 0;
  padding: 2px 8px;
  font-size: 11px;
  color: #999;
  text-transform: uppercase;
}

코드 복사 버튼 추가

코드 블록에 복사 버튼을 추가하면 사용자 경험이 크게 향상됩니다. gatsby-remark-code-buttons 플러그인을 사용합니다.

npm install gatsby-remark-code-buttons

gatsby-config.js에 플러그인을 추가합니다.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: "gatsby-transformer-remark",
      options: {
        plugins: [
          {
            resolve: "gatsby-remark-code-buttons",
            options: {
              buttonText: "복사",
              toasterText: "복사되었습니다!",
              toasterDuration: 2000,
            },
          },
          // ... 기존 플러그인들
        ],
      },
    },
  ],
}

복사 버튼의 스타일도 추가합니다.

/* 코드 복사 버튼 스타일 */
.gatsby-code-button-container {
  position: relative;
}

.gatsby-code-button {
  position: absolute;
  top: 8px;
  right: 8px;
  background: rgba(255, 255, 255, 0.1);
  border: 1px solid rgba(255, 255, 255, 0.2);
  border-radius: 4px;
  padding: 4px 10px;
  color: #ccc;
  font-size: 12px;
  cursor: pointer;
  transition: all 0.2s ease;
  z-index: 1;
}

.gatsby-code-button:hover {
  background: rgba(255, 255, 255, 0.2);
  color: #fff;
}

헤더/푸터 커스터마이징

헤더 수정

헤더는 블로그의 첫인상을 결정합니다. src/components/Header/index.js를 수정합니다.

// src/components/Header/index.js
import React from "react"
import styled from "styled-components"

const HeaderWrapper = styled.header`
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  height: 56px;
  background: ${props => props.theme.headerBackground};
  backdrop-filter: blur(12px);
  -webkit-backdrop-filter: blur(12px);
  border-bottom: 1px solid ${props => props.theme.border};
  z-index: 100;
  display: flex;
  align-items: center;
  justify-content: space-between;
  padding: 0 24px;
  transition: background 0.3s ease;
`

const Logo = styled.a`
  font-size: 1.2rem;
  font-weight: 700;
  color: ${props => props.theme.text};
  text-decoration: none;

  &:hover {
    color: ${props => props.theme.primary};
  }
`

팁: backdrop-filter: blur()를 사용하면 스크롤할 때 배경이 흐려지는 글래스모피즘 효과를 줄 수 있습니다.

푸터 추가

gatsby-starter-hoodie에는 기본 푸터가 간단하게 되어 있습니다. 커스텀 푸터를 추가해 봅시다.

// src/components/Footer/index.js
import React from "react"
import styled from "styled-components"

const FooterWrapper = styled.footer`
  margin-top: 80px;
  padding: 40px 0;
  border-top: 1px solid ${props => props.theme.border};
  text-align: center;
  font-size: 0.85rem;
  color: ${props => props.theme.textSecondary};
`

const Footer = () => (
  <FooterWrapper>
    <p>
      &copy; {new Date().getFullYear()} AI JAVAPARK. Built with{" "}
      <a href="https://www.gatsbyjs.com/" target="_blank" rel="noreferrer">
        Gatsby
      </a>
    </p>
  </FooterWrapper>
)

export default Footer

반응형 브레이크포인트 조정

다양한 디바이스에서 최적의 경험을 제공하기 위해 반응형 디자인을 조정합니다.

미디어 쿼리 정리

일관된 미디어 쿼리를 사용하기 위해 브레이크포인트를 정의합니다.

// src/assets/theme/breakpoints.js
const breakpoints = {
  mobile: "576px",
  tablet: "768px",
  desktop: "1024px",
  wide: "1200px",
}

const media = {
  mobile: `@media (max-width: ${breakpoints.mobile})`,
  tablet: `@media (max-width: ${breakpoints.tablet})`,
  desktop: `@media (max-width: ${breakpoints.desktop})`,
  wide: `@media (min-width: ${breakpoints.wide})`,
}

export { breakpoints, media }

styled-components에서 활용

import { media } from "../../assets/theme/breakpoints"

const Container = styled.div`
  max-width: 760px;
  margin: 0 auto;
  padding: 0 24px;

  ${media.tablet} {
    padding: 0 20px;
  }

  ${media.mobile} {
    padding: 0 16px;
  }
`

모바일 최적화 체크리스트

반응형 커스터마이징 시 다음 항목들을 꼭 확인합니다.

모바일에서 텍스트가 잘리지 않는지 확인
코드 블록이 가로 스크롤로 처리되는지 확인
이미지가 컨테이너 폭을 넘지 않는지 확인
터치 타겟(버튼, 링크)이 최소 44px 이상인지 확인
헤더가 모바일에서 적절히 축소되는지 확인

크롬 개발자 도구(F12)의 디바이스 툴바를 활용하면 다양한 화면 크기를 쉽게 테스트할 수 있습니다.

변경사항 적용 및 배포

모든 커스터마이징을 마쳤다면 개발 서버에서 결과를 확인하고 배포합니다.

# 개발 서버에서 확인
gatsby develop

# 문제가 없다면 배포
npm run deploy

주의: gatsby develop에서는 보이지 않는 문제가 gatsby build에서 발생할 수 있습니다. 배포 전에 반드시 gatsby build로 프로덕션 빌드를 테스트하세요.

자주 묻는 질문 (FAQ)

Q1. styled-components를 몰라도 커스터마이징할 수 있나요?

네, 기본 CSS 문법만 알면 됩니다. styled-components는 JavaScript 파일 안에 CSS를 작성하는 방식일 뿐, 문법 자체는 CSS와 동일합니다. 백틱(`) 안에 일반 CSS를 그대로 작성하면 됩니다. 다만 ${} 구문으로 JavaScript 변수를 활용할 수 있다는 점이 일반 CSS와 다릅니다.

Q2. 테마 수정 후 기존 글 스타일이 깨지는 경우 어떻게 하나요?

gatsby clean 명령어로 캐시를 초기화한 뒤 다시 빌드해 보세요. 대부분의 스타일 관련 이슈는 캐시 문제입니다.

gatsby clean && gatsby develop

그래도 문제가 지속된다면 브라우저 개발자 도구에서 해당 요소를 검사하여 어떤 스타일이 적용되고 있는지 확인합니다.

Q3. 다크모드 전환이 깜빡이는 현상이 있습니다.

SSR(서버 사이드 렌더링) 시점과 클라이언트 사이드 렌더링 시점의 테마가 다르면 깜빡임이 발생합니다. gatsby-ssr.js에서 초기 테마를 설정하는 스크립트를 <body> 태그 앞에 삽입하면 해결됩니다.

// gatsby-ssr.js
export const onRenderBody = ({ setPreBodyComponents }) => {
  setPreBodyComponents([
    <script
      key="theme-script"
      dangerouslySetInnerHTML={{
        __html: `
          (function() {
            try {
              var mode = localStorage.getItem('theme');
              if (mode) {
                document.body.className = mode;
              }
            } catch (e) {}
          })();
        `,
      }}
    />,
  ])
}

다음 포스팅에서는 마크다운 글쓰기와 카테고리 관리 방법을 다룹니다. frontmatter 작성법, 태그 전략, 시리즈 기능, 폴더 구조 설계까지 체계적인 블로그 운영법을 알아보겠습니다.

GitHub Actions로 블로그 자동 배포하기 — push만 하면 끝

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

"글 수정할 때마다 npm run build 하고 gh-pages 브랜치에 push하고... 이걸 매번 해야 하나요?"

솔직히 말하면, 수동 배포를 계속하다 보면 글 쓰는 것보다 배포가 더 귀찮아지는 순간이 옵니다. 결론부터 말씀드리면 — GitHub Actions를 설정하면 git push 한 번으로 빌드부터 배포까지 전부 자동화할 수 있습니다.

이번 포스팅에서는 Gatsby 블로그를 GitHub Actions로 자동 배포하는 CI/CD 파이프라인을 처음부터 끝까지 구축해보겠습니다.

수동 배포의 문제점

수동으로 GitHub Pages에 배포하려면 보통 이런 과정을 거칩니다.

# 1. 빌드
npm run build

# 2. gh-pages 브랜치에 배포
npx gh-pages -d public

# 3. 또는 직접 public 폴더를 gh-pages 브랜치에 push

이 방식의 문제점은 명확합니다.

글을 수정할 때마다 수동으로 빌드해야 합니다
빌드 명령어를 잊거나 실수하면 배포가 안 됩니다
로컬 환경에 따라 빌드 결과가 달라질 수 있습니다
시간이 오래 걸립니다 (특히 Gatsby 빌드는 느린 편)

자동화의 핵심은 단순합니다. 코드를 push하면 나머지는 서버가 알아서 하도록 만드는 것입니다.

GitHub Actions 기본 개념

GitHub Actions는 GitHub에서 제공하는 CI/CD(지속적 통합/지속적 배포) 서비스입니다. 레포지토리에 특정 이벤트(push, PR 등)가 발생하면 정의된 작업을 자동으로 실행합니다.

핵심 용어 정리

용어	설명	비유
Workflow	자동화 작업의 전체 흐름	레시피 전체
Event	워크플로우를 실행하는 트리거	"주문이 들어오면"
Job	워크플로우 안의 작업 단위	레시피의 각 단계 (재료 준비, 조리, 플레이팅)
Step	Job 안의 개별 명령어	"양파를 잘게 썬다"
Runner	워크플로우가 실행되는 서버	주방
Action	재사용 가능한 Step 묶음	밀키트 (미리 만들어진 것)

워크플로우 파일은 .github/workflows/ 디렉토리에 YAML 형식으로 작성합니다.

블로그 배포용 workflow 파일 작성

프로젝트 루트에 .github/workflows/deploy.yml 파일을 만들겠습니다.

전체 workflow 파일

# .github/workflows/deploy.yml
name: Deploy Blog to GitHub Pages

on:
  push:
    branches:
      - main  # main 브랜치에 push하면 실행

permissions:
  contents: write

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      # 1. 레포지토리 코드 체크아웃
      - name: Checkout repository
        uses: actions/checkout@v4

      # 2. Node.js 설정
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"

      # 3. 의존성 설치
      - name: Install dependencies
        run: npm ci

      # 4. Gatsby 빌드
      - name: Build Gatsby site
        run: npm run build
        env:
          PREFIX_PATHS: true

      # 5. GitHub Pages 배포
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          publish_branch: gh-pages

이 파일 하나면 main 브랜치에 push할 때마다 자동으로 빌드 후 gh-pages 브랜치에 배포됩니다.

파일 생성 방법

# 디렉토리 생성
mkdir -p .github/workflows

# 파일 생성 (위 내용을 붙여넣기)
nano .github/workflows/deploy.yml

각 Step 상세 설명

Step 1: actions/checkout

- name: Checkout repository
  uses: actions/checkout@v4

GitHub Actions Runner(서버)에 레포지토리 코드를 가져옵니다. 모든 워크플로우의 첫 번째 단계입니다.

Step 2: actions/setup-node

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: "20"
    cache: "npm"

Node.js를 설치합니다. node-version은 로컬에서 사용하는 버전과 맞추는 것이 좋습니다.

로컬 Node.js 버전 확인 방법:

node -v
# v20.11.0 이런 식으로 출력됩니다

Step 3: npm ci

- name: Install dependencies
  run: npm ci

npm install 대신 npm ci를 사용합니다. npm ci는 package-lock.json을 기반으로 정확히 동일한 의존성을 설치하므로, 빌드 환경의 일관성을 보장합니다.

Step 4: Gatsby 빌드

- name: Build Gatsby site
  run: npm run build
  env:
    PREFIX_PATHS: true

gatsby build 명령어를 실행해 정적 파일을 생성합니다. 결과물은 public/ 폴더에 저장됩니다.

Step 5: peaceiris/actions-gh-pages

- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public
    publish_branch: gh-pages

public/ 폴더의 내용을 gh-pages 브랜치에 자동으로 push합니다. GITHUB_TOKEN은 별도 설정 없이 GitHub Actions가 자동으로 제공합니다.

캐시 설정으로 빌드 속도 향상

Gatsby 빌드는 처음에는 시간이 꽤 걸립니다. 캐시를 설정하면 빌드 시간을 크게 줄일 수 있습니다.

npm 캐시 (이미 적용됨)

actions/setup-node의 cache: "npm" 옵션으로 npm 패키지 캐시는 이미 적용되어 있습니다.

Gatsby 캐시 추가

Gatsby는 .cache 폴더에 빌드 캐시를 저장합니다. 이것도 캐시하면 빌드 속도가 더 빨라집니다.

# Step 2와 Step 3 사이에 추가
- name: Cache Gatsby build
  uses: actions/cache@v4
  with:
    path: |
      .cache
      public
    key: gatsby-build-${{ hashFiles('package-lock.json') }}-${{ hashFiles('contents/**') }}
    restore-keys: |
      gatsby-build-${{ hashFiles('package-lock.json') }}-
      gatsby-build-

캐시 적용 전후 빌드 시간 비교

단계	캐시 없음	캐시 있음
npm install	~60초	~10초
gatsby build	~120초	~30초
전체	~3분	~1분

실제 시간은 블로그 규모에 따라 다르지만, 캐시만으로 2~3배 빨라지는 것을 체감할 수 있습니다.

캐시 포함 완성 workflow

캐시까지 포함한 최종 workflow 파일입니다.

# .github/workflows/deploy.yml
name: Deploy Blog to GitHub Pages

on:
  push:
    branches:
      - main

permissions:
  contents: write

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"

      - name: Cache Gatsby build
        uses: actions/cache@v4
        with:
          path: |
            .cache
            public
          key: gatsby-build-${{ hashFiles('package-lock.json') }}-${{ hashFiles('contents/**') }}
          restore-keys: |
            gatsby-build-${{ hashFiles('package-lock.json') }}-
            gatsby-build-

      - name: Install dependencies
        run: npm ci

      - name: Build Gatsby site
        run: npm run build
        env:
          PREFIX_PATHS: true

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          publish_branch: gh-pages

커스텀 도메인 설정 (CNAME)

blog.javapark.kr처럼 커스텀 도메인을 사용하고 있다면, 배포할 때마다 CNAME 파일이 유지되어야 합니다.

방법 1: static 폴더에 CNAME 파일 추가

echo "blog.javapark.kr" > static/CNAME

Gatsby 빌드 시 static/ 폴더의 파일이 그대로 public/에 복사되므로, 배포 시 자동으로 포함됩니다.

방법 2: workflow에서 CNAME 옵션 사용

- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public
    publish_branch: gh-pages
    cname: blog.javapark.kr

두 가지 방법 모두 동일한 결과를 만들지만, 저는 방법 1을 추천합니다. CNAME 파일이 프로젝트에 명시적으로 포함되어 있으면 관리가 더 편합니다.

GitHub Pages 설정 확인

workflow를 배포하기 전에 GitHub 레포지토리 설정을 확인해야 합니다.

GitHub 레포지토리 > Settings 탭 클릭
왼쪽 메뉴에서 Pages 클릭
Source 항목을 Deploy from a branch로 설정
Branch를 gh-pages / / (root)로 설정
Save 클릭

이 설정이 되어 있어야 gh-pages 브랜치에 push된 파일이 실제로 웹에 배포됩니다.

배포 상태 확인 및 디버깅

Actions 탭에서 확인

push 후 GitHub 레포지토리의 Actions 탭에 들어가면 워크플로우 실행 상태를 확인할 수 있습니다.

초록색 체크: 성공
빨간색 X: 실패
노란색 원: 진행 중

빌드 실패 시 확인할 것

실패한 워크플로우를 클릭하면 각 Step의 로그를 볼 수 있습니다. 자주 발생하는 오류와 해결법을 정리했습니다.

오류	원인	해결법
`npm ci` 실패	`package-lock.json` 불일치	로컬에서 `npm install` 후 lock 파일 커밋
`gatsby build` 실패	플러그인 설정 오류	로컬에서 `gatsby build` 먼저 테스트
권한 오류	`permissions` 미설정	workflow에 `permissions: contents: write` 추가
`gh-pages` 배포 안 됨	Pages 설정 미완료	Settings > Pages에서 브랜치 설정 확인

로컬에서 빌드 테스트

GitHub Actions에 push하기 전에 로컬에서 빌드가 정상인지 확인하는 습관을 들이면 좋습니다.

# 캐시 정리 후 빌드 테스트
gatsby clean && gatsby build

배포 프로세스 전체 흐름 정리

로컬에서 글 작성/수정
       |
       v
git add . && git commit -m "새 글 추가"
       |
       v
git push origin main
       |
       v
GitHub Actions 자동 실행
  1. 코드 체크아웃
  2. Node.js 설정
  3. 캐시 복원
  4. npm ci
  5. gatsby build
  6. gh-pages 브랜치에 배포
       |
       v
GitHub Pages가 gh-pages 브랜치 감지
       |
       v
https://blog.javapark.kr 에 반영 완료

이제 글을 쓰고 push만 하면 됩니다. 나머지는 전부 자동입니다.

자주 묻는 질문 (FAQ)

Q. GitHub Actions는 무료인가요?

네, 공개(public) 레포지토리에서는 완전 무료입니다. 비공개(private) 레포지토리에서는 월 2,000분의 무료 빌드 시간이 제공됩니다. 블로그 하나를 운영하기에는 충분한 양입니다.

Q. main 브랜치가 아닌 다른 브랜치에서 배포하고 싶어요

workflow 파일의 on.push.branches 값을 변경하면 됩니다. 예를 들어 develop 브랜치에서 배포하려면 다음과 같이 수정합니다.

on:
  push:
    branches:
      - develop

Q. 배포 후 사이트에 반영되기까지 얼마나 걸리나요?

보통 GitHub Actions 빌드에 1~~3분, GitHub Pages 반영에 1~~2분 정도 걸립니다. 전체적으로 push 후 3~5분이면 사이트에 반영됩니다. 캐시가 따뜻한(warm) 상태라면 더 빨라집니다.

여러분은 블로그 배포를 어떻게 하고 계신가요? 댓글로 알려주세요.

다음 포스팅에서는 블로그에 광고와 댓글 시스템을 다는 방법을 다룹니다. AdSense, 쿠팡 파트너스로 수익화하고, Utterances로 댓글 기능을 구축하는 방법까지 알아보겠습니다.

Gatsby로 GitHub 블로그 시작하기 — 설치부터 첫 배포까지

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

개발자라면 한 번쯤 나만의 기술 블로그를 운영해보고 싶다는 생각을 해보셨을 겁니다. 네이버 블로그, 티스토리, 벨로그 등 다양한 플랫폼이 있지만, 저는 GitHub Pages + Gatsby 조합을 강력히 추천합니다.

이 포스팅에서는 Gatsby와 gatsby-starter-hoodie 테마를 활용해 GitHub 블로그를 처음부터 배포까지 완성하는 전 과정을 다룹니다.

왜 GitHub Pages 블로그인가?

GitHub Pages 블로그를 선택해야 하는 이유는 명확합니다.

비용 0원: 호스팅 비용이 전혀 들지 않습니다. GitHub에서 무료로 제공합니다.
개발자 친화적: Git으로 버전 관리를 하고, 마크다운으로 글을 씁니다. 개발자에게 이보다 자연스러운 워크플로우는 없습니다.
마크다운 기반: 코드 블록, 수식, 표 등을 편리하게 작성할 수 있습니다. 기술 블로그에 최적화된 형식입니다.
커스터마이징 자유: HTML, CSS, JavaScript를 완전히 제어할 수 있습니다. 원하는 기능을 직접 추가하고, 디자인을 자유롭게 변경할 수 있습니다.
커스텀 도메인 지원: 무료 HTTPS와 함께 나만의 도메인을 연결할 수 있습니다.
SEO 유리: 정적 사이트 생성(SSG) 방식이라 검색엔진 최적화에 유리합니다.

다른 플랫폼과 비교

블로그 플랫폼을 선택할 때 가장 많이 고민하는 옵션들을 비교해 보겠습니다.

항목	GitHub Pages	티스토리	벨로그	Medium
비용	무료	무료	무료	일부 유료
커스터마이징	완전 자유	스킨 수준	제한적	거의 불가
마크다운	네이티브 지원	부분 지원	네이티브 지원	부분 지원
코드 블록	커스텀 가능	기본	기본	기본
SEO 제어	완전 제어	제한적	제한적	불가
광고 수익	직접 설정	카카오 애드핏	불가	Partner Program
초기 설정 난이도	높음	낮음	매우 낮음	매우 낮음

초기 설정이 다소 복잡하다는 단점이 있지만, 이 시리즈를 따라오시면 어렵지 않게 완성할 수 있습니다.

사전 준비

Gatsby 블로그를 시작하기 전에 다음 도구들이 필요합니다.

Node.js 설치

Gatsby는 Node.js 기반 프레임워크입니다. Node.js 공식 사이트에서 LTS 버전을 설치합니다.

# 설치 확인
node --version
# v20.x.x 이상 권장

npm --version
# 10.x.x 이상

팁: nvm(Node Version Manager)을 사용하면 Node.js 버전을 쉽게 관리할 수 있습니다.

Git 설치

Git 공식 사이트에서 설치하거나, 아래 명령어로 확인합니다.

git --version
# git version 2.x.x

GitHub 계정 생성

GitHub에 계정이 없다면 가입합니다. GitHub Pages를 사용하려면 GitHub 계정이 필수입니다.

Gatsby 설치 및 프로젝트 생성

Gatsby CLI 설치

먼저 Gatsby CLI를 전역으로 설치합니다.

npm install -g gatsby-cli

gatsby-starter-hoodie로 프로젝트 생성

gatsby-starter-hoodie는 깔끔한 디자인과 다크모드, 시리즈 기능 등을 기본 제공하는 테마입니다. 이 블로그(AI JAVAPARK)에서도 사용하고 있습니다.

# 프로젝트 생성
npx gatsby new my-blog https://github.com/devHudi/gatsby-starter-hoodie

# 프로젝트 폴더로 이동
cd my-blog

프로젝트 생성이 완료되면 다음과 같은 폴더 구조가 생성됩니다.

my-blog/
├── contents/
│   └── posts/          # 블로그 글 저장 폴더
├── src/
│   ├── assets/         # 테마, 이미지 등 정적 자원
│   ├── components/     # React 컴포넌트
│   ├── pages/          # 페이지 컴포넌트
│   └── templates/      # 템플릿 컴포넌트
├── static/             # 정적 파일 (favicon 등)
├── blog-config.js      # 블로그 설정 파일
├── gatsby-config.js    # Gatsby 설정 파일
├── gatsby-node.js      # Gatsby Node API
└── package.json

blog-config.js 설정

프로젝트 루트에 있는 blog-config.js 파일을 열어 블로그 기본 정보를 설정합니다.

module.exports = {
  title: "AI JAVAPARK",
  description: "개발과 AI를 다루는 기술 블로그",
  author: "자바파커",
  siteUrl: "https://blog.javapark.kr",
  links: {
    github: "https://github.com/javapark",
    // 사용하지 않는 링크는 빈 문자열로 두면 됩니다
    linkedIn: "",
    facebook: "",
    instagram: "",
    email: "mailto:your-email@example.com",
  },
  utterances: {
    repo: "javapark/blog-comments",
    type: "pathname",
  },
}

각 항목을 설명하면 다음과 같습니다.

title: 블로그 제목입니다. 브라우저 탭과 헤더에 표시됩니다.
description: 블로그 설명입니다. SEO 메타 태그에 사용됩니다.
author: 작성자 이름입니다.
siteUrl: 배포될 블로그 URL입니다. GitHub Pages 기본 URL(https://username.github.io) 또는 커스텀 도메인을 입력합니다.
links: SNS 링크입니다. 프로필 영역에 아이콘으로 표시됩니다.
utterances: GitHub Issues 기반 댓글 시스템 설정입니다.

로컬 개발 서버 실행

설정을 마쳤다면 로컬에서 블로그를 확인해 봅시다.

# 개발 서버 실행
gatsby develop

브라우저에서 http://localhost:8000으로 접속하면 블로그를 확인할 수 있습니다.

# 만약 포트 충돌이 발생한다면 포트를 변경할 수 있습니다
gatsby develop -p 9000

개발 서버는 핫 리로딩을 지원하므로, 파일을 수정하면 브라우저가 자동으로 새로고침됩니다. 글을 쓰면서 실시간으로 결과를 확인할 수 있어 매우 편리합니다.

빌드 테스트

배포 전에 프로덕션 빌드가 정상적으로 되는지 확인하는 것이 좋습니다.

# 프로덕션 빌드
gatsby build

# 빌드 결과 로컬에서 확인
gatsby serve

gatsby serve를 실행하면 http://localhost:9000에서 빌드된 결과물을 확인할 수 있습니다.

GitHub Pages 배포

이제 가장 중요한 단계인 배포를 진행합니다.

GitHub 리포지토리 생성

GitHub에서 New repository를 클릭합니다.
Repository name을 username.github.io 형식으로 입력합니다. (예: javapark.github.io)
Public으로 설정합니다. (GitHub Pages 무료 플랜은 Public 리포지토리에서만 동작합니다.)
Create repository를 클릭합니다.

원격 리포지토리 연결

# 기존 원격 저장소 제거 (starter 원본이 연결되어 있을 수 있습니다)
git remote remove origin

# 새 리포지토리 연결
git remote add origin https://github.com/username/username.github.io.git

# 기본 브랜치를 main으로 설정
git branch -M main

# 첫 커밋 및 푸시
git add .
git commit -m "Initial commit"
git push -u origin main

gh-pages 패키지로 배포

gh-pages 패키지를 사용하면 빌드 결과물만 별도 브랜치에 배포할 수 있습니다.

# gh-pages 패키지 설치
npm install gh-pages --save-dev

package.json에 배포 스크립트를 추가합니다.

{
  "scripts": {
    "deploy": "gatsby build && gh-pages -d public -b gh-pages"
  }
}

배포를 실행합니다.

npm run deploy

GitHub Pages 설정

GitHub 리포지토리 > Settings > Pages로 이동합니다.
Source를 Deploy from a branch로 선택합니다.
Branch를 gh-pages로 선택하고 폴더는 / (root)로 설정합니다.
Save를 클릭합니다.

몇 분 뒤 https://username.github.io에 블로그가 배포됩니다.

배포 확인

# 배포 상태 확인 (GitHub CLI가 설치되어 있다면)
gh api repos/{owner}/{repo}/pages --jq '.status'

브라우저에서 https://username.github.io에 접속하여 블로그가 정상적으로 표시되는지 확인합니다.

첫 글 작성해보기

배포가 완료되었으니 첫 글을 작성해 봅시다.

# 글 폴더 생성
mkdir -p contents/posts/my-first-post

contents/posts/my-first-post/index.md 파일을 만들고 다음과 같이 작성합니다.

---
title: "나의 첫 블로그 포스팅"
description: "GitHub 블로그에 첫 글을 작성했습니다."
date: 2026-04-04
update: 2026-04-04
tags:
  - 블로그
  - 시작
---

## 안녕하세요!

이것은 나의 첫 블로그 포스팅입니다.

### 코드 블록도 됩니다

\```javascript
console.log("Hello, Blog!");
\```

글을 작성한 뒤 다시 배포합니다.

npm run deploy

자주 묻는 질문 (FAQ)

Q1. GitHub Pages는 정말 무료인가요?

네, 완전히 무료입니다. Public 리포지토리에서는 GitHub Pages를 무료로 사용할 수 있으며, 월 트래픽 제한은 약 100GB입니다. 일반적인 개인 블로그에서는 이 제한에 도달할 일이 거의 없습니다.

Q2. gatsby-starter-hoodie 대신 다른 테마를 써도 되나요?

물론입니다. Gatsby Starter Library에서 다양한 테마를 확인할 수 있습니다. 다만 이 시리즈에서는 gatsby-starter-hoodie를 기준으로 설명하므로, 다른 테마를 선택하면 설정 방법이 다를 수 있습니다.

Q3. 커스텀 도메인은 어떻게 연결하나요?

GitHub 리포지토리 Settings > Pages에서 Custom domain 항목에 원하는 도메인을 입력합니다. 그 전에 도메인 DNS 설정에서 CNAME 레코드를 username.github.io로 지정해야 합니다. 이 부분은 시리즈 후반부에서 자세히 다룰 예정입니다.

다음 포스팅에서는 Gatsby 블로그 스킨 커스터마이징 방법을 다룹니다. 콘텐츠 폭, 폰트, 색상, 다크모드까지 나만의 블로그 디자인을 만들어 보겠습니다.

마크다운 글쓰기와 카테고리 관리 — 체계적인 블로그 운영법

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

지금까지 Gatsby 블로그를 설치하고, 스킨을 커스터마이징하는 방법을 다뤘습니다. 이번 포스팅에서는 실제 글을 작성하고 콘텐츠를 체계적으로 관리하는 방법을 알아보겠습니다. 마크다운 문법부터 frontmatter, 태그 전략, 시리즈 기능, 이미지 관리까지 블로그 운영에 필요한 모든 것을 다룹니다.

마크다운 기본 문법

마크다운은 텍스트 기반의 경량 마크업 언어입니다. 기술 블로그에서 가장 많이 사용되는 문법들을 정리합니다.

제목 (Heading)

# 기호의 개수로 제목 수준을 구분합니다.

# h1 — 포스트 제목 (frontmatter title과 중복되므로 본문에서는 사용하지 않습니다)
## h2 — 주요 섹션
### h3 — 하위 섹션
#### h4 — 세부 항목

팁: 본문에서는 ##(h2)부터 시작하는 것이 SEO와 문서 구조에 좋습니다. h1은 포스트 제목이 자동으로 사용합니다.

텍스트 서식

**굵게** 또는 __굵게__
*기울임* 또는 _기울임_
~~취소선~~
`인라인 코드`

결과:

굵게
기울임
~~취소선~~
인라인 코드

순서 없는 목록:
- 항목 1
- 항목 2
  - 중첩 항목 2-1
  - 중첩 항목 2-2

순서 있는 목록:
1. 첫 번째
2. 두 번째
3. 세 번째

코드 블록

기술 블로그의 핵심 요소입니다. 백틱 세 개(```)로 감싸고 언어를 지정합니다.

```javascript
const greeting = "안녕하세요!";
console.log(greeting);
```

```python
def hello():
    print("안녕하세요!")
```

```bash
npm install gatsby-cli -g
```

지원되는 주요 언어 키워드: javascript, typescript, python, java, bash, css, html, json, yaml, sql, go, rust, kotlin, swift 등

표 (Table)

| 기능 | 설명 | 필수 여부 |
|------|------|----------|
| title | 포스트 제목 | 필수 |
| description | 짧은 설명 | 권장 |
| date | 작성일 | 필수 |
| tags | 태그 목록 | 권장 |

결과:

기능	설명	필수 여부
title	포스트 제목	필수
description	짧은 설명	권장
date	작성일	필수
tags	태그 목록	권장

인용 (Blockquote)

> 이것은 인용문입니다.
> 여러 줄로 작성할 수 있습니다.

> **참고**: 강조 표시와 함께 사용하면 주의사항이나 팁을 효과적으로 전달할 수 있습니다.

참고: 강조 표시와 함께 사용하면 주의사항이나 팁을 효과적으로 전달할 수 있습니다.

링크와 이미지

[링크 텍스트](https://example.com)
[새 탭에서 열기](https://example.com){:target="_blank"}

![이미지 대체 텍스트](./images/example.png)
![외부 이미지](https://example.com/image.png)

구분선

---

세 개 이상의 하이픈(-), 별표(*), 밑줄(_)로 구분선을 만들 수 있습니다.

Frontmatter 구조

Frontmatter는 마크다운 파일 상단에 YAML 형식으로 작성하는 메타데이터입니다. gatsby-starter-hoodie에서 지원하는 필드를 자세히 알아봅시다.

기본 구조

---
title: "포스트 제목"
description: "포스트에 대한 짧은 설명 (SEO 메타 설명에 사용됩니다)"
date: 2026-04-04
update: 2026-04-04
tags:
  - gatsby
  - blog
series: "시리즈 이름"
---

각 필드 상세 설명

title (필수)

포스트의 제목입니다. HTML <title> 태그와 <h1> 태그에 사용됩니다.

title: "Gatsby로 GitHub 블로그 시작하기 — 설치부터 첫 배포까지"

큰따옴표로 감싸는 것이 안전합니다. 특히 콜론(:)이 포함된 경우 반드시 따옴표가 필요합니다.
SEO를 위해 핵심 키워드를 앞쪽에 배치합니다.
50~60자 이내가 검색 결과에서 잘리지 않아 적절합니다.

description (권장)

포스트에 대한 짧은 설명으로, 검색엔진 결과와 블로그 목록에 표시됩니다.

description: "Gatsby 설치부터 gatsby-starter-hoodie 테마 적용, GitHub Pages 배포까지 완전 가이드"

120~160자 이내가 적절합니다.
핵심 키워드를 자연스럽게 포함합니다.
클릭을 유도하는 명확한 문장을 작성합니다.

date / update

작성일과 수정일입니다. YYYY-MM-DD 형식으로 작성합니다.

date: 2026-04-04
update: 2026-04-04

date: 포스트 최초 작성일입니다. 목록 정렬에 사용됩니다.
update: 포스트 수정일입니다. 포스트를 업데이트했을 때 갱신합니다.

series

여러 포스트를 하나의 시리즈로 묶을 때 사용합니다.

series: "GitHub 블로그 A to Z"

같은 series 값을 가진 포스트들이 자동으로 그룹핑되어 포스트 하단에 시리즈 네비게이션이 표시됩니다.

폴더 구조 설계

블로그가 커지면 폴더 구조가 매우 중요해집니다. 처음부터 체계적으로 설계하면 나중에 관리가 편합니다.

네이밍 규칙

폴더와 파일 이름에 일관된 규칙을 적용합니다.

카테고리 폴더: 소문자 영문, 하이픈(-) 구분 (예: gatsby-blog, javascript)
포스트 폴더: 시리즈의 경우 번호 접두사 사용 (예: 01-getting-started)
단독 포스트: 핵심 키워드로 구성 (예: closure-explained)
TIL: 날짜 접두사 사용 (예: 2026-03-28-css-grid)
이미지 폴더: 포스트 폴더 내 images/ 하위에 관리

왜 index.md를 사용하는가?

포스트마다 폴더를 만들고 index.md를 사용하는 이유가 있습니다.

# 이렇게 하면
posts/my-post.md          # 이미지를 어디에 둘지 애매합니다

# 이렇게 하면
posts/my-post/index.md    # 관련 이미지를 같은 폴더에 둘 수 있습니다
posts/my-post/images/screenshot.png

이미지를 같은 폴더에 두면 상대 경로(./images/screenshot.png)로 참조할 수 있어 관리가 훨씬 편합니다.

태그 전략

태그를 잘 설계하면 독자가 관련 글을 쉽게 찾을 수 있고, SEO에도 도움이 됩니다.

태그 작성 규칙

소문자 통일: JavaScript 대신 javascript, React 대신 react를 사용합니다.
하이픈 구분: 두 단어 이상인 경우 하이픈으로 연결합니다. (예: github-pages, styled-components)
복수형 지양: algorithms 대신 algorithm처럼 단수형을 사용합니다.
의미 있는 태그: 기타, 잡담 같은 모호한 태그는 피합니다.
적정 개수: 포스트당 3~5개가 적절합니다. 너무 많으면 태그의 의미가 희석됩니다.

태그 분류 체계

태그를 기술/도구/개념/시리즈로 분류하면 체계적으로 관리할 수 있습니다.

# 기술/언어 태그
tags: [javascript, typescript, python, java, go]

# 프레임워크/도구 태그
tags: [gatsby, react, next.js, docker, github-actions]

# 개념 태그
tags: [algorithm, data-structure, design-pattern, clean-code]

# 유형 태그
tags: [tutorial, review, til]

태그 관리 스프레드시트

블로그가 커지면 태그 목록을 별도로 관리하는 것이 좋습니다. 간단한 표를 만들어 사용 중인 태그와 포스트 수를 추적합니다.

태그	포스트 수	비고
gatsby	6	블로그 시리즈
javascript	12	주력 언어
react	8	프론트엔드
til	25	Today I Learned

시리즈 기능 활용

gatsby-starter-hoodie의 시리즈 기능은 연관된 포스트를 그룹으로 묶어주는 강력한 기능입니다.

시리즈 설정 방법

frontmatter에 같은 series 값을 지정하면 자동으로 시리즈가 생성됩니다.

# 포스트 1
---
title: "Gatsby 블로그 시작하기"
series: "GitHub 블로그 A to Z"
date: 2026-04-01
---

# 포스트 2
---
title: "블로그 스킨 커스터마이징"
series: "GitHub 블로그 A to Z"
date: 2026-04-04
---

# 포스트 3
---
title: "마크다운 글쓰기와 카테고리 관리"
series: "GitHub 블로그 A to Z"
date: 2026-04-07
---

이렇게 설정하면 각 포스트 하단에 시리즈 목록이 자동으로 표시되어, 독자가 이전/다음 포스트로 쉽게 이동할 수 있습니다.

시리즈 네이밍 팁

시리즈 이름은 한국어로 작성해도 됩니다. 태그와 달리 시리즈 이름은 URL에 직접 사용되지 않습니다.
명확하고 구체적인 이름을 사용합니다. (예: "GitHub 블로그 A to Z", "React 핵심 개념 정리")
시리즈 내 포스트 순서는 date 값으로 결정됩니다. 날짜를 순차적으로 설정하면 원하는 순서대로 표시됩니다.

시리즈 활용 사례

시리즈 1: "GitHub 블로그 A to Z"
├── 01. Gatsby로 GitHub 블로그 시작하기
├── 02. 블로그 스킨 커스터마이징
├── 03. 마크다운 글쓰기와 카테고리 관리
├── 04. SEO 최적화
├── 05. GitHub Actions 자동 배포
└── 06. 광고 및 댓글 시스템

시리즈 2: "JavaScript 핵심 개념"
├── 01. 실행 컨텍스트와 호이스팅
├── 02. 클로저 완벽 이해
├── 03. 프로토타입과 상속
└── 04. 비동기 프로그래밍

이미지 관리

기술 블로그에서 이미지는 스크린샷, 다이어그램, 아키텍처 도표 등으로 자주 사용됩니다. 효율적인 이미지 관리 방법을 알아봅시다.

로컬 이미지

가장 간단한 방법은 포스트 폴더 내에 이미지를 함께 보관하는 것입니다.

posts/my-post/
├── index.md
└── images/
    ├── screenshot-01.png
    └── architecture-diagram.png

마크다운에서 상대 경로로 참조합니다.

![스크린샷](./images/screenshot-01.png)
![아키텍처 다이어그램](./images/architecture-diagram.png)

장점: 포스트와 이미지가 함께 관리되어 직관적입니다. 단점: 리포지토리 용량이 커질 수 있습니다. GitHub 리포지토리의 권장 용량은 1GB 이하입니다.

GitHub Release 활용

리포지토리 용량을 아끼면서 이미지를 관리하는 방법입니다.

GitHub 리포지토리 > Releases > Draft a new release로 이동합니다.
이미지 파일을 드래그 앤 드롭으로 업로드합니다.
생성된 URL을 마크다운에서 사용합니다.

![스크린샷](https://github.com/username/repo/releases/download/v1.0/screenshot.png)

팁: GitHub Issues에 이미지를 드래그 앤 드롭하면 자동으로 user-images.githubusercontent.com URL이 생성됩니다. 이 URL을 복사해서 사용할 수도 있습니다.

외부 CDN 활용

이미지가 많은 블로그라면 별도의 CDN 서비스를 사용하는 것이 효율적입니다.

Cloudflare Images: 합리적인 가격, 이미지 리사이징 지원
imgbb: 무료 이미지 호스팅
GitHub 자체 CDN: Issues/PR에 이미지를 업로드하면 생성되는 URL 활용

이미지 최적화

이미지 크기가 크면 페이지 로딩 속도에 영향을 줍니다. 다음 사항을 지키면 좋습니다.

포맷: 스크린샷은 PNG, 사진은 WebP 또는 JPEG를 사용합니다.
크기: 콘텐츠 폭의 2배(Retina 대응) 정도가 적절합니다. 본문 폭이 760px이면 이미지 폭은 1520px 이하로 유지합니다.
압축: Squoosh나 TinyPNG로 압축합니다.
alt 텍스트: 접근성과 SEO를 위해 항상 의미 있는 대체 텍스트를 작성합니다.

<!-- 좋은 예 -->
![Gatsby 프로젝트 폴더 구조](./images/folder-structure.png)

<!-- 나쁜 예 -->
![](./images/image1.png)
![사진](./images/photo.png)

글쓰기 워크플로우

마지막으로, 실제 글쓰기 워크플로우를 정리합니다.

새 포스트 작성 과정

# 1. 포스트 폴더 생성
mkdir -p contents/posts/category-name/post-title

# 2. index.md 파일 생성
touch contents/posts/category-name/post-title/index.md

# 3. frontmatter 작성
# 4. 본문 작성
# 5. 개발 서버에서 확인
gatsby develop

# 6. 문제가 없으면 커밋 및 배포
git add .
git commit -m "feat: add new post - 포스트 제목"
npm run deploy

포스트 템플릿

매번 frontmatter를 처음부터 작성하는 것은 번거롭습니다. 아래 템플릿을 복사해서 사용하세요.

---
title: ""
description: ""
date: 2026-04-04
update: 2026-04-04
tags:
  -
series: ""
---

안녕하세요, **자바파커**입니다.

(도입부: 이 글에서 다루는 내용과 독자가 얻을 수 있는 것)

## 섹션 1

### 하위 섹션

## 섹션 2

## 자주 묻는 질문 (FAQ)

### Q1.

### Q2.

---

다음 포스팅에서는 ~ 다룹니다.

자주 묻는 질문 (FAQ)

Q1. 마크다운 에디터는 무엇을 추천하나요?

VS Code를 가장 추천합니다. 마크다운 프리뷰(Ctrl+Shift+V), 마크다운 린트, 이미지 붙여넣기 등 블로그 글쓰기에 필요한 확장 기능이 풍부합니다. 추천 확장 프로그램은 다음과 같습니다.

Markdown All in One: 단축키, 목차 생성, 서식 지원
Markdown Preview Enhanced: 향상된 미리보기
Paste Image: 클립보드 이미지를 바로 붙여넣기
markdownlint: 마크다운 문법 검사

Q2. 태그와 시리즈, 카테고리의 차이점은 무엇인가요?

태그(tag): 포스트의 주제나 기술을 나타내는 키워드입니다. 하나의 포스트에 여러 태그를 붙일 수 있습니다. (예: javascript, react, tutorial)
시리즈(series): 순서대로 읽어야 하는 연속 포스트를 그룹핑합니다. 하나의 포스트는 하나의 시리즈에만 속할 수 있습니다.
카테고리: gatsby-starter-hoodie에서는 폴더 구조로 카테고리를 대체합니다. 별도의 카테고리 frontmatter 필드는 없으며, 폴더 경로가 곧 카테고리 역할을 합니다.

Q3. 이전에 작성한 글을 수정하면 date도 바꿔야 하나요?

date는 최초 작성일이므로 변경하지 않습니다. 대신 update 필드를 수정일로 갱신합니다. 이렇게 하면 목록 정렬 순서는 유지되면서 독자에게 "최근 업데이트 됨"을 알릴 수 있습니다.

date: 2026-04-04    # 최초 작성일 (변경하지 않음)
update: 2026-04-10  # 수정일 (갱신)

다음 포스팅에서는 SEO 최적화 방법을 다룹니다. 검색엔진에 블로그가 잘 노출되도록 메타 태그, 사이트맵, 구글 서치 콘솔 등록까지 실전 가이드를 알아보겠습니다.

GitHub 블로그 SEO 최적화 — 검색에 노출되는 블로그 만들기

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

"블로그 글을 열심히 썼는데, 구글에 검색해도 안 나와요."

GitHub Pages로 블로그를 만들고 글까지 발행했는데, 정작 검색 엔진에서 내 글이 보이지 않는다면 정말 허무하겠죠. 결론부터 말씀드리면 — 블로그를 만드는 것과 검색에 노출되는 것은 완전히 다른 문제입니다. SEO(Search Engine Optimization) 설정 없이는 아무리 좋은 글을 써도 구글이 찾아오지 않습니다.

이번 포스팅에서는 Gatsby 기반 GitHub 블로그의 SEO를 처음부터 끝까지 최적화하는 방법을 다룹니다.

SEO가 블로그에 중요한 이유

SEO란 검색 엔진 최적화(Search Engine Optimization)의 약자로, 구글이나 네이버 같은 검색 엔진이 내 블로그를 잘 이해하고, 검색 결과에 잘 노출시킬 수 있도록 만드는 작업입니다.

블로그에 SEO가 중요한 이유는 간단합니다.

항목	SEO 미적용	SEO 적용
검색 노출	거의 없음	키워드별 상위 노출 가능
유입 경로	직접 공유만 가능	구글 검색 유입
공유 시 미리보기	제목만 표시	이미지 + 설명 표시
크롤링	구조 파악 어려움	사이트맵으로 효율적 크롤링

특히 GitHub Pages 블로그는 티스토리나 워드프레스와 달리 SEO 설정이 자동으로 되지 않기 때문에 직접 설정해줘야 합니다.

Gatsby SEO 컴포넌트 만들기 (React Helmet)

Gatsby에서 <head> 태그를 제어하려면 react-helmet 또는 Gatsby의 Head API를 사용합니다. gatsby-starter-hoodie 테마에는 이미 SEO 컴포넌트가 포함되어 있지만, 직접 만드는 방법도 알아두면 좋습니다.

react-helmet 설치

npm install gatsby-plugin-react-helmet react-helmet

gatsby-config.js에 플러그인을 추가합니다.

// gatsby-config.js
module.exports = {
  plugins: [
    `gatsby-plugin-react-helmet`,
    // ... 기존 플러그인들
  ],
}

SEO 컴포넌트 기본 구조

// src/components/SEO.js
import React from "react"
import { Helmet } from "react-helmet"
import { useStaticQuery, graphql } from "gatsby"

const SEO = ({ title, description, image, url, article }) => {
  const { site } = useStaticQuery(graphql`
    query {
      site {
        siteMetadata {
          defaultTitle: title
          defaultDescription: description
          siteUrl
          defaultImage: image
        }
      }
    }
  `)

  const {
    defaultTitle,
    defaultDescription,
    siteUrl,
    defaultImage,
  } = site.siteMetadata

  const seo = {
    title: title || defaultTitle,
    description: description || defaultDescription,
    image: `${siteUrl}${image || defaultImage}`,
    url: `${siteUrl}${url || ""}`,
  }

  return (
    <Helmet title={seo.title}>
      <meta name="description" content={seo.description} />
      <meta name="image" content={seo.image} />

      {/* Open Graph */}
      <meta property="og:title" content={seo.title} />
      <meta property="og:description" content={seo.description} />
      <meta property="og:image" content={seo.image} />
      <meta property="og:url" content={seo.url} />
      <meta property="og:type" content={article ? "article" : "website"} />

      {/* Twitter Card */}
      <meta name="twitter:card" content="summary_large_image" />
      <meta name="twitter:title" content={seo.title} />
      <meta name="twitter:description" content={seo.description} />
      <meta name="twitter:image" content={seo.image} />
    </Helmet>
  )
}

export default SEO

이 컴포넌트를 각 페이지나 템플릿에서 불러와 사용하면 됩니다.

메타태그 최적화 — title, description, keywords

메타태그는 검색 엔진이 페이지의 내용을 파악하는 핵심 정보입니다.

title 태그 작성법

60자 이내로 작성합니다
핵심 키워드를 앞쪽에 배치합니다
페이지 제목 | 사이트명 형식이 일반적입니다

<title>GitHub 블로그 SEO 최적화 가이드 | AI JAVAPARK</title>

description 메타태그

150자 내외로 작성합니다
페이지 내용을 요약하되, 클릭을 유도하는 문장으로 구성합니다
검색 결과에서 제목 아래에 표시되는 텍스트입니다

<meta name="description" content="메타태그, sitemap, Open Graph 설정까지 — Gatsby 기반 GitHub 블로그의 검색 노출을 높이는 실전 SEO 가이드입니다." />

gatsby-config.js의 siteMetadata 활용

// gatsby-config.js
module.exports = {
  siteMetadata: {
    title: `AI JAVAPARK`,
    description: `AI와 개발 이야기를 나누는 블로그`,
    siteUrl: `https://blog.javapark.kr`,
    image: `/og-default.png`,
    author: `자바파커`,
  },
  // ...
}

각 포스팅의 frontmatter에 작성한 title과 description이 메타태그로 자동 연결되도록 템플릿을 구성하는 것이 좋습니다.

Open Graph와 Twitter Card 설정

Open Graph(OG)는 페이스북, 카카오톡 등에서 링크 공유 시 미리보기를 결정하는 프로토콜입니다. Twitter Card는 트위터(현 X)에서의 미리보기입니다.

Open Graph 필수 태그

<meta property="og:title" content="GitHub 블로그 SEO 최적화" />
<meta property="og:description" content="검색 노출을 높이는 실전 가이드" />
<meta property="og:image" content="https://blog.javapark.kr/og-image.png" />
<meta property="og:url" content="https://blog.javapark.kr/github-blog/04-seo-optimization/" />
<meta property="og:type" content="article" />
<meta property="og:site_name" content="AI JAVAPARK" />

Twitter Card 태그

<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="GitHub 블로그 SEO 최적화" />
<meta name="twitter:description" content="검색 노출을 높이는 실전 가이드" />
<meta name="twitter:image" content="https://blog.javapark.kr/og-image.png" />

OG 이미지 권장 사양

항목	권장값
크기	1200 x 630px
포맷	PNG 또는 JPG
파일 크기	1MB 이하
위치	static 폴더에 저장

OG 이미지가 잘 적용됐는지 확인하려면 Facebook Sharing Debugger나 Twitter Card Validator를 활용하세요.

sitemap.xml 생성하기

사이트맵은 검색 엔진에게 "내 블로그에는 이런 페이지들이 있습니다"라고 알려주는 XML 파일입니다. 일종의 블로그 목차라고 생각하면 됩니다.

gatsby-plugin-sitemap 설치 및 설정

npm install gatsby-plugin-sitemap

// gatsby-config.js
module.exports = {
  siteMetadata: {
    siteUrl: `https://blog.javapark.kr`,
  },
  plugins: [
    {
      resolve: `gatsby-plugin-sitemap`,
      options: {
        query: `
          {
            allSitePage {
              nodes {
                path
              }
            }
          }
        `,
        resolveSiteUrl: () => `https://blog.javapark.kr`,
        serialize: ({ path }) => ({
          url: path,
          changefreq: `weekly`,
          priority: path === `/` ? 1.0 : 0.7,
        }),
      },
    },
  ],
}

빌드 후 public/sitemap-index.xml에 사이트맵이 생성됩니다. https://blog.javapark.kr/sitemap-index.xml로 접근해서 확인할 수 있습니다.

robots.txt 설정하기

robots.txt는 검색 엔진 크롤러에게 "이 페이지는 크롤링해도 됩니다 / 하지 마세요"를 알려주는 파일입니다.

gatsby-plugin-robots-txt 설치 및 설정

npm install gatsby-plugin-robots-txt

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-robots-txt`,
      options: {
        host: `https://blog.javapark.kr`,
        sitemap: `https://blog.javapark.kr/sitemap-index.xml`,
        policy: [
          {
            userAgent: `*`,
            allow: `/`,
          },
        ],
      },
    },
  ],
}

빌드 후 생성되는 robots.txt 내용은 다음과 같습니다.

User-agent: *
Allow: /

Sitemap: https://blog.javapark.kr/sitemap-index.xml
Host: https://blog.javapark.kr

Google Search Console 등록

사이트맵과 robots.txt를 만들었으면, 이제 구글에 "내 블로그가 여기 있습니다"라고 직접 알려줘야 합니다.

등록 절차

Google Search Console에 접속합니다
속성 추가 버튼을 클릭합니다
URL 접두어 방식으로 https://blog.javapark.kr을 입력합니다
소유권 확인 방법 중 HTML 태그 방식을 선택합니다
제공되는 메타태그를 SEO 컴포넌트에 추가합니다

// SEO 컴포넌트에 추가
<Helmet>
  <meta
    name="google-site-verification"
    content="여기에_구글이_제공한_인증코드"
  />
</Helmet>

빌드 후 배포하고, Search Console에서 확인 버튼을 누릅니다
소유권 확인이 완료되면 Sitemaps 메뉴에서 사이트맵 URL을 제출합니다

https://blog.javapark.kr/sitemap-index.xml

네이버 서치어드바이저 등록

네이버 검색 노출도 원한다면 네이버 서치어드바이저에도 동일하게 등록합니다.

<meta name="naver-site-verification" content="네이버_인증코드" />

구조화 데이터 (JSON-LD) 추가하기

구조화 데이터(Structured Data)는 검색 엔진에게 페이지의 의미를 더 정확하게 알려주는 방법입니다. 구글 검색 결과에서 별점, 작성일, 작성자 같은 리치 스니펫(Rich Snippet)이 표시되는 게 바로 구조화 데이터 덕분입니다.

블로그 포스팅용 JSON-LD

// src/components/SEO.js 에 추가
const structuredData = {
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  headline: seo.title,
  description: seo.description,
  image: seo.image,
  url: seo.url,
  datePublished: date,
  dateModified: update || date,
  author: {
    "@type": "Person",
    name: "자바파커",
    url: "https://blog.javapark.kr",
  },
  publisher: {
    "@type": "Organization",
    name: "AI JAVAPARK",
    logo: {
      "@type": "ImageObject",
      url: "https://blog.javapark.kr/logo.png",
    },
  },
  mainEntityOfPage: {
    "@type": "WebPage",
    "@id": seo.url,
  },
}

Helmet을 통해 <script> 태그로 삽입합니다.

<Helmet>
  <script type="application/ld+json">
    {JSON.stringify(structuredData)}
  </script>
</Helmet>

구조화 데이터 테스트

구글의 리치 결과 테스트 도구에서 URL을 입력하면 구조화 데이터가 제대로 적용됐는지 확인할 수 있습니다.

GitHub 블로그 SEO 검색 노출 체크리스트

모든 설정을 마쳤다면, 아래 체크리스트로 빠진 항목이 없는지 확인해보세요.

자주 묻는 질문 (FAQ)

Q. SEO 설정 후 검색에 바로 노출되나요?

아닙니다. 구글이 크롤링하고 인덱싱하는 데에는 며칠에서 몇 주까지 걸릴 수 있습니다. Search Console에서 직접 URL 색인 요청을 하면 속도를 앞당길 수 있습니다. Search Console의 URL 검사 메뉴에서 URL을 입력한 뒤 색인 생성 요청 버튼을 누르면 됩니다.

Q. gatsby-starter-hoodie 테마에 이미 SEO가 적용되어 있나요?

네, 기본적인 메타태그와 OG 태그가 포함되어 있습니다. 다만 sitemap, robots.txt, 구조화 데이터, Search Console 등록은 직접 해야 합니다. 테마에 포함된 SEO 컴포넌트를 열어서 현재 어디까지 설정되어 있는지 확인해보시는 걸 추천합니다.

Q. OG 이미지를 포스팅마다 다르게 설정할 수 있나요?

네, frontmatter에 image 필드를 추가하고, SEO 컴포넌트에서 해당 값을 읽어오도록 구성하면 됩니다. 포스팅별로 고유한 OG 이미지를 설정하면 SNS 공유 시 클릭률이 높아집니다.

여러분은 블로그 SEO 어디까지 설정하고 계신가요? 댓글로 알려주세요.

다음 포스팅에서는 GitHub Actions로 블로그를 자동 배포하는 방법을 다룹니다. push만 하면 빌드부터 배포까지 알아서 되는 환경을 만들어보겠습니다.

블로그에 광고와 댓글 시스템 달기 — 수익화와 소통

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

"블로그에 글만 올리면 끝인가요? 수익도 낼 수 있고, 독자와 소통도 할 수 있다면 좋겠는데..."

GitHub Pages 블로그도 광고를 달아 수익을 만들 수 있고, 댓글 시스템을 붙여 독자와 소통할 수 있습니다. 결론부터 말씀드리면 — 정적 사이트라서 불가능할 것 같지만, 방법은 충분히 있습니다.

이번 포스팅에서는 Google AdSense와 쿠팡 파트너스로 수익화하는 방법, 그리고 Utterances로 GitHub 기반 댓글 시스템을 구축하는 방법을 다룹니다. "GitHub 블로그 A to Z" 시리즈의 마지막 편입니다.

블로그 수익화 옵션 비교

GitHub Pages 블로그에 적용할 수 있는 수익화 방법은 크게 세 가지입니다.

방법	난이도	승인 필요	수익 구조	특징
Google AdSense	중간	승인 심사 있음	CPC (클릭당 과금)	가장 보편적, 심사 통과가 관건
쿠팡 파트너스	쉬움	가입 즉시 가능	CPS (구매당 수수료)	한국 사용자 대상으로 효과적
제휴 마케팅	중간	업체별 다름	건당 수수료	특정 상품/서비스 추천

초보 블로거라면 쿠팡 파트너스를 먼저 시작하고, 블로그가 어느 정도 성장한 뒤 AdSense 승인을 신청하는 것을 추천합니다.

Google AdSense 신청 및 설정

AdSense 승인 조건

구글이 공식적으로 밝히지는 않지만, 경험적으로 알려진 조건들이 있습니다.

양질의 포스팅이 15개 이상
각 포스팅이 1,000자 이상의 충실한 내용
개인정보처리방침(Privacy Policy) 페이지 존재
커스텀 도메인 사용 (github.io 도메인으로는 승인이 어려울 수 있음)
저작권 문제가 없는 콘텐츠

AdSense 신청 절차

Google AdSense에 접속하여 가입합니다
블로그 URL(https://blog.javapark.kr)을 등록합니다
AdSense에서 제공하는 인증 코드를 블로그의 <head>에 추가합니다
심사 결과를 기다립니다 (보통 1~2주)

Gatsby에 AdSense 코드 삽입하기

gatsby-ssr.js 파일을 사용해 <head>에 스크립트를 추가합니다.

// gatsby-ssr.js
import React from "react"

export const onRenderBody = ({ setHeadComponents }) => {
  setHeadComponents([
    <script
      key="adsense"
      async
      src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-XXXXXXXXXXXXXXXX"
      crossOrigin="anonymous"
    />,
  ])
}

ca-pub-XXXXXXXXXXXXXXXX 부분은 AdSense에서 제공하는 본인의 퍼블리셔 ID로 교체합니다.

포스팅 내에 광고 배치하기

승인이 완료되면, 광고 컴포넌트를 만들어 원하는 위치에 삽입할 수 있습니다.

// src/components/AdSense.js
import React, { useEffect } from "react"

const AdSense = ({ slot, format = "auto", responsive = true }) => {
  useEffect(() => {
    try {
      ;(window.adsbygoogle = window.adsbygoogle || []).push({})
    } catch (e) {
      console.error("AdSense error:", e)
    }
  }, [])

  return (
    <div style={{ textAlign: "center", margin: "20px 0" }}>
      <ins
        className="adsbygoogle"
        style={{ display: "block" }}
        data-ad-client="ca-pub-XXXXXXXXXXXXXXXX"
        data-ad-slot={slot}
        data-ad-format={format}
        data-full-width-responsive={responsive}
      />
    </div>
  )
}

export default AdSense

포스팅 템플릿에서 사용할 때는 다음과 같이 합니다.

// 포스팅 본문 아래에 삽입
<AdSense slot="1234567890" />

쿠팡 파트너스 가입 및 광고 삽입

쿠팡 파트너스는 가입 후 바로 사용할 수 있어서 블로그 초기부터 적용하기 좋습니다. 방문자가 링크를 통해 24시간 내에 구매하면 수수료(보통 3~5%)를 받을 수 있습니다.

가입 절차

쿠팡 파트너스에 접속하여 가입합니다
미디어(블로그) 정보를 등록합니다
승인 후 광고 소재를 생성할 수 있습니다

다이나믹 배너 삽입 (iframe 방식)

쿠팡 파트너스에서 제공하는 다이나믹 배너를 Gatsby 컴포넌트로 만들어봅시다.

// src/components/CoupangAd.js
import React from "react"

const CoupangAd = ({ src, width = "100%", height = "100" }) => {
  return (
    <div style={{ margin: "20px 0", textAlign: "center" }}>
      <iframe
        src={src}
        width={width}
        height={height}
        frameBorder="0"
        scrolling="no"
        referrerPolicy="unsafe-url"
        title="쿠팡 파트너스"
        style={{ maxWidth: "100%" }}
      />
      <p style={{ fontSize: "11px", color: "#888", marginTop: "4px" }}>
        이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를
        제공받습니다.
      </p>
    </div>
  )
}

export default CoupangAd

쿠팡 파트너스 사이트에서 생성한 다이나믹 배너의 src 값을 복사해서 사용합니다.

텍스트 링크 방식

배너 대신 본문에 자연스럽게 상품 링크를 넣는 방법도 있습니다. 리뷰 글이나 추천 글에 적합합니다.

개발에 사용 중인 키보드가 궁금하시다면, [제가 사용하는 키보드](쿠팡_파트너스_링크)를 참고해보세요.

광고 위치 전략

위치	효과	주의사항
포스팅 상단 (제목 아래)	노출률 높음	사용자 이탈 위험
포스팅 중간	자연스러운 노출	내용 흐름을 깨지 않도록 배치
포스팅 하단 (본문 끝)	글을 다 읽은 독자에게 노출	가장 무난한 위치
사이드바	지속적 노출	모바일에서는 안 보일 수 있음

저는 포스팅 하단에 하나, 긴 글의 경우 중간에 하나 정도 배치하는 것을 추천합니다. 솔직히 광고를 너무 많이 넣으면 독자가 떠납니다.

댓글 시스템 비교

GitHub Pages는 서버가 없는 정적 사이트이기 때문에, 자체적으로 댓글 기능을 구현할 수 없습니다. 외부 서비스를 활용해야 합니다.

서비스	기반	로그인 방식	비용	장점	단점
Disqus	자체 플랫폼	소셜 로그인	무료 (광고 포함)	설정 간편	광고 삽입, 무거움
Utterances	GitHub Issues	GitHub 로그인	무료	가볍고 깔끔	GitHub 계정 필요
Giscus	GitHub Discussions	GitHub 로그인	무료	스레드 지원, 리액션	GitHub 계정 필요

개발 블로그라면 Utterances 또는 Giscus를 추천합니다. 독자 대부분이 개발자이고 GitHub 계정을 가지고 있을 테니까요. 이번 글에서는 설정이 간단한 Utterances를 기준으로 설명하겠습니다.

Utterances 설정하기

Utterances는 GitHub Issues를 댓글 저장소로 활용하는 오픈소스 위젯입니다. 누군가 댓글을 달면, 해당 포스팅에 대응하는 GitHub Issue가 자동으로 생성됩니다.

1단계: utterances 앱 설치

utterances 앱 페이지에 접속합니다
Install 버튼을 클릭합니다
블로그 레포지토리(예: javapark/javapark.github.io)를 선택합니다
Install 을 확인합니다

2단계: Utterances 컴포넌트 만들기

// src/components/Utterances.js
import React, { useEffect, useRef } from "react"

const Utterances = ({ repo, theme = "github-light" }) => {
  const containerRef = useRef(null)

  useEffect(() => {
    if (!containerRef.current) return

    const script = document.createElement("script")
    script.src = "https://utteranc.es/client.js"
    script.async = true
    script.setAttribute("repo", repo)
    script.setAttribute("issue-term", "pathname")
    script.setAttribute("theme", theme)
    script.setAttribute("crossorigin", "anonymous")

    // 기존 스크립트가 있으면 제거
    const existingScript = containerRef.current.querySelector("script")
    if (existingScript) {
      existingScript.remove()
    }

    containerRef.current.appendChild(script)
  }, [repo, theme])

  return <div ref={containerRef} />
}

export default Utterances

3단계: 포스팅 템플릿에 삽입

// src/templates/blog-post.js (또는 해당 템플릿 파일)
import Utterances from "../components/Utterances"

// 본문 아래에 추가
<Utterances
  repo="javapark/javapark.github.io"
  theme="github-light"
/>

Utterances 설정 옵션

옵션	값	설명
`repo`	`사용자명/레포명`	댓글이 저장될 레포지토리
`issue-term`	`pathname`	Issue 매핑 기준 (URL 경로 기준)
`issue-term`	`title`	Issue 매핑 기준 (포스팅 제목 기준)
`theme`	`github-light`	라이트 테마
`theme`	`github-dark`	다크 테마
`theme`	`preferred-color-scheme`	OS 설정에 따라 자동 전환

issue-term은 pathname을 추천합니다. URL이 바뀌지 않는 한 댓글이 유지되기 때문입니다.

다크모드 대응 댓글 시스템

gatsby-starter-hoodie 테마는 다크모드를 지원합니다. 블로그가 다크모드로 전환되면 댓글 위젯도 함께 변해야 자연스럽습니다.

테마 상태에 따라 Utterances 테마 변경

// src/components/Utterances.js (다크모드 대응 버전)
import React, { useEffect, useRef, useContext } from "react"
import { ThemeContext } from "../contexts/ThemeContext"

const Utterances = ({ repo }) => {
  const containerRef = useRef(null)
  const { isDarkMode } = useContext(ThemeContext)

  const theme = isDarkMode ? "github-dark" : "github-light"

  useEffect(() => {
    if (!containerRef.current) return

    // 기존 iframe 제거
    const existingIframe = containerRef.current.querySelector(
      ".utterances"
    )
    if (existingIframe) {
      existingIframe.remove()
    }

    const script = document.createElement("script")
    script.src = "https://utteranc.es/client.js"
    script.async = true
    script.setAttribute("repo", repo)
    script.setAttribute("issue-term", "pathname")
    script.setAttribute("theme", theme)
    script.setAttribute("crossorigin", "anonymous")

    containerRef.current.appendChild(script)
  }, [repo, theme])

  return <div ref={containerRef} />
}

export default Utterances

메시지 방식으로 테마 변경 (iframe 재생성 없이)

위 방법은 테마가 변경될 때마다 iframe을 다시 만들기 때문에 깜빡임이 발생합니다. postMessage를 활용하면 더 부드럽게 전환할 수 있습니다.

useEffect(() => {
  const iframe = document.querySelector(".utterances-frame")
  if (iframe) {
    iframe.contentWindow.postMessage(
      { type: "set-theme", theme },
      "https://utteranc.es"
    )
  }
}, [theme])

이 코드를 기존 컴포넌트의 useEffect와 별도로 추가하면, 다크모드 전환 시 댓글 위젯이 부드럽게 테마를 변경합니다.

광고 배치 팁 — 사용자 경험과 수익의 균형

솔직히 말하면, 광고는 많이 넣을수록 수익이 올라갈 것 같지만 현실은 반대인 경우가 많습니다.

광고 배치 원칙

본문 내용을 방해하지 않기 — 독자가 글을 읽다가 광고에 가로막히면 이탈합니다
한 페이지에 3개 이하 — AdSense 정책상 제한은 없지만, 3개를 넘기면 사용자 경험이 급격히 나빠집니다
모바일 대응 필수 — 모바일에서 화면을 가득 채우는 광고는 최악입니다
관련성 있는 광고 — 쿠팡 파트너스 링크는 포스팅 주제와 관련된 상품으로 설정합니다

시리즈 마무리 — GitHub 블로그 A to Z 정리

"GitHub 블로그 A to Z" 시리즈 6편을 통해 블로그의 생성부터 수익화까지 전 과정을 다뤘습니다. 지금까지의 여정을 정리해보겠습니다.

편	주제	핵심 내용
1편	시작하기	Gatsby + gatsby-starter-hoodie로 블로그 생성
2편	스킨 커스터마이징	테마 색상, 폰트, 레이아웃 변경
3편	마크다운과 카테고리	포스팅 작성법, 시리즈/태그 관리
4편	SEO 최적화	메타태그, sitemap, 구조화 데이터, Search Console
5편	자동 배포	GitHub Actions CI/CD 파이프라인
6편	광고와 댓글	AdSense, 쿠팡 파트너스, Utterances

블로그 운영을 시작하시는 분들께

블로그는 기술적 완성도보다 꾸준한 글쓰기가 훨씬 중요합니다. 완벽한 디자인과 모든 기능이 갖춰져야 시작할 수 있는 게 아닙니다. 글 하나라도 먼저 쓰고, 나머지는 천천히 개선해 나가시면 됩니다.

직접 조사하고 경험한 내용을 바탕으로 이 시리즈를 작성했는데, 여러분의 블로그 시작에 조금이라도 도움이 되었으면 좋겠습니다.

자주 묻는 질문 (FAQ)

Q. AdSense 승인이 거절되면 어떻게 하나요?

거절 사유를 메일로 받게 됩니다. 가장 흔한 거절 사유는 "콘텐츠 불충분"입니다. 양질의 포스팅을 5~10개 더 작성한 뒤 재신청하면 됩니다. 재신청 횟수에는 제한이 없으니, 콘텐츠를 보강하면서 꾸준히 신청해보세요. 커스텀 도메인을 사용하는 것도 승인률을 높이는 데 도움이 됩니다.

Q. Utterances 대신 Giscus를 사용하는 것이 더 좋나요?

둘 다 좋은 선택입니다. Giscus는 GitHub Discussions 기반이라 댓글에 대한 답글(스레드)과 리액션을 지원하는 장점이 있습니다. 설정 방법도 Utterances와 거의 동일합니다. 만약 댓글 간 대화가 활발할 것 같다면 Giscus를, 단순 댓글이면 Utterances를 추천합니다.

Q. 쿠팡 파트너스 수익은 어느 정도 나오나요?

솔직히 일일 방문자가 100명 이하일 때는 월 수익이 커피 한 잔 값도 안 됩니다. 블로그 트래픽이 핵심이기 때문에, SEO 최적화(4편 참고)와 꾸준한 포스팅으로 방문자를 먼저 늘리는 데 집중하시는 게 좋습니다. 트래픽이 올라오면 자연스럽게 수익도 따라옵니다.

여러분은 블로그 수익화를 어떻게 하고 계신가요? 또는 어떤 댓글 시스템을 사용하고 계신가요? 댓글로 알려주세요.

"GitHub 블로그 A to Z" 시리즈를 끝까지 읽어주셔서 감사합니다. 앞으로도 블로그 운영에 도움이 되는 글을 꾸준히 올리겠습니다.

윈도우 단축키 완전 정복 — 매일 쓰는 핵심 단축키만 모았습니다

Sat, 04 Apr 2026 00:00:00 GMT

안녕하세요, 자바파커입니다.

마우스 없이도 컴퓨터를 자유자재로 다룰 수 있다면 어떨까요?

솔직히 말하면, 윈도우 단축키는 수백 개가 넘습니다. 하지만 실제로 매일 쓰는 건 20~30개 정도면 충분합니다. 오늘은 "진짜 쓰는 것만" 카테고리별로 정리해봤습니다. 결론부터 말씀드리면 — 이 글에 나온 단축키만 1주일 연습하면, 작업 속도가 눈에 띄게 빨라집니다.

윈도우 기본 단축키 — 이것만은 반드시

가장 기본이면서도 가장 자주 쓰는 단축키입니다. 이미 아시는 것도 있겠지만, 한 번 더 정리해두면 좋습니다.

단축키	기능	활용 팁
`Ctrl + C`	복사	—
`Ctrl + X`	잘라내기	—
`Ctrl + V`	붙여넣기	—
`Ctrl + Z`	실행 취소	실수했을 때 생명줄
`Ctrl + Y`	다시 실행	취소한 걸 되돌릴 때
`Ctrl + A`	전체 선택	—
`Ctrl + S`	저장	수시로 누르는 습관 필수
`Ctrl + F`	찾기	문서, 브라우저, 탐색기 모두 동작
`Ctrl + P`	인쇄	PDF 저장에도 활용 가능
`F2`	이름 바꾸기	파일/폴더 선택 후 바로 사용
`Delete`	삭제	휴지통으로 이동
`Shift + Delete`	영구 삭제	휴지통 거치지 않음 (주의!)

윈도우 키 조합 단축키 — 생산성의 핵심

윈도우 키(⊞)를 활용한 단축키는 시스템 수준의 기능을 빠르게 실행할 수 있어서, 알아두면 가장 체감이 큽니다.

시스템 & 앱 실행

단축키	기능	한 줄 설명
`Win + E`	파일 탐색기 열기	가장 자주 쓰는 단축키 중 하나
`Win + I`	설정 열기	제어판 찾을 필요 없음
`Win + L`	화면 잠금	자리 비울 때 보안 필수
`Win + R`	실행 창 열기	`cmd`, `calc` 등 빠른 실행
`Win + S` (또는 `Win + Q`)	검색	앱, 파일, 설정 통합 검색
`Win + X`	빠른 링크 메뉴	장치 관리자, 터미널 등 고급 메뉴
`Win + .` (마침표)	이모지 패널	이모지, 특수문자, 가오모지 입력
`Win + 숫자(1~9)`	작업표시줄 앱 실행	1번째~9번째 고정 앱 바로 실행

창(Window) 관리 단축키

멀티태스킹의 핵심입니다. 이 단축키들을 익히면 마우스로 창을 드래그할 일이 거의 없어집니다.

단축키	기능
`Win + ←` / `Win + →`	창을 화면 왼쪽/오른쪽 반으로 스냅
`Win + ↑`	창 최대화
`Win + ↓`	창 최소화 (최대화 상태면 원래 크기로)
`Win + Z`	스냅 레이아웃 선택 (Windows 11)
`Win + D`	바탕화면 보기/복귀
`Win + M`	모든 창 최소화
`Win + Home`	현재 창 제외 모두 최소화 (설정에서 제목 표시줄 흔들기 활성화 필요)
`Alt + Tab`	열린 창 간 전환
`Alt + F4`	현재 창/프로그램 닫기
`Win + Tab`	작업 보기 (가상 데스크톱 포함)

가상 데스크톱 단축키 — 모니터 하나로도 충분합니다

윈도우 11의 가상 데스크톱 기능은 모니터가 하나뿐인 환경에서 특히 유용합니다. 업무용 데스크톱, 개인용 데스크톱을 분리해서 사용해보세요.

단축키	기능
`Win + Ctrl + D`	새 가상 데스크톱 만들기
`Win + Ctrl + ←` / `→`	데스크톱 간 전환
`Win + Ctrl + F4`	현재 가상 데스크톱 닫기
`Win + Tab`	전체 데스크톱 & 창 보기

저는 데스크톱 1번에 업무(슬랙, 이메일), 2번에 개발(VS Code, 터미널), 3번에 참고자료(브라우저)를 배치합니다. Win + Ctrl + ←/→로 순식간에 전환하니까, 듀얼 모니터 부럽지 않습니다.

스크린샷 & 클립보드 단축키 — 자료 정리의 필수 기능

단축키	기능	설명
`Win + Shift + S`	화면 캡처 (영역 선택)	가장 많이 쓰는 스크린샷 방법
`PrtScn`	전체 화면 캡처	클립보드에 복사
`Win + PrtScn`	전체 화면 캡처 후 자동 저장	`사진/스크린샷` 폴더에 저장
`Win + V`	클립보드 히스토리	이전에 복사한 내용 목록에서 선택

Win + V는 처음 사용 시 활성화가 필요합니다. 한 번 켜두면 복사 이력이 쌓이기 때문에, "아까 복사한 거 어디 갔지?" 하는 상황이 사라집니다.

브라우저 단축키 — 크롬, 엣지 공통

웹 브라우저에서의 단축키도 업무 속도에 큰 영향을 줍니다. 크롬과 엣지 모두 동일하게 작동합니다.

단축키	기능
`Ctrl + T`	새 탭 열기
`Ctrl + W`	현재 탭 닫기
`Ctrl + Shift + T`	닫은 탭 다시 열기 (최대 10개)
`Ctrl + Tab`	다음 탭으로 이동
`Ctrl + Shift + Tab`	이전 탭으로 이동
`Ctrl + L`	주소창 포커스
`Ctrl + 숫자(1~8)`	해당 번째 탭으로 이동
`Ctrl + 9`	마지막 탭으로 이동
`F5` / `Ctrl + R`	새로고침
`Ctrl + Shift + Delete`	인터넷 사용 기록 삭제

특히 Ctrl + Shift + T는 실수로 탭을 닫았을 때 정말 유용합니다. 직접 써보면 "이걸 왜 이제 알았지?" 하게 됩니다.

파일 탐색기 단축키 — 파일 관리가 빨라집니다

단축키	기능
`Ctrl + N`	새 탐색기 창 열기
`Ctrl + Shift + N`	새 폴더 만들기
`Alt + ←` / `→`	뒤로/앞으로 이동
`Alt + ↑`	상위 폴더로 이동
`Alt + D` 또는 `Ctrl + L`	경로 표시줄 포커스
`Alt + Enter`	선택한 항목의 속성 보기
`F2`	이름 바꾸기
`F5`	새로고침

팁: 파일 탐색기 상단의 커맨드 바는 선택한 파일 유형에 따라 관련 작업(복사, 이동, 압축 해제 등) 아이콘이 자동으로 바뀝니다. Alt 키를 누르면 키보드로 각 메뉴에 접근할 수 있습니다.

개발자를 위한 윈도우 단축키 추가 팁

개발자라면 아래 단축키도 함께 익혀두면 좋습니다.

단축키	기능
Win + ` (백틱)	Windows 터미널 Quake 모드 (터미널 앱 설치 필요)
`Ctrl + Shift + Esc`	작업 관리자 바로 열기
`Win + Pause`	시스템 정보 (설정 > 정보 페이지로 이동)
`Win + G`	Xbox Game Bar (화면 녹화)
`Ctrl + Shift + V`	서식 없이 붙여넣기 (브라우저, VS Code 등 지원 앱에서만 동작)

Win + `은 Windows 터미널의 Quake 모드로, 화면 상단에 터미널이 슬라이드로 나타납니다. Windows 터미널이 설치되어 있어야 동작합니다. Ctrl + Shift + V는 OS 기본 단축키가 아니라 앱별 지원 기능이지만, 크롬·엣지·VS Code 등 개발자가 주로 쓰는 앱에서는 대부분 동작합니다.

윈도우 단축키 빠르게 익히는 3단계 방법

단축키를 한꺼번에 외우려고 하면 오히려 역효과입니다. 아래 방법을 추천합니다.

1단계: 5개만 먼저 (1주차)

Win + E (탐색기), Win + L (잠금), Win + D (바탕화면)
Win + Shift + S (캡처), Win + V (클립보드)

2단계: 창 관리 추가 (2주차)

Win + ←/→ (스냅), Alt + Tab (창 전환)
Win + Tab (작업 보기), Win + Ctrl + D (가상 데스크톱)

3단계: 브라우저 & 탐색기 (3주차)

Ctrl + W/T/Shift+T (탭 관리)
Ctrl + Shift + N (새 폴더), Alt + ← (뒤로)

핵심은 한 번에 많이 외우는 것이 아니라, 매일 쓰는 동작부터 바꾸는 것입니다.

윈도우 단축키 한 장 요약표

가장 활용도 높은 단축키만 한 장으로 정리했습니다. 모니터 옆에 붙여두고 쓰세요.

카테고리	단축키	기능
필수	`Ctrl + C/X/V/Z`	복사/잘라내기/붙여넣기/취소
시스템	`Win + E`	파일 탐색기
시스템	`Win + I`	설정
시스템	`Win + L`	화면 잠금
창 관리	`Win + ←/→`	화면 분할
창 관리	`Alt + Tab`	창 전환
창 관리	`Win + D`	바탕화면
캡처	`Win + Shift + S`	영역 캡처
클립보드	`Win + V`	클립보드 히스토리
가상 데스크톱	`Win + Ctrl + D`	새 데스크톱
가상 데스크톱	`Win + Ctrl + ←/→`	데스크톱 전환
브라우저	`Ctrl + T/W`	새 탭/탭 닫기
브라우저	`Ctrl + Shift + T`	닫은 탭 복구

자주 묻는 질문 (FAQ)

Q. 윈도우 단축키가 안 먹힐 때는 어떻게 하나요?

일부 단축키는 특정 앱이 포커스를 가로채면 동작하지 않을 수 있습니다. Win + D로 바탕화면으로 나간 뒤 다시 시도하거나, 게임 모드가 활성화되어 있다면 Win + G에서 게임 모드를 꺼보세요. 키보드 드라이버 문제일 수도 있으니, 설정 > 접근성 > 키보드에서 고정 키, 필터 키가 꺼져 있는지 확인하세요.

Q. 윈도우 10과 11의 단축키 차이가 있나요?

대부분의 단축키는 동일합니다. 윈도우 11에서 새로 추가된 주요 단축키는 Win + Z(스냅 레이아웃), Win + C(Copilot 실행), Win + W(위젯) 등이 있습니다.

Q. 자주 쓰는 프로그램에 나만의 단축키를 지정할 수 있나요?

네, 가능합니다. 프로그램의 바로가기 아이콘을 우클릭 → 속성 → "바로 가기 키" 항목에 원하는 키 조합을 입력하면 됩니다. Ctrl + Alt + 원하는 키 형태로 지정할 수 있습니다.

오늘 소개한 단축키 중 하나만이라도 오늘부터 써보세요. 1주일이면 손에 붙고, 한 달이면 마우스 없이도 대부분의 작업이 가능해집니다.

더 자세한 전체 단축키 목록은 Microsoft 공식 키보드 단축키 문서에서 확인할 수 있습니다.

여러분이 가장 자주 쓰는 윈도우 단축키는 뭔가요? 댓글로 알려주세요!

파이썬 프로젝트 관리의 혁신: pipenv 사용가이드

Sun, 28 Jan 2024 00:00:00 GMT

파이썬 프로젝트 관리의 혁신: `pipenv` 사용 가이드

서론: 파이썬과 패키지 관리의 중요성

파이썬은 그 유연성과 강력한 라이브러리 덕분에 전 세계적으로 사랑받는 프로그래밍 언어입니다. 하지만, 프로젝트가 커지면서 다양한 패키지를 효율적으로 관리하는 것이 중요해집니다. 여기서 pipenv의 역할이 빛을 발합니다!

`pipenv`란 무엇인가?

pipenv는 파이썬의 공식 권장 패키지 관리 도구로, 패키지 의존성 관리와 가상 환경 설정을 하나의 도구로 통합합니다. 이를 통해 프로젝트별 종속성 관리가 더욱 쉬워집니다.

`pipenv`의 설치 및 기본 사용법

설치:
```
pip install pipenv
```
이 명령어로 pipenv를 설치할 수 있습니다.
프로젝트 시작:
```
mkdir myproject
cd myproject
pipenv shell
```
이렇게 하면 myproject 폴더 안에 새로운 가상 환경이 생성됩니다.
패키지 설치:
```
pipenv install requests
```
필요한 패키지를 설치하고, 이는 자동으로 Pipfile에 기록됩니다.

고급 사용법과 팁

개발 의존성: 개발 중에만 필요한 패키지는 pipenv install --dev [패키지명]을 통해 관리합니다.
스크립트 실행: pipenv run python script.py 명령어로 스크립트를 실행할 수 있습니다.

실습 예제: 웹 스크래핑

간단한 웹 스크래핑 프로젝트를 예로 들어보겠습니다. requests와 beautifulsoup4를 설치하고, 간단한 스크래핑 스크립트를 실행해봅니다.

pipenv install requests beautifulsoup4
pipenv run python scraper.py

아래는 간단한 웹 스크래핑을 위한 scraper.py의 예시 코드입니다. 이 예제에서는 requests와 beautifulsoup4를 사용하여 웹 페이지의 HTML을 가져오고, 특정 요소를 파싱합니다.

scraper.py 예시 코드

import requests
from bs4 import BeautifulSoup

def scrape_website(url):
    # URL에서 HTML을 가져옵니다.
    response = requests.get(url)
    # 요청이 성공했는지 확인합니다.
    if response.status_code != 200:
        print("Failed to retrieve the webpage")
        return
    
    # HTML 내용을 파싱합니다.
    soup = BeautifulSoup(response.text, 'html.parser')
    
    # 원하는 데이터를 추출합니다. (예: 모든 h1 태그)
    headers = soup.find_all('h1')
    for header in headers:
        print(header.text)

# 스크래핑할 웹사이트 URL
url = "http://example.com"
scrape_website(url)

이 코드는 기본적인 웹 스크래핑 구조를 보여줍니다. scrape_website 함수는 주어진 URL에서 HTML을 가져와 BeautifulSoup으로 파싱합니다. 이 예제에서는 모든 <h1> 태그의 텍스트를 찾아 출력합니다. 실제 사용 시에는 원하는 웹사이트 URL과 추출하고자 하는 데이터에 맞게 코드를 수정해야 합니다.

주의: 웹 스크래핑을 할 때는 해당 웹사이트의 이용 약관을 준수하고, 과도한 요청으로 서버에 부하를 주지 않도록 주의해야 합니다.

결론

pipenv는 파이썬 프로젝트의 패키지 관리와 가상 환경 관리를 간소화해줍니다. 이를 통해 개발자는 프로젝트의 의존성을 보다 쉽게 관리할 수 있습니다.

Ruff를 이용한 python 코드 품질 관리

Sun, 28 Jan 2024 00:00:00 GMT

Ruff 소개

최근 Python 개발자들 사이에서 Ruff가 많은 주목을 받고 있습니다. Ruff는 Python 코드의 품질을 향상시키는 데 도움이 되는 강력한 린트 도구입니다. 린트는 코딩 스타일, 프로그래밍 오류, 버그, 복잡한 구조 등을 분석하여 개선 방향을 제시하는 소프트웨어 도구입니다. Ruff는 빠른 성능과 사용 편의성으로 인해 많은 Python 개발자들에게 선택받고 있습니다.

Ruff의 장점

빠른 성능: Ruff는 다른 린트 도구보다 빠른 분석 속도를 제공합니다. 이는 대규모 프로젝트에서도 효율적으로 사용할 수 있음을 의미합니다.
사용 용이성: 설치 및 구성이 간단하며, 쉽게 사용할 수 있는 명령어 인터페이스를 제공합니다.
자동화: Ruff는 코드 작성 과정에서 자동으로 문제를 탐지하고 수정 제안을 합니다.

Ruff 설치 및 사용

설치 방법

Ruff는 Python의 패키지 관리자인 pip를 통해 쉽게 설치할 수 있습니다.

pip install ruff

사용 방법

Ruff를 사용하여 프로젝트의 코드를 분석하는 것은 매우 간단합니다. 터미널에서 다음 명령을 실행하기만 하면 됩니다.

ruff path/to/your/code

VS Code에서의 Python 코딩

Visual Studio Code (VS Code)는 다양한 프로그래밍 언어를 지원하는 인기 있는 코드 편집기입니다. Python 개발에도 매우 적합하며, Ruff와 같은 도구를 통합하여 사용할 수 있습니다.

VS Code 설정

Python 확장 설치: VS Code의 마켓플레이스에서 Python 확장을 설치합니다. 이 확장은 Python 개발에 필요한 다양한 기능을 제공합니다.
Ruff 통합: Ruff는 VS Code의 설정을 통해 Python 개발 환경에 쉽게 통합될 수 있습니다. 이를 통해 코드를 작성하는 동안 실시간으로 피드백을 받을 수 있습니다.

Python 코딩 예제

다음은 VS Code에서 Python 코드를 작성하고 Ruff를 사용하여 코드 품질을 관리하는 간단한 예제입니다.

# 예제 코드
def example_function():
    x = 1
    y = 2
    print(x + y)

example_function()

이 코드를 VS Code에서 작성하고 Ruff를 실행하면, Ruff는 코드 스타일과 구조상의 문제를 지적해 줄 것입니다. 예를 들어, 함수 내의 변수와 연산자 사이의 공백, 함수 정의와 호출 사이의 공백 등을 조정할 수 있습니다.

이러한 방식으로 Ruff와 VS Code를 활용하면 Python 개발 과정에서 코드 품질을 지속적으로 관리하고 개선할 수 있습니다. 더 나은 코드 품질로 안정적이고 효율적인 Python 애플리케이션 개발을 지향하는 개발자들에게 이러한 도구는 매우 유용합니다.

pyenv 를 이용한 파이썬 버전관리

Sun, 28 Jan 2024 00:00:00 GMT

Python 버전 관리의 중요성

Python은 지속적으로 발전하고 있는 프로그래밍 언어입니다. 다양한 버전의 Python이 공존하며, 각 프로젝트나 라이브러리는 특정 Python 버전에 최적화되어 있습니다. 이 때문에 동일한 시스템에서 여러 버전의 Python을 효율적으로 관리하는 것이 중요합니다. Python 버전 관리는 호환성 문제를 해결하고, 프로젝트의 요구사항을 정확히 충족시키는 데 도움을 줍니다.

pyenv 소개

pyenv는 Python 버전을 관리하는 탁월한 도구입니다. 여러 버전의 Python을 설치하고, 각각의 프로젝트에 적합한 버전으로 쉽게 전환할 수 있게 해줍니다. pyenv는 사용자의 시스템에 여러 Python 버전을 설치하고, 필요에 따라 전환하는 것을 간단한 명령어로 가능하게 합니다.

pyenv 설치 및 설정

설치

macOS: Homebrew를 사용하여 brew install pyenv 명령어로 설치할 수 있습니다.
Linux: Git을 통해 클론하거나 패키지 매니저를 사용하여 설치합니다.
Windows: pyenv-win을 사용하여 설치합니다.

기본 설정

설치 후, pyenv를 시스템 경로에 추가해야 합니다.
쉘 설정 파일(.bashrc, .zshrc 등)에 초기화 스크립트를 추가합니다.

pyenv를 사용한 Python 버전 관리

버전 설치: pyenv install 3.8.1과 같은 명령어로 특정 Python 버전을 설치합니다.
버전 전환: pyenv global 3.8.1 명령어로 전역 Python 버전을 설정합니다.
버전 확인: python --version을 사용하여 현재 사용 중인 Python 버전을 확인합니다.

실제 사용 사례

예를 들어, 프로젝트 A는 Python 3.7을, 프로젝트 B는 Python 3.9를 사용한다고 가정해 봅시다. pyenv를 사용하면 각 프로젝트 디렉토리에서 다른 버전의 Python을 설정할 수 있습니다. 이를 통해 각 프로젝트의 요구사항을 정확히 충족시키면서도 개발 환경을 깔끔하게 유지할 수 있습니다.

pyenv와 가상 환경

pyenv-virtualenv는 pyenv와 함께 사용하여 각 Python 버전에 대한 독립적인 가상 환경을 생성할 수 있습니다. 이는 라이브러리 의존성 관리를 간편하게 만들어 줍니다.

고급 팁과 트러블슈팅

팁: pyenv 명령어 자동완성 기능을 설정하여 사용성을 높일 수 있습니다.
문제 해결: 설치 중 발생하는 문제들은 주로 환경 변수 설정이나 의존성 문제에서 비롯됩니다. 문제 발생 시 공식 문서나 커뮤니티를 참조하세요.

결론

pyenv를 사용하면 Python 개발 환경을 효율적으로 관리할 수 있습니다. 이를 통해 개발자는 다양한 프로젝트에 유연하게 대응할 수 있으며, Python 개발의 생산성과 효율성을 크게 향상시킬 수 있습니다.

개발자들에게 형상관리는 선택이 아닌 필수

Wed, 22 Nov 2023 00:00:00 GMT

안녕하세요, 자바파커입니다.

"혼자 개발하는데 Git이 필요한가요?"

결론부터 말씀드리면 — 혼자 개발할 때야말로 Git이 더 필요합니다. 코드를 잘못 수정해서 되돌리고 싶을 때, 어제 작업한 내용이 뭔지 확인하고 싶을 때, 로컬 컴퓨터가 고장났을 때 — Git 없이는 모든 게 수작업입니다.

이 글에서는 형상관리가 왜 필수인지, Git의 핵심 개념부터 실전 워크플로우까지 정리합니다.

형상관리란 무엇인가

형상관리(SCM, Source Code Management)는 소스 코드의 변경 이력을 체계적으로 관리하는 것입니다. 단순히 백업하는 게 아니라, 누가, 언제, 왜, 무엇을 변경했는지를 기록합니다.

형상관리 없이 개발하면 생기는 일

프로젝트_최종.zip, 프로젝트_최종_진짜최종.zip, 프로젝트_최종_v3_수정.zip
"어제 고친 코드가 뭐였지?" — 기억에 의존
"이 버그, 언제부터 있었지?" — 추적 불가
컴퓨터 포맷하면 모든 히스토리 소실

형상관리 도구 비교

도구	방식	특징	현재 상태
Git	분산형	로컬 저장소, 브랜치 강력, 업계 표준	압도적 1위
Subversion (SVN)	중앙집중형	단순한 구조, 레거시 프로젝트	유지보수 모드
Mercurial	분산형	Git과 유사, 더 단순	거의 사용 안 함

2026년 현재 Git이 사실상 유일한 선택지입니다. GitHub, GitLab, Bitbucket 모두 Git 기반입니다.

Git 핵심 개념 — 이것만 알면 시작할 수 있다

저장소 (Repository)

프로젝트의 모든 파일과 변경 이력이 저장되는 공간입니다.

# 새 저장소 생성
git init

# 기존 저장소 복제
git clone https://github.com/username/repo.git

스테이징과 커밋

Git의 작업 흐름은 3단계입니다:

작업 디렉토리 → 스테이징 영역 → 저장소
 (수정)        (git add)      (git commit)

# 변경된 파일 확인
git status

# 파일을 스테이징에 추가
git add src/main.js

# 커밋 (변경 이력 저장)
git commit -m "로그인 기능 추가"

# 변경 이력 확인
git log --oneline

브랜치 (Branch)

브랜치는 독립적인 작업 공간입니다. 메인 코드에 영향 주지 않고 새 기능을 개발할 수 있습니다.

# 브랜치 생성 및 이동
git checkout -b feature/login

# 작업 완료 후 메인에 병합
git checkout main
git merge feature/login

# 브랜치 삭제
git branch -d feature/login

원격 저장소 (Remote)

GitHub, GitLab 같은 원격 서버에 코드를 저장합니다.

# 원격 저장소에 푸시
git push origin main

# 원격 저장소에서 가져오기
git pull origin main

커밋 메시지 컨벤션 — 잘 쓰는 것이 중요하다

나쁜 커밋 메시지:

수정
fix
ㅋㅋ
asdf

좋은 커밋 메시지:

feat: 소셜 로그인 기능 추가
fix: 비밀번호 유효성 검사 오류 수정
docs: README에 설치 가이드 추가
refactor: 인증 미들웨어 구조 개선

Conventional Commits 규칙

접두사	용도	예시
`feat`	새 기능	feat: 검색 필터 추가
`fix`	버그 수정	fix: 날짜 포맷 오류 수정
`docs`	문서 변경	docs: API 문서 업데이트
`style`	코드 스타일 (동작 변경 없음)	style: 들여쓰기 정리
`refactor`	리팩토링	refactor: 유저 서비스 분리
`test`	테스트 추가/수정	test: 로그인 단위 테스트 추가
`chore`	빌드, 설정 변경	chore: eslint 설정 업데이트

이 규칙을 따르면 git log만 봐도 프로젝트 히스토리를 한눈에 파악할 수 있습니다.

브랜치 전략 — 팀 규모에 맞게

혼자 개발할 때 (1인)

main ──●──●──●──●──●

main 브랜치 하나로 충분합니다. 커밋을 자주 하고, 의미 있는 단위로 나누세요.

소규모 팀 (2~5명)

main    ──●────────●────────●──
             \      /  \      /
feature/a  ──●──●──    ──●──●──

GitHub Flow — main + feature 브랜치만 사용합니다.

main에서 feature/기능명 브랜치 생성
작업 후 Pull Request 생성
코드 리뷰 후 main에 병합

중규모 이상 팀

main    ──●──────────────●──
           \            /
develop  ──●──●──●──●──●──
              \  /
feature   ──●──●

Git Flow — main, develop, feature, release, hotfix 브랜치를 사용합니다. 릴리즈 주기가 있는 프로젝트에 적합합니다.

실전 Git 워크플로우 — 매일 하는 루틴

아침에 시작할 때

# 최신 코드 받기
git pull origin main

# 작업 브랜치 생성
git checkout -b feature/user-profile

작업 중

# 자주 커밋하기 (의미 있는 단위로)
git add src/components/Profile.jsx
git commit -m "feat: 프로필 페이지 UI 구현"

git add src/services/user.js
git commit -m "feat: 프로필 데이터 조회 API 연동"

작업 완료 후

# 원격에 푸시
git push origin feature/user-profile

# GitHub에서 Pull Request 생성
# 리뷰 후 병합

자주 쓰는 Git 명령어 정리

명령어	설명
`git status`	현재 상태 확인
`git diff`	변경 내용 비교
`git log --oneline`	커밋 히스토리 (한 줄)
`git stash`	작업 임시 저장
`git stash pop`	임시 저장 복원
`git reset HEAD~1`	마지막 커밋 취소 (변경 유지)
`git checkout -- 파일명`	파일 변경 취소
`git blame 파일명`	각 줄의 마지막 수정자 확인
`git rebase -i HEAD~3`	최근 3개 커밋 정리

AI 시대의 형상관리

2026년 현재, AI 코딩 도구(Claude Code, Cursor, GitHub Copilot)가 코드를 대량으로 생성합니다. 이럴 때 형상관리가 더 중요해집니다.

AI와 Git을 함께 쓰는 팁

AI가 생성한 코드도 의미 있는 단위로 커밋하세요. "AI가 만든 코드"라고 한 덩어리로 커밋하면 나중에 추적이 어렵습니다.
AI 작업 전에 브랜치를 만드세요. AI가 예상과 다른 결과를 만들면 브랜치를 버리면 됩니다.
커밋 메시지에 AI 사용 여부를 남기세요. Co-Authored-By 태그를 활용하면 됩니다.

git commit -m "feat: 대시보드 차트 구현

Co-Authored-By: Claude <noreply@anthropic.com>"

.gitignore — 불필요한 파일 제외하기

프로젝트에 포함하면 안 되는 파일들을 .gitignore에 등록합니다.

# 의존성
node_modules/
__pycache__/

# 환경변수 (비밀키!)
.env
.env.local

# 빌드 결과물
dist/
build/
.cache/

# OS 파일
.DS_Store
Thumbs.db

# IDE 설정
.vscode/
.idea/

특히 .env 파일은 절대 커밋하면 안 됩니다. API 키, 비밀번호 등이 GitHub에 공개되면 보안 사고로 이어집니다.

자주 묻는 질문 (FAQ)

Q1. 혼자 개발하는데 Git이 정말 필요한가요?

네. 혼자일 때야말로 "3시간 전 코드로 돌아가고 싶다"는 상황이 자주 옵니다. Git 없이는 Ctrl+Z를 수십 번 누르거나, 백업 폴더를 뒤져야 합니다. git log와 git checkout이면 몇 초 만에 해결됩니다.

Q2. Git과 GitHub는 다른 건가요?

Git은 로컬에서 동작하는 버전 관리 도구이고, GitHub는 Git 저장소를 호스팅하는 웹 서비스입니다. Git은 도구, GitHub는 플랫폼입니다. GitLab, Bitbucket도 같은 역할을 합니다.

Q3. 커밋은 얼마나 자주 해야 하나요?

"의미 있는 변경 단위"마다 커밋하세요. 하루에 한 번 큰 커밋보다, 기능 단위로 작은 커밋 여러 개가 훨씬 낫습니다. "로그인 폼 UI 구현", "로그인 API 연동", "로그인 에러 처리" — 이렇게 나누면 나중에 문제가 생겨도 특정 커밋만 되돌릴 수 있습니다.

SheetJS

Thu, 09 Nov 2023 00:00:00 GMT

SheetJS는 다양한 형식의 스프레드시트 파일, 예를 들면 Excel (XLSX 및 XLS), CSV 및 기타 스프레드시트 형식을 읽고 쓸 수 있는 JavaScript 라이브러리입니다. 이 라이브러리를 사용하면 웹 애플리케이션에서 스프레드시트 데이터를 처리할 수 있는 강력한 API를 제공합니다.

SheetJS를 사용하면 서버 측 처리 없이도 브라우저에서 스프레드시트 데이터를 직접 조작할 수 있습니다. 이 라이브러리는 주로 웹 애플리케이션에서 Excel 파일 업로드, 데이터 내보내기 및 기타 스프레드시트 관련 작업을 처리하는 데 사용됩니다.

SheetJS를 사용하려면 스크립트 태그를 사용하거나 npm 또는 yarn과 같은 패키지 관리자를 사용하여 라이브러리를 프로젝트에 포함시킬 수 있습니다. 다음은 JavaScript에서 Excel 파일을 읽는 예제입니다:

먼저 SheetJS 라이브러리를 HTML 파일에 포함시킵니다:

<script src="https://cdnjs.cloudflare.com/ajax/libs/xlsx/0.18.0/xlsx.full.min.js"></script>

파일 업로드를 처리할 HTML 입력 요소를 만듭니다:

<input type="file" id="file-input" />
<div id="output"></div>

파일 업로드를 처리하고 Excel 데이터를 읽는 JavaScript 코드를 추가합니다:

document.getElementById('file-input').addEventListener('change', handleFile, false);
function handleFile(event) {
  const file = event.target.files[0];
  const reader = new FileReader();

  reader.onload = function (e) {
    const data = e.target.result;
    const workbook = XLSX.read(data, { type: 'binary' });

    // 첫 번째 시트를 읽고자 한다고 가정합니다
    const sheetName = workbook.SheetNames[0];
    const sheet = workbook.Sheets[sheetName];

    // 시트 데이터를 객체 배열로 파싱합니다
    const jsonData = XLSX.utils.sheet_to_json(sheet);

    // 파싱된 데이터를 사용합니다
    displayData(jsonData);
  };

  reader.readAsBinaryString(file);
}

function displayData(data) {
  const outputDiv = document.getElementById('output');
  outputDiv.innerHTML = JSON.stringify(data, null, 2);
}

이 예제에서는 사용자가 파일을 선택하면 Excel 데이터를 읽고 파싱하여 화면에 표시하는 기본적인 동작을 구현한 것입니다.

🎇 Next.js 미들웨어 설정하기

Thu, 14 Sep 2023 00:00:00 GMT

next.js에서 미들웨어 사용하기

Next.js에서 미들웨어를 사용하려면 next.config.js 파일을 생성하고 next.config.js 파일에서 middleware를 설정해야 합니다. 미들웨어는 페이지의 요청을 처리하기 전에 실행되는 함수로, 요청을 가로채고 수정할 수 있는 기능을 제공합니다.

다음은 Next.js에서 미들웨어를 사용하는 방법입니다:

next.config.js 파일 생성: 프로젝트 루트 디렉토리에 next.config.js 파일을 생성합니다.
미들웨어 함수 작성: 미들웨어 함수를 작성합니다. 미들웨어 함수는 요청(request), 응답(response), 그리고 next() 함수를 인자로 받습니다. 예를 들어, 간단한 로깅 미들웨어를 작성해보겠습니다.

// middleware/logger.js

export default function logger(req, res, next) {
  console.log(`Request received for: ${req.url}`);
  next(); // 다음 미들웨어나 핸들러로 요청을 전달
}

next.config.js에서 미들웨어 설정: `next.config.js`` 파일에서 미들웨어를 설정합니다. 미들웨어를 적용할 페이지나 API 경로를 지정할 수 있습니다.

// next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: '/api-handler/:path*',
      },
    ];
  },
  async redirects() {
    return [
      {
        source: '/old-route',
        destination: '/new-route',
        permanent: true,
      },
    ];
  },
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: securityHeaders,
      },
    ];
  },
  async middleware() {
    return [
      '~/middleware/logger.js', // 미들웨어 파일의 상대 경로나 모듈 경로를 지정
    ];
  },
};

위 예제에서는 logger.js 미들웨어를 설정에 추가하였습니다. 또한, rewrites, redirects, headers 섹션을 사용하여 리라이트, 리다이렉트, 헤더를 조작하는 미들웨어를 설정할 수도 있습니다.

이제 Next.js 애플리케이션에서 미들웨어를 사용할 수 있습니다. 만약 특정 페이지나 API 경로에만 미들웨어를 적용하고 싶다면, next.config.js에서 해당 경로에 대한 미들웨어를 설정할 수 있습니다.

🎇 Next.js 미들웨어 설정하기 - 로그

Fri, 10 Mar 2023 00:00:00 GMT

개요

SSR 에서 서버에서 공통 로그를 남기려고 하는데 어떻게 시작해야 하는지 Chat GPT 에게 물어보았다.

1. Next.js 를 이용한 React Application 샘플

다음은 Next.js를 사용하여 React 애플리케이션을 만드는 간단한 예제입니다.

먼저, Next.js를 설치해야합니다. **npm**을 사용하여 설치할 수 있습니다.

npm install next react react-dom

그리고 이제 다음과 같이 pages 폴더를 만들고 index.js 파일을 생성합니다.

// pages/index.js

function Home() {
  return <div>Welcome to Next.js!</div>;
}

export default Home;

그리고 마지막으로 다음과 같이 package.json 파일에 다음을 추가하여 애플리케이션을 실행합니다.

{
  "scripts": {
    "dev": "next dev"
  }
}

이제 터미널에서 npm run dev 명령을 실행하고 브라우저에서 **http://localhost:3000**으로 이동하면 "Welcome to Next.js!"라는 텍스트가 표시되는 것을 볼 수 있습니다.

이것은 Next.js를 사용하여 생성된 매우 간단한 React 애플리케이션입니다. 이제 Next.js를 더 깊이 이해하고 컴포넌트, 라우팅, 데이터 가져오기 등을 추가하여 애플리케이션을 더 발전시킬 수 있습니다.

2. 라우팅 추가

다음은 Next.js에서 라우팅을 추가하는 방법입니다.

pages 폴더 안에 새로운 파일을 생성하여 라우트를 추가합니다. 파일 이름은 라우트 경로와 일치해야합니다.

// pages/about.js

function About() {
  return <div>About us</div>;
}

export default About;

Link 컴포넌트를 사용하여 라우트로 이동할 수 있는 링크를 만듭니다.

// pages/index.js

import Link from 'next/link';

function Home() {
  return (
    <div>
      <div>Welcome to Next.js!</div>
      <Link href="/about">
        About us
      </Link>
    </div>
  );
}

export default Home;

next/router 모듈을 사용하여 프로그래밍 방식으로 라우팅을 수행할 수 있습니다.

jsxCopy code
// pages/index.js

import { useRouter } from 'next/router';

function Home() {
  const router = useRouter();

  const handleClick = (e) => {
    e.preventDefault();
    router.push('/about');
  };

  return (
    <div>
      <div>Welcome to Next.js!</div>
      <Link href="/about">
        About us
      </Link>
      <button onClick={handleClick}>Go to about page</button>
    </div>
  );
}

export default Home;

이제 **http://localhost:3000**에서 클릭 가능한 링크와 버튼이 있으며, 클릭하면 http://localhost:3000/about 페이지로 이동합니다.

3. 요청 마다 로그를 남기려면?

Next.js에서 각 요청마다 로그를 남기려면 미들웨어 함수를 사용할 수 있습니다. 미들웨어 함수는 요청과 응답에 대한 핸들러 함수로, 이를 사용하여 로그를 남기고 다음 미들웨어로 요청을 전달할 수 있습니다.

다음은 Next.js에서 미들웨어 함수를 사용하여 각 요청마다 로그를 남기는 방법입니다.

server.js 파일을 생성합니다. 이 파일은 Next.js에서 서버 측 렌더링을 구성하는 데 사용됩니다.

// server.js

const express = require('express');
const next = require('next');

const dev = process.env.NODE_ENV !== 'production';
const app = next({ dev });
const handle = app.getRequestHandler();

app.prepare().then(() => {
  const server = express();

  // 미들웨어 함수를 등록합니다.
  server.use((req, res, next) => {
    console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
    next();
  });

  server.get('*', (req, res) => {
    return handle(req, res);
  });

  server.listen(3000, (err) => {
    if (err) throw err;
    console.log('> Ready on http://localhost:3000');
  });
});

server.js 파일에서 등록한 미들웨어 함수는 각 요청마다 로그를 출력합니다. console.log 대신 파일에 로그를 기록하거나 로그 서버로 전송하는 등의 작업을 수행할 수도 있습니다.

이제 Next.js 애플리케이션을 시작하면 각 요청에 대한 로그가 콘솔에 출력됩니다. 미들웨어 함수를 사용하면 요청을 가로채고 필요한 작업을 수행할 수 있으므로, 요청을 기록하는 것 외에도 인증, 권한 부여, 캐싱 등의 작업을 수행할 수 있습니다.

4. 실행방법

server.js 파일을 만든 후에는 다음 명령어를 사용하여 Next.js 애플리케이션을 실행합니다.

node server.js

이 명령어는 Node.js로 server.js 파일을 실행합니다. server.js 파일은 Next.js에서 서버 측 렌더링을 구성하는 데 사용되므로, 이 파일을 실행하면 Next.js 애플리케이션이 서버에서 실행됩니다.

애플리케이션이 실행되면 브라우저에서 **http://localhost:3000**에 접속하여 애플리케이션을 확인할 수 있습니다. 이때 server.js 파일에서 등록한 미들웨어 함수가 요청을 가로채고 로그를 남길 것입니다.

서버에서 애플리케이션을 실행하려면 server.js 파일이 포함된 디렉토리에서 위 명령어를 실행해야 합니다.

결과

[2023-03-08T08:03:00.827Z] GET /_next/static/chunks/webpack.js?ts=1678262580782
[2023-03-08T08:03:00.831Z] GET /_next/static/chunks/main.js?ts=1678262580782
[2023-03-08T08:03:00.834Z] GET /_next/static/chunks/react-refresh.js?ts=1678262580782       
[2023-03-08T08:03:00.837Z] GET /_next/static/chunks/pages/_app.js?ts=1678262580782
[2023-03-08T08:03:00.841Z] GET /_next/static/chunks/pages/index.js?ts=1678262580782
[2023-03-08T08:03:00.842Z] GET /_next/static/development/_buildManifest.js?ts=1678262580782 
[2023-03-08T08:03:00.848Z] GET /_next/static/development/_ssgManifest.js?ts=1678262580782
[2023-03-08T08:03:01.055Z] GET /_next/static/development/_devMiddlewareManifest.json
[2023-03-08T08:03:03.658Z] GET /
[2023-03-08T08:03:03.682Z] GET /_next/static/chunks/webpack.js?ts=1678262583664
[2023-03-08T08:03:03.683Z] GET /_next/static/chunks/main.js?ts=1678262583664
[2023-03-08T08:03:03.684Z] GET /_next/static/chunks/react-refresh.js?ts=1678262583664       
[2023-03-08T08:03:03.688Z] GET /_next/static/chunks/pages/_app.js?ts=1678262583664
[2023-03-08T08:03:03.689Z] GET /_next/static/chunks/pages/index.js?ts=1678262583664
[2023-03-08T08:03:03.690Z] GET /_next/static/development/_buildManifest.js?ts=1678262583664 
[2023-03-08T08:03:03.693Z] GET /_next/static/development/_ssgManifest.js?ts=1678262583664   
[2023-03-08T08:03:03.885Z] GET /_next/static/development/_devMiddlewareManifest.json
[2023-03-08T08:03:05.912Z] GET /_next/static/development/_devPagesManifest.json
[2023-03-08T08:03:05.920Z] GET /_next/static/chunks/pages/about.js
wait  - compiling /about...

🎇 1. VuePress 시작하기

Wed, 26 Oct 2022 00:00:00 GMT

VuePress 시작하기

VuePress 를 이용하여 TIL 을 작성하려고 한다. VuePress 를 이용하여 md 파일을 html 로 변환하고 이를 서비스 하려고 한다. 그럼 Vuepress 는 무엇인가?

Vuepress 는 무엇?

Vuepress 는 Vue.js 로 개발되어진 정적 사이트 생성기이다
기술문서 작성을 위해 최적화된 기본테마를 제공해준다
Plugin API를 제공해주어 플러그인을 제작하거나 적용할 수 있다. ( Google Analytics, PWA 를 손쉽게 적용가능함 )

기본 설치 및 빌드

# global install
$ yarn global add vuepress

# install as a local dependency
$ yarn add -D vuepress

$ mkdir docs

# 마크다운 파일을 생성한다.
$ echo '# Hello VuePress' > docs/README.md

package.json 에 scripts 추가

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

# Development Mode
$ yarn docs:dev

# build to static files
$ yarn docs:build

Directory Structure

VuePress 에서 권장되는 구조는 아래와 같다

.
├── docs
│   ├── .vuepress (Optional)
│   │   ├── components (Optional)
│   │   ├── theme (Optional)
│   │   │   └── Layout.vue
│   │   ├── public (Optional)
│   │   ├── styles (Optional)
│   │   │   ├── index.styl
│   │   │   └── palette.styl
│   │   ├── templates (Optional, Danger Zone)
│   │   │   ├── dev.html
│   │   │   └── ssr.html
│   │   ├── config.js (Optional)
│   │   └── enhanceApp.js (Optional)
│   │ 
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json

:::warning Note 자세한 사항은 VuePress 공식문서 를 참고하길 바란다 :::

Default Page Routing

타겟 디렉토리로 docs 를 사용한다. 아래의 모든 '상대경로'는 docs 디렉토리에 상대적이다. 기본 페이지 라우팅 경로는 다음과 같다

경로	페이지 라우팅
`/README.md`	`/`
`/guide/README.md`	`/guide/`
`/config.md`	`/config.html`

Maekdown Extensions

Syntax Highlighting in Code Blocks

input

``` js
export default {
  name: 'MyComponent',
  // ...
}
```

output

export default {
  name: 'MyComponent',
  // ...
}

Line Numbers

You can enable line numbers for each code blocks via config:

module.exports = {
  markdown: {
    lineNumbers: true
  }
}

Deploying

GitHub Pages

docs/.vuepress/config.js 에 base 설정

https://github.com/<USERNAME>/<REPO> 의 경우 base 는 "//" 가 됨

프로젝트 내에 deploy.sh 설정

#!/usr/bin/env sh

# abort on errors
set -e

# build
npm run docs:build

# navigate into the build output directory
cd docs/.vuepress/dist

# if you are deploying to a custom domain
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# if you are deploying to https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

# if you are deploying to https://<USERNAME>.github.io/<REPO>
git push -f https://github.com/javapark/javapark.github.io.git master:gh-pages

cd -

main.yaml 설정

name: Build and Deploy
on: [push]
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@main

    - name: Vuepress deploy
      uses: jenkey2011/vuepress-deploy@1.0.1
      env:
        ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
        BUILD_SCRIPT: yarn && yarn docs:build
        TARGET_BRANCH: gh-pages
        BUILD_DIR: docs/.vuepress/dist

Netlify

Netlify , setup up a new project from GitHub with the following settings:

Build Command: vuepress build docs or yarn docs:build or npm run docs:build
Publish directory: docs/.vuepress/dist

Hit the deploy button