Goose 사용자를 위해

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

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

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

일하는 방식은 .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 힌트는 작업 합의입니다. 활용하세요.

# .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에게 맡기기.

// workflow 01

버그를 근원까지 추적하기

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가 셸을 열기 전에 순위화된 결과가 탐색 범위를 좁힙니다.

// workflow 02

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

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

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

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

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

Goose에서 설정하기

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

// step 01

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

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

// step 02

config.yaml의 extensions에 Maguyva 추가하기

~/.config/goose/config.yaml

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

// step 03

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

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