[AI 에이전트 프로토콜 시리즈 3편] ACP 실전 – Zed + Claude Agent로 AI 코딩 환경 구축하기

ACP 실전: Zed 에디터에서 AI 코딩 에이전트 활용하기

지난 1편에서 ACP(Agent Client Protocol)의 구조를, 2편에서 MCP(Model Context Protocol)의 핵심을 살펴봤다. 이번 3편에서는 이론을 넘어 실전으로 들어간다. ACP를 실제로 지원하는 에디터인 Zed에서 Claude Agent, Gemini CLI 등 외부 AI 에이전트를 설정하고 활용하는 방법을 단계별로 안내한다.

왜 Zed인가?

Zed는 Rust로 작성된 고성능 코드 에디터로, 2026년 현재 ACP를 가장 적극적으로 지원하는 클라이언트 중 하나다. VS Code가 익스텐션 생태계에 강점이 있다면, Zed는 ACP 프로토콜을 네이티브로 통합하여 외부 에이전트와의 연결을 에디터 수준에서 직접 처리한다.

2026년 1월 28일, Zed 팀은 ACP Registry의 출시를 발표했다. 이 레지스트리를 통해 에이전트 개발자는 한 번만 등록하면 Zed, JetBrains IDE 등 모든 ACP 호환 클라이언트에서 자동으로 사용할 수 있게 된다. Claude Code, Codex CLI, GitHub Copilot CLI, Gemini CLI 등 주요 에이전트가 이미 등록되어 있다.

Step 1: Zed 설치

macOS, Windows, Linux 모두 지원한다. 공식 사이트(zed.dev/download)에서 다운로드하거나, macOS에서는 Homebrew로 설치할 수 있다.

brew install --cask zed

설치 후 Zed를 실행하면 기본적인 에디터 환경이 준비된다. 에이전트 기능은 별도 플러그인 없이 내장되어 있다.

Step 2: Agent Panel 열기

에이전트 패널은 Zed의 핵심 AI 인터페이스다. 단축키로 바로 접근할 수 있다.

macOS: Cmd + ?
Windows/Linux: Ctrl + ?

패널이 열리면 우측 상단의 + 버튼을 클릭하여 새로운 에이전트 스레드를 시작할 수 있다. 여기서 Zed 내장 에이전트뿐 아니라 외부 에이전트도 선택 가능하다.

Step 3: Claude Agent 설정

Anthropic의 Claude Agent는 Claude Code를 기반으로 동작하며, ACP를 통해 Zed와 통신한다. 내부적으로는 claude-agent-acp라는 전용 어댑터가 ACP 프로토콜 변환을 담당한다.

설정 방법:

Agent Panel에서 + 버튼 클릭
Claude Agent 선택
처음 실행 시 인증 화면이 나타남
Anthropic API 키를 입력하거나 OAuth 인증 진행

키보드 단축키를 지정하려면 keymap.json에 다음을 추가한다.

[
  {
    "bindings": {
      "cmd-alt-c": ["agent::NewExternalAgentThread", { "agent": "claude_code" }]
    }
  }
]

인증이 완료되면 에디터 안에서 바로 Claude와 대화하며 코드를 생성하고, 리팩토링하고, 디버깅할 수 있다. 파일을 @멘션으로 컨텍스트에 추가하는 것도 가능하다.

Step 4: Gemini CLI 설정

Gemini CLI는 ACP의 레퍼런스 구현체로, Google이 공식 지원한다. Zed는 Gemini CLI를 자체적으로 관리하여 별도 설치 없이 바로 사용할 수 있다.

설정 방법:

Agent Panel에서 + 버튼 클릭
Gemini CLI 선택
처음 실행 시 자동으로 @google/gemini-cli 설치
인증 방식 선택: Google 로그인, Gemini API Key, 또는 Vertex AI

대부분의 사용자는 Google 로그인을 선택하면 된다. 브라우저에서 OAuth 인증이 진행되며, Zed는 토큰에 직접 접근하지 않는다.

이미 시스템에 Gemini CLI가 설치되어 있고 그것을 사용하고 싶다면 settings.json에 다음을 추가한다.

{
  "agent_servers": {
    "gemini": {
      "ignore_system_version": false
    }
  }
}

Step 5: ACP Registry에서 추가 에이전트 설치

ACP Registry는 에이전트의 앱스토어와 같다. Zed 안에서 바로 브라우징하고 설치할 수 있다.

현재 레지스트리에 등록된 주요 에이전트:

Claude Code – Anthropic의 코딩 에이전트
Codex CLI – OpenAI의 코딩 에이전트
GitHub Copilot CLI – GitHub의 AI 어시스턴트
OpenCode – 오픈소스 코딩 에이전트
Gemini CLI – Google의 AI 에이전트

레지스트리의 장점은 에이전트 개발자가 업데이트를 푸시하면 Zed의 익스텐션 리뷰 과정 없이 즉시 반영된다는 것이다. 항상 최신 버전을 사용할 수 있다.

ACP 기반 에이전트 활용 패턴

Zed 팀이 공유한 에이전트 활용 3원칙은 실전에서 매우 유용하다.

원칙 1: 이미 할 줄 아는 작업에만 에이전트를 사용하라

에이전트에게 코드를 시키기 전에 먼저 PLAN.md 파일에 계획을 작성하라. 목표, 제약 조건, 관련 파일을 명확히 정의하면 에이전트의 출력 품질이 극적으로 향상된다.

# PLAN.md 예시
## 목표
사용자 인증 모듈을 JWT 기반으로 리팩토링

## 관련 파일
- src/auth/handler.ts
- src/middleware/auth.ts
- src/types/user.ts

## 제약 조건
- 기존 세션 기반 인증과 하위 호환 유지
- refresh token 로직 포함
- 테스트 커버리지 80% 이상

원칙 2: 에이전트 루프에 계속 참여하라

에이전트가 예상치 못한 파일을 수정하거나, 같은 수정을 반복하거나, TODO 주석으로 대체하는 징후가 보이면 즉시 개입하라. 작은 단위로 작업을 나누어 리뷰 가능한 범위를 유지하는 것이 핵심이다.

원칙 3: 코드 리뷰를 반드시 하라

에이전트가 생성한 코드는 외부 기여자의 PR처럼 취급하라. 당신의 이름이 코드에 붙는다. 책임질 수 있는 코드만 머지하라.

ACP가 바꾸는 개발 워크플로우의 미래

ACP 이전에는 AI 코딩 도구가 에디터별로 독립적인 플러그인 형태였다. Copilot은 VS Code에 최적화되어 있었고, 다른 에디터에서는 제한적인 경험을 제공했다. ACP는 이 구조를 근본적으로 바꾼다.

현재 ACP를 지원하는 클라이언트 목록은 계속 늘어나고 있다:

Zed (네이티브 지원)
JetBrains IDE (공식 파트너십)
VS Code (vscode-acp 익스텐션)
Neovim (CodeCompanion, avante.nvim 등 플러그인)
Emacs (agent-shell.el)
Obsidian (Agent Client 플러그인)

에이전트 하나를 만들면 모든 에디터에서 동작하고, 에디터 하나에서 설정하면 모든 에이전트를 쓸 수 있다. 이것이 ACP가 약속하는 “한 번 구현하면 어디서든 동작한다(implement once, work everywhere)”의 현실이다.

다음 편 예고

4편에서는 ACP, MCP, 그리고 Google의 A2A(Agent-to-Agent) 프로토콜을 정면으로 비교한다. 세 프로토콜은 경쟁 관계인가, 보완 관계인가? 프로토콜 전쟁의 승자는 누가 될 것인가?