## 0. 들어가며 > [!quote] Andrej Karpathy, 2025.02 "There's a new kind of coding I call 'vibe coding'." > [!quote] Andrej Karpathy, 2026.02 "My current favorite term is **'agentic engineering'**: orchestrating agents who write code, acting as oversight." - 코드를 직접 쓰는 게 아니라, AI 에이전트를 오케스트레이션하고 감독하는 것이 엔지니어의 역할 - 왜 Claude Code인가? - IDE가 아니라 터미널 에이전트 - 파일 읽기/편집/명령어 실행을 자율적으로 수행 - 메모리 시스템 (CLAUDE.md + Auto Memory)으로 프로젝트 맥락 누적 - MCP 프로토콜로 무한 도구 확장 - Ralph Loop로 끝날 때까지 자율 반복 ## 1. 설치 ### 1-1. macOS / Linux / WSL ```bash # 방법 1: Native Installer (추천 - Node 불필요, 자동 업데이트) curl -fsSL https://claude.ai/install.sh | bash # 방법 2: Homebrew brew install --cask claude-code # 방법 3: npm (Node 18+ 필요) npm install -g @anthropic-ai/claude-code ``` ### 1-2. Windows ```powershell # PowerShell (관리자) irm https://claude.ai/install.ps1 | iex ``` ### 1-3. 설치 확인 & 업데이트 ```bash # 버전 확인 claude --version # 업데이트 claude update ``` ### 1-4. 인증 플랜 - Pro - $20/월 - Max - $100/월 - Max - $200/월 - API - Anthropic Console 충전 ## 2. 기본 실행 ### 2-1. 프로그램 실행 ```bash cd my-project claude # → 브라우저가 열리면서 OAuth 인증 (최초 1회) # → "이 폴더를 신뢰합니다" 클릭 # → 대화형 모드 진입 ``` ### 2-2. 권한 모드 전환 ```markdown Plan 모드 → 읽기만 가능, 코드 수정 불가, 설계/분석용 Default → 도구 사용 시 승인 요청, 일반 개발 Auto-accept → 모든 도구 자동 승인, 빠른 실행 ``` > [!quote] Boris Cherny "Plan 모드로 시작해서 계획을 다듬고, Auto-accept로 전환해서 한 번에 완성한다." ### 2-3. 모델 선택 ```bash /model # opus: 가장 똑똑 (비쌈, 복잡한 작업) # sonnet: 기본 (일반 작업) # haiku: 가볍고 빠름 (간단한 검색) ``` > [!quote] Boris Cherny "가장 똑똑한 모델을 최대 성능으로 써라. 느리지만 결국 더 빠르다. 덜 고쳐도 되니까." ## 3. 기본 명령어 ### 3-1. 세션 관리 ```bash # 새 세션 시작 claude # 최근 세션 이어가기 (--continue) claude -c # 세션 목록에서 선택 (--resume) claude -r # 상세 로그 (디버깅용) claude --verbose ``` ### 3-2. 슬래시 명령어 ```markdown /help 도움말 /clear 대화 초기화 ★ 새 작업 시작 전 필수! /compact 컨텍스트 압축 (토큰 절약) ★ /model 모델 변경 /init 프로젝트 분석 → CLAUDE.md 자동 생성 /memory 메모리 편집 (Auto Memory) /hooks Hook 설정 /permissions 도구 권한 관리 /mcp MCP 서버 상태 확인 /status 계정 & 시스템 상태 /doctor 환경 점검 체크리스트 /config 환경 설정 ``` > [!quote] clear를 자주 사용하세요. 새 작업을 시작할 때 컨텍스트를 비워야 할루시네이션이 줄고 윈도우를 최대로 활용할 수 있습니다. > [!quote] compact를 직접 실행하지 않으면 컨텍스트가 넘칠 때 auto-compact가 자동 실행됩니다. 자동 요약은 타이밍이 나빠서 정보 손실이 클 수 있으므로, 적절한 시점에 직접 compact를 실행하는 게 좋습니다. ### 3-3. 키보드 단축키 ```markdown Esc 실행 중단 ★ 잘못된 방향이면 과감하게! Ctrl+C 종료 Up/Down 이전 프롬프트 탐색 Ctrl+V 이미지 붙여넣기 @파일명 파일 태그 (Tab으로 탐색) #메모 CLAUDE.md에 빠르게 메모 추가 ``` > [!quote] Esc를 두려워하지 마세요. Claude가 잘못된 방향으로 가고 있으면 과감하게 중단하세요. 컨텍스트 오염을 방지합니다. ## 4. 프로젝트 초기화 ### 4-1. init 명령어 ```bash cd my-project claude > /init # → 프로젝트 전체를 분석 # → CLAUDE.md 파일 생성 ``` > [!quote] 새 프로젝트를 시작하면 반드시 init을 실행하세요. ### 4-2. CLAUDE.md ```markdown ~/.claude/CLAUDE.md ← 글로벌 (모든 프로젝트 공통 규칙) /project/CLAUDE.md ← 프로젝트 규칙, 구조, 명령어 /project/src/CLAUDE.md ← 디렉토리 (하위 폴더 전용) ``` > [!quote] src/CLAUDE.md를 만들면 Claude가 폴더에 진입할 때만 읽습니다. CLAUDE.md가 비대해지는 걸 막고 컨텍스트를 절약할 수 있습니다. ## 5. 메모리 시스템 ### 5-1. Auto Memory - 기존에는 CLAUDE.md에 직접 쓰지 않으면 세션이 끝나면 다 잊어버렸습니다. - Auto Memory는 Claude가 작업하면서 스스로 배운 것을 자동으로 기록하는 기능입니다. ### 5-2. 위치 & 구조 ```markdown ~/.claude/projects/<project-hash>/memory/ MEMORY.md ← 인덱스 (최대 200줄, 매 세션 자동 로드) debugging-patterns.md ← 상세 메모 (필요할 때만 로드) ``` > [!quote] MEMORY.md는 내용이 길어지면 별도 MD 파일로 분리하고 링크합니다. 이렇게 하면 토큰 절약 및 컨텍스트 최적화를 할 수 있습니다. ### 5-3. 사용 방법 ```bash # 기본 활성화 # Claude가 알아서 판단해서 자동 기록 # 수동 기록 # 사용자가 직접 지시 > 이 내용을 메모리에 저장해줘. # 옵션 설정 > /memory # → Auto Memory 토글 표시 # → User, Project, Folder 선택 ``` ## 6. Hooks ### 6-1. Hook이란? - Claude Code의 이벤트 기반 자동화 시스템 - 특정 이벤트가 발생할 때 셀 명령을 자동 실행합니다. - Claude가 파일 저장하면 → 코드 정리해줘. - Claude가 작업 끝나면 → 텔레그램으로 알려줘. - Claude가 파일 수정하면 → 문법 검사해줘. ### 6-2. 설정 방법 ```bash > /hooks # 또는 직접 편집 # .claude/settings.json (프로젝트) # ~/.claude/settings.json (개인) ``` ### 6-3. Hook 이벤트 - PreToolUse - 도구 실행 전 (예: 저장 전 린트 검사) - PostToolUse - 도구 실행 후 (예: 저장 후 코드 포맷) - Notification - 알림 발생 시 (예: Slack/텔레그램 전송) - Stop - 응답 완료 시 (예: 빌드 자동 검증) ### 6-4. Hook 유형 ```json // 1. command - 셸 명령어 { "type": "command", "command": "npx prettier --write $CLAUDE_FILE_PATH" } // 2. http - URL POST 요청 (JSON payload 자동 전송) { "type": "http", "url": "https://hooks.slack.com/..." } // 3. prompt - 단일 LLM 평가 (단일턴, 도구 접근 없음) { "type": "prompt", "prompt": "이 변경이 보안에 영향 있는지 확인해" } ``` > [!quote] Boris Cherny "알림 Hook을 설정해 두면, 여러 Claude 세션을 동시에 돌릴 때 "입력 대기 중"인 세션을 즉시 감지할 수 있습니다." ## 7. MCP 서버 ### 7-1. MCP(Model Context Protocol) ```markdown Claude Code ←→ MCP Protocol ←→ DB, API, 파일, 검색엔진, 브라우저 등 ``` ### 7-2. MCP 서버 추가 방법 ```bash # CLI에서 MCP 추가 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 mcp add context7 -- npx -y @upstash/context7-mcp@latest # MCP 연결 상태 확인 > /mcp ``` ### 7-3. Context7으로 최신 문서 조회 ```bash > React Query v5의 useQuery 사용법을 최신 공식 문서에서 찾아줘. # → [Context7 → resolve-library-id → query-docs] # → 공식 문서 기반의 정확한 코드 예시 제공 > Supabase JS v2의 realtime subscription 예시 코드 보여줘. # → Context7가 실시간으로 최신 문서 검색 ``` ### 7-4. Supabase MCP 활용 ```bash > deal_data 테이블의 컬럼 목록 알려줘. # → [Supabase MCP → execute_sql] 자동 호출 > users 테이블에 phone 컬럼 추가하는 마이그레이션 만들어줘. # → [Supabase MCP → apply_migration] ``` ## 8. 스킬(Skills) ### 8-1. 스킬이란? - 스킬은 Claude에게 작업 방식을 가르치는 마크다운 파일(SKILL.md)입니다. - 예를 들어 "디버깅할 때 가설 3개 세우고 검증해" 같은 절차를 스킬로 만들면, Claude가 매번 그 방식대로 작업합니다. - Hook = "이 시점에 이 명령 실행해" → 자동화 - MCP = "이 외부 도구 연결해" → 도구 확장 - 스킬 = "이 방식으로 작업해" → 행동 패턴 > [!quote] Claude Code 스킬은 Agent Skills 오픈 표준을 따릅니다. Claude 전용이 아니라 다른 AI 도구에서도 같은 스킬 형식을 사용할 수 있습니다. ### 8-2. 스킬 종류 - 내장 스킬 → Claude Code에 기본 포함 (/simplify, /batch) - Anthropic 공식 → Anthropic이 배포 (claude-api, mcp-builder, pdf 등) - 커뮤니티 스킬 → 마켓플레이스에서 설치 (350,000+ 스킬) - 플러그인 스킬 → 플러그인이 제공 (superpowers, OMC, BKIT) ### 8-3. 스킬 설치 방법 ```bash # 방법 1: Anthropic 공식 마켓플레이스 등록 → 설치 > /plugin marketplace add anthropics/skills > /plugin install skill-creator # 방법 2: 커뮤니티 마켓플레이스에서 설치 > /plugin marketplace add <GitHub URL> > /plugin install <skill-name> # 방법 3: 수동 설치 (SKILL.md 파일 직접 배치) # .claude/skills/ 폴더에 마크다운 파일 추가 .claude/skills/my-custom-skill/SKILL.md ``` > [!quote] 스킬은 가볍습니다. 메타데이터 스캔에 ~100토큰, 활성화 시 전체 내용 로딩에 ~5,000토큰만 사용합니다. Claude가 관련성을 판단해서 자동으로 로딩하거나, 이름으로 직접 호출할 수 있습니다. ### 8-4. 내장 스킬 ```bash # /simplify - 코드 자동 최적화 # 3개 리뷰 에이전트가 병렬로 검토 + 자동 수정 # (코드 재사용성 / 코드 품질 / 효율성) > /simplify 성능 최적화에 집중해줘. # /batch - 대규모 병렬 작업 # 5~30개 서브에이전트가 git worktree에서 병렬 작업 → PR 자동 생성 > /batch 모든 컴포넌트에 TypeScript strict 타입 추가해줘. ``` ### 8-5. Anthropic 공식 스킬 ```bash # GitHub: https://github.com/anthropics/skills # 1단계: 공식 마켓플레이스를 내 Claude Code에 연결 > /plugin marketplace add anthropics/skills # 2단계: 원하는 스킬 번들 설치 > /plugin install document-skills@anthropic-agent-skills > /plugin install example-skills@anthropic-agent-skills # 3단계: 사용 (Claude가 자동으로 관련 스킬 활용) > 이 PDF에서 표를 추출해서 Excel로 만들어줘. ``` ```markdown [document-skills 번들] - pdf - PDF 읽기/생성/편집 - xlsx - Excel 스프레드시트 처리 - docx - Word 문서 처리 - pptx - PowerPoint 생성/편집 [example-skills 번들] - claude-api - Claude API / Anthropic SDK 통합 가이드 - mcp-builder - MCP 서버 개발 가이드 - skill-creator - 새 스킬 만들기 도우미 - webapp-testing - Playwright 기반 웹앱 테스트 자동화 - frontend-design - 프론트엔드 UI 설계 - brand-guidelines - 브랜드 스타일링 적용 - theme-factory - 테마 스타일링 도구 - web-artifacts-builder - 웹 아티팩트 생성 - doc-coauthoring - 문서 공동 작성 - internal-comms - 사내 커뮤니케이션 작성 - algorithmic-art - 알고리즘 아트 생성 - canvas-design - 캔버스 디자인 - slack-gif-creator - Slack GIF 생성 ``` ### 8-6. 커뮤니티 스킬 - Vercel skills.sh (skills.sh) - 가장 큰 스킬 마켓플레이스 - GitHub - awesome-claude-skills 등 큐레이션 목록에서 검색 ```bash # 방법 1: Vercel skills CLI로 설치 npx skills add <패키지명> # 방법 2: GitHub 마켓플레이스 연결 > /plugin marketplace add <GitHub 저장소 URL> # 방법 3: Claude에게 그냥 요청 (가장 간단) > Next.js 관련 스킬을 GitHub에서 찾아서 설치해줘. ``` ### 8-7. 플러그인 스킬 - 플러그인을 설치하면 스킬이 함께 추가됩니다. ```bash # superpowers - 워크플로우 강화 > /superpowers:brainstorming # 설계 전 아이디어 정리 > /superpowers:systematic-debugging # 체계적 디버깅 > /superpowers:verification-before-completion # 완료 전 검증 # oh-my-claudecode (OMC) - 멀티에이전트 오케스트레이션 > /oh-my-claudecode:autopilot # 완전 자율 실행 > /oh-my-claudecode:ralph # 끝날 때까지 반복 # BKIT - PDCA 방법론 > /pdca plan # 계획 문서 생성 ``` ### 8-8. 나만의 스킬 만들기 ```markdown # .claude/skills/my-review/SKILL.md --- name: my-review description: 코드 리뷰 시 사용. "리뷰해줘"라고 하면 자동 트리거. --- ## 리뷰 절차 1. 변경된 파일 전체 읽기 2. 타입 안전성 확인 3. 비즈니스 로직 정확성 검증 4. 보안 취약점 체크 5. 결과를 요약해서 보고 ``` ```bash # Claude에게 만들어달라고 할 수도 있음 > /skill-creator 코드 리뷰 스킬을 만들어줘. # 스킬 검색 > /find-skills 테스트 관련 스킬 찾아줘. ``` > [!quote] SKILL.md = YAML 메타데이터 + 마크다운 지시사항으로, 폴더에 템플릿/스크립트/예시 파일도 함께 넣을 수 있습니다. ## 9. 멀티에이전트 & 서브에이전트 ### 9-1. Subagent - 하나의 세션 내에서 병렬 위임 ```bash > src/ 폴더의 API 엔드포인트를 정리하면서, 동시에 tests/ 폴더의 실패하는 테스트도 분석해줘. # → 2개의 subagent가 병렬로 작업 # → 결과를 메인 에이전트에게 보고 ``` ### 9-2. Agent Teams - 각 세션이 독립 컨텍스트 → 대형 작업에 적합 - 서로 직접 통신 가능 (Subagent와 차이점) ```markdown Team Lead (세션 1) ├── Frontend Agent (세션 2): 컴포넌트 구현 ├── Backend Agent (세션 3): API 구현 └── Test Agent (세션 4): 테스트 작성 ``` > [!quote] Boris Cherny "직원 5명을 동시에 부리는 것과 같다. 알림 설정을 해서 '입력 대기 중'인 세션을 감지하고, 오케스트라처럼 지휘한다." ### 9-3. 작업과 검증 분리 ```bash # 세션 1: 구현 > 로그인 기능을 구현해줘. # 세션 2: 독립적으로 검증 (또는 /clear 후) > src/auth/ 폴더의 변경사항을 보안 취약점 중심으로 리뷰해줘. ``` > [!quote] 작업과 검증 분리 차원으로 하나의 에이전트로 코딩한 뒤, clear로 초기화하거나 다른 세션에서 검증하면 서로 다른 관점을 얻을 수 있습니다. ## 10. Ralph Loop ### 10-1. Ralph Loop이란? - 기존 문제: Claude가 작업을 하다가 "완료했습니다"라고 중간에 끊거나, 추가 질문을 위해 멈춤. - Ralph Loop: 명확한 성공 기준이 있으면, 완료될 때까지 무한 루프로 반복 실행. - 원리: Hooks의 Stop 이벤트에 "계속해"를 트리거 → Claude가 멈출 때마다 자동으로 재시작. ### 10-2. 사용 방법 ```bash # 방법 1: 네이티브 (최신 Claude Code 기본 기능) # 프롬프트에 "끝날 때까지 멈추지 마"를 포함하면 # Claude가 자체적으로 지속 실행. 별도 설정 불필요. > 모든 테스트가 통과할 때까지 수정해줘. 끝날 때까지 멈추지 마. # 방법 2: OMC 플러그인 ralph (강화판) # → max-iteration, completion-phrase, verifier 검증 포함 > /oh-my-claudecode:ralph 모든 테스트가 통과할 때까지 수정해줘 # 방법 3: 수동 Hook 설정 (.claude/settings.json) # Stop 이벤트에 "The boulder never stops" 등의 프롬프트 추가 ``` ### 10-3. 적합한 경우 vs 부적합한 경우 - 적합: 명확한 성공 기준, 대규모 반복 작업, 자기 전에 돌려놓고 아침에 확인 - 부적합: 사람의 판단이 필요한 설계, 1회성 작업, 빠른 간단 수정 ## 11. 개발 방법론 ### 11-1. Boris Cherny의 3단계 워크플로우 ```markdown [1단계] Plan 모드 → 계획을 충분히 다듬음, 코드 수정 없음 [2단계] Auto-accept 모드 → 계획대로 한 번에 쭉 실행. [3단계] 검증 피드백 루프 ← 핵심! → Claude가 스스로 결과를 보고 수정, 품질 2~3배 향상 ``` ### 11-2. 찐 개발자의 실전 워크플로우 5단계 - "기획과 코딩의 분리. 이게 제가 아는 가장 중요한 단 한 가지." ```markdown [1단계] Research - 코드베이스 깊이 읽기 → 반드시 MD 파일로 저장! 채팅창 요약으로 끝내면 안 됨 [2단계] Plan - 상세 구현 계획 작성 → 역시 MD 파일로, 내장 plan 모드 대신 직접 파일로 저장 [3단계] Annotate - 계획에 인라인 메모 추가 → 에디터에서 직접 수정. 잘못된 가정 수정, 제약 추가. → "아직 구현하지 마" 반드시 포함! [4단계] Implement - 구현 → 계획 완전히 준비된 후에만 코드 작성. [5단계] Feedback & Iterate - 피드백 반복 → type-check, build, test 결과를 Claude에게 피드백. ``` ### 11-3. Research 단계 ```bash # 나쁜 예: "이 폴더 설명해줘" (대충 훑어봄) # 좋은 예: "깊이", "매우 상세히", "세부 사항" 키워드 사용 > src/auth/ 폴더를 깊이 읽고 어떻게 동작하는지 매우 상세히 이해해. > 모든 세부 사항을 파악해. 끝나면 research.md에 상세 보고서를 작성해. ``` ### 11-4. Plan 단계 ```bash # 내장 plan 모드의 문제 # 채팅창에 흘러가 버림 # 에디터에서 직접 편집 불가 # 세션 종료 시 사라짐 # 대신 MD 파일로 > 이 기능의 상세 구현 계획을 plan.md에 작성해. > 코드 스니펫도 포함해. 변경될 파일 경로도 명시해. > 아직 구현하지 마. ``` ### 11-5. Annotate 단계 ```markdown # plan.md 예시 (Claude가 작성한 내용 + 내 메모) ## 1. 인증 API 라우트 POST /api/auth/login - JWT 토큰 발급 > [메모] 아니 이건 PUT이 아니라 POST여야 해. ## 2. 리프레시 토큰 - 옵셔널 파라미터로 처리 > [메모] 선택사항 아님. 필수야. ## 3. 캐싱 레이어 - Redis 캐싱 추가 > [메모] 이 부분 제거해. 여기는 캐싱이 필요 없어. ``` ```bash # 메모 추가 후 Claude에게 > plan.md에 메모를 추가했어. 모든 메모를 반영하고 문서를 업데이트해. > 아직 구현하지 마. # 만족할 때까지 반복 (보통 1~3회) > plan.md를 todo 리스트로 변환해줘. 그리고 전부 구현해. > 단계를 완료하면 plan.md에서 완료로 표시해. > 모든 작업이 완료될 때까지 멈추지 마. > any 타입을 쓰지 마. 지속적으로 타입 체크를 실행해. ``` ### 11-6. Feedback 단계 ```bash # 나쁜 예: 결과를 확인 안 함 > StockTable.tsx에서 정렬 버그 수정해줘 # 좋은 예: 검증 수단 제공 > StockTable.tsx에서 정렬 버그 수정해줘. > 수정 후 npm run type-check와 npx vitest run tests/components/StockTable.test.tsx 실행해서 확인해. ``` ### 11-7. 매뉴얼 학습 ```bash > 이 실수를 CLAUDE.md에 추가해서 다시는 이런 실수를 하지 마. # Claude가 실수하면, CLAUDE.md에 기록 # → 다음부터 같은 실수 반복하지 않음 ``` > [!quote] Boris Cherny "새 직원이 같은 실수를 반복하면 매뉴얼에 추가하는 것처럼. 시간이 지날수록 Claude가 점점 우리 방식에 맞게 움직인다." ## 12. 실전 적용 사례 > [!quote] "Claude Code로 13개 메뉴, 29개 컴포넌트, 26개 RPC, 694개 테스트를 가진 ERP를 개발한 실전 사례" ### 12-1. 프로젝트 개요 ```markdown LED 부품 재고관리 시스템 - React 19 + TypeScript + Vite + Tailwind + Supabase - 13개 메뉴 (재고/생산/고객관리) - 29개 컴포넌트 파일, 7개 데이터 Hook - 26개 Supabase RPC 함수, 7개 Realtime 채널 - 694개 Vitest 테스트 + 289개 Playwright E2E - AI 챗봇 (150문항 평가 평균 95.8점) - 배포: Vercel (GitHub main 자동배포) ``` ### 12-2. CLAUDE.md 설계 ```markdown # 프로젝트 CLAUDE.md 구조 (실제 운영 중) ## 1. 도구 사용 규칙 (자동 트리거 표) | 조건 | 필수 도구 | | 모든 코드 수정 작업 | architecture-system.md 참조 | | DB 관련 작업 | Supabase MCP로 스키마 확인 | | 새 라이브러리 도입 | Context7로 최신 문서 조회 | | 3+ 파일 변경 | brainstorming 스킬 실행 | | 버그 수정 | systematic-debugging 먼저 | ## 2. 세션 워크플로우 (강제) [시작] 메모리 Read → [분석] Supabase/Context7 → [설계] brainstorming → [구현] 직접/Team → [검증] type-check + build → [완료] 메모리 업데이트 ## 3. 디버깅 원칙 (실패에서 배운 교훈) - 원인 100% 확인 전에 코드 수정 금지 - 한 파일 수정/원복 2회 반복하면 멈추고 재분석 - RPC 문제: Supabase API 로그 → SET ROLE → SECURITY DEFINER 확인 ``` ### 12-3. Auto Memory 설계 ```markdown ~/.claude/projects/<hash>/memory/ ├── MEMORY.md ← 허브 (200줄 인덱스) ├── architecture-system.md ← ASCII 아키텍처 다이어그램 5섹션 ├── ui-design-system.md ← 버튼/모달/폼/테이블 패턴 ├── database.md ← 스키마, RPC 26개, TODO ├── master-codes.md ← 담당자15/공장10/창고16 (변경금지) ├── test-scenarios.md ← 263개 시나리오 + 70 HITL │ ├── features-dashboard.md ← 페이지별 기능 정의서 (13개) ├── features-stock-master.md ├── features-sales-history.md ├── features-sales-entry.md ├── features-purchase-history.md ├── ... └── tech-debt.md ← 기술부채(추후 수정 사항) 추적 ``` > [!quote] 작업 시작 시 해당 메뉴의 기능 정의서를 Read하면, Claude가 화면 구조/버튼 동작/DB 연결을 정확히 파악하고 작업합니다. 13개 전부 MEMORY.md에 로드하지 않고, 필요한 것만 참조하므로 토큰이 절약됩니다. ### 12-4. 아키텍처 문서 ```markdown # architecture-system.md 5개 섹션 S1. 시스템 전체 구조 ← Browser → Supabase → Edge Functions S2. 영향도 분석 매트릭스 ← 컴포넌트 A 수정 시 B,C에 영향 S3. 메뉴-컴포넌트 연결 ← 사이드바 메뉴 → 컴포넌트 매핑 S4. RPC 체크시트 ← 26개 RPC 함수 → 사용처 매핑 S5. Hook 의존성 로딩 ← 7개 Hook의 조건부 로딩 순서 ``` ### 12-5. 세션 프로토콜 ```bash # 1. 사용자: "판매조회 페이지 수정해줘" # 2. Claude 자동 동작: # → MEMORY.md 읽기 (매 세션 자동 로드) # → features-sales-history.md 읽기 (키워드 매칭) # → architecture-system.md 영향도 확인 # → Supabase MCP로 deal_data 스키마 확인 # 3. 구현 후 검증 (CLAUDE.md에 강제 규칙): npm run type-check # 0 errors npm run build # PASS # 4. 메모리 업데이트: # → TODO 체크 ([ ] → [x]) # → 변경 파일 목록 기록 ``` ### 12-6. ERP를 만들며 배운 것 - CLAUDE.md 살아있는 매뉴얼 - 실수할 때마다 규칙 추가 → 시간이 갈수록 Claude가 정확해짐 - 기능 정의서 = 최강의 컨텍스트 - 13개 메뉴별 상세 스펙을 메모리에 두면 "알아서" 이해 - 아키텍처 문서는 ASCII - Mermaid보다 ASCII가 Claude 이해도 높고 토큰 절약 - MCP는 필수 - Supabase MCP 없이 DB 작업하면 추측으로 코딩 → 버그 - 검증 루프 자동화 - type-check + build를 CLAUDE.md에 강제하면 빌드 깨짐 0건 - 입력/조회 동시 점검 - 같은 기능이 양쪽에 있으면 반드시 함께 수정 ## 13. 추천 플러그인 ### 13-1. 플러그인 시스템 ```bash # 플러그인 마켓플레이스 추가 > /plugin marketplace add <url> # 플러그인 설치 > /plugin install <name> # 설치된 플러그인 확인 > /plugin list ``` ### 13-2. superpowers 플러그인 - Claude Code 워크플로우를 강화하는 프로세스 스킬 모음 - brainstorming - 설계 전 아이디어 정리 ```bash > /superpowers:brainstorming # 언제: 새 기능, 3개+ 파일 변경 예상될 때 # 1. 프로젝트 맥락 파악 (파일, 커밋 분석) # 2. 질문 1개씩 (다지선다 선호) # 3. 2~3가지 접근법 + 트레이드오프 # 4. 섹션별 설계 → 사용자 승인 # 5. 설계 문서 저장 → writing-plans로 전환 ``` - systematic-debugging - 체계적 디버깅 ```bash > /superpowers:systematic-debugging # 언제: 버그 원인 불명확. 추측으로 코드 고치기 전에. # 1. 증상 수집 → 재현 조건 파악 # 2. 가설 3개+ 수립 # 3. 가설별 검증 (로그, 코드 분석) # 4. 근본 원인 확정 → 수정 → 검증 ``` - verification-before-completion - 완료 전 검증 ```bash > /superpowers:verification-before-completion # 언제: "다 됐어요" 하기 전. 커밋/PR 전. # type-check → build → test → 결과 보고 ``` - writing-plans - 구현 계획 작성 ```bash > /superpowers:writing-plans 인증 시스템 구현 # 언제: 대형 작업(6+ 파일) 시작 전. # brainstorming 후 태스크 분해 → 순서/의존성 → 체크포인트 ``` - dispatching-parallel-agents — 병렬 에이전트 ```bash > /superpowers:dispatching-parallel-agents # 독립적인 2개+ 작업을 병렬 subagent로 분배 ``` ### 13-3. oh-my-claudecode 플러그인 - 21개 전문 에이전트 + 37개 스킬의 멀티에이전트 오케스트레이션 - 세션 지속성(Ralph), 병렬 실행(Ultrawork), 팀 협업(Team) 등을 플러그인 레벨에서 구현 - GitHub - [Yeachan-Heo/oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) - 문서 - [yeachan-heo.github.io/oh-my-claudecode-website](https://yeachan-heo.github.io/oh-my-claudecode-website/) - 설치 방법 ```bash > /plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode > /plugin install oh-my-claudecode > /oh-my-claudecode:omc-setup ``` - 핵심 에이전트 ```markdown 분석/설계: explore(Haiku), analyst(Opus), planner(Opus), architect(Opus) 구현: executor(Sonnet), deep-executor(Opus), debugger(Sonnet), build-fixer(Sonnet) 검증: verifier(Sonnet), test-engineer(Sonnet) 리뷰: quality-reviewer(Sonnet), security-reviewer(Sonnet), code-reviewer(Opus) 기타: designer(Sonnet), writer(Haiku), scientist(Sonnet), critic(Opus) ``` - 주요 스킬 ```bash # 완전 자율 실행 (아이디어 → 완성 코드) > /oh-my-claudecode:autopilot 로그인 페이지 만들어줘 # 끝날 때까지 반복 (시지프스 전략) > /oh-my-claudecode:ralph 모든 타입 에러를 0개로 만들어줘 # 최대 병렬성 (여러 파일 동시 수정) > /oh-my-claudecode:ultrawork 5개 컴포넌트를 동시에 리팩토링해줘 # N개 에이전트 팀 협업 > /oh-my-claudecode:team 인증 시스템 전체 구축 # 전략 계획 (Planner + Architect + Critic 합의) > /oh-my-claudecode:plan API 리디자인 계획 # 딥 분석 > /oh-my-claudecode:analyze 이 메모리 누수의 원인 찾아줘 # 모든 모드 취소 > /oh-my-claudecode:cancel ``` - 외부 AI 연동 (MCP 라우팅) ```bash # Codex(OpenAI)에게 아키텍처 리뷰 > ask codex 이 프로젝트의 아키텍처를 리뷰해줘 # Gemini(Google)에게 UI 리뷰 (1M 컨텍스트) > ask gemini 이 UI 컴포넌트들의 일관성을 검토해줘 ``` ### 13-4. BKIT 플러그인 - CTO 3명의 개발 노하우를 AI에 적용한 플러그인 - PDCA 컨설팅 기법과 9단계 개발 방법이 핵심 - PDCA - 오래된 검증 컨설팅 기법(Plan-Do-Check-Act)을 AI에게 적용 - 계획 → 설계 → 구현 → 갭 분석 → 자동 수정 사이클 - GitHub - [popup-studio-ai/bkit-claude-code](https://github.com/popup-studio-ai/bkit-claude-code) - 사이트 - [bkit.ai](https://bkit.ai) - 설치 방법 ```bash > /plugin marketplace add popup-studio-ai/bkit-claude-code > /plugin install bkit ``` - PDCA 워크플로우 ```bash # Plan - 계획 문서 자동 생성 (docs/01-plan.../) > /pdca plan 사용자 인증 시스템 # Design - 설계 문서 생성 (docs/02-design.../) > /pdca design 사용자 인증 시스템 # Do - 구현 가이드 + 실행 > /pdca do 사용자 인증 시스템 # Check - 갭 분석 (계획 vs 실제) > /pdca analyze 사용자 인증 시스템 # Act - 90% 달성까지 반복 자동 수정 # 작은 프로젝트: 1~2회면 90% 달성 # 큰 프로젝트: 60% → 70% → 80% → 90%로 수렴 > /pdca iterate 사용자 인증 시스템 # 보고서 생성 > /pdca report 사용자 인증 시스템 # 상태 확인 / 다음 단계 안내 > /pdca status > /pdca next ``` - CTO-Led Team 모드 ```bash > /pdca team 인증 시스템 # 3~5 에이전트 병렬 PDCA > /pdca team status # 팀 진행 모니터링 > /pdca team cleanup # 리소스 해제 ``` - OMC vs BKIT 비교 ```markdown OMC (oh-my-claudecode) - 철학: 멀티에이전트 오케스트레이션 - 강점: 실행력 (ralph, team, ultrawork) - 에이전트 21개 (역할 특화), 스킬 37개 - 계획: /plan, /ralplan (합의) - 반복: ralph (무한 루프) - 검증: verifier + reviewer - 외부 AI: Codex(GPT) + Gemini BKIT - 철학: PDCA 컨설팅 기법 + 9단계 개발 방법 - 강점: 프로세스 (갭 분석, 자동 보고서, 수렴 반복) - 에이전트 16개 (CTO-Led Team), 스킬 27개 - 계획: /pdca plan → design (문서 자동 생성) - 반복: pdca iterate (90% 달성까지 수렴) - 검증: pdca analyze (갭 분석) - 보고: pdca report (자동 보고서) - 다국어: 8개 (한국어 포함) ``` ### 13-5. 스킬/플러그인 선택 가이드 ``` "새 기능을 만들고 싶다" → 작을 때: 직접 프롬프트 + 검증 명령 → 중간: /superpowers:brainstorming → 구현 → 대형: /oh-my-claudecode:autopilot 또는 /team "버그를 고치고 싶다" → 원인 명확: 직접 프롬프트 → 원인 불명: /superpowers:systematic-debugging → 깊은 분석: /oh-my-claudecode:analyze "리팩토링하고 싶다" → 1~2 파일: 직접 프롬프트 → 여러 파일 동시: /oh-my-claudecode:ultrawork 또는 /batch → 끝날 때까지: /oh-my-claudecode:ralph "코드 리뷰" → 빠르게: /superpowers:requesting-code-review → 종합: /oh-my-claudecode:code-review → 보안: /oh-my-claudecode:security-review "작업 완료 확인" → /superpowers:verification-before-completion → /simplify (코드 최적화까지) "빌드/타입 에러" → /oh-my-claudecode:build-fix ``` ## 14. 실전 팁 & 베스트 프랙티스 ### 14-1. 프롬프트 잘 쓰는 법 ```bash # 나쁜 예 > 이 코드 고쳐줘 > 테스트 작성해줘 # 좋은 예 — 파일명 + 함수명 + 기대결과 + 검증방법 > StockTable.tsx의 handleSort 함수에서 한글 정렬이 깨지는 버그를 수정해줘. > Intl.Collator('ko')를 사용해. > 수정 후 npx vitest run tests/components/StockTable.test.tsx 실행해서 확인해. ``` ### 14-2. Git 연동 ```bash # gh CLI 설치 필수! — Claude가 자동으로 활용 > git diff를 보고 conventional commit 메시지를 작성해서 커밋해줘 > 현재 브랜치로 GitHub PR을 만들어줘 > main과의 머지 충돌을 해결해줘 # 롤백도 가능 > 마지막 커밋을 롤백해줘 > 이 변경사항을 전부 되돌려줘 ``` ### 14-3. 워크트리 ```bash # git worktree로 독립 작업 공간 생성 git worktree add ../feature-auth feature/auth cd ../feature-auth claude # 독립 세션 # 다른 터미널에서: cd ../my-project claude # 메인 브랜치 작업 # → 각 worktree에서 독립적으로 작업 # → PR로 머지 ``` ### 14-4. 이미지 활용 ```bash claude # 이미지 붙여넣기 (Mac/Windows 모두 Ctrl+V) # → 스크린샷 → Ctrl+V → "이 UI를 구현해줘" # → 에러 화면 → Ctrl+V → "이 에러 해결해줘" # 파일로 제공 > @screenshot.png 이 디자인대로 구현해줘 ``` ### 14-5. 체크리스트 & 스크래치패드 ```bash # 복잡한 작업은 체크리스트로 > 이 기능을 구현할 건데, 먼저 마크다운 체크리스트를 만들어줘. > 각 단계를 완료할 때마다 체크 표시하면서 진행해. ``` ### 14-6. 비용 관리 ```bash /cost # 세션 비용 확인 /model sonnet # 가벼운 작업 전환 /compact # 토큰 절약 /clear # 새 작업 시 초기화 ``` ### 14-7. 보안 체크리스트 ``` [ ] CLAUDE.md에 API 키/시크릿 넣지 않기 [ ] .env 파일은 .gitignore에 포함 [ ] Auto-accept 모드는 신뢰할 수 있는 프로젝트에서만 [ ] MCP 서버는 신뢰할 수 있는 소스에서만 설치 [ ] 커밋 전 반드시 diff 확인 ``` ### 14-8. IDE 연동 ```bash # VS Code # - Claude Code Extension 설치 # - 터미널에서 claude 실행 # - Ctrl+Esc / Cmd+Esc: 빠른 실행 # - 코드 하이라이트 → Claude에 자동 주입 # - 디프뷰와 연동해서 변경사항 확인 # - Alt+Ctrl+K (Win) / Cmd+Opt+K (Mac): 파일 참조 # 다른 IDE 연동 > /ide # → 외부 IDE 선택 가능 (JetBrains 등) ``` ### 14-9. Plan 모드 주의 — 컨텍스트 1M 시대의 재평가 ```markdown Claude Code의 Plan 모드는 컨텍스트 부족 시대의 산물. 현재 100만 토큰 컨텍스트에서는: - 설계에 아무리 들여도 전체의 10%도 못 쓴다 - Plan 모드의 형식 제약이 오히려 AI의 자유로운 탐색을 방해 - VibeMafia 실험: Plan 모드로 계획한 결과가 순정 모드보다 품질 낮았음 → 15-4 "9단계 설계 대화"를 권장. 컨텍스트가 모자란 소규모 작업에서만 Plan 모드 사용. ``` ### 14-10. "최선이야?" 채찍질 기법 AI가 성급한 답변을 할 때 관점을 바꿔가며 3회 반복 질문하면 답의 깊이가 달라집니다. ```markdown 1차: "그게 최선 맞아? 확실해?" 2차: "성능적으로 최선이야? 네가 구글 시니어 개발자도 이렇게 짤 거 같아?" 3차: "병렬로 돌리면 더 좋지 않아? 이건 고려 안 했지?" ``` > [!quote] VibeMafia "사람한테 하면 안 되지만 AI한테는 되게 좋다. 갈궈도 상처 안 받거든요." --- ## 15. 하네스 엔지니어링 (VibeMafia 기법 기반) > 2026년 4월 바이브마피아(최수민) 라이브 3종(**하네스 이론+실습**, **1시간 MVP 라이브**, **출시 가능한 진짜 앱**)의 방법론을 정리한 섹션. **설계 90% + 구현 10% = 1시간 MVP, 컨텍스트 13%** — 모델이 아니라 **하네스 구성**이 ROI를 만든다. ### 15-1. 하네스란 무엇인가 - **하네스 = 추론 모델의 thinking 편차를 파이프라인으로 커버하는 강제 장치.** - Claude가 스스로 하는 작업 순서(Clarify → Context → Plan → Generate → Evaluate)를 **매번** 하도록 강제 + 프로젝트 맞춤 지침 주입. - 모델 성능이 오락가락할 때(서버 상태에 따라 Claude가 thinking budget을 줄이는 현상) 하네스가 있으면 영향 최소화. > [!quote] VibeMafia "AI 성능이 오락가락하는 건 얘네가 thinking을 덜 하기 때문. 하네스로 앞단을 명시적으로 채우면 추론 모델 의존도가 줄어 모델 성능 변동에도 견딜 수 있다." **하네스를 쓸 때 / 쓰지 말 때 — 임계점** | 써야 할 때 | 쓰지 말아야 할 때 | |---|---| | 한 번의 컨텍스트로 부족한 큰 작업 | 단순 수정·1회성 작업 | | 반복 작업·대규모 리팩토링 | 명확한 성공 기준 없는 탐색 | | 검증이 많은 작업 | 컨텍스트 한계 안 느끼는 소형 작업 | | 다른 사람과 유능함을 공유할 때 | — | **하네스 만들기 전 필수 선행 조건 — 입력·출력 명확히 하기** 🎨 **다이어그램 1 — 입력·출력 명확히** ![[claude-code-01-input-output.svg]] ``` 입력 → 출력 ───────────────────── ────────────────────── 고객 상담 노트 → 예쁜 홈페이지 초안 Figma 링크 → 퍼블리싱 코드 상세 기획서 → 앱 MVP ``` > [!quote] VibeMafia "이게 안 되어 있으면 하네스는 거의 무조건 실패한다. 이것부터 꼭 정하셔야 되고요." ### 15-2. 5단계 파이프라인 — 사고의 기본 틀 🎨 **다이어그램 2 — 5단계 파이프라인** ![[claude-code-02-pipeline-5step.svg]] ``` Clarify → Context Gather → Plan → Generate → Evaluate 명확화 컨텍스트 수집 설계 생성 검증 ``` | 단계 | 역할 | 주요 질문 | |---|---|---| | Clarify | 요구사항 정확히 이해 | "사용자가 진짜 원하는 건?" | | Context Gather | 관련 기록/코드 탐색 | "이 작업에 필요한 기존 자산은?" | | Plan | 구현 계획 수립 | "어떤 순서로, 무엇을 만들까?" | | Generate | 코드/컨텐츠 생성 | "계획대로 실행" | | Evaluate | 결과 검증 | "기대대로 작동하는가?" | **핵심 원칙** 1. 이 5단계는 **코딩뿐 아니라 모든 작업**의 표준 흐름. AX(조직 자동화) 설계에도 적용 가능. 2. 한 에이전트가 5단계 전부 관리 = 디버깅 난이도 ↑. **단계별 분리가 하네스 디자인의 본질**. 3. Claude Code의 Plan 모드도 이미 5단계 일부를 따르지만 **매번 하지는 않는다**. 하네스가 매번 강제. ### 15-3. 컨텍스트 흐름 — 메인 세션은 깨끗하게 🎨 **다이어그램 5 — 메인 vs 서브 세션 컨텍스트 흐름** ![[claude-code-05-context-flow.svg]] **나쁜 예** — 메인 세션이 서브에이전트 오케스트레이션 책임까지 지면: - 페이지 10개 구현 시 1번 끝나면 2번 호출, 실패 시 재시도, 체크포인트 저장 등의 관리 작업이 전부 메인에 쌓임 - 결국 설계 10%만 썼는데 구현 끝에 **메인 컨텍스트 60%+ 소모** → 남은 작업에 양질 정보 사용 불가 **좋은 예 — 스크립트 오케스트레이션**: - 메인 세션은 설계·결정·통합만 담당 (**양질 컨텍스트 저장고**) - 파이썬 스크립트가 phase 파일들을 순차 호출, `index.json`에 체크포인트 관리, 실패 시 재시도 - **모델이 바뀌어도 오케스트레이션 방식 고정** → Claude → GLM, Gemini로 스왑해도 동일 동작 **실측 데이터 — VibeMafia 2시간 30분 라이브, Opus 4.6 Max 기준** - 설계 9단계 + 구현 완료 후 메인 세션 컨텍스트 **13% 소비** - 하네스 없이 구현했다면 **60%+ 예상** - 나머지 87%는 추가 작업에 계속 쓸 수 있음 > [!quote] VibeMafia "메인 세션의 양질 컨텍스트를 보존하는 것이 하네스의 가장 큰 ROI다." ### 15-4. 9단계 설계 대화 — 1시간 MVP의 비밀 🎨 **다이어그램 6 — 9단계 설계 대화 맵** ![[claude-code-06-design-dialogue-9step.svg]] VibeMafia 1시간 MVP 라이브의 핵심. 메인 세션에서 9단계 전부 티키타카 후, **5개 MD 문서**로 하네스 구현 세션에 전달. | 단계 | 역할 페르소나 | 산출물 | |---|---|---| | 1. 구현 가능성 검증 | **공동 창업자**, YC 배치 지원 중 | 리스크 · 대안 | | 2. 기술 스택 결정 | (1번에 흡수되는 경우 많음) | 스택 목록 | | 3. 사용 흐름 (Flow) | **구글 시니어 UX 리서처** | 유저 저니 | | 4. 화면 구성 | 같은 UX 역할 | 화면별 요소·기능 | | 5. API 설계 | **마이크로소프트 시니어 CTO** | 엔드포인트 목록 | | 6. 데이터 스키마 | CTO | 테이블·필드 | | 7. 코드 아키텍처 | CTO (5·6과 묶어 진행 가능) | 모듈 구조 | | 8. 기술적 결정 (ADR) | CTO — 왜 이렇게 결정했나 | ADR 레코드 | | 9. 최종 문서화 | — | PRD·Flow·Schema·Architecture·ADR 5개 MD | **AI 에이전트용 문서 3원칙** (9단계 끝에 반드시 주입할 프롬프트) > [!important] 문서 작성 시 주의 > 1. **컨텍스트 낭비 최소화** — 같은 내용은 더 간결하게 > 2. **결정 맥락·의도 제거 금지** — "왜 이렇게 했는가"는 반드시 남김 > 3. **문서만 봐도 AI가 기획·개발 철학 추론 가능**해야 함 **입력·프롬프트 Starter** ```markdown # 앱 이름: [이름] ## 요구사항 (비개발자 관점으로 뭘 만들 건지 — 기능 목록 위주) ## 구현 디테일 (가능한 만큼 개발자 관점. 모르면 "네가 추천해" 지시) ## 제약 조건 (안 할 것들. 이게 있어야 AI가 엉뚱한 짓 안 함) - 로그인 지금은 안 만든다 - 서버 DB 지금은 안 쓴다 - ... ## 완료 기준 (어떤 상태면 완료라고 판단할지) - [ ] [기능 1] 정상 작동 - [ ] [기능 2] 정상 작동 ``` ### 15-5. 구현 파이프라인 — task · phase · script 🎨 **다이어그램 3 — 구현 파이프라인** ![[claude-code-03-implement-pipeline.svg]] ``` 상세 기획 ───→ 구현 계획 작성 ───→ 구현 ↓ ↓ ↓ [항목별 task/phase 생성 script로 실행 세부 점검] task: 작업당 1개 각 phase를 하위 구현 가능성 phase: 여러 개 Claude Code 세션이 UX (e.g. 서버구현 직렬로 구현 데이터베이스 → 웹구현) ... ``` - **task**: 작업 하나에 대한 루트 파일 (예: "모핏 MVP 구현", "로그인 기능 추가") - **phase**: task를 여러 구현 단위로 쪼갠 것 (`phase_0_docs_update.md`, `phase_1_server.md`, `phase_2_web.md`, …) - **script**: task/phase 파일들을 순차 실행하는 파이썬 스크립트. `index.json` 체크포인트로 중단/재개 가능 **왜 서브에이전트 대신 스크립트인가?** → 15-3 참조. 메인 세션 컨텍스트 보존 + 모델 교체에도 동작 일관성 확보. ### 15-6. 하네스 진화 3단계 🎨 **다이어그램 4 — 하네스 진화 3단계** ![[claude-code-04-harness-evolution.svg]] **Stage 1: 스킬 1개** — `plan-and-build` 같은 스킬 하나에 5단계 지침 전부 기록 - 메인 세션에서 실행 - 유지보수 지점 최소 - **"사실 대부분 이걸로 충분"** — VibeMafia **Stage 2: 단계별 서브에이전트 분리** — 스킬 1개로 컨텍스트 부족해질 때 - 각 단계별 독립 서브에이전트 + 아티팩트로 결과 전달 - 스크립트 오케스트레이션 - 큰 코드베이스나 반복 작업에만 적용 (억지로 올리면 복잡도만 증가) **Stage 3: 모니터링 허브** — 하네스 자체를 데이터로 관측 - Argos(VibeMafia 내부 툴) 또는 `rtk gain`으로 세션별 토큰·툴 호출 기록 - Claude가 로그 읽고 **스스로 개선 제안** - **"측정 없으면 죽은 시스템이 된다"** > [!warning] 처음부터 복잡하게 만들지 말 것. Stage 1에서 시작 → 필요할 때만 Stage 2, 3로 승급. ### 15-7. 문서 diff 기반 기능 추가 — 기능 업그레이드 루틴 출시된 앱에 기능 추가할 때의 하네스 업그레이드 방법 (출시 앱 라이브 기법): 1. **phase_0**에서 무조건 관련 문서(PRD / Flow / Schema / Architecture / ADR) 먼저 수정 2. 스크립트가 **변경된 부분 diff**를 산출해 `phase_1` 이후가 참조하도록 주입 3. 구현이 늘 "최신 의도"에 정렬됨 **왜 이렇게 해야 하나?** → 요구사항이 코드보다 문서에 먼저 반영되면, 여러 phase 간 해석 차이가 최소화됨. diff만 보면 이번 변경의 scope도 명확. ### 15-8. 오토리서치 — Karpathy 기법 적용 **적용 조건 2가지 (둘 다 충족해야 함)** 1. **정량 목표**가 있을 것 (성능 측정 가능 — UX "예쁨"은 불가) 2. **AI가 자가 반복 가능한 입력**일 것 (실험 데이터 사전 준비) **실제 예시 — 운동 자세 카운트 인식 최적화 (모핏 앱)** ``` [사전 준비] - 비디오 N개 준비 (스쿼트·푸시업·윗몸일으키기) - videos/index.json에 카운트 시점 라벨링 (e.g. [14.0, 18.1, 22.1, 27.2]) - 허용 오차 ±0.3초 [프롬프트] "이 운동 유형을 최적화하고 싶다. 비디오 경로에 영상들을 추가해 뒀고 index.json에 각 영상별 카운트 시점이 적혀 있다. 관절 포인트 기반 카운팅 로직의 파라미터를 조금씩 바꿔가며 모든 카운트 시점을 잘 맞추고 아닐 때 안 세는 최적값을 찾아라. 스위프트와 달리 파이썬은 반복 실행이 빠르니 파이썬으로 실험하고 최적 파라미터만 찾아서 스위프트로 이식한다." [결과] Claude가 Python 스크립트로 실험 루프를 돌며 파라미터 자동 최적화 ``` **오토리서치 vs 일반 프롬프트 차이** - 일반: Claude가 한 번에 답을 낸 뒤 수정 몇 번 → 결과는 한계 - 오토리서치: Claude가 **정량 지표 측정 → 수정 → 재측정**을 반복 → 수렴 --- ## 16. 우리 스택 — 4-레이어 협력 모델 🎨 **다이어그램 7 — 4-레이어 하네스 협력 모델** ![[claude-code-07-harness-4layer.svg]] > 📝 **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/ ### 16-1. 4-레이어 + 커스텀 레이어 구성 Superpowers / gstack / autoresearch / OMC는 각각 **원 저작자의 독립 레포**가 존재합니다. Daniel의 콘텐츠·강의 특화 **커스텀 스킬**은 별도로 `daniel8824-del` 아래에 관리됩니다. | 레이어 | 역할 | 대표 스킬 | GitHub 레포 | |---|---|---|---| | **Superpowers** | "**언제**" — 워크플로우 가드레일 | `brainstorming` · `writing-plans` · `systematic-debugging` · `verification-before-completion` | [github.com/obra/superpowers](https://github.com/obra/superpowers) | | **OMC** (oh-my-claudecode) | "**누가·어떻게**" — 에이전트 오케스트레이션 | `autopilot` · `ralph` · `ultrawork` · `team` · `plan` · `ralplan` | [github.com/Yeachan-Heo/oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) | | **gstack** | "**안전 + 전문 도구**" | `careful` · `freeze` · `guard` · `browse` · `qa` · `benchmark` · `ship` · `land-and-deploy` | [github.com/garrytan/gstack](https://github.com/garrytan/gstack) | | **autoresearch** | "**방법**" — 자율 반복 프로토콜 | `autoresearch:debug` · `:security` · `:ship` · `:fix` · `:predict` · `:learn` | [github.com/karpathy/autoresearch](https://github.com/karpathy/autoresearch) | | **Daniel 커스텀 스킬** | 콘텐츠·강의·도메인 특화 | `slide-pptx` · `proposal-bid` · `biz-plan` · `landing-page` · `seteuk` · `report-tone` · `blog-collector` 등 | [github.com/daniel8824-del](https://github.com/daniel8824-del) (다수 레포 — 스킬별 분리 공개 예정) | **협력 원리** - 각 레이어는 **독립 레포**로 유지되며 Claude의 판단으로 협력 - 수강생은 원하는 레이어만 선택적으로 설치 가능 (`/plugin marketplace add <GitHub URL>`) - Hook 강제 발동은 **Tier 1**(안전·세션·핵심 워크플로우)만 - **Tier 2**는 `[SKILL SUGGESTION]` 태그로 추천 표시 (거절 가능) - **Tier 3**는 사용자 명시 요청 시만 발동 > [!note] 레포 분리 이유 > 각 레이어가 독립 레포이면 (1) 수강생이 필요한 것만 설치 (2) 기능별 PR·이슈 분리 관리 (3) 특정 레이어만 업데이트 가능 (4) 다른 사용자가 특정 레이어만 포크·개선 가능. 본 강의에서는 레이어 전체를 맥락으로 학습하지만, 실제 사용 시 **한 레이어씩 깔아가며 체감**하는 것을 권장. > [!warning] 현재 상태 (2026-04-21) > Superpowers · gstack · autoresearch의 원 저작자 레포 URL은 강의 전 Daniel님이 개별 공지 예정. Daniel 커스텀 스킬은 `daniel8824-del` GitHub에 순차 공개 중. ### 16-2. LLM Wiki 시스템 — 복리 지식 엔진 Karpathy의 **LLM Wiki Co-Pilot** 모델 구현. Zettelkasten 철학으로 세션을 넘어 지식을 누적. **위치** - 프로젝트 로컬: `.omc/wiki/` (각 프로젝트 내 위키 페이지) - Obsidian 볼트: `/mnt/c/Users/daniel/Desktop/Zettelkasten/` (30_Claude/ + 20_Wiki/) **9개 Verbs (동사 통일)** ```bash /wiki ingest # 외부 자료 → wiki 페이지 자동화 /wiki query # 시맨틱 검색 /wiki save # 현재 세션 지식 저장 /wiki lint # 중복·링크 검증 /wiki manage # 페이지 관리 (이동·삭제·정리) /wiki synthesize # 여러 페이지 합성 /wiki critique # 페이지 비판·보완 /wiki compare # 페이지 비교 /wiki eli5 # 쉬운 설명 생성 (비개발자용) ``` **replay-learnings 스킬과의 연동** - 세션 시작 시 `30_Claude/02_Learnings/` 최근 교훈을 자동 로드 - 과거 실수 반복 방지 (Tier 1 자동 실행) - `qmd-search`로 Obsidian 볼트 시맨틱 검색 — "이전에 했었나?"에 즉답 ### 16-3. 추천 스킬 큐레이션 #### Tier 1 — 자동 실행 (설치 직후부터) **안전·세션 필수** | 시점 | 스킬 | 역할 | |---|---|---| | 세션 시작 | `replay-learnings` | 과거 교훈 자동 로드 | | 위험 명령 | `careful` | `rm -rf`, `DROP TABLE` 등 경고 | | 컨텍스트 50% | `compact-guard` | 상태 보존 후 압축 | | 커밋 직전 | `smart-commit` | 품질 게이트 + conventional commit | | 사용자 교정 | `learn-rule` | "기억해"/"다음엔" = 즉시 저장 | **핵심 개발 워크플로우 (생략 시 품질 저하)** | 시점 | 스킬 | |---|---| | 기능/컴포넌트 생성 전 | `brainstorming` | | 3단계+ 멀티파일 작업 | `writing-plans` | | 에러/테스트 실패 | `systematic-debugging` | | 완료 주장 직전 | `verification-before-completion` | #### 용도별 큐레이션 — 콘텐츠 크리에이터 | 용도 | 스킬 | |---|---| | 슬라이드 PPTX 생성 | `slide-pptx` (6-phase 파이프라인) | | 랜딩 페이지 | `landing-page` (Gemini 이미지 + PDF) | | 입찰 제안서 | `proposal-bid` (Impact-8 + SVG→DrawingML) | | 사업계획서 | `biz-plan` (한국형 정부지원사업 템플릿) | | 블로그 수집 | `blog-collector` (네이버 검색) | | 유튜브 수집 | `youtube-collector` (자막·댓글) | | 학술자료 수집 | `naver-scholar` · `feynman` | | 뉴스 수집 | `news-collector` | | HWP 분석 | `hwp-analyzer` | | 리포트 톤·이미지 | `report-tone` · `report-image` | | 인스타그램 수집 | `instagram-collector` | #### 용도별 큐레이션 — 개발자 | 용도 | 스킬 | |---|---| | 배포 | `ship` → `land-and-deploy` → `canary` | | 코드 리뷰 | `review` · `receiving-code-review` · `requesting-code-review` | | 디버깅 | `systematic-debugging` (자동), `investigate` (딥다이브), `autoresearch:debug` | | 테스트 | `test-driven-development` · `qa` · `qa-only` | | 성능 | `benchmark` · `imp-optimize` | | 보안 | `cso` · `autoresearch:security` | | 리팩토링 | `simplify` · `ai-slop-cleaner` | | 2nd 의견 | `codex` (OpenAI Codex CLI) · `ccg` (Claude+Codex+Gemini 트리오) | | Git 관리 | `smart-commit` · `using-git-worktrees` · `finishing-a-development-branch` | #### 용도별 큐레이션 — 지식 관리 | 용도 | 스킬 | |---|---| | 세션 종료 | `session-handoff` → Obsidian 볼트에 저장 | | 학습 기록 | `learn-rule` → `02_Learnings/` | | 주간 회고 | `retro` → `03_Retros/` | | 설계 결정 | `brainstorming` → `06_Designs/` | | 리서치 결과 | `prometheus-planning` → `05_Research/` | | 볼트 검색 | `qmd-search` · `qmd-manage` | | 지식 그래프 | `graphify` · `wiki` (9-verb 통합) | | 볼트 저장 | `vault-save` (자동 호출 체인) | #### 용도별 큐레이션 — 디자인 | 용도 | 스킬 | |---|---| | 초기 컨셉 | `design-consultation` · `design-shotgun` | | 스타일 결정 | `taste-soft` · `taste-minimalist` · `taste-brutalist` · `taste-taste` · `taste-gpt-tasteskill` | | 실행 개선 | `imp-impeccable` · `imp-polish` · `imp-audit` · `imp-harden` | | 레이아웃 | `imp-layout` · `imp-adapt` · `imp-colorize` | | 미세 튜닝 | `imp-typeset` · `imp-animate` · `imp-delight` · `imp-critique` · `imp-bolder` · `imp-quieter` · `imp-distill` · `imp-clarify` · `imp-shape` · `imp-overdrive` | | 리뷰 | `design-review` · `devex-review` · `plan-design-review` · `visual-verdict` | | HTML 산출 | `design-html` | #### 용도별 큐레이션 — 학생·강의 | 용도 | 스킬 | |---|---| | 세특 작성 | `seteuk` (14 sub-skills, 5 phases) | | NotebookLM 활용 | `notebook-lm` | | 강의안 | `slide-pptx` + `taste-stitch` | | 리포트 | `report-tone` (학술 → 마케팅 톤 전환) | | 데이터 분석 | `data-analysis` (리뷰·감성·토픽·워드클라우드) | #### Tier 3 — 수동 호출만 사용자가 명시적으로 호출해야만 발동. 일상 작업에서는 추천하지 않음. `guard` · `retro` · `office-hours` · `investigate` · `health` · `codex` · `permission-tuner` · `freeze` · `unfreeze` ### 16-4. 인프라 도구 | 도구 | 역할 | 비고 | |---|---|---| | **RTK** (Rust Token Killer) | CLI 명령 자동 프록시 → **60-90% 토큰 절감** | `~/.claude/RTK.md` 참조 · `rtk gain`으로 통계 | | **Obsidian Skills** | 볼트 직접 조작 | `obsidian-cli` · `obsidian-markdown` · `json-canvas` · `obsidian-bases` | | **QMD** (Quick Memory Database) | Obsidian 볼트 시맨틱 인덱스 | `qmd update && qmd embed`로 주기 갱신 | | **autoresearch 프로토콜** | 정량 반복 개선 | 8 sub-skills (debug · security · ship · fix · predict · learn · scenario · plan) | | **Argos** (VibeMafia 툴) | 세션별 토큰·툴 호출 기록 | 현재 비공개 — `rtk gain --history`로 대체 가능 | ### 16-5. 개선 사이클 프로토콜 세션 라이프사이클을 따라 자연스럽게 연결되는 스킬 체인: | 시점 | 자동 체인 | |---|---| | 세션 시작 | `replay-learnings` → 과거 교훈 + QMD 로드 | | 작업 중 | Tier 1 워크플로우 자동 발동 (`brainstorming` → `writing-plans` → 구현) | | 실수 감지 | `learn-rule` 자동 저장 → `vault-save` → QMD 인덱싱 | | 세션 종료 | `session-handoff` → `learn` → `vault-save` | | 주간 회고 | `retro` → `learn-rule` → `vault-save` | | 다음 세션 | `replay-learnings` (개선된 메모리로 시작) | > 코드 수정 없이 이 프로토콜만으로 **복리 학습**이 작동. 매주 하네스가 똑똑해진다. --- ## 17. Discord 원격 개발 — 폰으로 하는 바이브 코딩 ### 17-1. 연동 구조 ``` VS Code (Claude Code 실행) ↔ Discord 봇 (채널 플러그인) ↔ 사용자(폰) ``` **장점** - 맥북은 집 책상에 켜두고 Claude Code 실행 - 디스코드 봇이 Claude 명령 라우팅 - **화장실·이동 중에도 폰으로 명령** 가능 - 라이브 방송·강의에서 **가독성 좋은 채팅 형태** 로 시연 > [!quote] VibeMafia "디스코드가 실질적으로 좋은 부분은 뭐 이렇게 하다가 화장실 가서도 할 수 있다는 거죠." ### 17-2. 설치 (4단계) ```bash # 1. Discord Developer Portal에서 Bot 생성 → Token 발급 # https://discord.com/developers/applications # 2. Bot 설정 # - Privileged Gateway Intents → Message Content Intent 활성화 # - OAuth2 → URL Generator → "bot" 스코프 선택 # - Bot Permissions: View Channels, Send Messages, Read Message History, # Attach Files, Add Reactions # - 생성된 URL로 접근해서 서버에 초대 # 3. Claude Code에서 플러그인 연동 > /discord:configure # → 토큰 붙여넣기 # 4. 채널 페어링 > /discord:access # → 허용 채널 등록 ``` 자세한 문서: `/plugin marketplace add` 후 `discord` 플러그인 설치 → `/discord:configure` 스킬 참조. ### 17-3. 사용 팁 - 봇 별칭: Claude가 응답할 때 쓰는 이름 커스텀 (예: "마피아", "내 비서") - 첨부 파일: Claude가 생성한 파일을 Discord로 보내면 폰에서 바로 다운로드 가능 - 스크린샷: 폰에서 촬영 → Discord로 업로드 → Claude가 분석 - 다중 세션: 여러 프로젝트별로 채널 분리 → 병렬 바이브 코딩 --- ### 관련 노트 [[LightRAG 설치 및 설정 가이드]] [[Claude Code 추가 가이드]] ## 🧠 Connected Insights > 📅 Last analyzed: 2026. 3. 14. 오후 9:09:09 > 💰 Analysis cost: $0.0196 ### 🔗 Related Notes - 🔼 [[클로드 클래스/Claude Code 설치 가이드.md]] - extends: ‘Claude Code 실전 가이드’는 설치 가이드의 내용을 실전 활용 관점에서 확장합니다. 설치 방법, 인증 플랜 등 기초 내용을 포함하면서도 실제 사용법, 권한 모드, 명령어, 메모리 시스템 등 실무 중심의 내용을 추가로 다룹니다. - Confidence: █████ (90%) - 🔼 [[클로드 코드/멀티 에이전트 협업 팀 만들기.md]] - extends: ‘Claude Code 실전 가이드’는 멀티 에이전트 협업, MCP 프로토콜, 에이전트 오케스트레이션 등 개념을 실전 맥락에서 설명하며, ‘멀티 에이전트 협업 팀 만들기’의 내용을 구체적 도구 사용법과 연결해 확장합니다. - Confidence: ████░ (79%) - 🔗 [[00_Inbox/04_Notion/프롬프트.md]] - related: 프롬프트 엔지니어링, LLM 모델 선택, 컨텍스트 관리 등에서 개념적 연관성이 높으며, Claude Code 실전 가이드 내에서도 프롬프트 및 컨텍스트 최적화 전략이 언급됩니다. - Confidence: ████░ (70%) - 🔗 [[에이전트 클래스/에이전트 클래스 Chapter 2.md]] - related: 에이전트 기반 LLM 활용법, 컨텍스트 관리, 프롬프트 엔지니어링 등에서 개념적 유사성이 있습니다. 실전 가이드의 agentic engineering 개념과 에이전트 클래스의 내용이 상호 보완적입니다. - Confidence: ████░ (75%) - 📝 [[사업계획서/사업계획서_시스템_프롬프트.md]] - examples: Claude Code 실전 가이드에서 언급된 프롬프트 엔지니어링 및 시스템 프롬프트 활용이 실제 비즈니스 사례(사업계획서 자동화)로 구체화된 예시입니다. - Confidence: ███░░ (60%) ### 📚 Knowledge Gaps - 🔴 **Agentic Engineering의 실제 사례 및 워크플로우** - Agentic Engineering 개념은 소개되었으나, 실제 프로젝트에서 Claude Code를 활용한 구체적 사례, 단계별 워크플로우, 문제 해결 과정 등 실전적 내용이 부족합니다. 실무적 이해와 적용을 위해 사례 중심의 심화가 필요합니다. - Suggested resources: https://karpathy.ai/agentic-engineering, https://www.anthropic.com/blog/agentic-workflows - 🟡 **Claude Code의 보안 및 프라이버시 관리** - 설치 및 사용법은 상세히 다루지만, 코드/데이터 접근 권한, 인증, 프라이버시, 로컬/클라우드 데이터 보호 등 보안 관련 실무 가이드가 부족합니다. 기업 및 팀 단위 도입 시 필수적인 영역입니다. - Suggested resources: https://docs.anthropic.com/security, https://owasp.org/www-project-top-ten/ - 🟡 **Claude Code와 타 LLM/에이전트 툴의 비교** - Claude Code의 특징은 언급되나, ChatGPT Code Interpreter, GitHub Copilot, Open Interpreter 등과의 기능/UX/확장성/비용 비교가 없습니다. 도구 선택 및 전략 수립에 중요한 정보입니다. - Suggested resources: https://github.com/features/copilot, https://openinterpreter.com/, https://www.promptingguide.ai/ - 🟡 **고급 Hook 자동화 및 확장 사례** - Hook 설정 및 MCP 프로토콜 언급은 있으나, 실제로 Hook을 활용한 자동화, 외부 도구 연동, 커스텀 워크플로우 구축 등 고급 활용 사례가 부족합니다. - Suggested resources: https://docs.anthropic.com/claude/docs/hooks, https://dev.to/anthropic/claude-hooks-examples - 🟢 **실전 프롬프트 엔지니어링 및 컨텍스트 최적화 전략** - 프롬프트 엔지니어링의 기본 개념은 언급되나, Claude Code 환경에서의 실전 프롬프트 설계, 컨텍스트 압축/요약, 세션 관리 등 구체적 전략이 더 필요합니다. - Suggested resources: https://www.promptingguide.ai/ko, https://www.anthropic.com/blog/context-management ### 💡 AI Insights ‘Claude Code 실전 가이드’는 Claude Code의 실무 활용법, 핵심 명령어, 에이전트 오케스트레이션 개념을 체계적으로 안내한다. 설치 가이드, 멀티 에이전트 협업, 프롬프트 엔지니어링 등 관련 노트들과 개념적·논리적으로 긴밀히 연결되어 있다. 그러나 Agentic Engineering의 실제 사례, 보안/프라이버시, 타 도구와의 비교, 고급 자동화, 실전 프롬프트 전략 등 실무적 깊이와 확장성을 위한 지식 갭이 존재한다. 이 갭을 보완하면 Claude Code의 실전적 가치와 활용도가 더욱 높아질 것이다.