AI 코딩 · 2026년 7월 10일 · 약 7분
Understand Anything 사용법: 코드베이스를 AI 지식 그래프로 바꿔 읽는 방법
Understand Anything은 코드와 문서를 인터랙티브 지식 그래프로 바꿔 Claude Code, Codex, Cursor, Copilot, Gemini CLI에서 탐색할 수 있게 해주는 오픈소스 도구다. 설치 방법, 첫 실행 순서, 토큰 사용 주의점, 팀에서 활용하는 방법을 초보자 기준으로 정리했다.
- Understand Anything
- AI 코드 분석
- 코드베이스 지식 그래프
- Claude Code
- Codex
- Cursor
- Gemini CLI
- AI 코딩 도구
출처: Egonex-AI GitHub
새 프로젝트를 열었는데 폴더 이름부터 낯설다면, 바로 코드를 고치기보다 구조부터 펼쳐 보세요. Understand Anything은 코드베이스와 문서를 인터랙티브 지식 그래프로 펼쳐 보여주는 오픈소스 도구입니다. 파일, 함수, 클래스, 의존 관계를 따라가다 보면 “어디부터 읽어야 하지?”에서 멈추는 시간을 줄일 수 있습니다.
2026년 7월 9일 GitHub API 기준으로 이 저장소는 72,338 stars, 6,034 forks, 264 open issues를 기록했고, 같은 날 push도 확인됐습니다. README는 Claude Code, Codex, Cursor, Copilot, Gemini CLI 등 여러 AI 코딩 도구와 함께 쓰는 방법을 안내합니다. 단순 코드 검색 도구라기보다, AI와 사람이 함께 참고할 “프로젝트 지도”를 만든다고 보면 이해하기 쉽습니다.
핵심 키워드
- Understand Anything 사용법
- AI 코드 분석
- 코드베이스 지식 그래프
- Claude Code 플러그인
- Codex 코드베이스 탐색
- AI 코딩 도구 활용법
Understand Anything이 하는 일
README 기준으로 Understand Anything은 코드베이스와 문서를 인터랙티브 지식 그래프로 바꿉니다. 여기서 말하는 지식 그래프는 프로젝트 안의 파일, 함수, 클래스, 문서, 의존 관계를 서로 연결해 보여주는 구조입니다. 처음 보는 저장소를 열었을 때 모든 파일을 위에서부터 읽는 대신, 중요한 연결 지점부터 살펴볼 수 있습니다.
| 상황 | 어떻게 도움을 주나 | 초보자에게 좋은 이유 |
|---|---|---|
| 처음 보는 코드베이스 | 파일과 함수 관계를 그래프로 탐색 | 읽을 순서를 잡기 쉽다 |
| 문서가 많은 프로젝트 | 코드와 문서를 함께 구조화 | 기능 설명과 실제 구현을 연결해 볼 수 있다 |
| AI 코딩 도구 사용 | Claude Code, Codex, Cursor 등에서 맥락을 더 잘 전달 | 막연한 질문보다 구체적인 질문을 만들 수 있다 |
| 변경 영향 확인 | 수정한 부분과 주변 연결을 확인 | 리팩터링 전 점검 포인트를 찾기 쉽다 |
Claude Code에서 설치하는 방법
Claude Code를 쓰고 있다면 README에 안내된 플러그인 명령으로 시작할 수 있습니다. 아래 두 줄을 순서대로 입력하면 됩니다.
Claude Code 설치 명령
- /plugin marketplace add Egonex-AI/Understand-Anything
- /plugin install understand-anything
Codex, Gemini, OpenCode 등에서는 one-line installer를 사용하는 방식이 안내되어 있습니다. 예를 들어 Codex용 설치는 아래 명령처럼 실행합니다. 설치 방식은 사용하는 도구와 환경에 따라 달라질 수 있으니, 실제 실행 전에는 GitHub README의 최신 설치 문구를 확인하세요.
Codex 설치 예시
- curl -fsSL https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.sh | bash -s codex
Codex, Gemini, OpenCode 계열 설치 흐름
- GitHub 저장소의 README에서 one-line installer 문구를 확인한다.
- 현재 쓰는 도구 이름이 installer에서 지원되는지 확인한다.
- 프로젝트 루트가 아니라 도구 설치 환경에 맞는 위치에서 실행한다.
- 설치 후 새 터미널이나 AI 코딩 도구 세션을 열어 명령이 잡히는지 확인한다.
첫 실행은 /understand부터 시작한다
설치가 끝났다면 프로젝트 루트에서 /understand를 실행합니다. 이 명령은 .understand-anything/knowledge-graph.json 파일을 만들고, 이후 그래프 탐색의 바탕이 되는 정보를 준비합니다. 처음 실행할 때는 저장소를 넓게 읽기 때문에 토큰 사용량이 커질 수 있습니다.
첫 실행 순서
- 프로젝트 루트 폴더를 연다.
- /understand를 실행해 .understand-anything/knowledge-graph.json 파일을 만든다.
- /understand-dashboard를 실행해 그래프 화면을 연다.
- 핵심 폴더, 주요 함수, 자주 연결되는 파일부터 클릭해 본다.
- 궁금한 흐름은 /understand-chat으로 자연어 질문을 던진다.
자주 쓰는 명령과 활용법
Understand Anything은 한 번 그래프를 만든 뒤 여러 명령으로 탐색을 이어가도록 설계되어 있습니다. 첫 분석 이후에는 변경 파일 중심의 증분 실행이 안내되어 있으므로, 매번 전체 저장소를 처음부터 다시 읽는 방식으로만 생각하지 않아도 됩니다.
| 명령 | 쓸 때 | 기대할 수 있는 효과 |
|---|---|---|
| /understand | 프로젝트 구조를 처음 분석할 때 | .understand-anything/knowledge-graph.json 생성 |
| /understand-dashboard | 그래프를 눈으로 확인하고 싶을 때 | 파일, 함수, 의존 관계를 탐색 |
| /understand-chat | 특정 흐름을 질문하고 싶을 때 | 코드 구조를 자연어로 물어보기 |
| /understand-diff | 변경 영향이 걱정될 때 | 수정한 부분 주변의 연결 확인 |
| /understand-onboard | 새 팀원이나 본인이 빠르게 맥락을 잡아야 할 때 | 읽을 순서와 핵심 구조 파악 |
| /understand-domain | 코드가 비즈니스 흐름과 어떻게 이어지는지 보고 싶을 때 | 도메인 관점으로 구조 정리 |
실무에서 바로 써볼 방법
가장 쉬운 시작은 작은 저장소나 하위 폴더에서 먼저 실행해 보는 것입니다. 전체 모노레포를 바로 분석하면 토큰 사용량과 처리 시간이 부담될 수 있습니다. 익숙하지 않은 프로젝트라면 핵심 기능 하나만 골라 그래프를 열고, 질문을 던지고, 변경 영향까지 확인하는 순서로 써보세요.
초보자용 실습 루틴
- 1단계: 작은 저장소나 기능 폴더에서 /understand를 실행한다.
- 2단계: /understand-dashboard에서 가장 많이 연결된 파일을 찾는다.
- 3단계: /understand-chat으로 “이 기능의 진입점은 어디야?”라고 묻는다.
- 4단계: 작은 수정 하나를 만든 뒤 /understand-diff로 주변 영향을 확인한다.
- 5단계: 팀 공유가 필요하면 그래프 결과를 최종 문서가 아니라 검토용 초안으로 다룬다.
복사해서 쓰는 질문 예시
그래프를 만든 뒤에는 질문을 너무 넓게 던지기보다, 기능과 확인 기준을 함께 적는 편이 좋습니다. 아래 문장에서 대괄호만 바꿔 쓰면 됩니다.
Understand Anything 질문 템플릿
- /understand-chat [로그인 / 결제 / 업로드] 기능의 시작 파일과 주요 호출 흐름을 알려줘.
- /understand-chat [파일명]이 어떤 모듈과 연결되어 있는지 초보자 기준으로 설명해줘.
- /understand-chat 이 프로젝트에서 [도메인 이름]과 관련된 핵심 파일 5개를 읽을 순서대로 추천해줘.
- /understand-diff 이번 변경이 영향을 줄 수 있는 주변 파일과 테스트 후보를 정리해줘.
- /understand-onboard 새로 합류한 개발자가 첫날 읽어야 할 구조를 단계별로 알려줘.
주의할 점
Understand Anything은 코드를 완벽히 대신 읽어주는 도구가 아닙니다. 사람이 프로젝트 구조를 더 빨리 잡도록 돕는 보조 도구에 가깝습니다. GitHub에 open issues가 264개 있다는 점도 설치 환경, 대형 저장소, 플랫폼별 차이를 확인하며 써야 한다는 신호로 볼 수 있습니다. 중요한 변경을 하기 전에는 그래프 설명을 그대로 믿지 말고 실제 코드, 테스트, 공식 문서를 함께 확인하세요.
| 문제 | 흔한 원인 | 해결 방법 |
|---|---|---|
| 첫 실행이 부담스럽다 | 저장소 범위가 너무 넓다 | 작은 저장소나 하위 폴더부터 시도한다 |
| 토큰 사용량이 크다 | 초기 분석에서 많은 파일을 읽는다 | 필요한 프로젝트에서만 실행하고 변경 후에는 증분 실행을 활용한다 |
| 그래프가 복잡하다 | 연결된 파일이 많다 | 핵심 기능 하나를 정해 관련 노드부터 본다 |
| 설명이 맞는지 불안하다 | AI 설명은 추론을 포함할 수 있다 | 실제 코드와 테스트로 다시 확인한다 |
오늘 바로 해볼 한 가지
최근에 열어 봤지만 구조가 잘 잡히지 않았던 저장소 하나를 고르세요. 전체를 이해하려고 오래 붙잡기보다 /understand로 그래프를 만들고, /understand-dashboard에서 가장 중심이 되는 파일을 3개만 확인해 봅니다. 그다음 /understand-chat에 “이 프로젝트에서 내가 먼저 읽어야 할 파일 순서를 알려줘”라고 물어보세요. 바로 수정에 들어가기 전, 어디를 봐야 할지 기준을 잡을 수 있습니다.
자주 묻는 질문
Understand Anything은 무엇인가요?
코드베이스와 문서를 인터랙티브 지식 그래프로 바꿔 주는 오픈소스 도구입니다. 처음 보는 프로젝트의 파일, 함수, 클래스, 의존 관계를 탐색하는 데 쓸 수 있습니다.
Claude Code 없이도 사용할 수 있나요?
README는 Claude Code뿐 아니라 Codex, Cursor, Copilot, Gemini CLI 등 여러 AI 코딩 도구와 함께 쓰는 흐름을 안내합니다. 다만 설치와 동작 방식은 사용하는 도구별로 README를 확인하는 편이 안전합니다.
/understand를 실행하면 어떤 파일이 만들어지나요?
/understand는 .understand-anything/knowledge-graph.json 파일을 생성합니다. 이 파일이 그래프 탐색의 기반이 됩니다.
첫 실행에 토큰이 많이 드는 이유는 무엇인가요?
초기 분석에서는 프로젝트의 코드와 문서를 넓게 읽어 구조를 만들기 때문입니다. 이후 실행은 변경 파일 중심의 증분 방식이 안내되어 있습니다.
AI가 만든 코드 설명을 그대로 믿어도 되나요?
그대로 믿기보다 탐색 보조 자료로 쓰는 편이 좋습니다. 중요한 판단은 실제 코드, 테스트 결과, 공식 문서와 함께 확인해야 합니다.