# AGENTS.md는 OpenCode에게 규칙을 알려줍니다. Maguyva는 코드를 보여줍니다.

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

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

OpenCode는 일하는 방식을 AGENTS.md에서 읽고, 나머지는 모두 MCP 서버를 호출합니다. Maguyva는 원격 MCP 서버로서 OpenCode에게 파일 경로와 줄 번호가 담긴, 질의 가능한 저장소 지도를 줍니다.

> mcp 아래 원격 항목 하나. 로컬에서는 아무것도 돌지 않습니다.

## OpenCode에 대해 알아둘 것

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

### opencode.json

프로젝트의 `opencode.json`에서 `mcp` 아래에 서버를 추가하세요. 모든 프로젝트에서 쓰려면 `~/.config/opencode/opencode.json`에 추가합니다.

### type: remote

OpenCode는 HTTP로 Maguyva의 엔드포인트에 연결합니다. 로컬에서는 아무것도 실행되지 않고 Node.js도 필요 없습니다.

### 환경 변수 참조

OpenCode는 설정 안의 환경 변수를 치환하므로, 헤더는 `Bearer {env:MAGUYVA_API_KEY}`가 되고 키는 커밋하는 파일에 들어가지 않습니다.

### 에이전트별로 범위 지정

MCP 서버마다 도구 정의가 컨텍스트에 더해집니다. OpenCode에서는 `"maguyva*": false` 같은 glob으로 서버의 도구를 전역에서 끄고, 필요한 에이전트에서만 다시 켤 수 있습니다.

## AGENTS.md는 작업 합의입니다. 활용하세요.

```text
> /init
# 저장소를 스캔해 AGENTS.md를 작성
```

OpenCode는 프로젝트 루트의 `AGENTS.md`와, 개인 규칙용 `~/.config/opencode/AGENTS.md`를 읽습니다. `AGENTS.md`가 없으면 `CLAUDE.md`로 대체합니다. 이런 용도로 쓰세요:

- 빌드, 테스트, lint 명령.
- 에이전트가 지켜야 할 규칙과 경계.
- 중요한 문서로 가는 포인터.

`/init` 시점의 스캔은 요약이지 인덱스가 아닙니다. 어제 추가된 함수를 누가 호출하는지 OpenCode에게 알려주지 않습니다.

## AGENTS.md가 한계에 부딪히는 곳

OpenCode가 grep과 인내심으로 메우는 세 가지 빈틈.

### // 요약은 인덱스가 아니다

AGENTS.md는 중요한 패키지 이름을 댈 수 있습니다. 모든 심볼과 호출 지점을 나열할 수는 없고, 그러려고 해서도 안 됩니다.

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

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

### // 파일은 어긋나기 마련

AGENTS.md는 작성된 날에는 맞습니다. 코드는 계속 움직이고, 파일은 누군가 기억해 낼 때에만 갱신됩니다.

## OpenCode의 원격 MCP 서버로서의 Maguyva

mcp 아래 항목 하나로 OpenCode가 얻는 것:

- **인덱싱된 저장소에 대한 11개의 도구**: 시맨틱, 구조적(AST), 그래프, 텍스트 검색에 더해 심볼 조회, 의존 요소, 파일 검색까지.
- **파일 경로와 줄 번호가 포함된 답**: 285개 이상의 언어에서.
- **어떤 모델에든 같은 답**: OpenCode는 여러 모델 공급자와 함께 동작합니다. 어느 모델이 묻든 Maguyva는 같은 지도를 돌려줍니다.

> AGENTS.md는 OpenCode에게 *일하는 방법*을 알려줍니다.
> Maguyva는 OpenCode에게 *일의 근거*를 줍니다.

## 두 가지 워크플로

같은 터미널에서 지도에 물어보세요.

### 01. 여러 패키지에 걸쳐 공유 타입 이름 바꾸기

```text
opencode> OrderStatus를 FulfillmentStatus로 이름 바꿔 줘

dependency_search("OrderStatus", dependents)
  패키지 8개에 걸친 참조 23건
structural_search(switch_statement, "OrderStatus")
  망라형 switch 4개

→ OpenCode가 switch까지 포함해 전체 목록을 편집합니다.
[exit 0]
```

망라형 switch야말로 텍스트 검색이 놓치고 컴파일러가 뒤늦게 잡아내는 곳입니다.

### 02. 코드와 문서 구분하기

```text
opencode> FEATURE_BULK_EXPORT는 어디서 읽나요?

text_pattern_search("FEATURE_BULK_EXPORT")
  src/config/flags.ts:17
  src/export/bulk.ts:5
  docs/flags.md:40   ← 문서뿐

→ 코드 경로 두 개, 낡은 문서 하나.
[exit 0]
```

정확히 일치하는 결과가 경로와 함께 오므로, OpenCode는 어느 쪽을 편집하기 전에 코드와 문서를 구분할 수 있습니다.

## OpenCode에서 설정하기

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

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

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

### 02. opencode.json의 mcp 아래에 Maguyva 추가하기

`opencode.json`

```json
{
  "mcp": {
    "maguyva": {
      "type": "remote",
      "url": "https://maguyva.tools/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MAGUYVA_API_KEY}"
      }
    }
  }
}
```

### 03. 키를 export하고 연결 확인하기

OpenCode를 실행하는 셸에서 `MAGUYVA_API_KEY`를 설정하세요. `opencode mcp list`가 설정된 서버를 모두 보여줍니다. 그런 다음 이미 답을 아는 질문 하나를 해보세요.

OpenCode의 [MCP 문서](https://opencode.ai/docs/mcp-servers/)에서 타임아웃, OAuth, 에이전트별 도구 접근을 다룹니다.

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

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