Cline · VS Code 자율 코딩 에이전트

📑 목차

1. Cline 기술이란?
2. Cline 기술 특징
3. Cline 기술 동작방식
4. Cline 기술 구성 및 흐름도
5. Cline 기술 설치 방법
6. Cline 기술 사용 방법
7. Cline 기술 자주 쓰는 명령어 / 멘션
8. Cline 기술 활용방안 (대안 비교 · 안 쓸 때)

1. Cline 기술이란?

왜 필요한가 — 기존 AI 코딩 도구의 3가지 한계

2024년 이전의 AI 코딩 도구는 크게 세 갈래로 갈렸습니다.

계열대표결정적 한계

자동완성	GitHub Copilot	한 줄~한 함수 한정. 멀티 파일 리팩토링·명령 실행 불가
편집 채팅	Cursor, Continue.dev	사람이 매번 “편집해줘” 트리거. 작업 단위가 아닌 라인 단위 사고
CLI 자율 에이전트	Aider, OpenHands, Goose	IDE와 분리 → 변경 리뷰·디버깅 마찰. 신뢰 부족

실무에서 진짜 필요했던 것은 “IDE 안에서 작업 단위로 위임하면서도 매 단계 통제할 수 있는” 에이전트였습니다. “이 디렉터리에서 마이그레이션 스크립트 만들고, 테스트 돌리고, README도 갱신해줘” 한 줄로 끝내고 싶지만, 보안·비용·실수 위험 때문에 완전 자율은 무섭다는 그 모순.

Cline의 정의

Cline은 VS Code 확장으로 동작하는 오픈소스 자율 코딩 에이전트입니다. 시스템 프롬프트와 작업 큐를 통해 LLM과 IDE를 묶고, 도구 호출(Tool Use)로 파일 시스템 · 터미널 · 브라우저 · MCP 서버를 조작합니다. 원래 이름은 Claude Dev였으나 모델 중립을 표방하며 Cline으로 개명했습니다.

핵심은 두 가지 설계 결정입니다. 첫째, Plan / Act 이중 모드로 “생각”과 “실행”을 분리해 비용·실수를 줄입니다. 둘째, 섀도우 Git 체크포인트로 모든 변경을 되돌릴 수 있게 만들어 신뢰 기반을 확보합니다.

2. Cline 기술 특징

특징설명

Plan / Act 모드	Plan은 읽기 전용·사고 위주(저렴한 모델), Act는 실제 파일 변경(강한 모델). 두 모드에 서로 다른 모델 지정 가능.
모델 중립	Anthropic · OpenAI · Google · DeepSeek · Mistral · OpenRouter · Ollama · LM Studio · Bedrock · Vertex AI · 자체 OpenAI 호환 엔드포인트까지 지원.
도구 승인 게이트	매 도구 호출마다 Approve/Reject. 도구별 화이트리스트로 부분 자동승인 가능.
체크포인트(Shadow Git)	작업 폴더 옆에 별도 Git 저장소를 두고 매 변경을 스냅샷. “Restore here” 버튼으로 임의 시점 복원.
MCP 네이티브	Model Context Protocol 서버를 stdio/SSE로 동적 연결. GitHub · Slack · Postgres · Playwright 같은 도구를 LLM 컨텍스트에 노출.
컴퓨터 사용(Computer Use)	Claude의 컴퓨터 사용 기능과 연동해 헤드리스 브라우저로 실제 페이지를 클릭·스크롤·캡처. 프론트엔드 검증에 유용.
비용/토큰 가시화	작업당 누적 토큰·캐시 히트율·예상 달러를 실시간 표시. 비용 폭주 조기 발견.
오픈소스 / 로컬 우선	Apache 2.0. 코드는 LLM 제공자로만 가고 별도 텔레메트리 서버 없음. 회사 정책에 맞춰 Ollama로 완전 로컬 운영 가능.

3. Cline 기술 동작방식

3-1. 핵심 구성 요소

컴포넌트역할

WebView UI	VS Code 사이드바 패널. React로 구현된 채팅·승인·diff 인터페이스.
Task Engine	사용자 요청을 받아 시스템 프롬프트 + 컨텍스트 + 메시지 히스토리를 빌드해 LLM에 전달.
API Handler	모델별 SDK 어댑터. 토큰 캐싱 헤더, max_tokens, stream 처리 추상화.
Tool Parser	LLM 출력에서 XML 형식 도구 호출(<read_file>, <execute_command> 등) 추출 및 검증.
Tool Executor	실제로 파일 IO · 터미널 PTY · 브라우저(Puppeteer) · MCP RPC 수행.
Checkpoint Tracker	작업 시작 시 워크스페이스를 섀도우 Git에 미러링. 도구 실행 후 자동 커밋.
MCP Hub	사용자 정의 MCP 서버를 spawn(stdio) 또는 connect(SSE)하고 tool 목록을 시스템 프롬프트에 주입.
Context Manager	메시지 히스토리 압축, 파일 멘션 자동 첨부, 컨텍스트 윈도우 한계 추적.

3-2. 데이터 흐름 (한 턴의 라이프사이클)

① 입력   사용자가 “테스트 추가하고 CI 통과시켜줘” 입력.
② 컨텍스트 빌드   @멘션, 열린 탭, environment_details, MCP 도구 목록을 시스템 프롬프트에 합성.
③ LLM 호출   선택된 모델 SDK로 stream 요청. 토큰 캐시 헤더 부착.
④ 응답 스트리밍   XML 도구 호출이 도착하는 즉시 Tool Parser가 인식.
⑤ 승인 게이트   UI에 “Cline wants to execute …” 표시. Auto-approve 규칙에 매칭되면 통과.
⑥ 도구 실행   Executor가 수행 → stdout/diff/screenshot 캡처.
⑦ 체크포인트   워크스페이스 변경이 있었다면 섀도우 Git에 커밋.
⑧ 결과 주입   결과를 다음 user 메시지로 묶어 ②로 회귀.
⑨ 종료   LLM이 <attempt_completion> 호출 시 작업 종료, 비용·체크포인트 ID 표시.

4. Cline 기술 구성 및 흐름도

UserVS Code WebView(채팅 · 승인 · diff)Task Engine시스템 프롬프트 빌드API Handler모델 SDK 어댑터Tool ParserXML tool-use 추출Tool ExecutorFS · Shell · BrowserCheckpointShadow Git SnapshotLLM ProviderClaude · GPT · LocalMCP Serversstdio · SSEWorkspace파일 · 터미널 · 브라우저

4-1. 단계별 처리 흐름 (실전 예: “버그 수정 + 테스트 추가” 작업)

단계행동내부 동작

1	Plan 모드 진입	읽기 전용 도구만 노출 → 저렴한 모델로 구조 파악
2	list_files + search_files	트리 + ripgrep으로 관련 코드 위치 식별
3	read_file	대상 파일을 컨텍스트에 적재 (토큰 캐시 활용)
4	Act 모드 전환	강한 모델로 변경. 체크포인트 자동 생성
5	replace_in_file	diff 미리보기 → 사용자 승인 → 적용
6	execute_command	npm test 실행 → 결과를 다음 턴에 주입
7	반복	테스트 실패 시 read_file → replace_in_file 루프
8	attempt_completion	최종 요약 + 비용 + 체크포인트 ID 표시 후 종료

5. Cline 기술 설치 방법

5-1. VS Code 마켓플레이스 (가장 일반)

# 1) VS Code 좌측 Extensions 아이콘 → "Cline" 검색
# 2) 또는 CLI로 직접 설치
code --install-extension saoudrizwan.claude-dev

# 3) 설치 후 좌측 사이드바에 Cline 로봇 아이콘 등장
# 4) Settings → API Provider 선택 후 키 입력

5-2. API 키 설정 (3가지 운영 모델)

방식월 비용 감각권장 상황

Anthropic 직접	중~높음 (Sonnet 기준 $20~80/주)	품질 최우선 · 캐시 효율이 가장 좋음
OpenRouter	중간 (모델 자유 전환)	여러 모델 비교 · 한 키로 통합 운영
Ollama / LM Studio	0원 (전기 + GPU 감가)	보안 민감 코드 · 외부 송신 금지 환경

주의 — 키를 settings.json에 박지 마세요. Git에 올라가는 사고가 많습니다. Cline은 VS Code SecretStorage(키체인)를 사용하므로 반드시 UI에서 입력하세요. 환경변수로 주입하고 싶다면 ANTHROPIC_API_KEY 가 아니라 Cline 설정의 “Use environment variable” 토글을 통해 인식시키는 게 안전합니다.

6. Cline 기술 사용 방법

6-1. 작업 시작과 컨텍스트 멘션

# 작업 예시 — @멘션으로 컨텍스트 자동 첨부
@/src/api/payment.ts 의 환불 로직에 멱등키 처리가 누락됐어.
@/tests/payment.test.ts 의 테스트 패턴을 따라
유닛 테스트를 추가하고 @problems 의 ESLint 경고도 같이 잡아줘.
완료 후 npm test 로 검증.

지원되는 멘션: @/파일경로, @/폴더경로/, @problems, @terminal, @git-changes, @http(s)://URL

6-2. .clinerules 파일 — 프로젝트 규칙 주입

워크스페이스 루트의 .clinerules 또는 .clinerules/ 폴더가 자동으로 시스템 프롬프트에 합쳐집니다. 팀 단위 코딩 컨벤션·금지 패턴을 못 박을 때 유용합니다.

# .clinerules
- TypeScript strict 모드 가정. any 사용 금지.
- console.log 대신 src/lib/logger 사용.
- DB 쿼리는 반드시 Prisma 트랜잭션으로 감싸기.
- 새 함수는 jsdoc 헤더 필수.
- 절대 .env 를 read_file 하지 말 것. (보안)

6-3. MCP 서버 추가 (cline_mcp_settings.json)

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." },
      "disabled": false,
      "autoApprove": ["search_repositories", "get_issue"]
    },
    "postgres": {
      "command": "uvx",
      "args": ["mcp-server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

운영 팁: autoApprove에 읽기 도구만 넣으세요. 쓰기/삭제 도구를 자동 승인하면 “LLM이 잘못 호출 → 자동 실행 → 복구 불가”의 사고가 발생합니다.

6-4. 운영 시 고려사항

• 비용 가드 — 작업 한 건이 $5를 넘기면 무조건 새 task로 분할. 컨텍스트 압축보다 분할이 저렴합니다.
• 모델 분리 — Plan은 Sonnet/Haiku, Act는 Sonnet/Opus. Plan에서 비싼 모델 쓰면 회수 불가능한 토큰을 태웁니다.
• 워크스페이스 신뢰 — Untrusted Workspace에서는 execute_command가 막힙니다. 신뢰 설정을 반드시 켜세요.
• 섀도우 Git 용량 — 큰 바이너리(영상·모델 weights)가 있는 폴더에서 켜면 디스크가 폭발합니다. .gitignore처럼 작동하는 제외 패턴을 설정에서 지정하세요.
• 터미널 셸 고정 — Windows에서 기본 셸을 PowerShell로 강제해두지 않으면 cmd로 떨어져 명령이 실패합니다.

7. Cline 기술 자주 쓰는 명령어 / 멘션

명령 / 멘션용도

Cline: New Task	컨텍스트 리셋 후 새 작업 시작 (Ctrl+Shift+P)
Plan ↔ Act 토글	하단 모드 버튼 또는 Cmd/Ctrl + Shift + A
@/path/to/file	파일 내용을 컨텍스트에 첨부
@problems	VS Code Problems 탭의 진단 정보 첨부
@terminal	현재 통합 터미널의 출력 첨부
@git-changes	스테이지된/안된 변경분 diff 첨부
Restore Checkpoint	메시지 옆 시계 아이콘 → 해당 시점으로 워크스페이스 복원
Cline: Open MCP Servers	MCP 서버 설정 JSON 열기

7-1. 실전 워크플로우 사례

시나리오권장 패턴

레거시 코드 이해	Plan 모드 + 저렴 모델로 “이 모듈의 책임을 다이어그램으로 설명” 요청
버그 수정	@problems + @terminal 멘션 → Act 모드 → 테스트 자동 실행 루프
신규 기능	.clinerules 로 아키텍처 제약 박고 Act 모드로 TDD 진행
DB 스키마 마이그레이션	Postgres MCP 서버로 실제 스키마 조회 → 마이그레이션 파일 생성
프론트엔드 E2E	Computer Use로 로컬 미리보기를 클릭·캡처 → 시각 회귀 검증

8. Cline 기술 활용방안

8-1. 대안 기술 비교

도구포지셔닝Cline 대비 강/약점

Cline	VS Code 자율 에이전트 (OSS)	기준점
Cursor	상용 AI IDE	+UX·자동완성 통합 / -코드 클라우드 송신, 폐쇄
GitHub Copilot	자동완성 + 채팅	+가격 예측 가능 / -자율 실행은 약함
Aider	CLI · Git 네이티브 페어프로그래밍	+RepoMap·커밋 자동화 / -IDE diff·승인 UI 없음
Continue.dev	IDE 어시스턴트	+자동완성 통합 / -자율 도구 실행 모드는 약함
OpenHands	샌드박스 자율 SWE	+완전 격리 / -IDE 외부, 학습 곡선
Goose	CLI · MCP 네이티브	+터미널 친화 / -VS Code 통합 약함
Tabby	자체호스팅 코드 완성	+사내 모델 / -에이전트 아님

8-2. 언제 쓰면 안 되는가

⛔ 비추천 시나리오
1. 강한 컴플라이언스 — 코드가 LLM 제공자로 송신되는 게 사규 위반이면 OSS 모델 + Ollama로만 운영하거나 도입을 보류하세요.
2. 리얼타임 자동완성 — Cline은 “작업 단위”에 최적. 라인 단위 ghost text는 Copilot 계열이 정답.
3. 거대한 모노레포 전역 탐색 — 토큰 비용이 발산. 우선 ripgrep으로 좁히고 부분 적재.
4. 본 적 없는 인프라 코드 — Terraform/Helm 변경은 사람이 plan/diff 한 번 더 봐야 합니다. auto-approve 금지.
5. 완전 자율 무인 배치 — 헤드리스로 24/7 돌리고 싶다면 OpenHands·Devin류가 더 적합.

8-3. 실전 트러블슈팅 (경험 기반)

증상원인해결

“Context window full” 에러 무한 반복	대용량 파일을 통째로 read_file → 컨텍스트가 모델 한계 초과	New Task로 분할. 특정 줄 범위만 첨부하도록 프롬프트에 명시. 200k 컨텍스트 모델(Claude Sonnet)로 전환.
토큰 비용 급증 (예상보다 3배)	읽기 도구 자동승인 + 매 턴 큰 파일 재첨부 → 프롬프트 캐시 미스	캐시 친화 모델 사용. 같은 파일은 한 번만 첨부. .clinerules 로 “필요한 부분만 search_files 사용” 명시.
diff 적용 실패 (replace_in_file 매칭 안 됨)	파일 줄바꿈이 CRLF인데 LLM이 LF로 매칭 시도. 또는 탭/스페이스 혼용	VS Code 하단의 EOL 표시기로 LF 통일. .editorconfig 정비. 그래도 안 되면 write_to_file 로 전체 재작성 유도.
MCP 서버 연결 실패 (붉은 점)	npx/uvx PATH 누락. VS Code가 GUI에서 띄울 때 셸 PATH를 못 읽음 (특히 macOS)	command를 절대 경로로 지정 (예: /Users/me/.nvm/.../npx). 또는 wrapper 스크립트로 PATH 주입.
Windows에서 execute_command 실패	기본 셸이 cmd로 떨어져 LLM이 만든 bash/PowerShell 문법 미호환	Terminal 설정에서 PowerShell 7 또는 Git Bash를 기본 프로파일로. 시스템 프롬프트에 OS 명시.
섀도우 Git 디스크 폭주	node_modules · build 산출물 · 영상 파일까지 체크포인트에 포함	설정의 Checkpoint Exclude에 패턴 추가. 오래된 task의 체크포인트는 “Delete Task” 로 정리.
Plan 모드인데 파일이 수정됨	모델이 Plan 모드 도구 제약을 무시하고 write 시도 → 사용자가 무심코 Approve	Plan 모드용 자동승인 화이트리스트에 쓰기 도구 절대 포함 금지. 의심되면 체크포인트 복원.
OpenRouter rate limit	동일 모델에 단기간 burst. 무료 티어 한도	크레딧 충전 또는 다른 provider로 fallback. Plan/Act 분리로 호출 분산.
로컬 모델(Ollama)에서 도구 호출 실패	XML tool-use 출력 정확도 부족. 작은 모델은 형식 깨짐	최소 Qwen2.5-Coder 14B / Llama 3.1 70B 이상 권장. Plan 전용으로 로컬, Act는 클라우드 모델로 하이브리드.
한국어 입력이 잘림	한글 토큰화로 컨텍스트가 영어 대비 1.5~2배 빠르게 소진	긴 한글 명세는 영어로 요약하거나 .clinerules에 영어로 박아두기. 토큰 효율 5~10배 차이.

8-4. 핵심 트레이드오프 정리

트레이드오프얻는 것잃는 것

매 도구 승인	안전성·감사성	속도 (계속 클릭 필요)
섀도우 Git 체크포인트	롤백 가능 · 사고 방지	디스크 사용량 증가
모델 중립 (XML tool-use)	자유로운 모델 선택	JSON function-calling 대비 약한 모델 호환성
VS Code 종속	diff·terminal·git 통합	JetBrains·neovim 미지원 (별도 fork 필요)