# Goose는 확장으로 움직입니다. 저장소를 아는 확장을 하나 더하세요.

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

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).

Goose는 확장을 통해 일하고, 모든 확장은 MCP 서버입니다. Maguyva는 코드베이스를 인덱싱하는 확장이라, Goose가 디렉터리를 나열하는 대신 무엇이 어디 있는지 물어봅니다.

> 일하는 방식은 .goosehints에. 지금 코드가 말하는 것은 Maguyva에.

## Goose에 대해 알아둘 것

Goose에만 해당하는 네 가지 사실.

### config.yaml

확장은 `~/.config/goose/config.yaml`의 `extensions` 아래에 둡니다. `goose configure` → Add Extension으로도 같은 종류의 항목이 작성됩니다.

### 원격 확장

Maguyva는 `streamable_http` 확장이므로 Goose가 직접 엔드포인트에 연결합니다. 로컬 프로세스도 Node.js도 필요 없습니다. URL은 `url`이 아니라 `uri`에 적습니다.

### headers

Goose는 요청마다 `headers` 맵을 보내므로 키는 `Authorization` 헤더에 넣습니다. `env_keys`에 나열한 환경 변수에서 채울 수도 있습니다.

### available_tools

확장은 도구 일부만 노출할 수 있습니다. 원하는 도구를 `available_tools` 아래에 나열하거나, 비워 두면 전부 쓸 수 있습니다.

## Goose 힌트는 작업 합의입니다. 활용하세요.

```text
# .goosehints
- npm이 아니라 pnpm을 쓴다.
- 변경을 완료라고 하기 전에 통합 테스트를 실행한다.
```

Goose는 기본적으로 `AGENTS.md`와 `.goosehints`를 불러옵니다. 전역 힌트는 `~/.config/goose/.goosehints`에서, 프로젝트 힌트는 저장소에서, 하위 폴더에서 작업할 때는 중첩된 파일도 읽습니다. 힌트를 쓰려면 Developer 확장이 필요합니다. 힌트에 적합한 것:

- 도구 선택과 명령.
- Goose가 따라야 할 규칙.
- 문서가 있는 위치.

힌트는 프로젝트를 설명합니다. “이것에 의존하는 건 무엇인가?”에는 답하지 않습니다.

## 힌트와 셸이 한계에 부딪히는 곳

Goose가 셸 명령으로, 파일 하나씩 메우는 세 가지 빈틈.

### // 목록은 지도가 아니다

낯선 저장소에서 Goose는 디렉터리 목록과 파일 읽기로 상황을 파악합니다. 그때마다 작업이 시작되기도 전에 컨텍스트를 씁니다.

### // grep은 호출자가 아니라 문자열을 찾는다

텍스트 검색으로는 진짜 호출과 주석, 목, 같은 이름의 메서드를 구분할 수 없습니다.

### // 힌트는 어긋나기 마련

지난 분기에 쓴 힌트 파일은 지난 분기의 구조를 설명합니다. 그래도 Goose는 따릅니다.

## Goose 확장으로서의 Maguyva

extensions 항목 하나로 Goose가 얻는 것:

- **인덱싱된 저장소에 대한 11개의 도구**: 시맨틱, 구조적(AST), 그래프, 텍스트 검색에 더해 심볼 조회, 의존 요소, 파일 검색까지.
- **파일 경로와 줄 번호가 포함된 답**: 285개 이상의 언어에서.
- **읽기만 하는 도구**: Maguyva의 도구는 인덱스를 조회할 뿐, 어느 것도 여러분의 파일을 편집하지 않습니다.

> 힌트는 Goose에게 *일하는 방법*을 알려줍니다.
> Maguyva는 Goose에게 *코드의 지도*를 줍니다.

## 두 가지 워크플로

먼저 지도, 그다음 Goose에게 맡기기.

### 01. 버그를 근원까지 추적하기

```text
goose> 일부 내보내기가 0행으로 끝나는 이유는?

semantic_search("export job empty result")
  src/export/runner.ts:118   flushBatch()
  src/export/filters.ts:40   applyTenantFilter()

→ Goose는 export 패키지 전체가 아니라 파일 두 개만 읽습니다.
[exit 0]
```

Goose가 셸을 열기 전에 순위화된 결과가 탐색 범위를 좁힙니다.

### 02. 리팩터링 전에 의존 요소 확인하기

```text
goose> Notifier 클래스를 이메일과 SMS로 나눠 줘

dependency_search("Notifier", dependents)
  패키지 5개에 걸친 참조 11건

→ 첫 편집 전에 계획이 열한 곳을 모두 다룹니다.
[exit 0]
```

Goose는 grep을 줄줄이 돌리는 대신 호출 한 번으로 전체 의존 요소 목록을 얻습니다.

## Goose에서 설정하기

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

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

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

### 02. config.yaml의 extensions에 Maguyva 추가하기

`~/.config/goose/config.yaml`

```yaml
extensions:
  maguyva:
    name: maguyva
    type: streamable_http
    uri: https://maguyva.tools/mcp
    enabled: true
    headers:
      Authorization: Bearer mgv_xxxx
    timeout: 300

```

### 03. 플레이스홀더를 바꾸고 세션 시작하기

`mgv_xxxx`를 여러분의 API 키로 바꾸고, `goose session`을 실행한 뒤, 이미 답을 아는 질문 하나를 해보세요. YAML은 들여쓰기에 민감합니다. 탭이 아니라 공백을 쓰세요.

Goose의 [확장 문서](https://goose-docs.ai/docs/getting-started/using-extensions/)에서 원격 확장, 타임아웃, 도구 필터를 다룹니다.

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

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