Mason – LLM을 위한 컨텍스트 빌더 👷

Mason은 LLM에게 코드베이스의 영구적인 맵을 제공하여 매 세션마다 처음부터 탐색하지 않도록 합니다.

문제점: LLM이 코드에 대해 새로운 대화를 시작할 때마다 grep을 수행하고, 파일을 읽고, 아키텍처를 조합합니다. 이는 어제 이미 이해했던 컨텍스트에 대해 토큰을 낭비하는 것입니다. 164개의 파일로 구성된 프로젝트에서 "이 앱은 어떤 기능을 가지고 있는가?"라는 질문에 답하려면 여러 도구 호출을 통해 8개 이상의 파일을 읽어야 합니다.

Mason의 해결책: 세션 간에 유지되는 개념 맵입니다. 하나의 도구 호출로 기능-파일 조회 테이블을 반환하므로, LLM은 탐색할 필요 없이 정확히 어디를 봐야 할지 알 수 있습니다.

측정 결과 (deepeval, Claude Sonnet, 164개 파일 KMP 프로젝트):

동일한 답변 품질(모든 테스트에서 0.9/1.0). 재현 방법: bench/.

빠른 시작

claude mcp add mason --scope user -- npx -p mason-context mason-mcp

Claude Code를 재시작한 후 다음을 요청하세요: "use mason to analyze this project and create a snapshot."

그것으로 충분합니다. Mason이 코드베이스를 분석하고 개념 맵을 생성합니다. 다음 세션에서는 모든 것을 다시 탐색하는 대신 맵을 로드합니다.

Related MCP server: ontomics

작동 원리

개념 맵

Mason의 핵심 기능입니다. 대화 간에 유지되는 .mason/snapshot.json에 기능-파일 맵을 저장합니다. LLM이 프로젝트를 이해해야 할 때, 전체 코드베이스를 grep하는 대신 이 맵을 읽습니다:

{
  "features": {
    "home screen": {
      "files": ["HomeScreen.kt", "HomeViewModel.kt", "GetWeatherDataUseCase.kt"]
    }
  },
  "flows": {
    "weather fetch": {
      "chain": ["HomeViewModel.kt", "WeatherRepositoryImpl.kt", "WeatherServiceImpl.kt"]
    }
  }
}

이 맵은 LLM 자체가 생성합니다. Mason은 분석 도구를 제공하고, LLM은 코드를 해석하여 기능과 흐름이 무엇인지 결정합니다. 즉, 이 맵은 단순한 파일 목록이 아니라 아키텍처에 대한 이해를 담고 있습니다.

AI 어시스턴트에게 *"create a mason snapshot"*이라고 요청하거나 CLI를 통해 생성하세요:

mason set-llm gemini          # configure a provider (no API key needed)
mason snapshot ~/my-project   # generate concept map
mason snapshot --install-hook # auto-update on every commit

변경 영향 분석

파일을 편집하기 전에 Mason은 영향을 받을 수 있는 다른 부분을 알려줄 수 있습니다. 수동으로 여러 도구를 호출해야 얻을 수 있는 세 가지 신호를 결합합니다:

• 공동 변경 기록(Co-change history) — git 커밋에서 역사적으로 함께 변경된 파일들

• 참조(References) — 대상을 이름으로 가져오거나 언급하는 파일들

• 관련 테스트(Related tests) — 명명 규칙에 따라 대상과 쌍을 이루는 테스트 파일들

mason impact WeatherRepository.kt -d ~/my-project

get_impact MCP 도구로도 사용할 수 있습니다. 어시스턴트에게 *"what would be affected if I changed WeatherRepository?"*라고 물어보세요.

Git 기록 분석

Mason은 수백 개의 커밋을 실행 가능한 통계로 집계합니다: 가장 자주 변경되는 파일(주의해야 할 핫 파일), 몇 달 동안 수정되지 않은 디렉토리(잠재적으로 오래된 코드), 팀이 따르는 커밋 규칙 등입니다. 이는 수동으로 계산하려면 수십 번의 git log 호출이 필요한 분석 유형입니다.

mason analyze ~/my-project

MCP 도구

Mason은 Model Context Protocol을 통해 6개의 도구를 노출합니다. MCP 호환 클라이언트(Claude Code, Cursor 등)라면 무엇이든 사용할 수 있습니다:

CLI 사용법

Mason은 MCP 클라이언트 없이 CLAUDE.md 파일을 생성하고 분석을 실행하기 위한 독립형 CLI로도 작동합니다. LLM 공급자를 한 번 구성한 후 명령어를 사용하세요:

mason set-llm claude|gemini|ollama|openai  # configure provider
mason generate                # analyze codebase + LLM -> CLAUDE.md
mason analyze                 # git stats only (no LLM needed)
mason impact File.kt          # change impact analysis
mason snapshot                # create/update concept map

대부분의 공급자는 API 키 없이 작동합니다. claude, gemini, ollama 모두 각자의 CLI를 직접 사용합니다.

보안

스냅샷 포함 내용: 기능 이름, 상대 파일 경로, 흐름 설명. 소스 코드, 비밀 정보, 비즈니스 로직은 포함되지 않습니다.

접근하지 않는 항목: Mason은 .gitignore를 준수하며(git ls-files 사용), .env, .pem, .key, 자격 증명 및 기타 민감한 파일이 샘플링되지 않도록 차단하는 거부 목록을 가지고 있습니다. 경로 탐색 보호를 통해 모든 파일 액세스가 프로젝트 루트 내에 유지되도록 합니다.

LLM 데이터 흐름: CLI를 통해 스냅샷을 생성하면 샘플링된 파일 내용이 구성된 LLM 공급자로 전송됩니다. 이는 모든 AI 코딩 어시스턴트가 코드를 읽는 방식과 동일합니다. 완전히 로컬에서 생성하려면 ollama를 사용하세요. MCP 서버 도구(get_snapshot, get_impact 등)는 로컬 파일만 읽습니다.

언어 지원

Mason은 언어에 구애받지 않습니다. 언어별 파싱이 아닌 파일 명명 패턴과 git 기록을 사용하므로, 소스 파일과 git 저장소가 있는 모든 프로젝트(TypeScript, Kotlin, Python, Go, Rust, Swift, Java, C#, Dart 등)에서 작동합니다.

라이선스

MIT