# AGENTS.md는 Codex에게 작업 방식을 알려줍니다. 무엇이 있는지는 알려주지 않습니다.

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

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

AGENTS.md는 작업 합의를 설정합니다. MCP는 Codex가 도구에 손을 뻗을 수 있게 합니다. Maguyva는 Codex에게 저장소의 조회 가능한 지도를 제공하는 MCP 서버이므로, 첫 편집이 파일 구조에 대한 추측으로 시작되지 않습니다.

> AGENTS.md는 합의입니다. MCP는 통로입니다. Maguyva는 지도입니다.

## 레이어로 이루어진 스택

네 가지 개념. 각각 하나의 역할을 합니다.

### AGENTS.md

Codex가 이 저장소에서 어떻게 행동해야 하는지.

### MCP

Codex가 외부 도구와 컨텍스트에 접근하는 방법.

### Maguyva

근거 있는 저장소 사실을 반환하는 MCP 서버.

### 좌석이 아니라 워크스페이스

에이전트는 좌석 비용을 내지 않습니다. [요금제 보기](https://maguyva.ai/ko/pricing)

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

영구적인 지침은 [`AGENTS.md`](https://developers.openai.com/codex/guides/agents-md)에 두어야 합니다. 다음과 같은 내용에 적합한 곳입니다:

- Codex가 실행해야 할 빌드, 테스트, 린트 명령어.
- 디렉터리 범위로 한정된 “항상 X를 해라 / 절대 Y를 하지 마라” 가드레일.
- 네이밍 관례와 리팩터링 선호 방식.
- 정본 의사결정 로그와 아키텍처 노트에 대한 링크.

간결하게 유지하세요. 범위를 정하세요. 커밋하세요.

하지만 `AGENTS.md`는 저장소의 모든 심볼, 파일, 호출 지점을 조회 가능한 인덱스로 담도록 설계된 적이 없습니다.

## AGENTS.md 단독으로는 규모가 커질수록 정적으로 굳어버리는 지점

네 가지 실패 양상, 카드마다 하나씩.

### // 합의는 인덱스가 아닙니다

Codex에게 *어떻게 작업할지* 알려주는 것은 *무엇이 존재하는지* 알려주는 것과 다릅니다. 낯선 패키지에서의 첫 편집은 파일 경로와 함수 이름에 대한 추측이 됩니다. AGENTS.md는 모든 심볼을 나열할 수 없고, 그러길 원하지도 않을 것입니다.

### // 문서는 코드에서 멀어집니다

큐 토폴로지를 설명하는 AGENTS.md 블록은 누군가 새로운 컨슈머를 도입하기 전까지는 맞습니다. 이제 코드가 진실의 원천이고 문서는 확신에 찬 채로 낡아 있습니다. Codex는 틀린 쪽을 읽습니다.

### // 이름 변경은 그래프 문제입니다

“이 클래스를 참조하는 곳은 어디인가?”라는 질문은 마크다운 파일로는 답할 수 없습니다. Codex는 모노레포 전체에 grep을 걸고 운에 맡기거나, 호출 지점을 채팅에 붙여넣어 달라고 요청합니다.

### // 컨텍스트 윈도우는 공짜가 아닙니다

Codex가 "충분히 안다"고 여길 때까지 AGENTS.md를 채워 넣으면 추론에 쓰여야 할 토큰을 잡아먹습니다. 몇 KB를 넘어서면 답변 품질을 정적 컨텍스트 분량과 맞바꾸는 셈입니다.

## 세 레이어가 맞물리는 방식

Codex 사용자는 이미 이런 구조로 생각하고 있습니다. 이 페이지는 그것을 명확하게 보여줄 뿐입니다.

- **AGENTS.md**: 합의 (Codex가 행동하는 방식)
- **MCP**: 통로 (접근하는 방식)
- **Maguyva**: 코드베이스 사실 (보는 것)

- **AGENTS.md**: Codex가 이 저장소에서 행동하는 방식.
- **MCP**: Codex가 도구와 컨텍스트에 접근하는 방식. [(스펙)](https://modelcontextprotocol.io/docs/getting-started/intro)
- **Maguyva**: Codex가 코드베이스에 질문할 때 보는 것. 파일 경로와 줄 번호가 포함된 시맨틱, AST, 그래프, 텍스트 검색 결과입니다.

> AGENTS.md는 Codex에게 *어떻게 작업할지* 알려줍니다.
> Maguyva는 Codex에게 *작업의 출발점*을 제공합니다.

## 세 가지 워크플로

Codex에 특화되어 있습니다. Codex의 grep이 아니라 실제 호출 그래프에 근거합니다.

### 01. 공유 클래스 이름을 바꾸기 전에 모든 의존 항목부터 찾기

```text
codex> PaymentClient → BillingClient로 이름 변경

graph::callers(PaymentClient)            7개 패키지에 걸친 12개 참조
graph::importers(src/payments/client.ts)  9개 임포터
graph::extends(PaymentClient)             2개 서브클래스 (RetryClient, MockClient)

→ Codex가 파일 목록을 인라인으로 포함한 21건의 편집 마이그레이션을 제안합니다.
[exit 0]
```

Codex는 편집을 시작하기 *전에* Maguyva에게 의존 항목을 요청합니다. 마이그레이션 목록은 Codex의 기억이 아니라 실제 그래프에 근거해 돌아옵니다.

### 02. 테스트 스텁이 아니라 실제 구현 찾기

```text
codex> normalizePhoneNumber는 E.164를 어떻게 처리하나요?

semantic::query("normalize phone E.164")
  src/util/phone.ts:88   normalizePhoneNumber()   ← 실제 구현
  test/util/phone.spec.ts:14  jest.mock(...)      ← 스텁
[exit 0]
```

이름은 거짓말을 합니다. 목(mock)은 실제 코드를 가립니다. Maguyva는 테스트 목보다 실제 구현을 위에 올려 랭킹합니다.

### 03. 리팩터링 전에 영향 범위 확인하기

```text
codex> QueueDispatcher.publish를 호출하는 곳은 어디인가요?

graph::callers(QueueDispatcher.publish)
  3 in src/billing/*    1 in src/audit/*    1 in src/notifications/*
[exit 0]
```

패키지를 넘나드는 호출 지점이 인라인으로 드러납니다. 변경 사항은 Codex의 grep이 아니라 실제 임포터에 근거합니다.

## Codex CLI에서 설정하기

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

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

답을 검증할 수 있도록 잘 아는 저장소를 선택하세요.

### 02. Codex 설정에서 Maguyva를 MCP 서버로 추가하기

`~/.codex/config.toml`

```text
export MAGUYVA_API_KEY=mgv_xxxx
codex mcp add maguyva --url https://maguyva.tools/mcp --bearer-token-env-var MAGUYVA_API_KEY
```

```toml
[mcp_servers.maguyva]
url = "https://maguyva.tools/mcp"
bearer_token_env_var = "MAGUYVA_API_KEY"
```

### 03. 이미 답을 알고 있는 질문 하나 해보기

회사 전체로 시작하지 마세요. 저장소 하나와 검증 가능한 질문 하나로 시작하세요.

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

MCP를 통해 Codex를 연결하세요. 답을 검증할 수 있는 질문 하나를 해보세요.