From dbba0703a9a8cb62854f96121586051f4ed7b591 Mon Sep 17 00:00:00 2001 From: Lum1104 Date: Sun, 24 May 2026 09:27:05 +0800 Subject: [PATCH] docs(readme): document incremental updates, subdir scoping, and tree-sitter+LLM split Add to all 8 READMEs (English + 7 translations): - "Keep learning" section gets inline commands for incremental re-runs, the --auto-update post-commit hook, and scoping /understand to a subdirectory for huge monorepos - "Under the Hood" gets a new "Tree-sitter + LLM hybrid" subsection explaining the deterministic-vs-semantic split that powers the pipeline --- README.md | 18 ++++++++++++++++++ READMEs/README.es-ES.md | 18 ++++++++++++++++++ READMEs/README.ja-JP.md | 18 ++++++++++++++++++ READMEs/README.ko-KR.md | 18 ++++++++++++++++++ READMEs/README.ru-RU.md | 18 ++++++++++++++++++ READMEs/README.tr-TR.md | 18 ++++++++++++++++++ READMEs/README.zh-CN.md | 18 ++++++++++++++++++ READMEs/README.zh-TW.md | 18 ++++++++++++++++++ 8 files changed, 144 insertions(+) diff --git a/README.md b/README.md index 1c75a78..07e2769 100644 --- a/README.md +++ b/README.md @@ -159,6 +159,15 @@ An interactive web dashboard opens with your codebase visualized as a graph — # Analyze a Karpathy-pattern LLM wiki knowledge base /understand-knowledge ~/path/to/wiki + +# Re-run anytime — incremental by default (only re-analyzes changed files) +/understand + +# Auto-update on every commit via a post-commit hook +/understand --auto-update + +# Scope to a subdirectory (for huge monorepos) +/understand src/frontend ``` --- @@ -258,6 +267,15 @@ git add .gitattributes .understand-anything/ ## 🔧 Under the Hood +### Tree-sitter + LLM hybrid + +Static analysis and LLMs do what each does best: + +- **Tree-sitter (deterministic)** — parses source into a concrete syntax tree and extracts structural facts: imports, exports, function/class definitions, call sites, inheritance. Pre-resolved into an `importMap` during the scan phase and passed to file-analyzers so they don't re-derive imports from source. Same input → same output, every run. Also powers fingerprint-based change detection for incremental updates. +- **LLM (semantic)** — reads the parsed structure alongside the original source to produce what parsers can't: plain-English summaries, tags, architectural layer assignments, business-domain mapping, guided tours, language concept callouts. + +This split is why the graph is reproducible on the structural side (the same code always yields the same edges) while still capturing intent on the semantic side (what a file is *for*, not just what it imports). + ### Multi-Agent Pipeline The `/understand` command orchestrates 5 specialized agents, and `/understand-domain` adds a 6th: diff --git a/READMEs/README.es-ES.md b/READMEs/README.es-ES.md index 99e5323..27884f9 100644 --- a/READMEs/README.es-ES.md +++ b/READMEs/README.es-ES.md @@ -157,6 +157,15 @@ Se abre un panel web interactivo con tu código visualizado como un grafo, codif # Analiza un wiki LLM con patrón Karpathy /understand-knowledge ~/path/to/wiki + +# Vuelve a ejecutarlo cuando quieras — incremental por defecto (solo archivos modificados) +/understand + +# Instala un hook post-commit para actualizaciones incrementales automáticas +/understand --auto-update + +# Acota el análisis a un subdirectorio (útil para monorepos enormes) +/understand src/frontend ``` --- @@ -256,6 +265,15 @@ git add .gitattributes .understand-anything/ ## 🔧 Bajo el Capó +### Híbrido Tree-sitter + LLM + +Lo determinista lo hace el análisis estático, lo semántico lo hace el LLM: + +- **Tree-sitter (determinista)** — parsea el código a un árbol de sintaxis concreto y extrae hechos estructurales: imports, exports, definiciones de funciones/clases, llamadas, herencia. Se preresuelve como `importMap` en la fase de escaneo y se pasa al file-analyzer para que no tenga que volver a derivar los imports desde el código fuente. La misma entrada siempre produce la misma salida, y también es la base de los fingerprints usados para las actualizaciones incrementales. +- **LLM (semántico)** — lee la estructura parseada junto con el código original para producir lo que los parsers no pueden: resúmenes en lenguaje natural, etiquetas, asignaciones de capa arquitectónica, mapeo de dominios de negocio, tours guiados, notas sobre conceptos del lenguaje. + +Esta división es la que hace que el grafo sea reproducible en lo estructural (el mismo código siempre genera las mismas aristas) y a la vez capture intención en lo semántico (para *qué* sirve un archivo, no solo qué importa). + ### Pipeline Multi-Agente El comando `/understand` orquesta 5 agentes especializados, y `/understand-domain` añade un sexto: diff --git a/READMEs/README.ja-JP.md b/READMEs/README.ja-JP.md index c0e24f3..78fe62c 100644 --- a/READMEs/README.ja-JP.md +++ b/READMEs/README.ja-JP.md @@ -158,6 +158,15 @@ Understand Anything は [Claude Code Plugin](https://code.claude.com/docs/en/plu # Karpathy パターンの LLM Wiki ナレッジベースを分析 /understand-knowledge ~/path/to/wiki + +# いつでも再実行 —— デフォルトでインクリメンタル（変更ファイルのみ再分析） +/understand + +# post-commit フックをインストールしてコミットごとに自動更新 +/understand --auto-update + +# 巨大なモノレポでも安心 —— サブディレクトリにスコープを絞る +/understand src/frontend ``` --- @@ -257,6 +266,15 @@ git add .gitattributes .understand-anything/ ## 🔧 内部の仕組み +### Tree-sitter + LLM ハイブリッド + +決定論的にできることは静的解析、意味理解が必要なことは LLM、と役割を分けています： + +- **Tree-sitter（決定論的）** —— ソースコードを具象構文木にパースし、構造的事実を抽出します：import、export、関数／クラス定義、呼び出し位置、継承関係。スキャンフェーズで `importMap` として事前解決し、file-analyzer に渡すことで、ソースから再度 import を導出する必要をなくしています。同じ入力からは常に同じ出力が得られ、インクリメンタル更新のフィンガープリントの基盤にもなります。 +- **LLM（意味的）** —— パース済みの構造と原文ソースを併せて読み、パーサーには出せないものを生成します：plain-English の要約、タグ、アーキテクチャレイヤの割当、業務ドメインマッピング、ガイド付きツアー、言語コンセプトの注釈。 + +この分担により、構造面ではグラフが再現可能（同じコードからは常に同じエッジが出る）でありながら、意味面ではそのファイルが「何のために」あるのかという意図を捉えられます。 + ### マルチエージェントパイプライン `/understand` コマンドは5つの専門エージェントをオーケストレーションし、`/understand-domain` は6つ目を追加します： diff --git a/READMEs/README.ko-KR.md b/READMEs/README.ko-KR.md index 9b651cb..13c4aef 100644 --- a/READMEs/README.ko-KR.md +++ b/READMEs/README.ko-KR.md @@ -157,6 +157,15 @@ Understand Anything은 [Claude Code Plugin](https://code.claude.com/docs/en/plug # Karpathy 패턴 LLM 위키 지식 베이스 분석 /understand-knowledge ~/path/to/wiki + +# 언제든 다시 실행 — 기본값은 증분 업데이트(변경된 파일만 재분석) +/understand + +# post-commit 훅을 설치해 매 커밋마다 자동 증분 업데이트 +/understand --auto-update + +# 거대한 모노레포라면 하위 디렉터리로 범위 제한 +/understand src/frontend ``` --- @@ -256,6 +265,15 @@ git add .gitattributes .understand-anything/ ## 🔧 작동 원리 +### Tree-sitter + LLM 하이브리드 + +결정적으로 처리할 수 있는 일은 정적 분석이, 의미 이해가 필요한 일은 LLM 이 담당합니다: + +- **Tree-sitter(결정적)** — 소스 코드를 구체 구문 트리로 파싱해 구조적 사실을 추출합니다: import, export, 함수/클래스 정의, 호출 위치, 상속. 스캔 단계에서 `importMap` 으로 사전 해석해 file-analyzer 에 전달하므로, 소스에서 다시 import 를 유도할 필요가 없습니다. 같은 입력은 항상 같은 출력을 내며, 증분 업데이트의 핑거프린트 기반이기도 합니다. +- **LLM(의미적)** — 파싱된 구조와 원본 소스를 함께 읽어 파서가 만들 수 없는 것들을 생성합니다: plain-English 요약, 태그, 아키텍처 레이어 할당, 비즈니스 도메인 매핑, 가이드 투어, 언어 개념 주석. + +이 분담 덕분에 그래프는 구조 측면에서는 재현 가능하면서(같은 코드는 항상 같은 엣지를 만든다), 의미 측면에서는 의도를 포착할 수 있습니다(파일이 단지 무엇을 import 하는지가 아니라 *무엇을 위해* 존재하는지). + ### 멀티 에이전트 파이프라인 `/understand` 명령은 5개의 전문 에이전트를 조율하며, `/understand-domain`은 6번째 에이전트를 추가합니다: diff --git a/READMEs/README.ru-RU.md b/READMEs/README.ru-RU.md index 41a3300..67182fb 100644 --- a/READMEs/README.ru-RU.md +++ b/READMEs/README.ru-RU.md @@ -158,6 +158,15 @@ Understand Anything — это [плагин для Claude Code](https://code.cl # Проанализируйте LLM-вики в стиле Карпати /understand-knowledge ~/path/to/wiki + +# Перезапускайте когда угодно — по умолчанию инкрементально (только изменённые файлы) +/understand + +# Установите post-commit хук для автоматических инкрементальных обновлений +/understand --auto-update + +# Огромный монорепозиторий? Ограничьте анализ подкаталогом +/understand src/frontend ``` --- @@ -257,6 +266,15 @@ git add .gitattributes .understand-anything/ ## 🔧 Под капотом +### Гибрид Tree-sitter + LLM + +Детерминированную работу делает статический анализ, семантическое понимание — LLM: + +- **Tree-sitter (детерминированно)** — парсит исходный код в конкретное синтаксическое дерево и извлекает структурные факты: import'ы, export'ы, определения функций/классов, точки вызова, наследование. На фазе сканирования заранее разрешается в `importMap` и передаётся file-analyzer'ам, чтобы они не выводили import'ы из исходника заново. Одинаковый ввод всегда даёт одинаковый вывод; это же лежит в основе fingerprint'ов для инкрементальных обновлений. +- **LLM (семантически)** — читает разобранную структуру вместе с исходным текстом и производит то, что не способны парсеры: понятные человеку резюме, теги, назначение архитектурных слоёв, отображение бизнес-доменов, ведомые туры, заметки о концепциях языка. + +Именно благодаря этому разделению граф воспроизводим со стороны структуры (один и тот же код всегда даёт одни и те же рёбра) и одновременно улавливает намерение со стороны семантики (для *чего* существует файл, а не только что он импортирует). + ### Мультиагентный пайплайн Команда `/understand` оркестрирует 5 специализированных агентов, а `/understand-domain` добавляет шестого: diff --git a/READMEs/README.tr-TR.md b/READMEs/README.tr-TR.md index 280e9c2..e03b993 100644 --- a/READMEs/README.tr-TR.md +++ b/READMEs/README.tr-TR.md @@ -158,6 +158,15 @@ Kod tabanın bir grafik olarak görselleştirilmiş, mimari katmana göre renkle # Karpathy deseni LLM Wiki bilgi tabanını analiz et /understand-knowledge ~/path/to/wiki + +# İstediğin zaman tekrar çalıştır — varsayılan olarak artımlıdır (yalnızca değişen dosyaları analiz eder) +/understand + +# Her commit'te otomatik artımlı güncelleme için post-commit kancası kur +/understand --auto-update + +# Devasa monorepo'larda analizi bir alt dizinle sınırla +/understand src/frontend ``` --- @@ -257,6 +266,15 @@ git add .gitattributes .understand-anything/ ## 🔧 Kaputun Altında +### Tree-sitter + LLM hibriti + +Deterministik olarak yapılabilecek işleri statik analiz, anlam çıkarımı gerektiren işleri LLM üstlenir: + +- **Tree-sitter (deterministik)** — kaynak kodu somut sözdizimi ağacına ayrıştırır ve yapısal gerçekleri çıkarır: import'lar, export'lar, fonksiyon/sınıf tanımları, çağrı noktaları, kalıtım. Tarama aşamasında önceden çözülmüş `importMap` olarak file-analyzer'a iletilir, böylece import'ları kaynaktan tekrar türetmek zorunda kalmaz. Aynı girdi her zaman aynı çıktıyı verir; ayrıca artımlı güncellemelerin parmak izlerinin de temelidir. +- **LLM (anlamsal)** — ayrıştırılmış yapıyı ve orijinal kaynağı birlikte okuyarak ayrıştırıcıların üretemediği şeyleri üretir: düz dilde özetler, etiketler, mimari katman atamaları, iş alanı eşlemeleri, rehberli turlar, dil kavramı notları. + +Bu ayrım sayesinde graf yapısal tarafta yeniden üretilebilir kalırken (aynı kod her zaman aynı kenarları üretir) anlamsal tarafta niyeti yakalayabilir (bir dosya yalnızca neyi import ettiği değil, *ne için* var olduğu da görülür). + ### Çok-Ajan Hattı `/understand` komutu 5 özel ajan düzenler ve `/understand-domain` 6. ajanı ekler: diff --git a/READMEs/README.zh-CN.md b/READMEs/README.zh-CN.md index 633c4b0..17b6e91 100644 --- a/READMEs/README.zh-CN.md +++ b/READMEs/README.zh-CN.md @@ -157,6 +157,15 @@ Understand Anything 是一个 [Claude Code Plugin](https://code.claude.com/docs/ # 分析 Karpathy 模式的 LLM Wiki 知识库 /understand-knowledge ~/path/to/wiki + +# 直接重跑即可 —— 默认增量更新，只分析变更的文件 +/understand + +# 安装 post-commit 钩子，每次提交自动增量更新 +/understand --auto-update + +# 大型 monorepo？把分析范围限定到某个子目录 +/understand src/frontend ``` --- @@ -256,6 +265,15 @@ git add .gitattributes .understand-anything/ ## 🔧 技术原理 +### Tree-sitter + LLM 混合分析 + +把确定性的事情交给静态分析，把需要语义理解的事情交给 LLM： + +- **Tree-sitter（确定性）** —— 将源码解析为具体语法树，提取结构性事实：导入、导出、函数 / 类定义、调用点、继承关系。在 scan 阶段预先解析为 `importMap` 并传给 file-analyzer，避免它们再从源码推导一次 import。同样的输入永远得到同样的输出，并作为增量更新的指纹基础。 +- **LLM（语义）** —— 读取解析后的结构以及原始源码，生成解析器做不了的事：plain-English 摘要、标签、架构层归属、业务领域映射、引导路径、语言概念标注。 + +正因为这个分工，图谱在结构层面是可复现的（同样的代码总是产生同样的边），同时在语义层面又能捕捉意图（一个文件是「为了什么」存在，而不仅仅是它 import 了什么）。 + ### 多智能体架构 `/understand` 命令调用 5 个 agent，`/understand-domain` 额外增加第 6 个： diff --git a/READMEs/README.zh-TW.md b/READMEs/README.zh-TW.md index 90a94b7..1d8c297 100644 --- a/READMEs/README.zh-TW.md +++ b/READMEs/README.zh-TW.md @@ -157,6 +157,15 @@ Understand Anything 是一個 [Claude Code Plugin](https://code.claude.com/docs/ # 分析 Karpathy 模式的 LLM Wiki 知識庫 /understand-knowledge ~/path/to/wiki + +# 直接重跑即可 —— 預設增量更新，只分析變更的檔案 +/understand + +# 安裝 post-commit 掛鉤，每次提交自動增量更新 +/understand --auto-update + +# 大型 monorepo？把分析範圍限定到某個子目錄 +/understand src/frontend ``` --- @@ -256,6 +265,15 @@ git add .gitattributes .understand-anything/ ## 🔧 技術原理 +### Tree-sitter + LLM 混合分析 + +把確定性的事情交給靜態分析，把需要語意理解的事情交給 LLM： + +- **Tree-sitter（確定性）** —— 將原始碼解析為具體語法樹，提取結構性事實：import、export、函式 / 類別定義、呼叫點、繼承關係。在 scan 階段預先解析為 `importMap` 並傳給 file-analyzer，避免它們再從原始碼推導一次 import。相同的輸入永遠得到相同的輸出，並作為增量更新的指紋基礎。 +- **LLM（語意）** —— 讀取解析後的結構以及原始碼，產生解析器做不到的事：plain-English 摘要、標籤、架構層歸屬、業務領域映射、導覽路徑、語言概念標註。 + +正是這個分工讓圖譜在結構層面具備可重現性（同樣的程式碼總是產生同樣的邊），同時在語意層面也能捕捉意圖（一個檔案是「為了什麼」而存在，不只是它 import 了什麼）。 + ### 多智能體架構 `/understand` 指令呼叫 5 個 agent，`/understand-domain` 額外增加第 6 個：