Windsurf IDE 완전 설치 가이드: 다운로드부터 Cascade AI 코딩 설정, Git 연동까지
Windsurf IDE란? AI 네이티브 코드 에디터의 새로운 기준
Windsurf는 Codeium이 개발한 AI 네이티브 IDE로, VS Code 기반의 친숙한 인터페이스에 Cascade라는 강력한 AI 코딩 어시스턴트를 내장하고 있습니다. Cascade는 단순한 코드 자동완성을 넘어 프로젝트 전체 컨텍스트를 이해하고, 멀티파일 편집과 터미널 명령 실행까지 자율적으로 수행합니다. 이 가이드에서는 Windsurf를 처음 설치하는 것부터 Cascade 설정, 커스텀 모델 선택, Git 연동, 첫 프로젝트 시작까지 전 과정을 단계별로 안내합니다.
1단계: Windsurf IDE 다운로드 및 설치
시스템 요구 사항
| 항목 | 최소 사양 | 권장 사양 |
|---|---|---|
| OS | Windows 10, macOS 12, Ubuntu 20.04 | Windows 11, macOS 14, Ubuntu 22.04 |
| RAM | 4GB | 8GB 이상 |
| 디스크 | 2GB 여유 공간 | SSD 5GB 이상 |
| 네트워크 | 인터넷 연결 필수 | 안정적 광대역 |
windsurf.com에 방문하여 운영체제에 맞는 설치 파일을 다운로드합니다.- **Windows 설치**:# 다운로드한 설치 파일 실행
Windsurf-Setup.exe
# 설치 완료 후 터미널에서 확인
windsurf --version- **macOS 설치**:- Linux 설치:# Homebrew를 이용한 설치 (지원 시) brew install --cask windsurf또는 .dmg 파일 다운로드 후 Applications 폴더로 이동
터미널에서 CLI 확인
windsurf —version
- 첫 실행: Windsurf를 실행하면 Codeium 계정 로그인 또는 회원가입 화면이 나타납니다. Google, GitHub 계정으로 간편 가입이 가능합니다.# .deb 패키지 설치 (Ubuntu/Debian) sudo dpkg -i windsurf_latest_amd64.deb sudo apt-get install -f또는 .rpm 패키지 (Fedora/RHEL)
sudo rpm -i windsurf_latest_x86_64.rpm
2단계: Cascade AI 코딩 어시스턴트 설정
Cascade는 Windsurf의 핵심 AI 기능으로, 설치 즉시 사용할 수 있습니다.
Cascade 패널 열기
- 단축키 Ctrl+L (macOS: Cmd+L)을 눌러 Cascade 채팅 패널을 엽니다.- 또는 사이드바의 Cascade 아이콘을 클릭합니다.- 채팅창에 자연어로 요청을 입력하면 AI가 코드를 생성하고 편집합니다.
Cascade 모드 이해하기
| 모드 | 설명 | 사용 시나리오 |
|---|---|---|
| **Write** | 파일 생성 및 수정을 자율적으로 수행 | 새 기능 구현, 리팩토링 |
| **Chat** | 코드 설명, 질문 응답 (파일 수정 없음) | 코드 리뷰, 학습, 디버깅 질문 |
# Cascade 채팅창에 입력하는 예시 프롬프트들
새 프로젝트 생성
“React와 TypeScript로 할일 관리 앱의 기본 구조를 만들어줘”
기존 코드 리팩토링
“이 함수를 async/await 패턴으로 변환하고 에러 핸들링을 추가해줘”
테스트 코드 작성
“UserService 클래스에 대한 Jest 단위 테스트를 작성해줘”
3단계: 커스텀 AI 모델 선택 및 설정
Windsurf는 다양한 AI 모델을 지원하며, 작업 특성에 따라 모델을 선택할 수 있습니다.
- **모델 선택**: Cascade 패널 상단의 모델 드롭다운에서 원하는 모델을 선택합니다.- **사용 가능한 모델**: GPT-4o, Claude Sonnet, Gemini 등 여러 프리미엄 모델이 플랜에 따라 제공됩니다.- **설정 파일로 기본 모델 지정**: Settings → Cascade 섹션에서 기본 모델과 관련 옵션을 설정합니다.
### 외부 API 키 연동 (Pro/Team 플랜)
// settings.json에서 커스텀 API 설정
{
"windsurf.cascade.apiProvider": "openai",
"windsurf.cascade.apiKey": "YOUR_API_KEY",
"windsurf.cascade.model": "gpt-4o"
}
## 4단계: Git 연동 및 버전 관리 설정
- **Git 설치 확인**:
git --version
# git version 2.43.0 이상 권장git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"Ctrl+Shift+P로 명령 팔레트를 열고 Git: Clone을 검색하여 GitHub 리포지토리를 클론합니다.
### Cascade와 Git 워크플로우 통합
# Cascade에게 Git 작업 요청 예시 "현재 변경사항을 리뷰하고 적절한 커밋 메시지를 작성해줘"
“main 브랜치에서 feature/auth 브랜치를 생성하고 체크아웃해줘”
5단계: 첫 프로젝트 시작하기
- 프로젝트 폴더 생성 및 열기:
- Cascade로 프로젝트 초기화: Cascade에 다음과 같이 요청합니다:mkdir my-first-project cd my-first-project windsurf .
- 생성된 코드 확인 및 실행:“Node.js Express API 서버 프로젝트를 초기화해줘. TypeScript, ESLint, Prettier를 포함하고 기본 health check 엔드포인트를 만들어줘”npm install npm run dev
http://localhost:3000/health 에서 확인
Pro Tips: 파워 유저를 위한 고급 설정
- 컨텍스트 핀(Pin): 자주 참조하는 파일을 Cascade 컨텍스트에 고정하면 더 정확한 응답을 받을 수 있습니다. 파일 탭을 우클릭하고
Pin to Cascade를 선택하세요.- Rules 파일 활용: 프로젝트 루트에.windsurfrules파일을 생성하여 코딩 컨벤션과 프로젝트 규칙을 정의하면 Cascade가 이를 준수합니다.# .windsurfrules 예시 - TypeScript strict 모드를 사용할 것
- 함수는 반드시 JSDoc 주석을 포함할 것
컴포넌트는 함수형으로 작성할 것- 키보드 단축키: Ctrl+I로 인라인 AI 편집, Tab으로 자동완성 수락, Ctrl+Shift+I로 Cascade 터미널 모드를 활용하세요.- 멀티파일 편집: Cascade Write 모드에서 “이 프로젝트의 모든 API 라우트에 인증 미들웨어를 추가해줘”처럼 요청하면 여러 파일을 동시에 수정합니다.- VS Code 확장 호환: Windsurf는 대부분의 VS Code 확장을 지원합니다.Extensions패널에서 기존에 사용하던 확장을 검색하여 설치하세요.
Troubleshooting: 자주 발생하는 문제 해결
| 문제 | 원인 | 해결 방법 |
|---|---|---|
| Cascade 응답이 없음 | 네트워크 연결 문제 또는 인증 만료 | 인터넷 연결 확인 후 Ctrl+Shift+P → Codeium: Sign Out → 재로그인 |
| 자동완성이 작동하지 않음 | Codeium 확장 비활성화 | 설정에서 Codeium: Enable이 체크되어 있는지 확인 |
| Git push 실패 | 인증 토큰 만료 | git credential reject 후 재인증, 또는 SSH 키 방식으로 전환 |
| 설치 후 실행 안 됨 | 의존성 누락 (Linux) | sudo apt-get install -f 실행 후 재설치 |
| 모델 선택 불가 | 무료 플랜 제한 | Pro 플랜 업그레이드 또는 무료 크레딧 한도 확인 |
Q1: Windsurf는 무료로 사용할 수 있나요?
네, Windsurf는 무료 플랜을 제공합니다. 무료 플랜에서는 매월 일정량의 Cascade 크레딧과 자동완성 기능을 사용할 수 있습니다. 더 많은 크레딧과 프리미엄 모델 접근이 필요하다면 Pro 플랜(월 $15)이나 Team 플랜을 선택할 수 있습니다. 무료 플랜만으로도 개인 프로젝트와 학습 용도에는 충분합니다.
Q2: VS Code에서 Windsurf로 설정과 확장을 마이그레이션할 수 있나요?
Windsurf는 VS Code 기반이므로 대부분의 설정과 확장이 호환됩니다. 첫 실행 시 VS Code 설정 가져오기 옵션이 나타나며, settings.json, 키바인딩, 설치된 확장을 자동으로 마이그레이션할 수 있습니다. 일부 특수 확장은 호환되지 않을 수 있으므로, 마이그레이션 후 확장 패널에서 정상 작동 여부를 확인하세요.
Q3: Cascade가 제 코드를 학습하거나 외부로 유출하나요?
Codeium은 사용자의 코드를 AI 모델 학습에 사용하지 않는다고 명시하고 있습니다. Cascade와의 대화 및 코드 컨텍스트는 응답 생성을 위해 일시적으로 처리되며, 저장되거나 학습 데이터로 활용되지 않습니다. 기업 환경에서는 Team 플랜의 제로 데이터 보존(Zero Data Retention) 정책과 SOC 2 Type II 인증을 통해 추가적인 보안을 보장받을 수 있습니다.