> [!info] 이 수업안의 원칙 > - 차시당 **2시간** 분량 (설명 60분 + 실습 60분) > - 각 차시 = **다이어그램 1장 + eli5 블록 1개 + 실습 체크리스트 1개** > - 본문 개념은 [[Claude Code 실전 가이드]]참조. 이 문서는 **진행 스크립트**. --- ## 📚 전체 개괄 | 차시 | 주제 | 핵심 산출물 | |---|---|---| | 1 | 왜 하네스인가 | CLAUDE.md 1페이지 | | 2 | 5단계 파이프라인 사고법 | 요구사항 4요소 MD | | 3 | 9단계 설계 대화 | PRD·Flow·Schema·Architecture·ADR 5종 | | 4 | 훅·MCP·메모리 | 나만의 Hook + MCP 세팅 | | 5 | 스킬·서브에이전트·팀 | 나만의 plan-and-build 스킬 | | 6 | 하네스 스택·실전 라이브 | MVP 1개 완성 + Railway 배포 | --- ## 차시 1 — 왜 하네스인가 (개론) ### 🎯 학습 목표 - 바이브 코딩 → 에이전틱 엔지니어링 → 하네스 엔지니어링 개념 전환 - Claude Code 설치·인증·첫 세션 + `/init`으로 CLAUDE.md 생성 - **4-레이어 하네스 + Context7 MCP** 설치 ### 🧰 설치 명령 (복붙용) ```bash # 4-레이어 하네스 /plugin marketplace add obra/superpowers /plugin install superpowers /plugin marketplace add Yeachan-Heo/oh-my-claudecode /plugin install oh-my-claudecode /oh-my-claudecode:omc-setup /plugin marketplace add garrytan/gstack /plugin install gstack /plugin marketplace add karpathy/autoresearch /plugin install autoresearch # Context7 MCP claude mcp add context7 -- npx -y @upstash/context7-mcp@latest ``` ### 🔗 4-레이어 GitHub 레포 - **Superpowers** — [github.com/obra/superpowers](https://github.com/obra/superpowers) - **OMC** — [github.com/Yeachan-Heo/oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) - **gstack** — [github.com/garrytan/gstack](https://github.com/garrytan/gstack) - **autoresearch** — [github.com/karpathy/autoresearch](https://github.com/karpathy/autoresearch) ### 📊 다이어그램 🎨 **[다이어그램 1 — 입력·출력 명확히](https://excalidraw.com/#json=QTLQkN5ZHZqalZTnrIxlb,AAL02WcMv5F1GKDORIshIg)** ### 🐣 eli5 (5줄 요약) 1. **바이브 코딩** = AI한테 "대충 만들어줘" 던지기 2. **에이전틱 엔지니어링** = AI한테 "이 순서로 만들어줘" 체계화 3. **하네스** = 그 순서를 매번 자동으로 강제하는 장치 4. 하네스 없으면 AI가 지 멋대로 움직여 결과가 오락가락 5. 하네스 잘 만들어 놓으면 **남도 내 방식대로 AI를 쓸 수 있음** = 유능함의 복제 ### 💬 강의 핵심 인용 > "코딩할 줄 안다고 개발자가 아니에요. 코드 쓰는 것 자체가 어려운 게 아니라, 이 코드가 유지보수·기술부채·의사결정에 맞는지를 판단하는 게 어려운 겁니다." --- ## 차시 2 — 5단계 파이프라인 사고법 (핵심) ### 🎯 학습 목표 - **Clarify → Context Gather → Plan → Generate → Evaluate** 5단계 체화 - 요구사항 4요소(요구/구현/제약/완료) 작성 - "메인 세션 컨텍스트는 양질 지식 저장고" 철학 체화 ### 📊 다이어그램 - 🎨 **[다이어그램 1 — 입력·출력](https://excalidraw.com/#json=QTLQkN5ZHZqalZTnrIxlb,AAL02WcMv5F1GKDORIshIg)** - 🎨 **[다이어그램 2 — 5단계 파이프라인](https://excalidraw.com/#json=iaMhMvVX1orRTdmNwVX8r,4Z89LVQ-L028Lf5oZtpDfg)** ### 🐣 eli5 1. AI한테 일 시킬 때 순서가 있다: **질문 → 탐색 → 설계 → 구현 → 검증** 2. 이 5단계 중 하나라도 빠지면 결과물이 엉망 3. 대충 시키면 AI가 중간 단계 건너뛰고 그냥 만듦 4. 그래서 **5단계를 매번 강제하는 것**이 하네스의 핵심 5. 이 5단계를 에이전트 5개로 쪼개면 **메인 세션 컨텍스트가 보존됨** ### 📌 실습 프롬프트 **프롬프트 A — 입력·출력 정의** ``` 나는 [내 도메인]을 일하는 [역할]이다. 내 업무에서 자주 반복하는 작업의 입력→출력을 3개 적는다: 1. [입력] → [출력] 2. [입력] → [출력] 3. [입력] → [출력] 이 중 어느 것을 하네스화하면 가장 큰 ROI가 나올지 평가하고, 하네스 만들 때 빠지기 쉬운 함정 3개를 알려줘. ``` **프롬프트 B — 요구사항 4요소 작성** ```markdown # 앱 이름: [이름] ## 요구사항 (비개발자 관점으로 뭘 만들 건지 — 기능 목록 위주) ## 구현 디테일 (가능한 만큼 개발자 관점. 모르면 "네가 추천해"라고 지시) ## 제약 조건 (안 할 것들. 이게 있어야 AI가 엉뚱한 짓 안 함) - 로그인 안 만든다 - 서버 DB 지금은 안 쓴다 - ... ## 완료 기준 (어떤 상태면 완료라고 판단할지) - [ ] [기능 1] 정상 작동 - [ ] [기능 2] 정상 작동 ``` ### 💬 강의 핵심 인용 > "보통 이렇게 안 이렇거든요. 그래서 이거부터 꼭 정하셔야 되고요." --- ## 차시 3 — 9단계 설계 대화 (1시간 MVP 재현) ### 🎯 학습 목표 - **9단계 설계 대화** 체득 (구현가능성 → 기술스택 → 흐름 → 화면 → API → 데이터 → 아키텍처 → ADR → 문서) - 역할 페르소나 기법 (공동 창업자·UX 리서처·CTO) - **AI 에이전트용 문서 3원칙** 주입 ### 📊 다이어그램 🎨 **[다이어그램 6 — 9단계 설계 대화 맵](https://excalidraw.com/#json=HogqyN0YyriVdpixbH53I,XwWbi5TCmkWw5kzp1excOQ)** ### 🐣 eli5 1. AI한테 "MVP 만들어줘" 한 번에 던지면 망함 2. 대신 **9단계**에 걸쳐 AI랑 티키타카하면서 구체화 3. 각 단계마다 AI 역할을 바꿔줌 (공동 창업자 → UX 리서처 → CTO) 4. 끝나면 **5개 MD 파일**로 의사결정을 기록 5. 그 5개 MD가 구현 세션에 "설계서"로 전달 → **90분에 MVP 완성** ### 📌 실습 프롬프트 **프롬프트 C — 1단계: 구현 가능성 검증 (공동 창업자 역할)** ``` 지금부터 위 요구 사항을 구현하기 위한 설계를 시작할 것이다. 첫 단계는 구현 가능성 검증이다. 너는 나의 공동 창업자고 우리의 목표는 빠르게 스타트업을 만들어 다음 Y 콤비네이터 배치에 합격하는 거다. 그걸 위해서 우리는 빠르게 MVP를 출시하고 시장의 반응을 보면서 여러 가설을 테스트해야만 한다. 속도는 생명이다. 그러면서도 안정적인 서비스를 만들어야 한다. 이 둘 간의 트레이드오프를 명심해라. 그럼 지금부터 시작하자. 네가 주도적으로 구현 가능성을 점검하고, 조금이라도 모호하거나 구체화해야 할 것이 있다면 나와 논의하자. ``` **프롬프트 D — 3단계: 사용 흐름 (UX 리서처 역할)** ``` 다음은 사용자 흐름을 논의하고 싶어. 구현 가능성 때처럼 조금이라도 모호하거나 구체화하고 싶은 게 있으면 내게 말해 줘. 참고로 너는 이제부터 구글 시니어 UX 리서처로서 응답하면 돼. 이번 단계에서 네가 지향해야 할 것은 이 앱을 사용하는 주요 흐름이 내 머릿속에 생생히 재현돼서 그대로 앱으로 바로 옮길 수 있을 정도로 명확해지는 것이다. 이 수준에 도달하지 못했다면 전부 잡아내야 돼. 그럼 이제 시작해 보자. ``` **프롬프트 E — 9단계: 최종 문서화 (AI 에이전트 3원칙)** ``` 좋아. 이제 우리가 지금까지 논의한 내용을 바탕으로 분석·문서를 생성하자. 다음 문서들이 필요하다: - PRD.md - Flow.md - Schema.md - Architecture.md - ADR.md 참고로 이 문서들을 만들 때는 다음 주의사항을 반드시 숙지해서 적절한 내용으로 구성해라: 이 문서는 대체로 AI 에이전트를 위한 것이다. 그들의 컨텍스트를 낭비하지 않도록 같은 내용이라도 더 간결하게 쓸 수 있도록 해야 한다. 간결한 문서를 추구하되 의사 결정 맥락, 결정 의도와 같은 맥락적 정보가 아예 제거되어서도 안 된다. 이 문서를 보고 AI 에이전트가 우리의 기획적·개발적 철학을 온전히 추론할 수 있어야 한다. ``` ### 💬 강의 핵심 인용 > "생각보다 번거로워 보이는데 '이게 무슨 딸각이냐' 싶을 수 있는데, 이거는 사실 내 생각을 정리하는 관점에서 그냥 해야 되는 거예요. 이걸 안 거치고 그냥 만들면 나한테 필요한 게 아니라 그럴싸한데 필요 없는 무언가가 나와요." --- ## 차시 4 — 훅·MCP·메모리 (자동화 인프라) ### 🎯 학습 목표 - **Hook 4종** (PreToolUse / PostToolUse / Notification / Stop) 실전 - **MCP 연동** (Context7 · Supabase · Firecrawl · Brave · Excalidraw) - **Auto Memory** 200줄 인덱스 패턴 ### 📊 다이어그램 (차시 4는 기존 [[[Claude Code 실전 가이드]]섹션 6·7 참조. 추가 다이어그램 없음) ### 🐣 eli5 1. **Hook** = Claude가 뭔가 할 때마다 "그때 이 명령어도 돌려" 지시 2. **MCP** = Claude가 외부 DB·API·브라우저 쓰게 해주는 연결선 3. **메모리** = Claude가 스스로 배운 걸 다음 세션에도 기억하게 해주는 파일 4. 이 셋 잘 세팅하면 "매번 같은 설명" 안 해도 됨 5. 단 메모리 너무 채우면 컨텍스트 먹으니 **200줄 인덱스 패턴** 필수 ### 📌 실습 프롬프트 **프롬프트 F — Stop Hook (텔레그램 알림)** ``` .claude/settings.json에 Stop 이벤트 hook을 추가해서 작업이 끝날 때마다 텔레그램으로 "빌드 완료" 메시지를 보내게 해줘. 내 텔레그램 봇 토큰은 @daniel8824_bot이고 chat_id는 [ID]. ``` **프롬프트 G — MCP 다중 설치** ```bash claude mcp add context7 -- npx -y @upstash/context7-mcp@latest claude mcp add --transport http github https://api.githubcopilot.com/mcp/ claude mcp add supabase -- npx -y @supabase/mcp-server-supabase@latest --project-ref [YOUR_REF] # Claude Code 재실행 후 > /mcp # 연결 상태 확인 ``` ### 💬 강의 핵심 인용 > "알림 Hook을 설정해 두면, 여러 Claude 세션을 동시에 돌릴 때 '입력 대기 중'인 세션을 즉시 감지할 수 있습니다." — Boris Cherny (Anthropic) --- ## 차시 5 — 스킬·서브에이전트·팀 (실행 인프라) ### 🎯 학습 목표 - **스킬 1개 → 서브에이전트 분리 → 스크립트 오케스트레이션** 진화 체득 - 내장 / Anthropic / 커뮤니티 / 플러그인 스킬 지도 - 내 도메인용 `plan-and-build` 스킬 포크 ### 📊 다이어그램 - 🎨 **[다이어그램 3 — 구현 파이프라인](https://excalidraw.com/#json=nUisX8_s6gQqLFVFpiRfa,29MDgraMaMa1uXwPK_QvlA)** - 🎨 **[다이어그램 4 — 하네스 진화 3단계](https://excalidraw.com/#json=TZkC3q9tY78lzTb0bUQBQ,MrTMgmi8-B10JMaugK2IRQ)** - 🎨 **[다이어그램 5 — 컨텍스트 흐름](https://excalidraw.com/#json=QKXmTbmCG3l9hwVmSf_aO,jDB69ms6g9iV9syL_iSijA)** ### 🐣 eli5 1. **스킬** = Claude한테 "이 방식으로 일해" 가르치는 MD 파일 2. 처음엔 **스킬 1개**로 시작 (작업 전체를 하나에 기록) 3. 커지면 **5단계별로 서브에이전트 쪼개서** 병렬 가능 4. 그때 메인 세션이 서브들 관리하면 컨텍스트 먹음 5. → **파이썬 스크립트**가 오케스트레이션하면 메인은 깨끗 유지 ### 📌 실습 프롬프트 **프롬프트 H — 스킬 생성 (Stage 1)** ``` 다음과 같이 작동하는 스킬을 만들어라: [5단계 파이프라인 본문 붙여넣기 — Clarify/Context/Plan/Generate/Evaluate 정의] 스킬 이름은 "plan-and-build"로 하고 .claude/skills/plan-and-build/SKILL.md에 저장. 각 단계에서 사용자와 어떤 상호작용을 해야 하는지도 명시. ``` **프롬프트 I — 스킬 → 서브에이전트 분리 (Stage 2)** ``` 이 하네스 파이프라인을 개선하고 싶다. 각 단계별로 별도의 서브에이전트로 호출하고 해당 서브에이전트가 결과를 아티팩트(MD 파일)로 생성해서 다음 단계에 전달하도록 구축하자. - Clarify 서브에이전트 → clarify_output.md - Context Gather 서브에이전트 → context_output.md - Plan 서브에이전트 → plan_output.md - Generate 서브에이전트 → 구현 코드 - Evaluate 서브에이전트 → verification_report.md 오케스트레이션은 scripts/run_harness.py 파이썬 스크립트로 구현. index.json 체크포인트로 중단·재개 가능하게. ``` ### 💬 강의 핵심 인용 > "처음부터 협력 관계를 설계하려고 하면 어렵거든요. 그러니까 일단 스킬로 만드시고요. 사실 대부분의 문제는 그냥 스킬을 잘 하나 만드는 것만으로도 해결될 가능성이 높아요." --- ## 차시 6 — 하네스 스택 & 실전 라이브 ### 🎯 학습 목표 - **4-레이어 하네스 협력 모델** (Superpowers · OMC · gstack · autoresearch) - **"최선이야?" 채찍질 기법** + **오토리서치** 실전 - **문서 diff 기반 기능 추가** — 출시된 앱 업그레이드 루틴 - Railway + Supabase 배포까지 한 번에 ### 📊 다이어그램 🎨 **[다이어그램 7 — 4-레이어 하네스 협력 모델](https://excalidraw.com/#json=8DSmiuRElQXI6c-sL5FLJ,clodtQFdb7k5LlVbJknvCQ)** > 📝 **2026-04-25 추가 검증** — 본 수업안의 4-레이어는 베이스. 실제는 **6-Layer + 외부 CLI 도구 2개**로 확장됨: > - 5번째 레이어 **OMO** (code-yeongyu/oh-my-openagent ★53,993) — Planning 메타 (prometheus/metis/momus) > - 6번째 레이어 **pro-workflow** (rohitg00/pro-workflow ★2,007) — Self-correcting memory (handoff/replay/learn-rule + 5 utility) > - 외부 CLI: **tobi/qmd** ★23,122 (Tobias Lütke, Shopify CEO) · **getcompanion-ai/feynman** ★5,780 > - 자세히: [[2026-04-25 스킬 분류표]] · [[research-2026-04-25-planning-skills-audit]] · 카탈로그 https://daniel8824-del.github.io/claude-skill-catalog/ ### 🐣 eli5 1. **하네스** = Claude한테 일 시키는 공장 2. **Superpowers** = 공장 운영 매뉴얼 (언제 뭘 할지) 3. **OMC** = 공장 작업자들 (에이전트들) 4. **gstack** = 공장 안전장치 + 특수 공구 5. **autoresearch** = 공장이 스스로 개선하는 엔진 (반복 실험) ### 📌 실습 프롬프트 **프롬프트 J — "최선이야?" 3연타** ``` (AI 답변 받은 후) 1차: "그게 최선 맞아? 확실해?" 2차: "성능적으로 최선이야? 네가 구글 시니어 개발자라도 이렇게 짤 거 같아?" 3차: "병렬로 돌리면 어떨까? [다른 관점]으로도 고려해봤어? 더 나은 접근은 없어?" ``` **프롬프트 K — 오토리서치** ``` [도메인]의 [정량 목표]를 달성하고 싶다. 실험 데이터는 [데이터 경로]에 있다. [정확한 목표치 설명 — 예: 영상 N개 각각의 카운트 시점들과 허용 오차] 내 목표는 파라미터를 조금씩 바꿔가며 자동으로 반복 실행하는 파이썬 스크립트를 만드는 것이다. 모든 목표치를 잘 맞추면서 아닐 때 안 잡는 최적값을 찾아라. [본 플랫폼]과 달리 파이썬은 반복 실행이 빠르니 파이썬으로 실험하고 최적 파라미터만 찾아서 [본 플랫폼]으로 이식한다. ``` **프롬프트 L — 문서 diff 기반 기능 추가** ``` 기능 추가: [기능 설명] 플랜앤빌드 스킬을 사용하되, phase_0에서 다음 문서들을 반드시 먼저 업데이트해라: - docs/PRD.md - docs/Flow.md - docs/Schema.md - docs/Architecture.md - docs/ADR.md 문서 변경의 diff를 artifact/doc_changes.md로 추출해서 phase_1 이후의 서브에이전트가 이 파일을 참조하도록 구성해라. ``` **프롬프트 M — 로그인 + Railway + Supabase 배포** ``` 난 로그인 기능을 이 앱에 붙이고 싶어. 다음 내용을 참고해서 작업해 줘. 플랜앤빌드 스킬을 사용하면 돼. [요구사항 4요소 붙여넣기] ## 구현 디테일 - 서버는 Railway에 배포 - DB는 Supabase 사용 - Railway CLI 지원 → 서버 배포 자동화 - Supabase MCP 지원 → 스키마 마이그레이션 자동화 - JWT 직접 구현 (Supabase Auth 안 씀) ``` ### 💬 강의 핵심 인용 > "유능한 작업자는 그 사람 한 명이 유능한 거잖아요. 그런데 하네스를 잘 만드는 작업자는 유능함을 복제시키는 사람이에요. 그래서 조직에 기여할 수 있는 수준이 차원이 다릅니다."