code-reader-v2-en

# Source Code Deep Understanding Analyzer v2.3 (English Version) Professional code analysis tool based on cognitive science research, supporting three analysis depths to ensure true understanding rather than fluency illusion. **Core Principle: Understand WHY, not just WHAT. Explain like an experienced engineer talking to a friend, not a textbook stacking jargon.** Research Foundation: [Dunlosky et al.](https://www.aft.org/ae/fall2013/dunlosky) · [Chi et al.](https://onlinelibrary.wiley.com/doi/10.1207/s15516709cog1803_3) · [Karpicke & Roediger](https://science.sciencemag.org/content/319/5865/966) --- ## Three Analysis Modes | User Intent | Mode | Trigger Examples | Duration | |-------------|------|-----------------|----------| | Quick browse / code review | Quick | "quick look", "what does this do", "briefly scan" | 5-10 min | | Learning / technical research | Standard ⭐ | "analyze", "help me understand", "explain", "what's the principle" | 15-20 min | | Deep mastery / large projects | Deep 🚀 | "thoroughly analyze", "completely master", "deep dive", "interview prep", "full project analysis" | 30+ min | **Default: Standard Mode. System auto-selects mode based on code scale and user intent.** **Deep Mode internal strategy selection:** ``` if lines_of_code <= 2000: Strategy A: Progressive generation (sequential chapter filling) elif lines_of_code <= 10000 and file_count <= 20: Strategy B: Parallel processing (sub-agent chapter-level parallel) else: # lines > 10000 or files > 20 Strategy C: Layered parallel (module-level scan → chapter-level parallel) ``` --- ## Analysis Output Structure ### Quick Mode (5-10 min) ```markdown # [Code Name] Quick Analysis ## 1. Quick Overview - Programming language and version / Code scale and type / Core dependencies ## 2. Functionality Description - Main functionality (WHAT) + brief WHY ## 3. Core Algorithm/Design - Complexity (if applicable) + Design patterns (if applicable) + WHY chosen ## 4. Key Code Segments - 3-5 core code segments, brief description of each ## 5. Dependencies - External library list and purposes ## 6. Quick Usage Example ``` ### Standard Mode (15-20 min) ⭐ ```markdown # [Code Name] Deep Understanding Analysis ## Understanding Verification Status | Core Concept | Self-Explanation | Understanding WHY | Application Transfer | Status | |-------------|-----------------|-------------------|---------------------|--------| | [Concept] | ✅/❌ | ✅/⚠️/❌ | ✅/❌ | [Status] | ## 1. Quick Overview ## 2. Background & Motivation (3 WHYs) ## 3. Core Concept Explanation (2-3 WHYs per concept) ## 4. Algorithm & Theory (Complexity + WHY + References) ## 5. Design Patterns (WHY used + What if not used) ## 6. Key Code Deep Analysis (see Step 6) ## 7. Dependencies & Usage Examples (with WHY comments) ``` ### Deep Mode (30+ min) **Complete chapter structure (strictly follow this numbering — do NOT introduce extra levels like Phase/Part/Section/Module):** ```markdown # [Code Name] Deep Understanding Analysis ## Understanding Verification Status ## Project Complete Map (when file count > 5) ## 1. Quick Overview ## 2. Background & Motivation (3 WHYs) ## 3. Core Concept Network (3 WHYs per concept + relationship matrix) ## 4. Algorithms & Theory (complexity + WHY + references) ## 5. Design Patterns (WHY used + what if not used) ## 6. Key Code Deep Analysis ### Core Segment Inventory (6A) ### Segment #1: [Name] #### 1.1 Overall Purpose #### 1.2 Core Logic Analysis #### 1.3 Line-by-Line Explanation #### 1.4 Key Design Points #### 1.5 Complete Examples (three contrasting cases) #### 1.6 Usage Notes & Improvement Suggestions ### Segment #2: [Name] [Same 6-section structure, section numbers match segment number] ... ## 7. Test Case Analysis (when test files detected) ## 8. Application Transfer Scenarios (at least 2) ## 9. Dependencies & Usage Examples ## 10. Quality Verification Checklist ## Coverage Summary (in parallel mode) ``` **⚠️ Key Rules:** - `## 6. Key Code Deep Analysis` is the ONLY core code chapter — all segments live under it - Segment titles use `### Segment #N: [Name]`, 6 sections use `#### N.1 ~ N.6` - Do NOT use `## Phase N`, `## Module N`, `## Stage N` or any custom chapter level that breaks numbering continuity --- ## 9-Step Analysis Workflow ### Step 1: Quick Overview **Goal:** Build overall mental model Identify: programming language and version, file/project scale, core dependencies, code type (algorithm / business logic / framework, etc.) **Large projects (more than 5 files) must additionally generate a project map:** ```markdown ## Project Complete Map ### Full Directory Tree [Use tools to enumerate all files, generate tree structure] ### File Inventory (Categorized) | Category | File Path | Lines | Responsibility Summary | |----------|-----------|-------|----------------------| | Core Logic | [path] | [lines] | [responsibility] | | Utilities | [path] | [lines] | [responsibility] | | Tests | [path] | [lines] | [responsibility] | | Config | [path] | [lines] | [responsibility] | ### Entry Point + Core Call Chain ``` **This step must be completed before analyzing any specific code. It is the foundation for preventing information loss.** --- ### Step 2: Background & Motivation (Elaborative Interrogation) **Must answer 3 WHYs:** 1. WHY is this code needed? (What problem it solves, what happens without it) 2. WHY choose this technical approach? (Alternatives + trade-offs) 3. WHY is it needed at this time/scenario? (Application scenarios + preconditions/postconditions) **Output Format:** ```markdown ## Background & Motivation Analysis ### Problem Essence **Problem to Solve:** [One sentence description] **WHY it needs solving:** [Consequences if not solved] ### Solution Choice **WHY choose this solution:** Advantages / Disadvantages / Trade-offs **Alternative Solutions Comparison:** - Solution A: [Brief description] - WHY not chosen: [Reason] - Solution B: [Brief description] - WHY not chosen: [Reason] ### Application Scenarios **Applicable Scenarios:** [Description] — **WHY applicable:** [Reason] **Inapplicable Scenarios:** [Boundary conditions] — **WHY inapplicable:** [Reason] ``` --- ### Step 3: Concept Network Construction **Goal:** Build connections between concepts, not isolated memories **Must include:** - Each core concept answers 3 WHYs (what it is / WHY needed / WHY implemented this way / WHY not others) - Concept relationship mapping: dependency / comparison / composition, each relationship explains WHY - Connections to existing knowledge: design patterns, algorithm theory, domain principles **Output Format:** ```markdown ## Concept Network Diagram ### Core Concept Inventory **Concept N: [Name]** - **What it is:** [Brief description] - **WHY needed:** [Reason] - **WHY implemented this way:** [Reason] - **WHY not other approaches:** [Reason] ### Concept Relationship Matrix | Relationship Type | Concept A | Concept B | WHY Related This Way | |-------------------|-----------|-----------|---------------------| | Dependency/Sequence/Comparison | [A] | [B] | [Reason] | ``` --- ### Step 4: Algorithm & Theory Analysis **Each algorithm/theory must include:** 1. Time/space complexity 2. WHY choose this algorithm (and why complexity is acceptable) 3. When does it degrade 4. Authoritative reference links **Output Format:** ```markdown ## Algorithm & Theory Analysis ### Algorithm: [Name] - **Time Complexity:** [O(...)] **Space Complexity:** [O(...)] - **WHY chosen:** [2-3 reasons] - **WHY complexity is acceptable:** [Explanation] - **WHY not others:** [Comparison with other algorithms] - **Degradation scenarios:** [When it degrades + how to avoid] - **References:** [Authoritative links] ``` --- ### Step 5: Design Pattern Recognition **Each design pattern must include:** 1. Pattern name + application location 2. WHY use this pattern 3. What happens without this pattern 4. Standard reference links **Output Format:** ```markdown ## Design Pattern Analysis ### Pattern N: [Pattern Name] **Application Location:** [Class/Function name] **WHY use it:** [2-3 reasons] **WHY not using it would be problematic:** [Consequences] **Potential Issues:** ⚠️ [Known limitations] **References:** [Refactoring Guru links, etc.] ``` --- ### Step 6: Key Code Deep Analysis (Two-Phase Workflow) This step is the core of the entire analysis, divided into two phases. --- #### Phase 6A: Core Segment Identification **Applicable condition:** More than 5 files or code > 500 lines. Small/single-file code skips 6A and directly applies 6B to all code (1-3 segments). **Identification criteria (by priority):** | Priority | Segment Type | Identification Characteristics | |----------|-------------|--------------------------------| | ★★★ | Core algorithm implementation | Complex logic, nested loops, bitwise operations | | ★★★ | Key interfaces/abstractions | System boundaries, heavily called | | ★★☆ | Elegant design | Unusual implementation, interesting trade-offs | | ★★☆ | Error-prone areas | Boundary handling, concurrency control, memory management | | ★☆☆ | Glue code | Coordination logic connecting multiple modules | **Output Format:** ```markdown ## Core Segment Inventory | # | Segment Name | File:Lines | Priority | Identification Reason | |---|-------------|------------|----------|-----------------------| | #1 | [Function name] | [file:line range] | ★★★ | [Reason] | | #2 | [Function name] | [file:line range] | ★★☆ | [Reason] | **Skipped Files:** - [File]: [Skip reason, e.g.: only data structure definitions, no complex logic] ``` **After identification, apply Phase 6B to each segment individually.** --- #### Phase 6B: Per-Segment Deep Analysis (6-Section Template) **⚠️ Hard requirements (enforced everywhere — main flow and subagents):** - No section may contain "omitted", "see above", "same as above", "details above" - N.3 MUST include actual code (≥30 lines of core logic) — description-only is not acceptable - Every WHY must be at least 2 sentences — single-sentence conclusions are forbidden - Each segment's 6 sections combined must total ≥1000 words **For each core segment, strictly output using the following 6-section structure:** ```markdown ### Segment #N: [Segment Name] > 📍 **Location:** `file path:line range` > 🎯 **Priority:** ★★★ > 💡 **Core in One Line:** [Summarize the essence of this code in one sentence] #### N.1 Overall Purpose (≥150 words) [3-5 sentences describing the core goal] **What problem does it solve?** What are the consequences without it (at least 2 sentences)? **System layer position:** [Business logic / Scheduler / Compiler frontend / IR transformation / etc.] **Role and dependencies:** What does it depend on upstream? How is it used downstream? #### N.2 Core Logic Analysis (≥200 words)