🛠️ Stage 2 · 개발환경 & 문서화 인프라

만들기 전에
설계도를 먼저

코드를 짜기 전에 프로젝트 구조와 문서를 먼저 잡습니다. 좋은 CLAUDE.md 하나가 수십 시간의 삽질을 막아줍니다. 이 Stage가 끝나면 Claude Code에게 시킬 "헌법"이 손에 들어옵니다.

학습 시간 약 4~5시간

터미널 첫 경험

산출물 3개

✦ 이 커리큘럼을 관통하는 한 문장

"기술은 AI가, 영혼은 사람이"

Stage 1에서 비전을 정했다면, Stage 2는 그 비전을 AI가 읽고 따라할 수 있는 형태의 문서로 만드는 작업입니다. 좋은 문서는 한 번 잘 써두면 Stage 9까지 자동으로 일을 합니다.

🎯 Stage 1에서 받아온 것 → Stage 2에서 만들 것

예시 프로젝트: AI 뉴스레터 자동화 서비스

Stage 1에서 만든 lean-canvas.md와 personas.md를 가져옵니다. 이 두 파일이 이번 Stage의 PRD.md 도입부가 됩니다. 그리고 PRD.md + CLAUDE.md + ARCHITECTURE.md 3종 세트를 완성합니다. Stage 5의 Claude Code가 이 세 파일을 자동으로 읽고 일을 시작합니다.

Stage 1: 기획

→

Stage 2: 문서화

→

Stage 3: CLAUDE.md 심화

→

Stage 5: Claude Code

→

Stage 6: 배포 URL

→

Stage 7: n8n 자동화

터미널 10분 속성

Claude Code를 쓰려면 최소한 알아야 하는 것 — 10분이면 충분합니다

"검은 화면에 글자만 깜빡이는 그것"이 터미널입니다. Claude Code는 이 터미널 안에서 돕니다. 무서워 보이지만 10개 명령어만 알면 평생 충분합니다. 마우스로 폴더를 더블클릭하는 것을 글자로 쓰는 것뿐입니다.

🧭 비유로 이해하기

탐색기(Finder)는 "지도를 보며 걷기", 터미널은 "주소를 부르면 순간이동". 처음엔 지도가 편하지만, 익숙해지면 주소가 압도적으로 빠릅니다. AI는 마우스를 못 씁니다. 그래서 AI와 일하려면 주소 부르는 법을 배워야 합니다.

⌨️ 평생 쓸 10개 명령어

pwd

지금 내가 어느 폴더에 있는지 알려줌. "Print Working Directory"

→ /Users/me/Documents/newsletter

현재 폴더에 뭐가 있는지 목록 출력. "List"

→ docs/ src/ CLAUDE.md README.md

cd 폴더명

폴더 안으로 들어감. cd .. 은 부모 폴더로 나가기

→ cd Documents/newsletter

mkdir 이름

새 폴더 만들기. "Make Directory"

→ mkdir docs

cat 파일

파일 내용을 화면에 출력. 빠른 확인용

→ cat CLAUDE.md

clear

화면을 깨끗이 비움. 정신이 어지러울 때 누름

→ Ctrl+L 단축키도 동일

Tab (자동완성)

파일·폴더 이름 입력 중 Tab 누르면 자동완성. 필수

→ cd Doc + Tab → cd Documents/

Ctrl+C

실행 중인 명령어 강제 중단. AI가 멈추지 않을 때 구원

→ "취소!" 버튼이라고 생각

open .

현재 폴더를 Finder로 엶 (Mac). Windows는 explorer .

→ 터미널 ↔ 탐색기 왔다 갔다

exit

터미널 세션 종료. 대화창 닫기와 같음

→ Cmd+W로 창 닫기도 동일

📁 한 작업 = 한 폴더 원칙

초보자가 가장 자주 망치는 것: 여러 프로젝트를 한 폴더에 섞기. 절대 안 됩니다. AI가 혼란스러워서 엉뚱한 파일을 수정합니다. 작업 하나당 폴더 하나. 그 폴더 안에 CLAUDE.md를 두고 거기서 Claude Code를 실행합니다.

📂 추천 폴더 구조

~/Documents/projects/ (모든 프로젝트의 부모 폴더)
├── newsletter-mvp/ ← 이번 학습용 ← 여기서 claude 실행
├── blog-redesign/
└── side-experiment/

각 폴더 안에 자체 CLAUDE.md, docs/, src/가 들어갑니다. AI는 자기가 실행된 폴더만 봅니다.

⚡ 실전 흐름 — Claude Code 첫 실행까지

실제로는 이렇게 흘러갑니다. 매번 같은 패턴이라 5번만 해보면 손에 익습니다.

Terminal — me@macbook ~

# 1. 지금 어디 있는지 확인 $ pwd /Users/me # 2. 프로젝트 폴더로 이동 $ cd Documents/projects/newsletter-mvp # 3. 폴더 내용 확인 (CLAUDE.md 있는지 보기) $ ls CLAUDE.md docs/ README.md # 4. Claude Code 실행 (이 폴더가 작업 영역이 됨) $ claude Welcome to Claude Code v2.0 Reading CLAUDE.md ... Ready. What should I do?

💡 Pro Tip

3번에서 ls를 꼭 하세요. CLAUDE.md가 없는 폴더에서 claude를 실행하면 AI가 백지 상태로 시작합니다. CLAUDE.md가 있는지 매번 확인하는 습관을 들이세요. 없으면 만들고, 있으면 안심하고 시작.

Antigravity vs Claude Code vs VS Code

"3개 다 깔아야 하나?" — 역할이 달라서 다 필요합니다. 단, 메인은 하나만

🔧 3가지 도구의 역할

초보자가 가장 자주 묻는 질문: "Claude Code랑 Antigravity 뭐가 다른가요?" 비유로 말하면 자동차의 엔진과 계기판입니다. 엔진(Claude Code)이 실제로 일을 하고, 계기판(Antigravity)으로 그 진행 상황을 보면서 지휘합니다.

⚙️

Claude Code

엔진

터미널에서 도는 진짜 일꾼. 코드를 쓰고, 파일을 만들고, 명령어를 실행. 모든 작업의 본체.

📊

Antigravity

대시보드

엔진의 상태를 보여주는 시각화 인터페이스. 여러 에이전트를 동시에 돌리고 진행을 확인.

📝

VS Code

편집기

코드를 손으로 다듬을 때 쓰는 에디터. AI가 만든 결과를 검토·미세 조정하는 용도.

🗺️ 언제 뭘 쓰나 — 작업별 도구 매핑

작업	주력 도구	이유
새 기능 개발 (0 → 1)	Claude Code	터미널에서 빠르게 명령 → AI가 파일 생성·수정. 가장 효율적
여러 에이전트 동시 작업	Antigravity	"백엔드 만들어 + 프론트 만들어 + 테스트 작성해" 병렬 진행을 한눈에
버그 미세 수정	VS Code	한 줄짜리 수정은 손이 더 빠름. AI에게 시키면 오버킬
긴 문서 작성 (CLAUDE.md, PRD)	VS Code + Claude Code	Claude로 초안 → VS Code에서 다듬기
코드 리뷰	Antigravity	여러 PR을 동시에 검토하는 흐름이 매끄러움

🎯 1인 창업가 추천 셋업

Phase 1 (Stage 5까지): Claude Code 한 개만 깊이 익히기. Antigravity는 나중에.
Phase 2 (Stage 6 이후): 동시에 여러 작업이 늘면 Antigravity 추가.
VS Code는 처음부터 깔아두고 Claude가 만든 결과를 열어보는 용도로 사용.

🚀 Antigravity 설치 & AGENTS.md

Antigravity는 Google이 만든 "AI 에이전트 IDE"입니다. antigravity.google에서 다운로드 → 설치 → VS Code 설정 가져오기로 시작합니다. VS Code 사용자라면 5분이면 끝납니다.

📋 AGENTS.md = Antigravity의 CLAUDE.md

Antigravity에서는 AGENTS.md가 CLAUDE.md와 같은 역할을 합니다. 폴더 루트에 두면 모든 에이전트가 자동으로 읽습니다.

실용 팁: CLAUDE.md를 잘 써뒀다면 cp CLAUDE.md AGENTS.md로 복사만 해도 80%는 호환됩니다. 둘 다 마크다운 텍스트 기반이라 거의 동일한 형식을 씁니다.

프로젝트 5종 문서 템플릿

이 5개만 잘 써두면 AI가 알아서 일합니다. 프로젝트의 "헌법 + 법률 + 시행령"

개발자 출신은 무의식적으로 알지만 비개발자는 모릅니다 — 코드보다 문서가 더 중요합니다. 코드는 AI가 짭니다. 문서는 사람이 짭니다. 문서가 부실하면 AI가 짠 코드도 같이 부실해집니다.

CLAUDE.md 에이전트 지침서

프로젝트의 헌법. 매 세션 자동 로드. AI가 절대 어기면 안 되는 규칙들 (한국어로 답하기, 특정 라이브러리 쓰지 말기, 코딩 스타일 등).

📰 뉴스레터 예시: "Next.js 15 + Supabase 사용. n8n 워크플로우 수정 금지(별도 권한). 응답은 한국어. 카카오 API 호출 시 환경변수 사용."

PRD.md 제품 요구사항

"무엇을, 누구를 위해, 왜 만드는가"의 정의서. Stage 1의 Lean Canvas + 페르소나 + JTBD를 흡수해서 한 단계 구체화.

📰 뉴스레터 예시: "타겟: 30대 IT 직장인. 핵심 가치: 매일 5분 요약. MVP 기능: 이메일 발송, 주제 선택, 결제. 제외: 모바일 앱."

ARCHITECTURE.md 기술 구조

"어떻게 만드는가"의 청사진. 어떤 라이브러리, 어떤 DB, 어떤 흐름으로 데이터가 움직이는지. AI가 새 코드를 짤 때 이걸 보고 일관성 유지.

📰 뉴스레터 예시: "Next.js → Supabase Auth → n8n cron → Claude API 요약 → SendGrid 이메일. 결제는 Stripe Checkout."

UI_GUIDE.md 디자인 원칙

"어떻게 보이는가"의 가이드. 컬러 토큰, 폰트, 컴포넌트 스타일, 톤앤매너. Stage 4(디자인)에서 본격 작성.

📰 뉴스레터 예시: "톤: 친근하지만 전문적. 컬러: blue primary. 이메일: Inter 폰트. 본문 600px 고정."

ADR.md 결정 기록

"왜 이걸 선택했는가"의 로그. Architecture Decision Record. 한 결정당 한 항목. 6개월 뒤 미래의 내가 "왜 그랬지?" 헤맬 때 구원자.

📰 뉴스레터 예시: "ADR-001: 이메일 서비스로 SendGrid 선택 (이유: 무료 티어 100통/일, Mailgun보다 한국 도달률 우수)"

⚠️ 한꺼번에 다 만들지 말 것

5개를 다 한번에 쓰려고 하면 무너집니다. 이번 Stage에서는 PRD.md + CLAUDE.md + ARCHITECTURE.md 3개만. UI_GUIDE는 Stage 4에서, ADR은 결정이 생길 때마다 한 줄씩 추가합니다.

PRD 작성법

기획서랑 뭐가 다른가? 한 마디로 "AI가 읽을 수 있는 형태"

기획서는 사람이 읽고 사람이 해석합니다. 모호해도 회의로 메꿉니다. PRD(Product Requirements Document)는 AI가 읽고 AI가 코드로 변환합니다. 모호하면 AI가 마음대로 짭니다. 그래서 PRD는 항목별로 명확하게, 번호 매겨서 씁니다.

📊 기획서 vs PRD

기획서: "사용자가 편하게 뉴스를 받아볼 수 있도록 한다" (멋있지만 모호)
PRD: "사용자는 매일 오전 8시에 자기가 선택한 카테고리(IT/투자/AI) 뉴스 5개를 이메일로 받는다. 카테고리는 마이페이지에서 변경 가능. 발송 실패 시 재시도 3회." (구체적, AI가 코드로 옮길 수 있음)

📐 PRD 5단 구조

복잡할 필요 없습니다. 5개 항목만 답하면 PRD입니다.

목표

왜 만드나?

사용자

누구를 위해?

핵심 기능

무엇을 하나?

MVP 제외

뭘 안 만드나?

성공 지표

어떻게 안다?

💡 4번 "MVP 제외"가 가장 중요

초보자가 가장 자주 망치는 부분. "이것도 좋겠다, 저것도 넣자" 하면 영원히 안 끝납니다. PRD에 "이건 안 만든다" 목록을 명시적으로 쓰세요. AI도 그 목록을 보고 "유혹에 안 빠집니다".

✅ Must Have vs ❌ Won't Have — 뉴스레터 서비스 예시

✅ MUST HAVE (MVP 3개)

1. 이메일로 가입 + 주제 선택 (IT/투자/AI 중 1개)
2. 매일 오전 8시 자동 발송 (Claude 요약 + 5개 기사)
3. 월 9,900원 Stripe 결제 + 구독 관리 페이지

❌ WON'T HAVE (이번엔 안 함)

× 모바일 앱 (웹만)
× 카카오 발송 (이메일만, Stage 7에서 추가)
× 사용자 댓글·커뮤니티
× 다크모드
× 추천 시스템 (Stage 8)

🔄 Lean Canvas → PRD 자동 변환

Stage 1에서 만든 lean-canvas.md의 9개 칸이 PRD의 재료입니다.
Customer Segments + Persona → PRD의 ② 사용자
Problem + UVP → PRD의 ① 목표
Solution → PRD의 ③ 핵심 기능
Key Metrics → PRD의 ⑤ 성공 지표

AI에게 lean-canvas.md를 던지고 "이걸 PRD.md로 변환해줘"라고 시키면 70%가 자동으로 나옵니다. 나머지 30%는 ④ MVP 제외 목록 — 이건 사람이 결정합니다.

⚡ PRD.md 작성 프롬프트

첨부한 lean-canvas.md와 personas.md를 읽고 PRD.md 초안을 작성해줘. 서비스: AI 뉴스레터 자동화 서비스 타겟: 한국 IT/비즈니스 직장인 (월 9,900원 구독) PRD 구조 (5단): 1. 목표 — 왜 만드나 (Lean Canvas의 Problem + UVP에서 도출) 2. 사용자 — 페르소나 2명 요약 + 핵심 JTBD 3. 핵심 기능 — Must Have 3개를 사용자 시나리오 형식으로 "사용자는 [상황]에서 [행동]을 하면 [결과]를 얻는다" 4. MVP 제외 — 이번엔 안 만들 것 5~7개 (이유 1줄씩) 5. 성공 지표 — NSM 1개 + 보조 지표 3개 (정량 측정 가능하게) 마크다운 형식. AI 코딩 에이전트가 그대로 코드로 옮길 수 있을 정도로 구체적으로.

GitHub 기본 워크플로우

코드 백업 + Claude Code와의 협업 거점 — 무료, 필수

"GitHub는 개발자만 쓰는 거 아닌가요?" 아닙니다. 2026년의 GitHub는 1인 창업가의 클라우드 백업 + AI 협업 플랫폼입니다. Claude Code가 만든 코드가 자동으로 GitHub에 올라가고, 어디서든 다시 불러올 수 있습니다. 노트북이 망가져도 안 사라집니다.

💚 GitHub가 주는 3가지

1. 백업: 코드 + 문서 + 모든 기록이 클라우드에 자동 저장
2. 시간 여행: "어제 잘 됐는데 오늘 망가졌다" → 어제 버전으로 1초 복원
3. AI 협업: Claude Code, Cursor, Codex 등 모든 AI 도구가 GitHub 저장소를 읽고 일함

🔄 기본 흐름 — 처음 한 번만

📁

폴더 만들기

mkdir newsletter

→

🔧

git 초기화

git init

→

📝

첫 커밋

git commit

→

☁️

GitHub 연결

git push

🪄 Claude Code에게 통째로 시키기

위 4단계를 외울 필요 없습니다. Claude Code 프롬프트에 한 줄로:

"이 프로젝트를 GitHub 비공개 저장소로 올려줘. 저장소 이름은 newsletter-mvp. README도 만들어줘."

Claude가 git 명령어를 알아서 실행합니다. 처음 한 번 GitHub 계정 연결만 해두면, 그 다음부터는 AI가 다 해줍니다. 이게 2026년의 1인 창업가가 GitHub를 쓰는 방식입니다.

📋 GitHub 첫 설정 체크리스트

단계	해야 할 일	걸리는 시간
1	github.com 가입 (이메일 + 비밀번호)	2분
2	Git 설치 (Mac은 기본 내장, Windows는 git-scm.com)	5분
3	GitHub Desktop 설치 (선택, 시각화 보고 싶으면)	3분
4	SSH 키 등록 또는 Personal Access Token 발급	10분
5	Claude Code에서 첫 push 테스트	5분

⚠️ .gitignore 잊지 말기

.env 파일에 API 키 같은 비밀이 들어있는데 이걸 GitHub에 올리면 전 세계가 봅니다. .gitignore 파일로 막아야 합니다. Claude Code에 시킬 때 "표준 .gitignore 같이 만들어줘"를 잊지 마세요. Next.js 템플릿엔 이미 들어있습니다.

⚡ GitHub 첫 설정 프롬프트

현재 폴더(newsletter-mvp)를 GitHub에 올리려고 한다. 해야 할 일: 1. 이 폴더를 git 저장소로 초기화 (git init) 2. 표준 .gitignore 만들기 (Next.js + macOS + .env) 3. 모든 파일을 첫 커밋 ("Initial commit: PRD + CLAUDE.md + ARCHITECTURE") 4. GitHub에 비공개 저장소 newsletter-mvp 만들고 연결 5. 첫 push 실행 각 단계마다 실행할 명령어를 보여주고, 내가 확인하면 다음으로 넘어가는 식으로 천천히 진행해줘. 중간에 GitHub 인증이 필요하면 어떻게 하는지 안내해줘.

코드 독해력 30분

짜는 능력 아닌 "이 부분이 이상하다"고 알아차리는 능력

코드를 짤 줄 알 필요 없습니다. AI가 짭니다. 하지만 AI가 짠 코드를 보고 "어 이거 이상한데?"라고 느낄 수 있어야 합니다. 그래야 AI가 잘못된 길로 가는 걸 막을 수 있습니다. 30분이면 핵심만 익힙니다.

📜 JavaScript 3가지 핵심 패턴

웹 프론트엔드 + Next.js의 표준 언어. 이 3개만 알아보면 95%의 코드를 "읽을" 수 있습니다.

JS · 1. 변수

const / let — 값에 이름 붙이기

바뀌지 않는 값은 const, 바뀌는 값은 let. 거의 모든 변수는 const입니다.

const price = 9900; const service = "newsletter"; let subscriberCount = 0; subscriberCount = 1; // OK

JS · 2. 조건문

if / else — 분기 처리

"이러면 저렇게, 아니면 이렇게". 가장 많이 보는 구조.

if (subscriberCount > 100) { send("premium-content"); } else { send("basic-content"); }

JS · 3. 비동기

async / await — 기다리는 작업

API 호출, DB 조회 등 시간이 걸리는 일. await = "끝날 때까지 기다려".

async function fetchNews() { const news = await claude.summarize(); return news; }

PY · 1. 자료구조

list / dict — 데이터 묶음

리스트([])는 순서 있는 묶음, 딕셔너리({})는 키-값 쌍.

topics = ["IT", "AI", "투자"] user = { "name": "이준호", "plan": "monthly" }

PY · 2. 함수/루프

def / for — 작업 정의·반복

함수는 작업 한 덩어리, for는 리스트의 각 항목에 같은 일 반복.

def send_to(user): email(user["email"]) for u in subscribers: send_to(u)

PY · 3. import

import — 도구 가져오기

남이 만든 라이브러리를 빌려옴. 파일 맨 위에 모아 둠.

import requests from anthropic import Claude client = Claude(api_key=KEY)

🎯 실전 — Claude Code가 만든 코드 읽어보기

Stage 5에서 Claude Code에게 "뉴스 요약 함수 만들어줘"라고 시키면 위 패턴들이 섞인 코드가 나옵니다. 한 줄씩 읽으면서 "이건 변수, 이건 조건, 이건 함수"라고 분류만 할 수 있으면 충분합니다. 의미가 헷갈리면 AI에게 "이 함수가 뭘 하는지 한국어로 한 줄로 설명해줘"하면 즉시 알려줍니다.

📚 더 깊이 들어가지 말 것

유튜브 "JavaScript 입문 강의 30시간"을 듣지 마세요. 1인 창업가에게는 시간 낭비입니다. 위 6가지 패턴 + AI에게 물어보기가 더 효율적. 모르면 그때 그때 묻고, 만들면서 익힙니다. AI가 코드를 짜는 시대에 사람이 익혀야 하는 건 코드가 아니라 "코드를 평가하는 눈"입니다.

🎯 Stage 2 산출물 — 이걸 만들어야 끝입니다

내 손으로 만든 3개의 문서

읽기만 하면 의미 없습니다. 지금 바로 빈 폴더 하나 만들어서 아래 3개를 채우세요. 이 3개가 Stage 3·5의 재료가 됩니다. Claude Code가 매 세션 시작할 때 자동으로 읽는 핵심 파일들입니다.

📋 PRD.md — 제품 요구사항 문서

Stage 1의 lean-canvas.md와 personas.md를 재료로 PRD 5단 구조(목표/사용자/핵심기능/MVP제외/성공지표)로 작성. Must Have 3개와 Won't Have 5~7개를 명시. 파일명: docs/PRD.md

📜 CLAUDE.md — 에이전트 지침서

100줄 이내로 작성. 프로젝트 개요·기술 스택·코딩 규칙·금지 사항·응답 언어·핵심 황금률 포함. 프로젝트 루트에 위치. 파일명: CLAUDE.md

🏗️ ARCHITECTURE.md — 기술 구조 초안

기술 스택 선택 + 데이터 흐름도 텍스트(사용자 → 회원가입 → DB → 발송 cron → AI 요약 → 이메일). Stage 5 Claude Code 시작 시 자동 로드. 파일명: docs/ARCHITECTURE.md

📎 Stage 연결 고리: 지금 만든 PRD.md + CLAUDE.md는 Stage 3에서 컨텍스트 엔지니어링 심화 재료로 쓰입니다. ARCHITECTURE.md는 Stage 5에서 Claude Code가 첫 코드를 짤 때 자동으로 읽는 청사진이 됩니다. 한 문서가 다음 문서를 만들고, 한 Stage가 다음 Stage를 자동화합니다.

🤖

Stage 2 AI 튜터

개발환경 · 문서화 · PRD · CLAUDE.md · GitHub

LIVE AI

AI 튜터 응답