// 파일은 코드베이스가 아닙니다
Claude에게 어떻게 행동할지 알려주는 것은 무엇이 존재하는지 알려주는 것과 다릅니다. 낯선 리포지토리에서의 첫 편집은 파일 경로, 함수 이름, 호출 지점에 대한 추측이 됩니다. CLAUDE.md는 모든 심볼을 나열할 수 없고, 그러길 원하지도 않을 것입니다.
Claude Code 사용자를 위해
Claude는 매 세션을 아무것도 모르는 채로 시작합니다.
CLAUDE.md는 Claude에게 행동 방식을 알려줍니다. 리포지토리에 무엇이 있는지는 알려주지 않습니다. Maguyva는 코드베이스를 인덱싱해 MCP로 되돌려주므로, Claude는 마치 이미 코드를 읽은 것처럼 편집합니다.
Free 등급: 리포지토리 3개, 인덱싱된 리포지토리 라인 최대 5만 줄, 카드 등록 불필요.
행동 방식은 CLAUDE.md로. 현재 코드베이스 사실은 Maguyva로.CLAUDE.md는 모범 사례입니다. 그대로 활용하세요.
> cat CLAUDE.md
# 프로젝트 관례, 명령어, 범위가 지정된 규칙영구적인 지침은 CLAUDE.md에 두어야 합니다. 다음과 같은 내용에 적합한 곳입니다:
- 에이전트가 실행해야 할 빌드, 테스트, 린트 명령어.
- 코딩 스타일 규칙과 네이밍 관례.
- 디렉터리 범위로 한정된 “항상 X를 해라 / 절대 Y를 하지 마라” 가드레일.
- 정본 문서와 의사결정 로그에 대한 링크.
Anthropic의 메모리 문서가 이를 잘 설명하고 있습니다. 간결하게 유지하세요. 범위를 정하세요. 커밋하세요.
하지만 CLAUDE.md가 코드베이스의 지도가 되도록 만들어진 적은 없습니다.
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에게 하는 질문들이, 실제 코드 줄에 근거해 답을 얻습니다.
// workflow 01
테스트 스텁이 아니라 실제 구현 찾기
You: "결제 클라이언트에서 재시도는 어떻게 작동하나요?"
Maguyva 없이 → Claude가 retry를 grep으로 검색해 14개의 결과를 찾고, 그중 하나를 고릅니다(종종 테스트 목).
Maguyva와 함께 → Maguyva가 심볼 정의, 호출 지점, 그리고
랭킹된 실제 구현의 file:line을 반환합니다.// workflow 02
리팩터링 전에 영향 범위 확인하기
You: "normalizePhoneNumber를 호출하는 곳은 어디인가요?"
Maguyva의 반환값: 4개 패키지에 걸친 7개의 호출 지점. 그중 하나는 gRPC 스텁을
통해 이를 임포트하는 Python 서비스에 있습니다. Claude는 CI가 실패한 뒤가 아니라
마이그레이션 목록을 인라인으로 포함해 변경 사항을 제안합니다.// workflow 03
diff를 승인하기 전에 에이전트를 검증하기
Claude: "토큰 갱신을 고치기 위해src/auth/session.ts:142를 편집했습니다." Maguyva에게 물어보기: "session.ts:130-160과 session을 임포트하는 모든 것을 보여주세요." Maguyva가 반환한 실시간 파일 조각과 3개의 임포터. 이제 diff는 토큰 #11,000 시점의 Claude 기억이 아니라 실제 코드 줄에 근거합니다.
Claude Code에서 설정하기
세 단계로 끝. Free 등급: 리포지토리 3개, 인덱싱된 리포지토리 라인 최대 5만 줄, 카드 등록 불필요.
// step 01
maguyva.ai에서 리포지토리 인덱싱하기
정확한 답변인지 확인할 수 있도록 잘 아는 저장소를 선택하세요. Free 등급은 리포지토리 3개, 인덱싱된 리포지토리 라인 최대 5만 줄까지 지원합니다.
// step 02
Claude Code에 Maguyva 플러그인 설치하기
/plugin marketplace add maguyva/claude-code-plugin /plugin install maguyva@maguyva # the plugin reads your key from the environment export MAGUYVA_API_KEY=mgv_xxxx// step 03
이미 답을 알고 있는 질문 하나 해보기
회사 전체가 아니라 리포지토리 하나와 검증 가능한 질문 하나로 시작하세요. 답이 여러분이 생각한 것과 일치한다면 준비가 된 것입니다.