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

Canonical source: https://maguyva.ai/ko/for-zed

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

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

> 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 도구를 하나씩 허용하세요.

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

```text
# .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는 에이전트에게 *코드의 지도*를 줍니다.

## 두 가지 워크플로

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

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

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

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

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

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

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

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

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

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

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

## Zed에서 설정하기

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

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

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

### 02. Zed 설정의 context_servers에 Maguyva 추가하기

`~/.config/zed/settings.json`

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

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

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

Zed 공식 [MCP 문서](https://zed.dev/docs/ai/mcp)에서 컨텍스트 서버, 에이전트 프로필, 도구 권한을 다룹니다.

## 이미 알고 있는 저장소 하나를 인덱싱하세요.

MCP로 Zed를 연결한 뒤, 확인할 수 있는 질문 하나를 해보세요.