Understand-Anything

KO | EN

gitlite — search

#react #ai #llm #rust #deep-learning #linux #nodejs #windows #cli #kubernetes #vue #security #openai #ios

Understand-Anything

(★ 79,512)

감동을 주는 그래프보다 가르쳐주는 그래프가 더 좋습니다. 어떤 코드든 탐색하고, 검색하고, 질문할 수 있는 인터랙티브 지식 그래프로 변환하세요. Claude Code, Codex, Cursor, Copilot, Gemini CLI 등과 함께 작동합니다.

Understand-Anything 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">Understand Anything</h1>

<p align="center">
  <strong>코드베이스, 지식 베이스 또는 문서를 탐색하고, 검색하고, 질문할 수 있는 대화형 지식 그래프로 변환하세요.</strong>
  <br />
  <em>Claude Code, Codex, Cursor, Copilot, Gemini CLI 등과 함께 작동합니다.</em>
</p>

<p align="center">
  <strong>Understand Anything. <a href="https://egonex.ai">Understand Anyone.</a></strong>
  <br />
  <em>AI는 사람을 대체하는 것이 아니라 도와야 합니다.</em>
</p>

<p align="center">
  <a href="README.md">English</a> | <a href="READMEs/README.zh-CN.md">简体中文</a> | <a href="READMEs/README.zh-TW.md">繁體中文</a> | <a href="READMEs/README.ja-JP.md">日本語</a> | <a href="READMEs/README.ko-KR.md">한국어</a> | <a href="READMEs/README.es-ES.md">Español</a> | <a href="READMEs/README.tr-TR.md">Türkçe</a> | <a href="READMEs/README.ru-RU.md">Русский</a>
</p>

<p align="center">
  <strong><a href="https://github.com/Egonex-AI">Egonex</a>의 오픈소스 프로젝트</strong>
  <br />
  <em>원작자: <a href="https://github.com/Lum1104">Lum1104</a>.</em>
</p>

---

**새로운 팀에 합류했습니다. 코드베이스가 20만 줄에 달합니다. 어디서부터 시작해야 할까요?**

Understand Anything은 멀티 에이전트 파이프라인으로 프로젝트를 분석하여 모든 파일, 함수, 클래스, 의존성에 대한 지식 그래프를 구축한 다음, 시각적으로 탐색할 수 있는 대화형 대시보드를 제공하는 [Claude Code Plugin](https://code.claude.com/docs/en/plugins-reference#plugins-reference)입니다. 맹목적인 코드 리딩은 그만두세요. 큰 그림을 확인하기 시작하세요.

> **목표는 코드베이스가 얼마나 복잡한지 보여주며 감탄을 자아내는 그래프가 아니라, 각 조각이 어떻게 맞물려 돌아가는지 조용히 가르쳐주는 그래프입니다.**

---

## ✨ 기능

> [!NOTE]
> **읽는 것을 건너뛰고 싶으신가요?** [홈페이지](https://understand-anything.com/)의 [라이브 데모](https://understand-anything.com/demo/)를 사용해 보세요. 브라우저에서 바로 패닝, 확대/축소, 검색, 탐색이 가능한 완전한 대화형 대시보드입니다.

### 구조적 그래프 탐색

대화형 지식 그래프로 코드베이스를 탐색하세요. 모든 파일, 함수, 클래스는 클릭하고, 검색하고, 탐색할 수 있는 노드입니다. 노드를 선택하여 평이한 영어로 된 요약, 관계 및 가이드 투어를 확인하세요.

### 비즈니스 로직 이해

도메인 뷰로 전환하여 코드가 실제 비즈니스 프로세스(수평 그래프로 배치된 도메인, 흐름, 단계)와 어떻게 매핑되는지 확인하세요.

### 지식 베이스 분석

[Karpathy-pattern LLM wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)에 `/understand-knowledge`를 지정하면 커뮤니티 클러스터링이 포함된 힘 방향(force-directed) 지식 그래프를 얻을 수 있습니다. 결정론적 파서(deterministic parser)가 `index.md`에서 위키 링크와 카테고리를 추출하고, LLM 에이전트가 암묵적 관계를 발견하고, 엔티티를 추출하며, 클레임을 표면화하여 위키를 상호 연결된 아이디어의 탐색 가능한 그래프로 변환합니다.

<table>
  <tr>
    <td width="50%" valign="top">
      <h3>🧭 가이드 투어 (Guided Tours)</h3>
      <p>의존성에 따라 정렬된 아키텍처 자동 생성 워크스루입니다. 올바른 순서로 코드베이스를 학습하세요.</p>
    </td>
    <td width="50%" valign="top">
      <h3>🔍 퍼지 및 시맨틱 검색 (Fuzzy & Semantic Search)</h3>
      <p>이름이나 의미로 무엇이든 찾으세요. "인증을 처리하는 부분이 어디지?"라고 검색하여 그래프 전체에서 관련 결과를 얻으세요.</p>
    </td>
  </tr>
  <tr>
    <td width="50%" valign="top">
      <h3>📊 Diff 영향 분석 (Diff Impact Analysis)</h3>
      <p>커밋하기 전에 변경 사항이 시스템의 어떤 부분에 영향을 미치는지 확인하세요. 코드베이스 전반의 연쇄 효과를 이해하세요.</p>
    </td>
    <td width="50%" valign="top">
      <h3>🎭 페르소나 적응형 UI (Persona-Adaptive UI)</h3>
      <p>주니어 개발자, PM, 파워 유저 등 사용자가 누구인지에 따라 대시보드의 상세 수준이 조정됩니다.</p>
    </td>
  </tr>
  <tr>
    <td width="50%" valign="top">
      <h3>🏗️ 레이어 시각화 (Layer Visualization)</h3>
      <p>아키텍처 레이어별(API, 서비스, 데이터, UI, 유틸리티) 자동 그룹화 및 색상 코딩 범례를 제공합니다.</p>
    </td>
    <td width="50%" valign="top">
      <h3>📚 언어 개념 (Language Concepts)</h3>
      <p>나타나는 위치에서 문맥에 맞게 설명되는 12가지 프로그래밍 패턴(제네릭, 클로저, 데코레이터 등).</p>
    </td>
  </tr>
</table>

---

## 🚀 빠른 시작

### 1. 플러그인 설치

```bash
/plugin marketplace add Egonex-AI/Understand-Anything
/plugin install understand-anything
```

> **로컬 모델을 사용하고 계신가요?** 프라이버시나 기업 환경을 위해 [Ollama](https://docs.ollama.com/integrations) 같은 로컬 모델 제공업체를 지정하려면 해당 통합 가이드에 따라 모델 제공업체를 변경하세요.

### 2. 코드베이스 분석

```bash
/understand
```

멀티 에이전트 파이프라인이 프로젝트를 스캔하여 모든 파일, 함수, 클래스, 의존성을 추출한 후 `.ua/knowledge-graph.json`에 저장되는 지식 그래프를 구축합니다. (이미 `.understand-anything/` 디렉토리가 있는 프로젝트는 해당 디렉토리를 계속 사용합니다. 존재할 경우 데이터 디렉토리로 유지되므로 마이그레이션이 필요 없습니다.)

> **토큰 사용량 주의:** 최초 `/understand`는 전체 코드베이스를 분석하므로 대규모 프로젝트에서는 상당한 양의 토큰을 소비할 수 있습니다. 토큰 플랜/구독을 사용하거나 초기화 시 로컬 모델(위 참조)을 사용하는 것을 권장합니다. 이후 실행은 기본적으로 증분(incremental) 방식으로 변경된 파일만 다시 분석하므로 훨씬 적은 토큰을 사용합니다.

**지역화된 출력:** 원하는 언어로 콘텐츠를 생성하려면 `--language`를 사용하세요.

```bash
# 중국어 콘텐츠 생성 (지식 그래프 노드 설명 및 대시보드 UI)
/understand --language zh

# 지원되는 언어: en (기본값), zh, zh-TW, ja, ko, ru
```

프로젝트 **첫 실행 시**(`--language`를 전달하지 않고 아직 저장된 언어가 없는 경우) `/understand`는 사용자가 대화하고 있는 언어를 감지합니다. 영어가 아닌 경우 생성하기 전에 확인(또는 재정의)을 요청하며, 영어 대화에는 영향을 미치지 않습니다. 선택한 언어는 `.ua/config.json`에 저장되며 이후 모든 실행에서 재사용됩니다.

`--language` 파라미터는 다음 항목에 영향을 미칩니다:
- 지식 그래프의 노드 요약 및 설명
- 대시보드 UI 라벨, 버튼 및 툴팁
- 가이드 투어 설명

### 3. 대시보드 탐색

```bash
/understand-dashboard
```

아키텍처 레이어별 색상 코딩, 검색 및 클릭 기능이 포함된 코드베이스 시각화 그래프와 함께 대화형 웹 대시보드가 열립니다. 노드를 선택하여 코드, 관계, 평이한 영어로 된 설명을 확인하세요.

### 4. 지속적인 학습

```bash
# 코드베이스에 대해 무엇이든 질문하기
/understand-chat How does the payment flow work?

# 현재 변경 사항의 영향 분석하기
/understand-diff

# 특정 파일이나 함수 심층 분석하기
/understand-explain src/auth/login.ts

# 신규 팀원을 위한 온보딩 가이드 생성하기
/understand-onboard

# 비즈니스 도메인 지식 추출 (도메인, 흐름, 단계)
/understand-domain

# Karpathy-pattern LLM 위키 지식 베이스 분석
/understand-knowledge ~/path/to/wiki

# 언제든지 다시 실행 — 기본적으로 증분 방식 (변경된 파일만 다시 분석)
/understand

# post-commit 훅을 통해 모든 커밋 시 자동 업데이트
/understand --auto-update

# 하위 디렉토리로 범위 지정 (대규모 모노레포용)
/understand src/frontend
```

---

## 🌐 멀티 플랫폼 설치

Understand-Anything은 여러 AI 코딩 플랫폼에서 작동합니다.

### Claude Code (네이티브)

```bash
/plugin marketplace add Egonex-AI/Understand-Anything
/plugin install understand-anything
```

### 한 줄 설치 (Codex / OpenCode / OpenClaw / Antigravity / Gemini CLI / Pi Agent / Vibe CLI / VS Code Copilot / Hermes / Cline / KIMI CLI / Trae / Nanobot / Kiro)

**macOS / Linux:**
```bash
curl -fsSL https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.sh | bash
# 또는 플랫폼을 전달하여 프롬프트 건너뛰기:
curl -fsSL https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.sh | bash -s codex
```

**Windows (PowerShell):**
```powershell
iwr -useb https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.ps1 | iex
```

설치 프로그램은 저장소를 `~/.understand-anything/repo`에 복제하고 선택한 플랫폼에 맞는 심볼릭 링크를 생성합니다. 이후 CLI/IDE를 재시작하세요.

> **스킬 호출 참고 사항:** 호출 접두사는 플랫폼마다 다릅니다. 대부분의 플랫폼은 슬래시 명령어(`/understand`)를 사용하지만, **Codex는 대신 `$`를 사용**합니다. `/understand` 대신 `$understand`를 입력하세요. 플랫폼에서 두 접두사 모두 인식되지 않는 경우 일반 언어로 질문하세요: *"Use the understand skill to analyze this project."*

- 지원되는 `<platform>` 값: `gemini`, `codex`, `opencode`, `pi`, `openclaw`, `antigravity`, `vibe`, `vscode`, `hermes`, `cline`, `kimi`, `trae`, `nanobot`, `kiro`
- 나중에 업데이트: `./install.sh --update`
- 제거: `./install.sh --uninstall <platform>`

### Cursor

이 저장소가 복제되면 Cursor는 `.cursor-plugin/plugin.json`을 통해 플러그인을 자동으로 검색합니다. 수동 설치가 필요하지 않습니다. 복제한 후 Cursor에서 열기만 하면 됩니다.

자동 검색이 감지하지 못하는 경우 수동으로 설치하세요. **Cursor 설정 → 플러그인(Plugins)**을 열고 검색창에 `https://github.com/Egonex-AI/Understand-Anything`을 붙여넣은 후 추가하세요.

### VS Code + GitHub Copilot

GitHub Copilot(v1.108+)이 포함된 VS Code는 이 저장소가 복제될 때 `.copilot-plugin/plugin.json`을 통해 플러그인을 자동으로 검색합니다. 수동 설치가 필요하지 않습니다. 복제한 후 VS Code에서 열기만 하면 됩니다.

개인 스킬(모든 프로젝트에서 사용 가능)의 경우 위에서 `vscode` 플랫폼을 지정하여 `install.sh`를 실행하세요.

### Copilot CLI

```bash
copilot plugin install Egonex-AI/Understand-Anything:understand-anything-plugin
```

### Kiro CLI / IDE

```bash
curl -fsSL https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.sh | bash -s kiro
```

설치 후:
- **Kiro CLI**: `kiro-cli chat --agent understand "Analyze this project"`
- **Kiro IDE**: 스킬이 `~/.kiro/skills/`에 심볼릭 링크되고 `understand` 에이전트가 `~/.kiro/agents/understand.json`에 기록되므로, IDE를 재시작한 후 둘 다 사용할 수 있습니다.

개인 스킬(모든 프로젝트에서 사용 가능)의 경우 위에서 `kiro` 플랫폼을 지정하여 `install.sh`를 실행하세요.

### 플랫폼 호환성

| 플랫폼 | 상태 | 설치 방법 |
|----------|--------|----------------|
| Claude Code | ✅ 네이티브 | 플러그인 마켓플레이스 |
| Cursor | ✅ 지원됨 | 자동 검색 |
| VS Code + GitHub Copilot | ✅ 지원됨 | 자동 검색 |
| Copilot CLI | ✅ 지원됨 | 플러그인 설치 |
| Codex | ✅ 지원됨 | `install.sh codex` |
| OpenCode | ✅ 지원됨 | `install.sh opencode` |
| OpenClaw | ✅ 지원됨 | `install.sh openclaw` |
| Antigravity | ✅ 지원됨 | `install.sh antigravity` |
| Gemini CLI | ✅ 지원됨 | `install.sh gemini` |
| Pi Agent | ✅ 지원됨 | `install.sh pi` |
| Vibe CLI | ✅ 지원됨 | `install.sh vibe` |
| Hermes | ✅ 지원됨 | `install.sh hermes` |
| Cline | ✅ 지원됨 | `install.sh cline` |
| KIMI CLI | ✅ 지원됨 | `install.sh kimi` |
| Trae | ✅ 지원됨 | `install.sh trae` |
| Nanobot | ✅ 지원됨 | `install.sh nanobot` |
| Kiro CLI / IDE | ✅ 지원됨 | `install.sh kiro` |

---

## 📦 팀과 그래프 공유하기

그래프는 단지 JSON일 뿐입니다. **한 번만 커밋하면 팀원들은 파이프라인을 건너뛸 수 있습니다.** 온보딩, PR 리뷰, 코드로 보는 문서(docs-as-code)에 유용합니다.

> **예시:** [GoogleCloudPlatform/microservices-demo](https://github.com/GoogleCloudPlatform/microservices-demo) — 그래프가 커밋되어 있는 Go / Java / Python / Node 레퍼런스.

**커밋할 항목:** `intermediate/` 및 `diff-overlay.json`(로컬 임시 파일)을 **제외한** `.ua/`의 모든 항목. (레거시 프로젝트는 `.understand-anything/`을 사용합니다. 해당 디렉토리가 있는 경우 아래 디렉토리 이름으로 대체하세요.)

```gitignore
.ua/intermediate/
.ua/diff-overlay.json
```

**최신 상태 유지:** `/understand --auto-update`를 활성화하세요. post-commit 훅이 그래프를 증분 방식으로 패치하여 각 커밋에 일치하는 그래프가 함께 포함되도록 합니다. 또는 릴리스 전에 수동으로 `/understand`를 다시 실행하세요.

**대용량 그래프 (10 MB+):** **git-lfs**로 추적하세요.

```bash
git lfs install
git lfs track ".ua/*.json"
git add .gitattributes .ua/
```

### Claude Code 없이 대시보드 보기

그래프가 생성되고 커밋되면 팀원 누구나 Claude Code, LLM, API 키 없이 하나의 명령어로 그래프를 열 수 있습니다. Node.js (>= 18)만 필요합니다:

```bash
npx https://github.com/Egonex-AI/Understand-Anything/releases/latest/download/understand-anything-viewer.tgz /path/to/analyzed/project
```

터미널에 토큰화된 URL(`http://127.0.0.1:5173/?token=…`)이 출력되고 브라우저에서 완전한 대화형 대시보드가 열립니다. 프로젝트 디렉토리(기본값: 현재 디렉토리)에는 커밋된 데이터 디렉토리(`.ua/` 또는 레거시 `.understand-anything/`)가 포함되어 있어야 합니다. 모든 것은 로컬 디스크에서 읽기 전용으로 제공되며, LLM 호출이 없고 데이터가 머신 외부로 유출되지 않습니다.

클론 버전에서 작업 중이신가요? `pnpm install && pnpm --filter @understand-anything/core build` 후 `GRAPH_DIR=/path/to/analyzed/project pnpm dev:dashboard`를 실행하면 Vite 개발 서버를 통해 동일하게 작동합니다.

---

## 🔧 내부 작동 원리

### Tree-sitter + LLM 하이브리드

정적 분석과 LLM이 각각 가장 잘하는 일을 수행합니다.

- **Tree-sitter (결정론적)** — 소스를 구문 분석 트리(concrete syntax tree)로 파싱하고 구조적 사실(임포트, 익스포트, 함수/클래스 정의, 호출 지점, 상속)을 추출합니다. 스캔 단계에서 `importMap`으로 미리 해결되어 파일 분석기에 전달되므로 소스에서 임포트를 다시 도출할 필요가 없습니다. 매번 실행할 때마다 동일한 입력 → 동일한 출력. 또한 증분 업데이트를 위한 지문 기반 변경 감지 기능을 구동합니다.
- **LLM (시맨틱)** — 파싱된 구조를 원본 소스와 함께 읽어 파서가 할 수 없는 평이한 영어 요약, 태그, 아키텍처 레이어 할당, 비즈니스 도메인 매핑, 가이드 투어, 언어 개념 설명을 생성합니다.

이러한 분할 덕분에 구조적 측면에서 그래프가 재현 가능하면서도(동일한 코드는 항상 동일한 에지를 생성함) 시맨틱 측면에서 의도(파일이 무엇을 임포트하는지뿐만 아니라 *무엇을 위한* 것인지)를 포착할 수 있습니다.

### 멀티 에이전트 파이프라인

`/understand` 명령어는 5개의 특화된 에이전트를 조율하며, `/understand-domain`은 6번째 에이전트를 추가합니다:

| 에이전트 | 역할 |
|-------|------|
| `project-scanner` | 파일 발견, 언어 및 프레임워크 감지 |
| `file-analyzer` | 함수, 클래스, 임포트 추출; 그래프 노드 및 에지 생성 |
| `architecture-analyzer` | 아키텍처 레이어 식별 |
| `tour-builder` | 가이드 학습 투어 생성 |
| `graph-reviewer` | 그래프 완전성 및 참조 무결성 검증 (기본적으로 인라인 실행; 전체 LLM 리뷰를 위해 `--review` 사용) |
| `domain-analyzer` | 비즈니스 도메인, 흐름 및 프로세스 단계 추출 (`/understand-domain`에서 사용) |
| `article-analyzer` | 위키 문서에서 엔티티, 클레임 및 암묵적 관계 추출 (`/understand-knowledge`에서 사용) |

파일 분석기는 병렬로 실행됩니다(최대 5개 동시 실행, 배치당 20~30개 파일). 증분 업데이트를 지원하여 마지막 실행 이후 변경된 파일 페이지만 다시 분석합니다.

---

## 🎥 커뮤니티

**Better Stack**이 제작한 커뮤니티 워크스루.

<p align="center">
  <a href="https://www.youtube.com/watch?v=VmIUXVlt7_I"><img src="https://img.youtube.com/vi/VmIUXVlt7_I/maxresdefault.jpg" alt="Community walkthrough by Better Stack — watch on YouTube" width="480" /></a>
  <br />
  <em><a href="https://www.youtube.com/watch?v=VmIUXVlt7_I">YouTube에서 시청하기 &rarr;</a></em>
</p>

비디오, 블로그 포스트 또는 튜토리얼을 만드셨나요? 이슈나 PR을 열어주세요. 여기에 기꺼이 소개해 드립니다!

---

## 🤝 기여하기

기여는 언제나 환영합니다! 시작하는 방법은 다음과 같습니다:

1. 저장소를 포크(Fork)합니다.
2. 피처 브랜치를 생성합니다 (`git checkout -b feature/my-feature`).
3. 테스트를 실행합니다 (`pnpm --filter @understand-anything/core test`).
4. 변경 사항을 커밋하고 풀 리퀘스트(Pull Request)를 엽니다.

큰 변경 사항의 경우 접근 방식을 논의할 수 있도록 먼저 이슈를 열어주시기 바랍니다.

---

<p align="center">
  <strong>맹목적인 코드 리딩은 그만두세요. 모든 것을 이해하기 시작하세요.</strong>
</p>

## Star History

<p align="center">
  <em>사용해주시고 기여해주신 모든 분들께 감사드립니다. 이 도구가 사람들의 시간을 아껴준다는 사실이 바로 만들 가치를 부여한 원동력입니다.</em>
</p>

Understand-Anything

Understand-Anything 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Understand-Anything

Understand-Anything 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README