Explore: Скилл для глубокого анализа кода

--- name: explore description: Meta-skill for internal codebase exploration at varying depths (quick/deep/architecture) allowed-tools: [Bash, Task, Read, Glob, Grep, Write] keywords: [explore, codebase, architecture, understand, analyze, layers, call graph, brownfield] --- # Explore - Internal Codebase Exploration Meta-skill for exploring an internal codebase at varying depths. READ-ONLY workflow - no code changes. ## Usage ``` /explore <depth> [options] ``` ## Question Flow (No Arguments) If the user types just `/explore` with no or partial arguments, guide them through this question flow. Use AskUserQuestion for each phase. ### Phase 0: Workflow Selection ```yaml question: "How would you like to explore?" header: "Explore" options: - label: "Help me choose (Recommended)" description: "I'll ask questions to pick the right exploration depth" - label: "Quick - fast overview" description: "Chain: tldr tree → tldr structure (~1 min)" - label: "Deep - comprehensive analysis" description: "Chain: onboard → tldr → research → document (~5 min)" - label: "Architecture - layers & dependencies" description: "Chain: tldr arch → call graph → layer mapping (~3 min)" ``` **Mapping:** - "Help me choose" → Continue to Phase 1-4 questions - "Quick" → Set depth=quick, skip to Phase 2 (scope) - "Deep" → Set depth=deep, skip to Phase 2 (scope) - "Architecture" → Set depth=architecture, skip to Phase 2 (scope) **If Answer is Unclear (via "Other"):** ```yaml question: "I want to understand how deep you want to explore. Did you mean..." header: "Clarify" options: - label: "Help me choose" description: "Not sure - guide me through questions" - label: "Quick - fast overview" description: "Just want to see what's here" - label: "Deep - comprehensive analysis" description: "Need thorough understanding" - label: "Neither - let me explain differently" description: "I'll describe what I need" ``` ### Phase 1: Exploration Goal ```yaml question: "What are you trying to understand?" header: "Goal" options: - label: "Get oriented in the codebase" description: "Quick overview of structure" - label: "Understand how something works" description: "Deep dive into specific area" - label: "Map the architecture" description: "Layers, dependencies, patterns" - label: "Find where something is" description: "Locate specific code/functionality" ``` **Mapping:** - "Get oriented" → quick depth - "Understand how" → deep depth - "Map architecture" → architecture depth - "Find where" → quick with --focus ### Phase 2: Scope ```yaml question: "What area should I focus on?" header: "Focus" options: - label: "Entire codebase" description: "Explore everything" - label: "Specific directory or module" description: "I'll specify the path" - label: "Specific concept/feature" description: "e.g., 'authentication', 'API routes'" ``` If "Specific directory" or "Specific concept" → ask follow-up for the path/keyword. ### Phase 3: Output Format ```yaml question: "What should I produce?" header: "Output" options: - label: "Just tell me what you find" description: "Interactive summary in chat" - label: "Create a documentation file" description: "Write to thoughts/shared/docs/" - label: "Create handoff for implementation" description: "Prepare context for coding agent" ``` **Mapping:** - "Documentation file" → --output doc - "Handoff for implementation" → --output handoff ### Phase 4: Entry Point (Architecture only) If architecture depth selected: ```yaml question: "Where should I start the analysis?" header: "Entry point" options: - label: "Auto-detect (main, cli, app)" description: "Find common entry points" - label: "Specific function/file" description: "I'll specify the entry point" ``` ### Summary Before Execution ``` Based on your answers, I'll run: **Depth:** deep **Focus:** "authentication" **Output:** handoff **Path:** src/ Proceed? [Yes / Adjust settings] ``` ### Depths | Depth | Time | What it does | |-------|------|--------------| | `quick` | ~1 min | tldr-explorer only - fast structure overview | | `deep` | ~5 min | onboard + tldr-explorer + research-codebase + write doc | | `architecture` | ~3 min | tldr arch + call graph + layer mapping + circular dep detection | ### Options | Option | Description | Example | |--------|-------------|---------| | `--focus "area"` | Focus on specific area | `--focus "auth"`, `--focus "api"` | | `--output handoff` | Create handoff for next agent | `--output handoff` | | `--output doc` | Create documentation file | `--output doc` | | `--entry "func"` | Start from specific entry point | `--entry "main"`, `--entry "process_request"` | ## Examples ```bash # Quick structure overview /explore quick # Deep exploration focused on auth /explore deep --focus "auth" --output doc # Architecture analysis from specific entry /explore architecture --entry "cli" --output handoff # Quick focused exploration /explore quick --focus "hooks" ``` ## Workflow Details ### Quick Depth Fast structure overview using tldr-explorer. Best for: - Initial orientation - Quick questions about structure - Finding where things are **Steps:** 1. Run `tldr tree` for file structure 2. Run `tldr structure` for codemaps 3. If `--focus` provided, run `tldr search` for targeted results 4. Return summary **Commands:** ```bash # 1. File tree tldr tree ${PATH:-src/} --ext .py # 2. Code structure tldr structure ${PATH:-src/} --lang python # 3. Focused search (if --focus provided) tldr search "${FOCUS}" ${PATH:-src/} ``` ### Deep Depth Comprehensive exploration with documentation output. Best for: - First time in a codebase - Preparing for major work - Creating reference documentation **Steps:** 1. Check if onboarded (look for `.claude/cache/tldr/`), if not run onboard 2. Run tldr-explorer for structure 3. Spawn research-codebase agent for patterns 4. Write findings to doc or handoff **Subprocess:** ``` # 1. Onboard check if [ ! -f .claude/cache/tldr/arch.json ]; then # Spawn onboard agent fi # 2. Structure analysis tldr structure src/ --lang python tldr calls src/ # 3. Research patterns (via scout agent) Task: research-codebase → "Document existing patterns in ${FOCUS:-codebase}" # 4. Write output → thoughts/shared/research/YYYY-MM-DD-explore-{focus}.md → OR thoughts/shared/handoffs/{session}/explore-{focus}.yaml ``` ### Architecture Depth Architecture-focused analysis with layer detection. Best for: - Understanding system boundaries - Preparing for refactoring - Identifying coupling issues **Steps:** 1. Run `tldr arch` for layer detection 2. Run `tldr calls` for cross-file call graph 3. Analyze entry/middle/leaf layers 4. Detect circular dependencies 5. Map architectural boundaries **Commands:** ```bash # 1. Architecture detection tldr arch ${PATH:-src/} # Returns: entry_layer, middle_layer, leaf_layer, circular_deps # 2. Call graph tldr calls ${PATH:-src/} # Returns: edges, nodes # 3. Impact analysis from entry point (if --entry provided) tldr impact ${ENTRY} ${PATH:-src/} --depth 3 ``` **Output Structure:** ```yaml layers: entry: [routes.py, cli.py, main.py] # Controllers/handlers middle: [services.py, auth.py] # Business logic leaf: [utils.py, helpers.py] # Utilities call_graph: total_edges: 142 hot_paths: [process_request → validate → authorize] circular_deps: - [module_a, module_b] # A imports B, B imports A boundaries: - name: API layer files: [src/api/*] calls_to: [src/services/*] ``` ## Output Formats ### --output doc Creates: `thoughts/shared/research/YYYY-MM-DD-explore-{focus}.md` ```markdown --- date: {ISO timestamp} type: exploration depth: {quick|deep|architecture} focus: {focus area or "full"} commit: {git hash} --- # Codebase Exploration: {focus} ## Summary {High-level findings} ## Structure {File tree / codemaps} ## Architecture {Layer analysis - for architecture depth} ## Key Components {Important files and their roles} ## Patterns Found {Existing patterns - for deep depth} ## References - `path/to/file.py:line` - Description ``` ### --output handoff Creates: `thoughts/shared/handoffs/{session}/explore-{focus}.yaml` ```yaml --- type: exploration ts: {ISO timestamp} depth: {quick|deep|architecture} focus: {focus area} commit: {git hash} --- summary: {One-line summary of findings} structure: entry_points: [{main.py}, {cli.py}] key_modules: [{auth.py}, {routes.py}] test_coverage: [{tests/}] architecture: layers: entry: [{files}] middle: [{files}] leaf: [{files}] circular_deps: [{pairs}] findings: - {key finding with file:line} next_steps: - {Recommended action based on exploration} refs: - path: {file.py} role: {what it does} ``` ## Integration with /build The explore skill is designed to feed into `/build brownfield`: ```bash # Step 1: Explore to understand /explore architecture --output handoff # Step 2: Build with context from exploration /build brownfield --from-handoff thoughts/shared/handoffs/session/explore-full.yaml ``` ## Implementation When user invokes `/explore <depth> [options]`: ### Parse Arguments ```python depth = args[0] # quick | deep | architecture focus = extract_option(args, "--focus") output = extract_option(args, "--output") # handoff | doc entry = extract_option(args, "--entry") ``` ### Execute Based on Depth **Quick:** ```bash # Just tldr commands, no agents tldr tree ${src_dir} --ext .py tldr structure ${src_dir} --lang python if [ -n "$focus" ]; then tldr search "$focus" ${src_dir} fi ``` **Deep:** ```bash # 1. Check/run onboard if [ ! -f .claude/cache/tldr/meta.json ]; then # Spawn onboard agent via Task tool fi # 2. Structure tldr structure src/ --lang python # 3. Research (spawn scout agent) # Task tool with subagent_type: "scout" # Prompt: "Research patterns in ${focus:-codebase}" # 4. Write output # → doc or handoff based on --output ``` **Architecture:** ```bash # 1. Arch detection arch_output=$(tldr arch ${src_dir}) # 2. Call graph calls_output=$(tldr calls ${src_dir}) # 3. Impact from entry (if provided) if [ -n "$entry" ]; then impact_output=$(tldr impact $entry ${src_dir} --depth 3) fi # 4. Synthesize and write output ``` ## Key Principles 1. **READ-ONLY** - This skill never modifies code 2. **Uses scout, not Explore** - Per project rules, scout (Sonnet) over Explore (Haiku) 3. **Token-efficient** - Uses tldr commands (95% savings over raw reads) 4. **Outputs to shared locations** - `thoughts/shared/research/` or handoff directory 5. **Entry point to /build** - Exploration handoffs feed into brownfield builds ## Related Skills | Skill | When to Use | |-------|-------------| | **tldr-explorer** | Direct tldr commands (used internally by explore) | | **tldr-code** | Specific analysis commands (cfg, dfg, slice) | | **onboard** | First-time project setup (used by deep depth) | | **research-codebase** | Pattern documentation (used by deep depth) | | **create_handoff** | Handoff format (used by --output handoff) | ## Troubleshooting **tldr not found:** ```bash # Check if installed which tldr # Install if missing uv tool install llm-tldr # or: pip install llm-tldr ``` **No Python files found:** ```bash # Check language, adjust --lang tldr structure src/ --lang typescript # or go, rust ``` **Empty architecture output:** ```bash # May need to specify src directory tldr arch ./ # Current directory tldr arch src/ # Explicit src ```