Claude Code 를 이용한 vibe coding 시 best practice 가이드 문서들을 한글로 번역했습니다.
원본: https://gist.github.com/swerner/b7fd285ec3f2edbcc55ebccdaffc950a
모든 문서의 저작권은 https://gist.github.com/swerner 에게 있습니다.
이 파일은 이 리포지토리의 코드로 작업할 때 Claude Code(claude.ai/code)에 대한 가이드를 제공합니다.
작업을 시작하기 전, 다음 파일들을 순서대로 읽어주세요:
pair_programming.md- 스토리 기반 개발을 위한 저희의 워크플로우 프로세스project_plan_{some_extension}.md- 현재 진행 상황 및 다음에 작업할 스토리technical_considerations.md- 학습한 내용 및 구현 결정 사항mcp-browser-architecture.md- 전체 아키텍처 및 디자인 결정 사항
색상 마이그레이션 작업을 위해서는 다음 파일도 읽어주세요:
5. color_migration_analysis_report.md - 종합적인 색상 감사 및 시맨틱 매핑 가이드
주요 워크플로우 알림:
- 스토리 진행 상황을 추적하려면 항상 TodoWrite 도구를 사용하세요.
pair_programming.md에 있는 정확한 사용자 검증 형식을 따르세요.- 절대
pnpm tauri dev를 실행하지 마세요 - 수동 테스트는 사람이 처리합니다. - 각 스토리가 끝난 후 학습한 내용으로
technical_considerations.md를 업데이트하세요.
Protocollie는 Tauri 2.0과 React/TypeScript로 구축된 데스크톱 애플리케이션으로, MCP(Model Context Protocol) 서버를 위한 종합적인 테스트 및 탐색 도구 역할을 합니다. API용 Postman과 유사하게 작동하여, 개발자가 여러 MCP 서버에 연결하고, 그 기능들을 탐색하며, 실시간으로 기능을 테스트할 수 있게 해줍니다.
pnpm dev- 개발 서버 시작 (Vite 개발 서버 실행)pnpm build- 프로덕션용 React 프론트엔드 빌드pnpm preview- 프로덕션 빌드 미리보기
pnpm tauri build- 전체 데스크톱 애플리케이션 빌드pnpm tauri build --no-bundle- 번들링 없이 빌드 (더 빠르며, 컴파일 테스트에 좋음)pnpm tauri- Tauri CLI 명령어 접근- 참고: 자동화된 워크플로우에서
pnpm tauri dev를 실행하지 마세요 - 수동 테스트는 사람이 처리합니다.
- 패키지 매니저로
pnpm을 사용합니다 (npm이나 yarn이 아님). - 락 파일:
pnpm-lock.yaml
- 프론트엔드: React 18 + TypeScript + Vite + Tailwind CSS v4
- 백엔드: Rust와 Tauri 2.0
- 데스크톱 프레임워크: Tauri 2.0 (크로스-플랫폼 데스크톱 앱)
- MCP 통합: JSON-RPC 프로토콜을 사용하는 직접적인 시스템 Node.js 프로세스
- 데이터 저장: SQLite와 rusqlite + 인메모리 + JSON 하이브리드 방식
- 프로세스 통신: 개별 MCP 서버 프로세스와의 직접적인 stdin/stdout IPC
이 애플리케이션은 MCP 서버 통신을 위해 직접적인 시스템 Node.js 프로세스를 사용합니다:
- Rust/Tauri: 데스크톱 앱, UI, 그리고 개별 MCP 서버 프로세스의 라이프사이클을 관리합니다.
- 시스템 Node.js: 각 MCP 서버 연결에 대해 직접적인 프로세스를 생성합니다.
- 통신: 프로세스별 JSON-RPC 프로토콜을 사용한 직접적인 stdin/stdout IPC
- 장점: 단순한 아키텍처, 범용 명령어 지원, 더 작은 앱 크기, 실제 MCP 사용 환경과 일치
구현 상태: ✅ 완료 - 직접적인 프로세스 관리, 범용 명령어 지원, 향상된 오류 메시징, JSON-RPC 프로토콜, 프로세스 라이프사이클 관리 및 도구 실행 모두 작동 중입니다.
자세한 컴포넌트 구성은 mcp-browser-architecture.md를 참조하세요. 주요 위치:
src/- 컴포넌트, 훅, 타입을 포함한 React 프론트엔드src-tauri/src/- 데이터베이스, MCP 프로세스 관리, Tauri 명령어를 포함한 Rust 백엔드- 루트 디렉토리의 문서 파일들
이 애플리케이션은 MCP(Model Context Protocol) 서버 테스트 및 탐색을 위해 특별히 설계되었습니다. 이 앱은 동적 서버 연결 관리, 도구 실행, 요청/응답 기록 기능을 갖춘 Postman과 유사한 인터페이스를 MCP 서버 개발 및 테스트를 위해 제공합니다.
중요: 이 앱은 Tailwind의 기본 다크 모드가 아닌, 커스텀 테마 시스템을 사용합니다.
useTheme()훅 사용:const { resolvedTheme } = useTheme()- 절대
dark:접두사를 사용하지 마세요 - 저희의.light클래스 시스템과 호환되지 않습니다. resolvedTheme === 'light'vs'dark'에 기반한 조건부 스타일링을 만드세요.- 자세한 테마 구현 패턴은
mcp-browser-architecture.md를 참조하세요.
- 라이트 모드에서 선택 하이라이트가 읽기 어려움 → theme-conditional 색상 사용
- 다크 모드에서 code/kbd 요소가 읽기 어려움 → theme-aware 배경 사용
- 호환되지 않는
dark:접두사를 사용하는 배지 컴포넌트 → 제거하고 theme-neutral 색상 사용