From ded60f8116c23506a2f4aaa80e59515c0871c936 Mon Sep 17 00:00:00 2001 From: Lum1104 Date: Sun, 15 Mar 2026 12:40:07 +0800 Subject: [PATCH] docs: update CLAUDE.md with current architecture and versioning guide Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 45 +++++++++++++++++++++++++++------------------ 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e4d48e2..02ae299 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,34 +6,43 @@ An open-source tool combining LLM intelligence + static analysis to produce inte ## Architecture - **Monorepo** with pnpm workspaces - **understand-anything-plugin/** — Claude Code plugin containing all source code: - - **understand-anything-plugin/packages/core** — Shared analysis engine (types, persistence, tree-sitter plugin, LLM prompt templates) - - **understand-anything-plugin/packages/dashboard** — React + TypeScript web dashboard (React Flow, Monaco Editor, Zustand, TailwindCSS) - - **understand-anything-plugin/src** — Skill TypeScript source for `/understand-chat`, `/understand-diff`, `/understand-explain`, `/understand-onboard` - - **understand-anything-plugin/skills** — Skill definitions - - **understand-anything-plugin/agents** — Agent definitions + - **packages/core** — Shared analysis engine (types, persistence, tree-sitter, search, schema, tours, plugins) + - **packages/dashboard** — React + TypeScript web dashboard (React Flow, Zustand, TailwindCSS v4) + - **src/** — Skill TypeScript source for `/understand-chat`, `/understand-diff`, `/understand-explain`, `/understand-onboard` + - **skills/** — Skill definitions (`/understand`, `/understand-dashboard`, etc.) + - **agents/** — Agent definitions (project-scanner, file-analyzer, architecture-analyzer, tour-builder, graph-reviewer) + +## Dashboard +- Dark luxury theme: deep blacks (#0a0a0a), gold/amber accents (#d4a574), DM Serif Display typography +- Graph-first layout: 75% graph + 360px right sidebar +- No ChatPanel or Monaco Editor +- Sidebar: ProjectOverview (default) → NodeInfo (node selected) → LearnPanel (Learn persona) +- Code viewer: styled summary overlay (slides up from bottom on file node click) +- Schema validation on graph load with error banner + +## Agent Pipeline +- Agents write intermediate results to `.understand-anything/intermediate/` on disk (not returned to context) +- Agent models: sonnet for simple tasks (project-scanner, graph-reviewer), opus for complex (file-analyzer, architecture-analyzer, tour-builder) +- `/understand` auto-triggers `/understand-dashboard` after completion +- Intermediate files cleaned up after graph assembly ## Key Commands - `pnpm install` — Install all dependencies - `pnpm --filter @understand-anything/core build` — Build the core package - `pnpm --filter @understand-anything/core test` — Run core tests -- `pnpm dev:dashboard` — Start dashboard dev server - -## Key Commands (plugin) - `pnpm --filter @understand-anything/skill build` — Build the plugin package - `pnpm --filter @understand-anything/skill test` — Run plugin tests - -## Phase 2 Features -- Fuzzy search via Fuse.js (SearchEngine in core) -- Zod schema validation on graph loading -- Staleness detection + incremental graph merging -- Layer auto-detection (heuristic + LLM prompt) -- `/understand-chat` skill command -- Dashboard chat panel (Claude API integration) -- Dagre auto-layout for graph visualization -- Layer visualization with grouping and legend +- `pnpm --filter @understand-anything/dashboard build` — Build the dashboard +- `pnpm dev:dashboard` — Start dashboard dev server ## Conventions - TypeScript strict mode everywhere - Vitest for testing - ESM modules (`"type": "module"`) - Knowledge graph JSON lives in `.understand-anything/` directory of analyzed projects +- Core uses subpath exports (`./search`, `./types`, `./schema`) to avoid pulling Node.js modules into browser + +## Versioning +When pushing to remote, bump the version in **both** of these files (keep them in sync): +- `understand-anything-plugin/package.json` → `"version"` field +- `.claude-plugin/marketplace.json` → `plugins[0].version` field