1. 시작 전에
준비물 — 개인 노트북(여유 공간 20GB · 메모리 8GB 이상) · Claude 유료 플랜(Pro 이상) · Google 또는 이메일 계정
사용할 도구 — Claude Code (Mac: 데스크톱 앱 Code 탭 / Windows: 데스크톱 앱 또는 VS Code 확장) · Git · GitHub · Docker Desktop
바이브 코딩은 “무엇을 만들지”를 말로 설명하고, AI가 만든 결과를 눈으로 확인하며 고쳐 나가는 방식입니다. 코드는 AI가, 결정과 검증은 우리가 합니다.
알아 둘 용어 네 개
개념 | 무엇인가 · 오늘 실습에서 |
하네스 | 루프를 감싸는 실행 환경 — 어느 폴더에서, 어떤 도구를, 얼마나 허락을 물으며. Claude Code 앱이 곧 하네스 |
컨텍스트 | |
스킬 | 반복 절차를 문서로 묶어 둔 업무 매뉴얼 (예: 카파시 스킬) |
커넥터(MCP) | 에이전트의 손 — GitHub·Notion 같은 외부 서비스 연결 |
CLAUDE.md — 프로젝트 규칙 파일
# 우리 팀 아카이브
## 데이터
- Omeka S API: http://localhost:8080/api
- 템플릿: 기록 · 인물 · 장소 · 사건
## 규칙
- HTML/CSS/JS만, 라이브러리는 CDN으로
- 모든 페이지 utf-8, 반응형
- API 키는 .env에만, 코드에 쓰지 않는다
- 큰 작업 전엔 계획을 먼저 보여 준다
## 디자인
- 여백 넉넉히, 이미지 중심, 포인트 1색
Markdown
복사
카파시 스킬 한 줄로 받기: github.com/multica-ai/andrej-karpathy-skills 의 CLAUDE.md 내용을 이 폴더의 CLAUDE.md로 만들어 줘.
Git과 GitHub — 되돌릴 수 있어야 마음 놓고 시킨다
flowchart LR A["내 폴더<br>파일 수정"] -->|commit| B["로컬 Git<br>변경 이력"] -->|push| C["GitHub<br>원격 저장소"] -->|deploy| D["Pages<br>공개 URL"]
Mermaid
복사
용어 | 뜻 | Claude에게 이렇게 |
저장소 | 프로젝트 파일 + 전체 변경 이력 | “이 폴더를 git 저장소로 만들어 줘” |
커밋 | 변경을 기록한 스냅샷 하나 | “지금 상태를 커밋해 줘” |
푸시 | 커밋을 GitHub에 올리기 | “GitHub에 푸시해 줘” |
되돌리기 | 이전 커밋 상태로 복원 | “마지막 커밋 상태로 되돌려 줘” |
권한 모드와 모델
모드 | 동작 | 언제 |
Manual | 파일 수정·명령마다 허락을 묻는다 | 처음 5분 |
Accept edits | 편집은 자동, 명령 실행은 묻는다 | 권장 |
Auto | 안전한 작업은 자동, 위험한 것만 묻는다 | 익숙해지면 |
Plan | 코드는 안 바꾸고 계획만 | 큰 기능 전에 |
입력창 옆 선택기 또는 Shift+Tab에서 변경. 모델은 전송 버튼 옆 드롭다운 — 실습은 기본(Sonnet), 복잡한 설계는 Opus.
2. 개발환경 설치 따라하기
여섯 단계, 약 40분 — ① Claude 앱(10분) → ② 첫 세션(5분) → ③ Git(10분) → ④ GitHub 가입(3분) → ⑤ GitHub 연결(5분) → ⑥ Docker Desktop(10분 + 재부팅)
Windows는 ① 대신 ①-B VS Code + Claude Code 확장으로 진행해도 됩니다.
점검: 여유 공간 20GB 이상 · 메모리 8GB 이상 · Windows는 관리자 권한 계정. 각 단계의 
확인이 통과하면 다음으로.
확인이 통과하면 다음으로.① Claude 데스크톱 앱 — 다운로드와 설치
Claude 다운로드 페이지
claude.com/download 에서 내 운영체제용을 받습니다. macOS는 Intel·Apple Silicon 공용, Windows는 x64 / arm64 중 선택(설정 → 시스템 → 정보 → 시스템 종류).
Mac
1.
Claude.dmg 열기
2.
Claude 아이콘을 Applications 폴더로 끌어 놓기
3.
응용 프로그램에서 Claude 실행 → “열기” 허용
Windows
1.
Claude Setup.exe 실행 (자동 설치)
2.
시작 메뉴에서 Claude 실행
로그인과 Code 탭
1.
Anthropic 계정으로 로그인 (Google 계정 가능)
2.
상단 가운데 Code 탭 클릭
3.
업그레이드 안내가 뜨면 유료 플랜(Pro 이상) 구독, 로그인 요청이 다시 뜨면 로그인 후 앱 재시작
4.
Git 설치 안내가 뜨면 “나중에”를 누르지 말고 ③으로
Claude Code의 Git 설치 안내
확인: Code 탭에 입력창과 Local 선택기가 보인다①-B Windows 대안 — VS Code + Claude Code 확장
데스크톱 앱 대신 써도 됩니다. Windows에서 데스크톱 앱 설치·로그인이 잘 안 되거나, 코드와 파일을 한 화면에서 보고 싶다면 VS Code에 Claude Code for VS Code 확장을 설치해 같은 Claude Code를 씁니다. 같은 Claude 계정(Pro 이상)으로 로그인하고, API 키는 필요 없습니다. Mac에서도 똑같이 동작합니다.
1) VS Code 설치
VS Code 다운로드 페이지
1.
2.
동의 → 추가 작업 선택에서 “PATH에 추가”, “Code(으)로 열기” 작업 추가 체크 → 설치
3.
(선택) 한국어 화면: 확장에서 “Korean Language Pack” 설치 후 재시작
확인: VS Code 1.94 이상 (도움말 → 정보)2) Claude Code 확장 설치
왼쪽 활동 막대의 확장(Extensions) 아이콘과 검색창
설치할 확장: Claude Code for VS Code · 게시자 Anthropic
1.
왼쪽 활동 막대의 확장(Extensions) 아이콘 클릭 또는 Ctrl+Shift+X
2.
검색창에 Claude Code 입력
3.
Claude Code for VS Code (게시자 Anthropic, 인증 배지) → Install. 이름이 비슷한 다른 게시자의 확장은 설치하지 않습니다
4.
목록에 안 보이면 Ctrl+Shift+P → Developer: Reload Window
3) 작업 폴더 열고 Claude 패널 열기
편집기 오른쪽 위의 Spark(✱) 아이콘
1.
파일 → 폴더 열기 → my-archive 선택 → “작성자를 신뢰합니다” 클릭 (제한 모드에서는 확장이 작동하지 않음)
2.
아무 파일이나 하나 연 상태에서 편집기 오른쪽 위 주황색 Spark(✱) 아이콘 클릭
3.
아이콘이 안 보이면: 왼쪽 활동 막대의 Spark 아이콘 · 오른쪽 아래 상태 표시줄 ✻ Claude Code · Ctrl+Shift+P → “Claude Code: Open in New Tab”
4) 로그인하고 첫 요청
VS Code 오른쪽 Claude Code 패널에서 대화하는 모습
1.
2.
입력창 아래 모드 선택기에서 처음에는 Ask before edits(수동), 익숙해지면 Edit automatically. 큰 작업 전엔 Plan
3.
모델 변경은 입력창에 /model
4.
②의 확인용 프롬프트(hello.html)를 그대로 보내 보기 → 바뀐 내용은 편집기에 비교(diff) 화면으로 뜨고 수락/거절을 고릅니다
확장 전체 화면: 왼쪽 파일 탐색기, 가운데 편집기, 오른쪽 Claude 대화
단축키 (Windows) | 하는 일 |
Ctrl+Esc | 편집기  Claude 입력창 포커스 전환 |
Alt+K | 선택한 줄을 @파일#줄 형태로 입력창에 넣기 |
Ctrl+Shift+Esc | 새 대화 탭 열기 |
확인: 오른쪽 패널에서 Claude가 답하고, my-archive 폴더에 hello.html이 생겼다
이후 단계(Git·GitHub·Docker·Omeka S)는 데스크톱 앱과 똑같이 진행합니다. “Code 탭 입력창”이라고 쓴 곳은 VS Code의 Claude 패널로 읽으면 됩니다. Git은 ③대로 설치해야 하며, 설치 후 VS Code를 다시 시작하세요. VS Code 안의 터미널(Ctrl+\)에서 claude` 명령을 쓰려면 CLI를 따로 설치해야 하지만, 이 수업에서는 필요 없습니다.
② 첫 세션 열기
1.
Finder·파일 탐색기에서 작업 폴더 만들기: 홈/claude/my-archive
2.
입력창 아래 Local 선택 → Select folder → my-archive
3.
전송 버튼 옆에서 모델 선택, 권한은 Accept edits
4.
설치 확인용 프롬프트:
안녕! 이 폴더에 hello.html 파일을 만들고, "준비 완료"라고 크게 보이게 해 줘. 그리고 브라우저로 열어 줘.
Plain Text
복사
확인: my-archive 폴더에 hello.html이 생겼다 · 입력이 안 되면 Git이 없는 것 → ③③ Git 설치 — Windows
Git for Windows 설치 페이지
1.
2.
설치 파일 실행 → “예”(관리자 권한)
3.
편집기 선택 화면만 Use Notepad as Git’s default editor(VS Code가 있으면 VS Code)로 바꾸고 나머지는 모두 기본값 Next → Install
편집기 선택 단계
대안: PowerShell에서 winget install --id Git.Git -e --source winget
③ Git 설치 — Mac
방법 A (권장) — 터미널(응용 프로그램 › 유틸리티 › 터미널)에서:
xcode-select --install # 팝업에서 "설치" → 동의 → 5–10분
git --version
Bash
복사
방법 B — Homebrew를 쓸 사람:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 끝에 나오는 Next steps 두 줄도 실행
brew install git
Bash
복사
Homebrew 공식 사이트
비밀번호를 물으면 Mac 로그인 암호 (입력해도 화면에 안 보임).
③ Git 확인과 앱 재시작
git --version # git version 2.xx.x 가 나오면 성공
git config --global user.name "홍길동"
git config --global user.email "me@example.com" # GitHub 가입 이메일과 같게
Bash
복사
Claude 앱이 여전히 “Git을 설치하세요”라고 하면 완전 종료 후 재실행:
•
Windows: 작업 표시줄 오른쪽 ^ 트레이 → Claude 아이콘 우클릭 → 종료
•
Mac: 메뉴 막대 Claude → Quit Claude(⌘Q)
트레이에서 Claude 종료
④ GitHub 가입
GitHub 로그인·가입 화면
1.
github.com → Sign up (Google 계정으로 가입 가능)
2.
이메일 인증 코드 입력 → 사용자 이름(Username) 정하기
3.
아이디 = 주소: https://아이디.github.io/my-archive/ — 짧고 말하기 쉬운 이름으로
⑤ GitHub 연결
방법 A · 브라우저 인증 (권장) — 세션 입력창에:
이 로컬 저장소를 내 깃허브 저장소와 연결해 줘.
Plain Text
복사
Connect to GitHub 팝업 → Sign in with your browser → 계정 확인 후 Authorize git-ecosystem → 이메일 인증 코드 입력 → 연결 완료
Connect to GitHub 팝업
Authorize git-ecosystem
방법 B · 커넥터 — 앱 설정 → 커넥터(Connectors) → GitHub → 연결 → 브라우저 로그인 → Authorize
확인: “GitHub에 test-repo라는 비공개 저장소를 만들어 줘”가 성공하면 연결 완료저장소 만들기 — 배포할 거라면 Public
GitHub에 my-archive라는 공개 저장소를 만들고 이 프로젝트를 푸시해 줘. README도 만들어 줘.
Plain Text
복사
직접 만들 때: Repositories → New → 이름·Public → Create → 주소를 Claude에게 “여기로 푸시해 줘”
Repository 공개 범위 선택
GitHub Pages 무료 배포는 Public 저장소에서만. .env(키·비밀번호)는 절대 올리지 않습니다.
⑥ Docker — 딱 세 개념
개념 | 비유 | 한 줄 정의 |
이미지 | 밀키트 | 프로그램 + 실행 환경을 통째로 포장한 꾸러미. Docker Hub에서 내려받는다 |
컨테이너 | 차린 한 상 | 이미지를 실행한 상태. 지우고 다시 만들어도 항상 같은 결과 — 망가뜨려도 된다 |
Compose | 차림표 | Omeka S + DB를 docker-compose.yml 한 장으로 띄우고 치운다 |
왜 쓰나: ① 내 노트북에서 되면 팀원 노트북에서도 ② Apache·PHP·MySQL을 직접 깔지 않는다 ③ 볼륨 덕분에 컨테이너를 지워도 파일·DB는 내 폴더에 남는다
⑥ Docker Desktop 설치 — Mac
Docker 문서 Mac 설치 페이지
1.
내 칩 확인: Apple 메뉴 → 이 Mac에 관하여 → “칩”이 Apple M 시리즈면 Apple silicon, Intel이면 Intel
2.
docs.docker.com/desktop/setup/install/mac-install 에서 맞는 버튼으로 Docker.dmg 다운로드
3.
열어서 고래 아이콘을 Applications로 끌어 놓기 → Docker 실행
4.
서비스 약관 Accept → 설정 화면이 나오면 Use recommended settings → Finish (Mac 암호)
5.
로그인 화면은 Skip 해도 됨
확인: 메뉴 막대에 고래 아이콘, 대시보드에 “Engine running”요구사항: 최근 3개 macOS · RAM 4GB 이상 · 개인·교육용 무료(직원 250명 이상 기업은 유료)
⑥ Docker Desktop 설치 — Windows
Docker 문서 Windows 설치 페이지
1.
2.
Installer.exe 실행 → “예”
3.
Configuration에서 Use WSL 2 instead of Hyper-V 체크 유지 → OK
4.
Close and restart → 재부팅
5.
Docker Desktop 실행 → 약관 Accept (로그인은 Skip 가능)
확인: 트레이에 고래 아이콘 · “Engine running”•
WSL 오류: PowerShell(관리자)에서 wsl --install 또는 wsl --update → 재부팅
•
“가상화 꺼짐”: BIOS/UEFI에서 Virtualization(Intel VT-x · AMD SVM) 켜기. 작업 관리자 → 성능 → CPU의 “가상화: 사용”으로 확인
요구사항: Windows 10 22H2(19045) / 11 23H2 이상 64비트 · RAM 8GB · BIOS 가상화 활성
⑥ Docker 실행 확인
Docker Desktop 대시보드
docker --version
docker compose version
Bash
복사
•
권장: Settings → Resources → Memory 4GB 이상
•
Containers 탭에서 시작·중지·로그 보기가 전부 버튼
•
Omeka S를 쓰는 동안 Docker Desktop은 켜 두기
설치 트러블슈팅
증상 | 해결 |
Code 탭에서 업그레이드 안내 | Pro 이상 플랜 구독 후 앱 재시작 |
입력창에 글자가 안 써짐 / “Git 설치” 안내 | Git 설치 → 앱 완전 종료(트레이·⌘Q) → 재실행 |
Mac “확인되지 않은 개발자” | 시스템 설정 → 개인정보 보호 및 보안 → “그래도 열기” |
git: command not found | 터미널을 새로 열기. 그래도 안 되면 재설치 |
GitHub 푸시 시 인증 실패 | “GitHub 인증을 다시 해 줘” → 브라우저 로그인 · 커넥터 재연결 |
Docker “WSL 2 installation is incomplete” | PowerShell(관리자) wsl --update → 재부팅 |
Docker “Virtualization not enabled” | BIOS/UEFI에서 Intel VT-x · AMD SVM 켜기 |
Docker 엔진이 계속 Starting | 종료 후 재실행 → 안 되면 Troubleshoot → Restart |
그 밖의 모든 에러 | 에러 메시지를 통째로 Claude에게: “이 에러 그대로야. 원인 찾아서 고쳐 줘” |
3. 내 노트북에 Omeka S 띄우기
① 프로젝트 준비 — 완성되면 이런 모습
my-archive/
├─ CLAUDE.md # 작업 규칙
├─ docker-compose.yml # 차림표
├─ .env # 비밀번호·키 (커밋 금지)
├─ .gitignore
├─ omeka/ # 볼륨: files/ modules/ themes/
├─ uploads/ # 원자료·참고자료
├─ data/ # 정제한 CSV·JSON
└─ site/ # 바이브 코딩 화면
Plain Text
복사
1.
Code 탭 → New session → Local → my-archive 폴더
2.
3.
uploads/에 팀 원자료 넣기
② [실습] Omeka S 인스턴스 생성
실습 프롬프트의 2-1 환경 구축 프롬프트를 팀 상황에 맞게 다듬어 보냅니다. 계획 읽기 → “진행해” → Docker 대시보드에 컨테이너 2개 → 브라우저에 설치 화면 (약 5–10분).
③ localhost — 내 노트북이 서버가 된다
http:// (프로토콜) + localhost (내 컴퓨터) + :8080 (문 번호·포트) + /admin (경로)
1.
localhost:8080 → 관리자 이메일·비밀번호·사이트 이름 입력
2.
localhost:8080/admin 로그인 — 데모에서 한 것을 이제 내 것에서
3.
Modules → Install · Activate (Mapping · Custom Vocab · Value Suggest · CSV Import 등)
localhost는 나만 볼 수 있습니다. 남에게 보여 주려면 배포가 필요합니다.
④ 막혔을 때의 대화법
실습 프롬프트의 6-1 원인부터 좁히기 사용 — 원인 가설 → 확인 → 확정 전에는 수정 금지.
⑤ Omeka S API와 키
•
읽기는 공개, 쓰기(등록·수정·삭제)는 키 필요
•
발급: 관리자 → Users → 내 계정 → API keys 탭 → 라벨 → key_identity · key_credential (credential은 한 번만 보임)
•
Claude에게 주소와 키를 알려 주고 .env에 저장하게 한다. 키는 코드·노션·카톡에 쓰지 않는다
•
.env는 .gitignore에. 커밋 이력에 한 번이라도 찍히면 폐기·재발급
⑥ 데이터 수집·정제·설계 (강사 멘토링)
flowchart LR A["1 수집<br>uploads/"] --> B["2 정제<br>data/*.csv"] --> C["3 설계<br>열↔속성 매핑"] --> D["4 적재<br>CSV Import · API"]
Mermaid
복사
멘토링 점검: 아이템 20건 이상? · 장소에 좌표? · 사건에 날짜? · 관계 필드가 있나? — AI가 채운 값은 사람이 검증한다.
4. 과제와 배포, 발표
과제 — 기본 1 + 선택 2 이상
구분 | 화면 | 도구 · 필요한 데이터 |
기본 | 컬렉션 · 아이템 페이지 | 카드 목록 + 필터 + 상세(메타데이터·이미지·관련 자료) |
선택 A · 시간 | Timeline 연표 | TimelineJS · vis-timeline — 사건의 날짜 |
선택 B · 장소 | 장소 스토리텔링 | StoryMapJS · Leaflet — 장소의 좌표 |
선택 C · 관계 | 관계망 시각화 | vis-network · Cytoscape — 인물·장소·사건 연결 |
선택 D · 질문 | 자연어 검색 | LLM(Anthropic API 키 또는 Ollama)이 질문을 검색 조건으로 변환 |
통합 | 하나의 전시 페이지 | 소개 → 지도 → 연표 → 관계망 → 결론 |
화면별 프롬프트는 실습 프롬프트 4장 참고. 관계망을 만들었다면 “연결이 가장 많은 노드 3개는 왜 그런가”를 한 문장으로 해석해 오세요.
[팀 실습] 기획안 한 장 — 15분 작성, 2분 발표
•
주제·제목 — 무엇에 관한 아카이브인가
•
이용자 1–4순위 — 누가 무엇을 찾으러 오는가
•
원자료 — 형식·건수·권리(공개 가능한가)
•
클래스·관계 — 개체 유형 3–5개, 주요 트리플 5개
•
만들 화면 — 기본 + 선택 2개, 화면을 말로 그리기
•
역할 분담 — 데이터 정제 · Omeka 입력 · 화면 개발 · 발표
11/10 배포 — 로컬을 넘어 공개 URL로
•
GitHub Pages: 저장소 Settings → Pages → Branch main · /(root) → Save → 1–2분 뒤 아이디.github.io/저장소
•
정적 배포는 “그 순간의 사본” — localhost의 Omeka S는 인터넷에서 보이지 않습니다. 배포 직전에 API로 data.json을 받아 함께 올리고, Omeka를 고치면 다시 받아 재배포합니다.
최종 발표와 평가
공개 URL을 열고 세 가지를 말합니다: ① 무엇을 보여 주나 ② 가장 잘 통한 프롬프트 ③ 막혔던 곳 하나
평가 기준 | 보는 것 |
데이터 설계 | 표준 어휘 사용, 클래스·관계의 타당성, 기술의 일관성 |
화면 구현 | 이용자가 탐색할 이유가 있는가, 동작하는가 |
설명 책임 | AI가 만든 코드의 각 부분이 왜 있는지 설명할 수 있는가 |
참고자료
•
•