# Claude는 매 세션을 아무것도 모르는 채로 시작합니다.

Canonical source: https://maguyva.ai/ko/for-claude-code

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

`CLAUDE.md`는 Claude에게 행동 방식을 알려줍니다. 저장소에 무엇이 있는지는 알려주지 않습니다. Maguyva는 코드베이스를 인덱싱해 MCP로 되돌려주므로, Claude는 마치 이미 코드를 읽은 것처럼 편집합니다.

> 행동 방식은 CLAUDE.md로. 현재 코드베이스 사실은 Maguyva로.

## CLAUDE.md는 모범 사례입니다. 그대로 활용하세요.

```text
> cat CLAUDE.md
# 프로젝트 관례, 명령어, 범위가 지정된 규칙
```

영구적인 지침은 `CLAUDE.md`에 두어야 합니다. 다음과 같은 내용에 적합한 곳입니다:

- 에이전트가 실행해야 할 빌드, 테스트, 린트 명령어.
- 코딩 스타일 규칙과 네이밍 관례.
- 디렉터리 범위로 한정된 “항상 X를 해라 / 절대 Y를 하지 마라” 가드레일.
- 정본 문서와 의사결정 로그에 대한 링크.

Anthropic의 [메모리 문서](https://code.claude.com/docs/en/memory)가 이를 잘 설명하고 있습니다. 간결하게 유지하세요. 범위를 정하세요. 커밋하세요.

하지만 `CLAUDE.md`가 코드베이스의 지도가 되도록 만들어진 적은 없습니다.

## CLAUDE.md만으로는 충분하지 않게 되는 지점

마크다운만으로는 고칠 수 없는 네 가지 실패 양상.

### // 파일은 코드베이스가 아닙니다

Claude에게 *어떻게 행동할지* 알려주는 것은 *무엇이 존재하는지* 알려주는 것과 다릅니다. 낯선 저장소에서의 첫 편집은 파일 경로, 함수 이름, 호출 지점에 대한 추측이 됩니다. CLAUDE.md는 모든 심볼을 나열할 수 없고, 그러길 원하지도 않을 것입니다.

### // 문서는 낡지만 코드는 그렇지 않습니다

인증 흐름을 설명하는 `CLAUDE.md` 블록은 누군가 인증을 리팩터링하기 전까지는 맞습니다. 이제 코드가 진실의 원천이고 문서는 확신에 찬 채로 틀려 있습니다. Claude는 틀린 쪽을 읽습니다.

### // 의존성은 마크다운에 없습니다

“이 함수를 변경하면 무엇이 깨지는가?”는 그래프 질문입니다. 문서 파일로는 답할 수 없습니다. Claude는 grep을 걸고 운에 맡기거나, 파일을 채팅에 붙여넣어 달라고 요청합니다.

### // 컨텍스트 윈도우에는 예산이 있습니다

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

## Maguyva는 CLAUDE.md가 다루지 못하는 레이어입니다

Claude Code에 다음을 제공하는 원격 MCP 서버입니다:

- **시맨틱, AST, 그래프, 텍스트 검색**: 인덱싱된 저장소 전체에서, 파일 경로와 줄 번호와 함께 반환됩니다.
- **의존성, 타입, 호출 지점 조회**: 그래프는 답할 수 있지만 문서 파일은 답할 수 없는 질문들입니다.
- **브랜치 인식 결과**: Claude가 실제로 편집 중인 코드 버전을 보게 됩니다.
- **워크스페이스 단위 요금제**: 좌석 단위가 아닙니다. 저장소 1개든 50개든 인덱싱하세요. 에이전트는 좌석 비용을 내지 않습니다.

> CLAUDE.md는 Claude에게 *어떻게 행동할지* 알려줍니다.
> Maguyva는 Claude에게 *코드의 조회 가능한 지도*를 제공합니다.

## 세 가지 워크플로

번호가 매겨진, 코드 블록 위주의 예시입니다. 여러분이 이미 Claude에게 하는 질문들이, 실제 코드 줄에 근거해 답을 얻습니다.

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

```text
사용자: "결제 클라이언트에서 재시도는 어떻게 작동하나요?"

Maguyva 없이 → Claude가 retry를 grep으로 검색해 14개의 결과를 찾고, 그중 하나를 고릅니다(종종 테스트 목).
Maguyva와 함께    → Maguyva가 심볼 정의, 호출 지점, 그리고
                   랭킹된 실제 구현의 file:line을 반환합니다.
```

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

```text
사용자: "normalizePhoneNumber를 호출하는 곳은 어디인가요?"

Maguyva의 반환값: 4개 패키지에 걸친 7개의 호출 지점. 그중 하나는 gRPC 스텁을
통해 이를 임포트하는 Python 서비스에 있습니다. Claude는 CI가 실패한 뒤가 아니라
마이그레이션 목록을 인라인으로 포함해 변경 사항을 제안합니다.
```

### 03. diff를 승인하기 전에 에이전트를 검증하기

```text
Claude: "토큰 갱신을 고치기 위해 src/auth/session.ts:142를 편집했습니다."

Maguyva에게 물어보기: "session.ts:130-160과 session을 임포트하는 모든 것을 보여주세요."

Maguyva가 반환한 실시간 파일 조각과 3개의 임포터. 이제 diff는 토큰 #11,000 시점의
Claude 기억이 아니라 실제 코드 줄에 근거합니다.
```

## Claude Code에서 설정하기

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

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

정확한 답변인지 확인할 수 있도록 잘 아는 저장소를 선택하세요. Free 등급은 저장소 3개, 인덱싱된 저장소 라인 최대 5만 줄까지 지원합니다.

### 02. Claude Code에 Maguyva 플러그인 설치하기

```text
/plugin marketplace add maguyva/agent-plugins
/plugin install maguyva@maguyva

# the plugin reads your key from the environment
export MAGUYVA_API_KEY=mgv_xxxx
```

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

회사 전체가 아니라 저장소 하나와 검증 가능한 질문 하나로 시작하세요. 답이 여러분이 생각한 것과 일치한다면 준비가 된 것입니다.

전체 안내는 [Maguyva의 문서](https://maguyva.ai/ko/docs)에서 확인할 수 있습니다.

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

답을 검증할 수 있는 질문 하나를 테스트해보세요. 온보딩은 그게 전부입니다.