Zed 사용자를 위해

Zed는 빠릅니다. 그래도 에이전트는 코드를 찾아야 합니다.

Zed 에이전트는 여러분이 연 파일과 준 지시를 바탕으로 작업합니다. Maguyva는 저장소 전체를 인덱싱해 MCP로 돌려주므로, 에이전트는 추측하는 대신 심볼이 어디 있는지 물어봅니다.

Free 등급: 저장소 3개, 인덱싱된 저장소 라인 최대 5만 줄, 카드 등록 불필요.

context_servers 항목 하나: URL 하나와 Authorization 헤더 하나.

Zed에 대해 알아둘 것

Zed에만 해당하는 네 가지 사실. 어려운 건 없습니다.

// 설정 파일

settings.json

원격 서버는 context_servers 아래에 둡니다. zed: open settings file로 파일을 열거나, Settings → AI → MCP Servers에서 서버를 추가하세요.

// 전송 방식

URL로 원격 연결

Zed는 HTTP로 Maguyva의 원격 엔드포인트에 바로 연결합니다. 로컬 프로세스도, Node.js도 필요 없습니다.

// 키

헤더에 그대로 기입

이 가이드에서는 Zed 헤더의 환경 변수 확장을 검증하지 않았으므로, 키를 Authorization 헤더에 직접 넣습니다. 커밋하는 파일이 아니라 사용자 설정에 두세요.

// 승인

도구 권한

Zed는 기본적으로 도구를 호출할 때마다 확인을 요청합니다. agent.tool_permissions.tools 아래에서 mcp:maguyva:find_symbol 같은 키로 Maguyva 도구를 하나씩 허용하세요.

프로젝트 지침은 작업 합의입니다. 활용하세요.

# .rules
- 변경을 완료라고 하기 전에 저장소 테스트 명령을 실행한다.
- 요청받은 패키지 안에서만 편집한다.

Zed는 프로젝트 지침 파일을 하나만 불러옵니다. .rules로 시작해 AGENTS.md와 CLAUDE.md를 포함하는 고정 목록에서 처음 일치하는 파일입니다. 개인 지침은 ~/.config/zed/AGENTS.md에 둡니다. 이런 용도로 쓰세요:

빌드, 테스트, lint 명령.
에이전트가 자꾸 틀리는 규칙.
에이전트가 건드리면 안 되는 디렉터리.

지침 파일은 에이전트에게 일하는 방법을 알려줍니다. 하지만 지금 바꾸려는 함수를 파일 4,000개 중 어느 것이 호출하는지는 알려주지 못합니다.

열린 버퍼가 한계에 부딪히는 곳

Zed 에이전트가 눈앞의 파일만으로는 알 수 없는 세 가지.

// 열린 파일은 저장소가 아니다

에이전트에게 보이는 건 여러분이 연 것과 grep으로 찾은 것뿐입니다. 다른 패키지에 있는 같은 이름의 헬퍼는 잘못된 쪽이 배포되기 전까지 똑같아 보입니다.

// 호출자는 화면에 없다

“이 시그니처를 바꾸면 무엇이 깨지나?”는 그래프 질문입니다. 인덱스가 없으면 에이전트는 턴이나 컨텍스트가 바닥날 때까지 파일을 하나씩 읽습니다.

// 컨텍스트에는 예산이 있다

에이전트가 파악하려고 여는 파일마다, 변경 자체에 쓸 수 있었던 토큰이 소모됩니다. file:line이 붙은 순위화된 답 하나가 탐색용 읽기 열 번보다 저렴합니다.

Zed 컨텍스트 서버로서의 Maguyva

context_servers 항목 하나로 Zed 에이전트가 얻는 것:

인덱싱된 저장소에 대한 11개의 도구 시맨틱, 구조적(AST), 그래프, 텍스트 검색에 더해 심볼 조회, 의존 요소, 파일 검색까지.
파일 경로와 줄 번호가 포함된 답 285개 이상의 언어에서. 에이전트가 처음부터 올바른 파일을 엽니다.
늘 최신인 도구 목록 서버가 변경을 알리면 Zed는 재시작 없이 그 서버의 도구를 다시 불러옵니다.

Zed는 에이전트에게 빠른 에디터를 줍니다.
Maguyva는 에이전트에게 코드의 지도를 줍니다.

두 가지 워크플로

먼저 지도에 묻고, 그다음 편집하세요.

// workflow 01

에이전트가 탭을 열기 전에 구현 찾기

zed agent> 외부 웹훅의 재시도 정책은 어디 있나요?

find_symbol("retryPolicy")
  src/webhooks/dispatch.ts:41   retryPolicy()   ← 구현
  src/webhooks/__mocks__/dispatch.ts:9   ← 목

→ 에이전트는 목이 아니라 dispatch.ts:41을 엽니다.
[exit 0]

순위화된 조회 한 번이 grep 한 바퀴를 대신합니다. 답은 에이전트가 바로 열 수 있는 경로와 줄로 돌아옵니다.

// workflow 02

시그니처를 바꾸기 전에 의존 요소 확인하기

zed agent> fetchInvoice에 timeout 인자를 추가해 줘

dependency_search("fetchInvoice", dependents)
  패키지 4개에 걸친 호출자 7개

→ 에이전트가 호출 지점 일곱 곳을 한 번에 고칩니다.
[exit 0]

영향 범위는 빌드가 실패한 뒤가 아니라 첫 편집 전에 나옵니다.

Zed에서 설정하기

세 단계로 끝. Free 등급: 저장소 3개, 인덱싱된 저장소 라인 최대 5만 줄, 카드 등록 불필요.

// step 01

maguyva.ai에서 저장소 인덱싱하기

답을 채점할 수 있도록 이미 잘 아는 저장소를 고르세요.

// step 02

Zed 설정의 context_servers에 Maguyva 추가하기

~/.config/zed/settings.json

{
  "context_servers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

// step 03

플레이스홀더를 바꾸고 질문 하나 해보기

mgv_xxxx를 여러분의 API 키로 바꾸고 저장하세요. 이미 답을 아는 질문 하나를 에이전트에게 한 뒤, 인용된 파일을 열어 보세요.