Cline 가이드

소개

Cline (이전 이름: Claude Dev)은 VS Code 확장으로, 단순한 코드 생성을 넘어 파일 시스템 조작, 터미널 명령 실행, 브라우저 제어까지 가능한 자율 AI 에이전트입니다.

자율 에이전트란?

일반적인 AI 코딩 도구는 사용자가 요청할 때마다 응답합니다. 하지만 자율 에이전트는:

• 계획 수립: 복잡한 작업을 단계별로 분해
• 자율 실행: 각 단계를 스스로 실행
• 에러 처리: 실패 시 자동으로 수정 시도
• 승인 요청: 중요한 작업은 사용자 확인 요청

핵심 기능

다른 도구와의 차이점

설치

VS Code 확장 설치

방법 1: 마켓플레이스

1. VS Code 열기
2. Extensions (Cmd/Ctrl + Shift + X)
3. "Cline" 검색
4. Install
5. Reload

방법 2: 커맨드라인

code --install-extension saoudrizwan.claude-dev

API 키 설정

Cline은 Anthropic, OpenAI, Google 모델을 지원합니다. 아래는 Anthropic 기준 예시입니다.

1. API 키 발급 (Anthropic 예시)

1. https://console.anthropic.com 접속
2. "Get API Keys" 클릭
3. API 키 생성 및 복사
4. 키 형식: sk-ant-api03-xxxxxxx

2. Cline에 API 키 입력

# 방법 1: Cline UI
1. Cline 사이드바 열기 (좌측 아이콘)
2. Settings (톱니바퀴 아이콘)
3. API Provider: Anthropic
4. API Key 입력
5. Model: claude-

# 방법 2: 환경 변수
export ANTHROPIC_API_KEY="sk-ant-api03-xxx"

첫 실행

# 1. Cline 사이드바 열기
좌측 아이콘 클릭 또는 Cmd/Ctrl + Shift + P → "Cline: Open"

# 2. 첫 요청
💬 You: "안녕! 간단한 테스트로 hello.txt 파일 만들어줘."

🤖 Cline: "hello.txt를 생성하겠습니다."

# 승인 요청
[Cline] 📝 Write to file: hello.txt
Approve? (Y/n)

# Y 누르면 파일 생성됨

기본 사용법

간단한 작업

파일 생성

💬 You: "Python으로 간단한 계산기 만들어줘. calculator.py 파일로."

🤖 Cline: "calculator.py를 생성하겠습니다."

# Cline이 자동으로:
1. 파일 생성 (calculator.py)
2. 코드 작성 (덧셈, 뺄셈, 곱셈, 나눗셈)
3. 사용 예제 주석 추가

✅ 완료!

파일 수정

💬 You: "calculator.py에 제곱 기능 추가해줘."

🤖 Cline: "파일을 읽고 수정하겠습니다."

# Cline이 자동으로:
1. 파일 읽기
2. power() 함수 추가
3. 파일 저장

✅ 완료! power() 함수를 추가했습니다.

복잡한 작업

전체 프로젝트 생성

💬 You: "React + TypeScript 투두 앱 만들어줘.

필요한 것:
- Create React App 설정
- TypeScript 타입 정의
- 컴포넌트 (TodoList, TodoItem, AddTodo)
- 로컬 스토리지 저장
- Tailwind CSS 스타일링

모든 설정과 코드 작성해줘."

🤖 Cline: "React 투두 앱을 생성하겠습니다."

# Cline이 자율적으로:

Step 1: 프로젝트 생성
→ npx create-react-app todo-app --template typescript

Step 2: Tailwind 설치
→ npm install -D tailwindcss postcss autoprefixer
→ npx tailwindcss init -p

Step 3: 파일 생성
→ src/types/todo.ts
→ src/components/TodoList.tsx
→ src/components/TodoItem.tsx
→ src/components/AddTodo.tsx
→ src/hooks/useTodos.ts
→ src/utils/localStorage.ts

Step 4: 설정 파일 수정
→ tailwind.config.js
→ src/index.css

Step 5: 앱 통합
→ src/App.tsx

Step 6: 테스트
→ npm start

✅ 완료! 브라우저에서 http://localhost:3000 확인하세요.

자율 작동 방식

Cline은 작업을 단계별로 분해하고 각 단계를 자율적으로 실행합니다.

💬 You: "사용자 인증 시스템 추가해줘."

🤖 Cline의 내부 계획:

1. 현재 프로젝트 구조 파악
   → package.json 읽기
   → 사용 중인 프레임워크 확인

2. 필요한 패키지 설치
   → npm install jsonwebtoken bcrypt express-session

3. 파일 생성
   → auth/jwt.js (JWT 유틸리티)
   → middleware/auth.js (인증 미들웨어)
   → routes/auth.js (인증 라우트)
   → models/User.js (사용자 모델)

4. 기존 파일 수정
   → server.js (라우트 연결)
   → .env (환경 변수)

5. 테스트
   → 서버 재시작
   → API 테스트 (curl)

# 각 단계마다 승인 요청 또는 자동 실행

승인 시스템

Cline은 중요한 작업 전에 사용자 승인을 요청합니다.

# 승인 요청 예시

[Cline] 🔧 Execute command:
npm install express mongoose

This will modify package.json and install dependencies.
Approve? (Y/n/edit)

Y → 실행
n → 취소
edit → 명령어 수정 후 실행

고급 기능

터미널 제어

Cline은 터미널 명령을 실행하고 출력을 읽어 다음 단계를 결정합니다.

💬 You: "npm test 실행하고 실패한 테스트 수정해줘."

🤖 Cline:

Step 1: 테스트 실행
→ npm test

Output:
FAIL src/utils/math.test.js
  ● sum › should add two numbers
    Expected: 5, Received: 4

Step 2: 분석
→ src/utils/math.js 읽기
→ 버그 발견: return a + b; → return a + b - 1;

Step 3: 수정
→ src/utils/math.js 수정

Step 4: 재실행
→ npm test

✅ 모든 테스트 통과!

브라우저 제어

Cline은 Puppeteer를 사용하여 브라우저를 제어할 수 있습니다.

💬 You: "앱 실행하고 스크린샷 찍어줘. 버그 있으면 수정."

🤖 Cline:

Step 1: 서버 시작
→ npm start (백그라운드)

Step 2: 브라우저 열기
→ http://localhost:3000

Step 3: 스크린샷
→ screenshot.png 저장

Step 4: 시각적 분석
→ 버튼이 화면 밖으로 나감 (CSS 문제)

Step 5: 수정
→ styles.css 수정

Step 6: 재확인
→ 브라우저 새로고침, 스크린샷

✅ UI 수정 완료!

컨텍스트 인식

Cline은 프로젝트 구조를 이해하고 파일 간 의존성을 파악합니다.

💬 You: "API 엔드포인트 추가해줘. /api/users"

🤖 Cline의 컨텍스트 이해:

1. 프로젝트 타입 파악
   → package.json 읽기 → Express 사용 중

2. 기존 구조 확인
   → routes/ 디렉토리 있음
   → server.js에서 라우트 연결 방식 확인

3. 데이터베이스 확인
   → models/ 디렉토리 확인 → Mongoose 사용 중

4. 일관된 코드 생성
   → routes/users.js 생성 (기존 스타일 따름)
   → models/User.js 생성 (기존 스키마 패턴 따름)
   → server.js 수정 (기존 라우트 연결 방식 따름)

✅ 프로젝트 스타일에 맞게 통합 완료!

기억 및 히스토리

Cline은 대화 히스토리를 저장하고 이전 작업을 참조합니다.

💬 You: "React 컴포넌트 만들어줘. Button."
🤖 Cline: "Button.tsx를 생성했습니다."

💬 You: "이 버튼에 hover 효과 추가해줘."
🤖 Cline: "Button.tsx에 hover 스타일을 추가했습니다."
# "이 버튼" = Button.tsx (컨텍스트 이해)

💬 You: "테스트 코드도 작성해줘."
🤖 Cline: "Button.test.tsx를 생성했습니다."
# Button 컴포넌트에 대한 테스트 (암묵적 이해)

실전 워크플로우

새 프로젝트 시작

💬 You: "Next.js 13 블로그 프로젝트 만들어줘.

요구사항:
- TypeScript
- App Router
- Tailwind CSS
- Prisma + PostgreSQL
- 마크다운 블로그 글
- 관리자 페이지

처음부터 끝까지 설정하고 실행까지 해줘."

🤖 Cline: "Next.js 블로그를 생성하겠습니다."

# Cline이 자동으로 수행:

1. 프로젝트 생성
   → npx create-next-app@latest blog --typescript --tailwind --app

2. Prisma 설정
   → npm install prisma @prisma/client
   → npx prisma init
   → prisma/schema.prisma 작성

3. 데이터베이스 연결
   → .env 파일 생성
   → DATABASE_URL 설정

4. 파일 생성 (20개 이상)
   → app/page.tsx (홈)
   → app/blog/[slug]/page.tsx (블로그 글)
   → app/admin/page.tsx (관리자)
   → components/ (여러 컴포넌트)
   → lib/prisma.ts
   → lib/markdown.ts

5. 데이터베이스 마이그레이션
   → npx prisma migrate dev

6. 샘플 데이터 생성
   → prisma/seed.ts
   → npm run seed

7. 실행 및 테스트
   → npm run dev
   → 브라우저 열기
   → 스크린샷

✅ 완료! 전체 블로그 시스템이 준비되었습니다.

기능 추가

💬 You: "블로그에 댓글 기능 추가해줘.
- 비회원도 작성 가능 (이름, 이메일 입력)
- 대댓글 지원
- 관리자 승인 시스템"

🤖 Cline:

1. 기존 코드 분석
   → Prisma 스키마 확인
   → 라우트 구조 파악

2. 데이터베이스 스키마 수정
   → prisma/schema.prisma (Comment 모델 추가)
   → npx prisma migrate dev

3. API 라우트 생성
   → app/api/comments/route.ts
   → app/api/comments/[id]/route.ts

4. 컴포넌트 생성
   → components/CommentForm.tsx
   → components/CommentList.tsx
   → components/CommentItem.tsx

5. 블로그 글 페이지 통합
   → app/blog/[slug]/page.tsx 수정

6. 관리자 페이지 추가
   → app/admin/comments/page.tsx

7. 테스트
   → npm run dev
   → 브라우저에서 댓글 작성 테스트

✅ 댓글 시스템 완료!

디버깅

💬 You: "앱 실행했는데 에러 나. 고쳐줘."

🤖 Cline:

Step 1: 앱 실행
→ npm run dev

Error Output:
Error: Cannot find module 'react-markdown'
  at Module._resolveFilename

Step 2: 문제 진단
→ 패키지가 설치되지 않음

Step 3: 수정
→ npm install react-markdown

Step 4: 재실행
→ npm run dev

New Error:
TypeError: Cannot read property 'map' of undefined
  at BlogList.tsx:15

Step 5: 파일 확인
→ BlogList.tsx 읽기
→ posts 배열 null 체크 누락

Step 6: 수정
→ Optional chaining 추가

Step 7: 재실행
→ npm run dev

✅ 앱이 정상 작동합니다!

리팩토링

💬 You: "코드 품질 개선해줘.
- TypeScript strict 모드
- ESLint 에러 수정
- 중복 코드 제거
- 성능 최적화"

🤖 Cline:

1. TypeScript 설정 강화
   → tsconfig.json (strict: true)
   → 모든 타입 에러 수정

2. ESLint 실행
   → npm run lint
   → 모든 경고 수정

3. 중복 코드 분석
   → 유사한 컴포넌트 발견
   → 공통 컴포넌트로 추출

4. 성능 최적화
   → React.memo 추가
   → useMemo, useCallback 적용
   → 이미지 최적화 (Next.js Image)

5. 테스트
   → npm run build
   → 빌드 성공 확인

✅ 코드 품질 개선 완료!

설정

API 제공자 설정

# Cline Settings

API Provider: Anthropic
Model: claude-
API Key: sk-ant-api03-xxx

# 다른 제공자도 지원
- OpenAI (GPT-4)
- Google (Gemini)
- Azure OpenAI
- OpenRouter

동작 설정

커스텀 지시사항

# Cline Settings → Custom Instructions

프로젝트 규칙:
- TypeScript strict 모드 사용
- 함수형 컴포넌트 (React Hooks)
- Tailwind CSS로 스타일링
- 모든 함수에 JSDoc 주석
- 에러 처리 필수
- 테스트 코드 작성

네이밍 규칙:
- 컴포넌트: PascalCase
- 함수: camelCase
- 상수: UPPER_SNAKE_CASE

파일 구조:
src/
  components/
  hooks/
  utils/
  types/

다른 도구와 비교

vs Continue

vs Codex

Codex는 앱/웹/CLI에서 작업 단위로 실행되는 코딩 에이전트이며, Cline은 VS Code 내부에서 실행되는 에이전트입니다. 워크플로우와 승인 흐름이 다르므로 팀 규칙에 맞게 선택하세요. 자세한 흐름은 Codex 가이드를 참고하세요.

vs Cursor

Cline을 사용해야 하는 경우

• 복잡한 프로젝트를 빠르게 시작하고 싶음
• AI가 자율적으로 작업하길 원함
• 터미널 명령 자동 실행 필요
• 브라우저 테스트 자동화 필요
• VS Code 환경 유지하면서 강력한 AI 도구 사용

Cline을 사용하지 말아야 하는 경우

• 완전 무료 솔루션 필요 → Continue + Ollama
• 수동 제어 선호 → Cursor, Continue
• 간단한 코드 편집만 필요 → Continue
• 터미널 명령어만 필요 → GitHub Copilot CLI

팁과 트릭

효과적인 프롬프트

❌ 나쁜 예

💬 You: "앱 만들어줘."

너무 모호함. Cline이 여러 번 질문해야 함.

✅ 좋은 예

💬 You: "React + TypeScript 투두 앱 만들어줘.

기능:
- 할 일 추가/삭제/완료
- 로컬 스토리지 저장
- 필터 (전체/진행중/완료)

기술 스택:
- Create React App (TypeScript)
- Tailwind CSS
- React Hooks

처음부터 끝까지 설정하고 실행까지 해줘."

안전 사용 팁

1. 중요 프로젝트는 Git 사용

   git init
   git add .
   git commit -m "Before Cline changes"

2. 자동 승인 주의
   • 개발 초기: Auto Approve ON (빠른 프로토타입)
   • 중요 작업: Auto Approve OFF (안전)
3. 대화 분할

   # 복잡한 작업은 단계별로
   1단계: "프로젝트 초기 설정만 해줘"
   2단계: "이제 인증 기능 추가해줘"
   3단계: "테스트 작성해줘"

비용 최적화

• 명확한 요청: 모호한 요청은 재시도로 이어져 비용 증가
• Claude Haiku: 간단한 작업은 Haiku 모델 사용
• Auto Approve: 승인 과정을 줄여 API 호출 감소
• 대화 초기화: 불필요한 컨텍스트 제거

트러블슈팅

일반적인 문제

❌ Cline이 응답하지 않음

해결:

• API 키 확인
• 네트워크 연결 확인
• VS Code 재시작
• Cline 확장 재설치

❌ 파일이 생성되지 않음

해결:

• 워크스페이스 폴더가 열려 있는지 확인
• 파일 쓰기 권한 확인
• 승인 요청을 놓치지 않았는지 확인

❌ 터미널 명령이 실행되지 않음

해결:

# Settings 확인
Terminal Integration: Enabled

# VS Code 터미널 활성화
View → Terminal

❌ 브라우저 제어 실패

해결:

# Puppeteer 설치
npm install -g puppeteer

# Settings에서 브라우저 활성화
Browser Enabled: true

핵심 정리

• Cline 가이드의 핵심 개념과 흐름을 정리합니다.
• 소개를 단계별로 이해합니다.
• 실전 적용 시 기준과 주의점을 확인합니다.