1탄 2·3장
1탄 — 메타 매뉴얼 · 2장
프로젝트 시작 30분: 폴더부터 5파일까지
빈 폴더에서 git init + 5파일 생성 + Claude Code 실행 준비까지 30분 안에 마칩니다
📑 이 챕터에서 다룰 내용

1장에서 5파일+의 정체성을 정의했습니다. 이 장은 짧습니다. 30분 안에 빈 폴더에서 5파일 + git init + Claude Code 실행 준비까지 마치는 작업입니다. 코드 한 줄도 안 짜고, 결정도 안 합니다. 다음 단계(4장 이후)가 실제 결정의 자리이고, 이 장은 그 결정을 담을 "빈 그릇"을 준비합니다.

📚 사전 지식 체크🎯 이 장의 목적✅ 완료 후 결과물
3장 Claude Code 설치 완료 + Node.js + git 설치 완료새 앱 프로젝트를 처음 시작할 때 반드시 만들어야 하는 폴더 구조와 5파일을 30분 안에 완성한다프로젝트 폴더 + 5파일 생성 + git init + 첫 commit + Claude Code 실행 준비 완료
📘 인지 부하 이론 — 스웰러, 1988

1장에서 5파일+의 정체성과 5파일 × 표준 매핑 × 확장 결합을 한 표로 정리했습니다. 그 표를 머릿속에 들고 이 장의 작업(실제 5파일을 손으로 만드는 일)을 진행하면, 인지 부하가 분산됩니다. 정체성은 1장에서 처리됐고, 이 장은 손작업만 합니다.

5개 파일의 역할을 짧게 복기합니다.

SPEC.mdPLAN.mdREVIEW.mdBUILD.mdCLAUDE.md
무엇 만들 것인가 (5장)어떤 순서로 (6장)진입 준비 됐는가 (8장)진행 로그 (9장)Claude 컨텍스트 (11장)
2-1 30분 안에 완료하는 프로젝트 초기화 순서 🔗

아래 순서를 그대로 따르면 됩니다. 순서를 바꾸면 안 됩니다. 특히 git init은 반드시 5파일 생성 전에 해야 합니다 — 5파일이 처음부터 git 추적에 들어가야 git history가 깨끗합니다.

①
폴더 생성

프로젝트 이름으로 폴더 만들기 (5분)

②
git 초기화

git init + .gitignore 생성 (2분)

③
5파일 생성

빈 .md 파일 5개 생성 (3분)

④
CLAUDE.md 작성

기본 규칙 입력 — 11장 작성 전 최소 틀 (10분)

⑤
첫 커밋

git add + git commit (2분)

⑥
Claude Code 실행

claude 명령으로 실행 + /powerup (3분)

⑦
확인

ls 명령으로 5파일 존재 확인 (1분)

2-2 단계별 실행 명령어 (전체) 🔗

아래 명령어를 순서대로 터미널에 입력합니다. [앱이름] 부분만 실제 앱 이름으로 바꾸면 됩니다.

💻 프로젝트 초기화 전체 명령어
# ① 프로젝트 폴더 생성
mkdir [앱이름] && cd [앱이름]

# ② git 초기화
git init

# .gitignore 생성 (환경변수 파일은 절대 올리지 않음)
cat > .gitignore << 'EOF'
node_modules/
.env
.env.local
.env*.local
dist/
.expo/
EOF

# ③ 5파일 생성 (빈 파일)
touch SPEC.md PLAN.md REVIEW.md BUILD.md CLAUDE.md

# 생성 확인
ls *.md
# 출력 결과: BUILD.md  CLAUDE.md  PLAN.md  REVIEW.md  SPEC.md

# ④ CLAUDE.md 최소 내용 입력 (이후 11장에서 완성)
cat > CLAUDE.md << 'EOF'
# 프로젝트: [앱이름]
# 상태: 초기화 완료 — SPEC.md 작성 전

## 절대 금지
- 요청하지 않은 파일을 임의로 수정하지 않는다
- API 키를 코드에 직접 넣지 않는다

## 현재 완성된 것
- 없음 (Phase 0: 초기화 단계)
EOF

# ⑤ 첫 커밋
git add .
git commit -m "프로젝트 초기화: 5파일+ 구조 생성"

# ⑥ Claude Code 실행
claude
/powerup     # ← 환경 최적화 (반드시 실행)

# ⑦ 5파일 존재 확인
ls *.md      # ← 5개 파일 모두 보여야 한다
💡 비개발자 동업자께 — 이 명령어들이 무엇인가요?
  • mkdir = 폴더 만들기
  • git init = 변경 추적 시작 (Word의 "변경 내용 추적"과 비슷, 그러나 무한 정밀)
  • touch = 빈 파일 만들기
  • cat > 파일명 << 'EOF' ... EOF = 파일에 내용 입력
  • git add . + git commit = "지금까지 만든 것을 저장" (체크포인트)
  • claude = Claude Code 실행

명령어 자체는 외울 필요 없습니다. 책에서 그대로 복사해서 붙여넣으면 됩니다. 시간이 지나면 자연스럽게 익숙해집니다.

2-3 5파일의 역할과 흐름 🔗

1장 1.7절에서 한 표로 정리했지만, 이 장에서는 "실제로 어떻게 연결되는지"의 흐름 관점으로 다시 봅니다.

파일만드는 장 / 내용다음 단계에서 어떻게 쓰이는가
SPEC.md5장 — 무엇을 만들 것인가 + E1 회색지대PLAN.md 작성 시 참조: "이 SPEC을 보고 Phase를 나눠줘"
PLAN.md6장 — Phase 순서 + 완료 기준 + E2 1인 페이스REVIEW.md 작성 시 참조: "이 PLAN을 보고 10가지를 점검해줘"
REVIEW.md8장 — 10가지 체크 + READY 판정 + E3 두 검토자BUILD 시작 전 참조: "REVIEW.md에 READY: YES가 있어야 BUILD 시작"
BUILD.md9장 — 현재 진행 중인 Phase 로그 + E4 LogOnTable/clear 후 참조: "BUILD.md를 읽고 현재 상황을 파악해줘"
CLAUDE.md11장 — 규칙 + 스택 + 완성된 것 + E5 콘텐츠 SSOT모든 세션에서 자동 로드 — 항상 최신 상태 유지
🎉 5파일이 /clear를 완전히 안전하게 만드는 이유

/clear를 누르면 Claude의 대화 기억이 초기화됩니다. 하지만 5파일은 디스크에 남아 있습니다.

새 세션에서 한 줄이면 전체 맥락이 복원됩니다:

SPEC.md, PLAN.md, REVIEW.md, BUILD.md, CLAUDE.md 파일을 읽고 현재 상황을 파악해줘.

이 한 줄로 Claude는 이전 세션의 결정·진행 상태·다음 단계를 즉시 파악합니다.

2-4 Phase 완성마다 하는 루틴 🔗

5파일+ 구조를 유지하려면 기능이 완성될 때마다 반드시 이 루틴을 따라야 합니다. 처음에는 번거롭지만, 이 루틴이 /clear의 두려움을 완전히 없애줍니다.

💻 Phase 완성 루틴 (4단계)
# STEP 1: BUILD.md 업데이트
# Claude Code에서:
#   "BUILD.md에 방금 완성한 기능명을 기록해줘.
#    현재 진행 중인 것과 다음 단계도 업데이트해줘."

# STEP 2: CLAUDE.md 업데이트
# Claude Code에서:
#   "CLAUDE.md의 '현재 완성된 것' 목록에 [기능명]을 추가해줘."

# STEP 3: git commit
git add .
git commit -m "[기능명] 완성"

# STEP 4: /clear
/clear     # ← 이제 완전히 안전합니다

# STEP 5: 다음 기능 시작 (새 세션)
# 새 세션 첫 메시지:
#   "SPEC.md, PLAN.md, REVIEW.md, BUILD.md, CLAUDE.md를 읽고
#    현재 상황을 파악한 뒤 다음 단계를 알려줘."
⚠️ 이 루틴을 건너뛰면 일어나는 일

STEP 1~2를 건너뛰고 STEP 3(git commit)만 하면:

  • /clear 후 새 세션에서 Claude가 "현재 상황"을 모릅니다
  • 이미 만든 기능을 다시 만들기 시작합니다
  • 비용·시간 낭비

STEP 3(git commit) 없이 /clear 하면:

  • 완성한 코드가 날아갑니다. 복구 불가능합니다.

순서: BUILD.md → CLAUDE.md → git commit → /clear. 이 순서는 절대 바꾸지 않습니다.

📘 표준 도구와의 비교

GSD의 atomic commit + STATE.md 갱신 루틴과 비슷합니다. 다만 GSD는 자동(/gsd-execute-phase가 commit 자동), 5파일+ 는 수동(학습 + 인수인계 가치)입니다. 자동화의 필요성이 커지는 시점(예: 19리그 확장)에 GSD 같은 표준 도구로 옮길 수 있습니다.

📌 2장 정리
  • 1️⃣ 30분 안에: 빈 폴더 → git init → 5파일 생성 → CLAUDE.md 최소 틀 → 첫 커밋 → Claude Code 실행 준비.
  • 2️⃣ 7단계 순서 절대 불변: ① 폴더 → ② git init + .gitignore → ③ 5파일 touch → ④ CLAUDE.md 최소 입력 → ⑤ 첫 commit → ⑥ claude + /powerup → ⑦ ls *.md 확인
  • 3️⃣ Phase 완성 루틴 절대 불변: BUILD.md 갱신 → CLAUDE.md 갱신 → git commit → /clear → 새 세션
  • 4️⃣ 5확장 결합 시점: SPEC.md(5장)←E1 / PLAN.md(6장)←E2 / REVIEW.md(8장)←E3 / BUILD.md(9장)←E4 / CLAUDE.md(11장)←E5
1탄 — 메타 매뉴얼 · 3장
Claude Code 설치: 천천히, 순서대로
인생에서 딱 한 번 — Node.js부터 /powerup까지 순서대로 설치합니다

이 장도 짧습니다. Claude Code를 컴퓨터에 설치하고 /powerup으로 환경을 초기화하는 작업입니다. 인생에서 딱 한 번이고, 완료되면 4장부터는 설치 걱정 없습니다.

📚 사전 지식 체크🎯 이 장의 목적✅ 완료 후 결과물
Windows·Mac·Linux 컴퓨터를 켜고 끌 수 있으면 충분. 코딩 경험 전혀 불필요Claude Code를 컴퓨터에 설치하고 /powerup으로 환경을 초기화해 언제든 쓸 수 있는 상태로 만든다claude 명령으로 Claude Code가 켜진다. 설치 오류 10가지 대응법을 안다
💡 9개 도구 풍경에서 Claude Code의 자리

0장에서 9개 SDD 표준 도구 풍경을 봤습니다. Claude Code는 그 9개와 다른 카테고리입니다.

  • 9개 도구 = "방법론·프로세스" (어떤 순서로 명세를 만들고 코드를 짤 것인가)
  • Claude Code = "AI 코딩 에이전트 런타임" (실제 명령을 실행하는 도구)

GSD·Spec-Kit·OpenSpec·BMAD 모두 Claude Code 위에서 작동합니다. 3장은 "런타임 설치", 4장 이후는 "방법론 학습"입니다.

걱정하지 마세요. 이 설치 과정은 지금 이 세상에서 수백만 명이 매일 하는 일입니다. 스마트폰에 앱을 설치하는 것과 비슷합니다. 단지 앱 대신 Claude Code를 설치하는 것뿐입니다.

3-1 설치 전 딱 하나만 확인 — Node.js 🔗

Claude Code를 설치하기 전에 Node.js가 필요합니다.

📘 비개발자께 — Node.js가 무엇인가요?

Node.js는 JavaScript를 컴퓨터에서 실행할 수 있게 해주는 프로그램입니다. 스마트폰으로 비유하면 Claude Code는 앱이고, Node.js는 그 앱을 실행하는 운영체제입니다. 운영체제 없이는 앱을 설치할 수 없듯이, Node.js 없이는 Claude Code를 설치할 수 없습니다.

Node.js가 이미 설치됐는지 먼저 확인합니다.

💻 PowerShell(Windows) 또는 Terminal(Mac)에서 확인
node --version

# v22.0.0 이상 숫자가 나오면 → 3-2 STEP 2부터 시작
# 아무것도 안 나오면 → 3-2 STEP 1부터 시작
💡 PowerShell이 뭔가요?

명령을 입력하는 창입니다. 네비게이션에 목적지를 입력하는 것과 같습니다.

  • Windows: 시작 버튼 → "PowerShell" 검색 → 엔터
  • Mac: Command + Space → "Terminal" 검색 → 엔터

이 책의 명령어는 그대로 복사해서 붙여넣으면 됩니다. 영어를 이해할 필요가 없습니다.

3-2 5단계 설치 절차 🔗

각 단계 완료 후 "성공 확인" 문구가 나오는지 보고 다음으로 넘어갑니다.

STEP 1 — Node.js 22 설치 (약 3분)

📘 설치 안내

nodejs.org/ko 접속 → LTS 버전 클릭 → 다운로드 → 설치 완료

설치 중 모든 옵션 기본값 그대로 — 복잡한 설정 건드리지 않아도 됩니다

💻 설치 확인
node --version
# v22.x.x 이상 숫자가 나오면 성공

STEP 2 — Claude Code 설치 (약 1분)

💻 Claude Code 설치
npm install -g @anthropic-ai/claude-code
claude --version
# 1.x.x 이상 숫자가 나오면 성공
💡 "permission denied" 오류 시

PowerShell을 "관리자 권한으로 실행"하세요.

STEP 3 — API 키 등록 (약 2분)

📘 API 키 발급 방법

console.anthropic.com → 로그인 → API Keys → Create Key → 복사

💻 API 키 등록
# Windows PowerShell:
$env:ANTHROPIC_API_KEY="sk-ant-여기에붙여넣기"

# Mac/Linux Terminal:
export ANTHROPIC_API_KEY="sk-ant-여기에붙여넣기"
⚠️ API 키는 "sk-ant-"로 시작합니다

은행 카드 번호처럼 소중하게 관리하세요. 절대 코드에 직접 넣거나 공개 저장소에 올리면 안 됩니다.

STEP 4 — 첫 실행

💻 첫 실행
claude
# Claude Code 환영 화면이 나오면 성공
# 처음 실행 시 이메일 인증을 요청할 수 있습니다 — 안내에 따라 진행하세요

STEP 5 — 환경 초기화 (반드시 실행)

💻 환경 초기화
/powerup
# "환경이 준비됐습니다" 또는 설정 안내가 나오면 성공
# 이 명령을 반드시 실행해야 Claude Code가 최적화됩니다
3-3 설치 완료 검증 🔗
확인 명령어정상 결과
node --versionv22.x.x 이상
claude --version1.x.x 이상
claude환영 화면 표시
🎉 세 가지 모두 통과하면 설치 완료입니다!

이 과정은 인생에서 딱 한 번입니다. 다음 장부터 5파일+ 사이클 학습이 시작됩니다.

3-4 자주 발생하는 설치 오류 10가지 🔗

설치 과정에서 오류가 났다고 포기하지 마세요. 이 오류들은 처음 설치하는 사람의 80%가 경험하는 일반적인 문제입니다. 아래 표에서 오류 메시지를 찾으면 해결 방법이 있습니다.

오류 메시지원인해결법
'node'은 인식되지 않습니다Node.js 미설치nodejs.org → LTS 설치 후 PowerShell 재시작
npm WARN deprecated...오래된 패키지 경고 (무해)무시하고 계속 진행
permission denied / EACCES관리자 권한 부족PowerShell "관리자 권한으로 실행"
ANTHROPIC_API_KEY not setAPI 키 미등록STEP 3을 다시 실행
rate_limit_exceeded요청 한도 초과Pro 플랜 확인 또는 잠시 대기
SSL certificate error보안 설정 문제VPN 끄기 또는 회사 방화벽 확인
Module not found패키지 누락npm install -g @anthropic-ai/claude-code 재실행
claude: command not found설치 경로 문제PowerShell 완전 종료 후 재시작
ENOENT: no such file폴더 경로 오류cd 명령으로 작업 폴더 이동 후 재시도
timeout / ECONNREFUSED인터넷 연결 문제인터넷 연결 확인 후 재시도
3-5 플랜별 차이 🔗
플랜월 비용 / 사용 한도이 책 강의에서
Free무료 / 하루 소량새2~3장 실습은 충분. 이후 Pro 권장
Pro$20 / 넉넉한 한도이 책 1탄 전 과정 가능. 권장
Max 5x$100 / Pro의 5배대형 앱·Agent Teams 장시간 활용
💡 비용 우려 시

21장 "토큰 최적화"를 적용하면 실제 부담은 표시 가격의 30~50% 수준으로 줄어듭니다. 처음에는 Pro로 시작하시고, 사용 패턴을 본 후 조정하시면 됩니다.

📌 3장 정리
  • 1️⃣ 핵심 한 줄: Claude Code 설치 = Node.js → claude-code 패키지 → API 키 → 첫 실행 → /powerup. 인생 한 번입니다.
  • 2️⃣ 5단계 설치 절차: ① Node.js 22 LTS → ② npm install -g @anthropic-ai/claude-code → ③ API 키 등록 (sk-ant-...) → ④ claude 첫 실행 → ⑤ /powerup 환경 초기화
  • 3️⃣ 검증 3종: node --version (v22.x+) + claude --version (1.x+) + claude (환영 화면)
  • 4️⃣ 오류 10가지 빠른 참조: 3-4 표 (PowerShell 관리자 권한·API 키 미등록·SSL·timeout 등)
  • 5️⃣ 플랜 권장: 처음에는 Pro ($20). 21장 토큰 최적화 적용 시 실부담 30~50% 절감.
  • 6️⃣ Claude Code의 자리: 9개 SDD 표준 도구(방법론) 위에서 작동하는 "AI 코딩 에이전트 런타임". 5파일+ 사이클은 Claude Code 위의 자체 방법론.
  • 7️⃣ 다음 장: 4장 — 5파일+ 사이클 학습 (1탄 v1.0 2장 "GSD 워크플로우"가 전면 재작성된 자리).
📘
1탄 도우미
질문하기 OK
안녕하세요! 프로젝트 초기화와 Claude Code 설치에 대해 무엇이든 물어보세요. 👇