| name | code-reader-v2-en |
| description | Cognitive science-based source code deep understanding assistant (English improved version). Supports 3 analysis modes: Quick (quick overview), Standard (standard understanding), Deep (deep mastery, auto-parallel for large projects). Combines elaborative interrogation, self-explanation testing, and retrieval practice to help truly understand and master code. |
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. · Chi et al. · Karpicke & Roediger
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)
# [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) ⭐
# [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):
# [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:
## 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:
- WHY is this code needed? (What problem it solves, what happens without it)
- WHY choose this technical approach? (Alternatives + trade-offs)
- WHY is it needed at this time/scenario? (Application scenarios + preconditions/postconditions)
Output Format:
## 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:
## 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:
- Time/space complexity
- WHY choose this algorithm (and why complexity is acceptable)
- When does it degrade
- Authoritative reference links
Output Format:
## 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:
- Pattern name + application location
- WHY use this pattern
- What happens without this pattern
- Standard reference links
Output Format:
## 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:
## 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:
### 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)
**Execution Flow:**
Input → [Step 1] → [Step 2] → ... → Output
↓
[Branch A / Branch B]
**Key algorithm/data structure:** [Name] — Why chosen (at least 2 sentences explaining WHY)?
**Core state variables:**
| Variable | Initial Value | When it Changes | Final State |
|----------|--------------|-----------------|-------------|
| [var] | [init] | [timing] | [final] |
**Multiple execution paths (at least 2):**
- **Path A (normal):** Trigger condition → Key state changes → Result
- **Path B (exception/boundary):** Trigger condition → Key state changes → Result
#### N.3 Line-by-Line Code Analysis (≥300 words, MUST include actual code)
> **Running example input:** `[Specific value]`
```[language]
[Paste real code — at least 30 lines of core logic]
// Step 1: [Operation description]
[code line]
// WHY: [Reason — at least 2 sentences]
// At this point: [variable] = [value]
// Scenario 1: [Condition description]
if [condition]:
[code]
// WHY: [Reason — at least 2 sentences]
Comment style conventions:
# Scenario N: [description] / // Scenario N: [description] — label conditional branches (if/else/switch)# Step N: [description] / // Step N: [description] — label sequential execution flow# At this point: [variable] = [value] — track variable state
N.4 Key Design Points (≥200 words)
| Design Dimension | Analysis (each row ≥2 sentences) |
|---|
| Implementation Choice | Why this approach? What alternatives exist? Why not alternatives? |
| Performance Optimization | Memory, computation, concurrency optimizations? Quantify if possible. |
| Compiler-Related | IR transformations/Pass design/scheduling strategy? (write "N/A" if not applicable) |
| Safety & Robustness | Boundary checks, error handling, exception paths? |
| Extensibility | Where are the extension points? How to extend? |
| Potential Issues | Known limitations, risks, or areas for improvement? |
N.5 Complete Examples (Three Contrasting Cases, ≥150 words)
Three examples use the same code logic with only input changes to form a contrast.
Example 1 — Basic Scenario
- Input:
[Specific value] → Execution: [Key variable changes] → Output: [Result]
Example 2 — Complex/Typical Scenario
- Input:
[More complex value] → Key difference: [Difference from Example 1] → Result: [Output]
Example 3 — Boundary or Exception Case
- Input:
[Extreme/null/invalid input] → Handling: [Is there protection? Crash or graceful degradation?] → Result and reason
N.6 Usage Notes & Improvement Suggestions (≥100 words)
Things to note when using this segment (≥2 notes, each ≥2 sentences):
- [Note 1 + what happens if ignored]
- [Note 2 + what happens if ignored]
Possible improvements (≥1):
- [Improvement direction: specific description + WHY it's better (at least 2 sentences)]
---
### Step 6.5: Test Case Reverse Understanding (Execute when test files are detected)
**Goal:** Reverse-verify and deepen understanding of code functionality through test cases. Tests are the most accurate "user manual," covering boundary conditions and exception scenarios.
**Patterns for detecting test files:**
| Language | Test File Patterns | Common Directories |
|----------|-------------------|-------------------|
| Python | `test_*.py`, `*_test.py` | `tests/`, `test/` |
| JavaScript/TypeScript | `*.test.ts`, `*.spec.ts` | `__tests__/` |
| Go | `*_test.go` | Same directory as source |
| Java | `*Test.java` | `src/test/java/` |
| C++ | `*_test.cpp` (gtest) | `test/`, `tests/` |
| MLIR/LLVM | `*.mlir` (test files) | `test/Dialect/*/` |
**Output Format:**
```markdown
## Test Case Analysis
### Test File Inventory
| Test File/Directory | Module Tested | Number of Test Cases |
|--------------------|---------------|---------------------|
| [path] | [module] | [count] |
### Functionality Coverage Matrix
| Core Functionality | Main Code Location | Test Coverage | Coverage Assessment |
|-------------------|-------------------|---------------|---------------------|
| [functionality] | [location] | ✅/⚠️/❌ | [assessment] |
### Boundary Conditions Discovered from Tests
[Select 3-5 most valuable test cases, explain what details they reveal that are easy to miss when reading code alone]
### Test Quality Assessment
- Normal flow: ✅/⚠️/❌
- Boundary inputs: ✅/⚠️/❌
- Invalid inputs: ✅/⚠️/❌
- Concurrency scenarios: ✅/⚠️/❌
### Test Quality Recommendations
[If tests are insufficient, provide specific improvement suggestions]
Step 7: Application Transfer Testing
Goal: Test whether concepts can transfer to different scenarios, verify true understanding
Must include: At least 2 application scenarios in different domains, each explaining:
- Constant principles (core ideas)
- Parts that need modification (specific code/logic)
- WHY transfer this way (connecting to universal patterns)
Output Format:
## Application Transfer Scenarios
### Scenario 1: [Original Scenario] → [New Scenario]
**Constant principles:** [List core ideas that remain unchanged]
**Parts that need modification:**
[Code comparison with WHY comments]
**Universal pattern learned:** [Extract reusable abstract pattern]
### Scenario 2: [Original Scenario] → [New Scenario]
[Same structure as above]
Step 8: Dependencies & Usage Examples
Each dependency must explain: WHY chosen + WHY not using alternatives
Output Format:
## Dependency Analysis
### External Libraries
**[Library Name] (v[version])**
- **Purpose:** [Brief description]
- **WHY chosen:** [2-3 reasons]
- **WHY not [alternative]:** [Reason]
### Internal Module Dependencies
**[Module A] → [Module B]**
- **Dependency reason:** [Reason]
- **WHY designed this way:** [Design principle]
## Complete Usage Example
[Complete runnable example with detailed WHY comments]
Step 9: Quality Verification Checklist
## Quality Verification Checklist
### Understanding Depth
- [ ] Each core concept answered 3 WHYs (needed / implementation / why not others)
- [ ] Self-explanation test: can explain every core concept without looking at code
- [ ] Concept connections: dependency / comparison / composition relationships and WHYs annotated
### Technical Accuracy
- [ ] Algorithms: Complexity + WHY chosen + WHY acceptable + references
- [ ] Design patterns: Pattern name + WHY used + what happens without it
- [ ] Code analysis: Line-by-line WHY + concrete data execution examples + error-prone points
### Practicality
- [ ] Application transfer: At least 2 scenarios, constant principles + modified parts
- [ ] Usage examples: Complete code + WHY comments + execution results
- [ ] Improvement suggestions: Identify issues + WHY it's a problem + improvement plan
### Final "Four Abilities" Test
Based on this analysis document (without looking at original code):
1. ✅ Can you understand the design rationale of the code?
2. ✅ Can you independently implement similar functionality?
3. ✅ Can you apply it to different scenarios?
4. ✅ Can you clearly explain it to others?
**If any answer is "no", the analysis is not deep enough and needs supplementation.**
Deep Mode Parallel Processing Detailed Workflow (Strategy B/C)
Execution Phases
| Phase | Executor | Operation | Output |
|---|
| 1. Project Map | Master Agent | Enumerate all files, build complete directory tree and module inventory | project-map.md |
| 2. Framework Prep | Master Agent | Based on project map, generate outline, core concepts list, chapter-to-file mapping | 00-framework.json |
| 3. Task Dispatch | Master Agent | Create independent tasks for each chapter with specific file path lists | Task list |
| 4. Parallel Execution | Sub-Agents | Each sub-agent focuses on one chapter, reads assigned files and generates depth analysis | chapter-N.md |
| 5. Coverage Check | Master Agent | Compare against project map, check which files/modules are uncovered | Coverage report |
| 6. Result Aggregation | Master Agent | Merge all chapters, unify format, write final document | complete-analysis.md |
| 7. Quality Verification | Master Agent | Check depth standards, supplement weak sections | Final document |
Sub-Agent Task Template
# Sub-Agent Task: [Chapter Name]
## Context Information
- **Code Name:** [Project/Code name]
- **Programming Language:** [Language]
- **Core Concepts:** [Concept list passed from master agent]
- **Your Assigned Files:** [Explicit list of file paths]
- **Other Module Summary:** [Brief description of other modules' responsibilities, to avoid duplicate analysis]
## Mandatory Execution Steps
1. Use Read tool to read every file listed in "Your Assigned Files" in sequence
2. Only begin analysis after confirming file contents (no analysis from memory or assumptions)
3. Analysis content must reference actual code lines
## Special Instructions: If you are responsible for the "Key Code Analysis" chapter
Must execute two-phase workflow:
**Phase 1 — Core Segment Identification (6A):**
After reading all assigned files, select 3-7 segments most worth deep analysis, by priority:
1. ★★★ Core algorithm implementation (complex logic/nested loops/bitwise operations)
2. ★★★ Key interfaces (system boundaries/heavily called)
3. ★★☆ Elegant design (unusual implementation/interesting trade-offs)
4. ★★☆ Error-prone areas (boundary handling/concurrency control/memory management)
5. ★☆☆ Glue code (coordination logic connecting multiple modules)
First output "Core Segment Inventory":
| # | Segment Name | File:Lines | Priority | Identification Reason |
**Phase 2 — Per-Segment Deep Analysis (6B):**
Each segment strictly outputs 6 sections:
- N.1 Overall purpose (core goal + problem solved + system layer + role dependencies)
- N.2 Core logic analysis (execution flow + algorithm/data structure selection + state variable table + multi-path explanation)
- N.3 Line-by-line code analysis (define running example first, annotate each line with "Scenario/Step + WHY + current variable value")
- N.4 Key design points (implementation choice/performance optimization/compiler-related/safety robustness/extensibility/potential issues)
- N.5 Complete examples (same code logic, 3 contrasting inputs: basic/complex/boundary exception)
- N.6 Usage notes and improvement suggestions (2-3 notes + optional improvement directions)
## Output Requirements
- This chapter must be at least [X] words, each WHY at least 2-3 sentences
- Code comments use Scenario/Step + WHY style
- Provide authoritative reference links
- Every public function/class in assigned files must be mentioned
## Depth Self-Check
- [ ] All assigned files have been read
- [ ] All subsections covered (no "skipped" or "same as above")
- [ ] Each WHY has at least 2-3 sentences of explanation
- [ ] Code examples have complete comments
- [ ] Execution flows have concrete data tracking
- [ ] "Key Code Analysis" has output core segment inventory + 6-section deep analysis per segment
Output Markdown format directly, starting with `## [Chapter Name]`.
Coverage Check Format
## Coverage Check Report
### File Coverage
| File Path | Analyzed | Chapter | Notes |
|-----------|----------|---------|-------|
| [path] | ✅/❌ | [chapter] | [explanation] |
### Module Coverage Rate
- Core modules: X/Y covered (target: 100%)
- Utility modules: X/Y covered
- Test files: X/Y covered (target: ≥ 80%)
### Uncovered Content Handling
- Important files (core business logic): Supplement analysis immediately
- Secondary files (config/utilities): Briefly mention in dependencies chapter
- Test files: Confirm already covered in test case analysis chapter
Strategy C: Very Large Project Layered Parallel (Files > 20 or Lines > 10000)
- Phase 1 — Module-Level Scan (Sequential): Divide project into 3-8 modules by directory/functionality, generate independent module summaries (sub-agents in parallel)
- Phase 2 — Chapter-Level Analysis (Parallel): Each chapter sub-agent receives complete project map + responsible module summaries + key files list to read in depth
- Phase 3 — Aggregation: Same as Strategy B
Depth Self-Check Checklist (Check after each chapter is complete)
## Chapter Depth Self-Check
### Content Completeness
- [ ] All subsections covered (no "skipped", "see above", or "same as above")
- [ ] Each WHY has specific explanation (at least 2-3 sentences)
- [ ] Code examples have complete comments (Scenario/Step + WHY)
- [ ] References have source links
### Analysis Depth (by chapter type)
- **Concept chapters:** 3 WHYs per concept (needed / implementation / why not others)
- **Algorithm chapters:** Complexity + WHY chosen + WHY acceptable + degradation scenarios
- **Design pattern chapters:** Pattern name + WHY used + what happens without it
- **Code analysis chapters:** Core segment inventory (≥3, with file:lines + priority + reason) + 6-section analysis per segment + running example + three contrasting cases
### Minimum Word Count and Required Elements per Chapter
| Chapter | Min Words | Required Elements |
|---------|-----------|-------------------|
| 1. Quick Overview | 200 | Language, scale, dependencies, type |
| 2. Background & Motivation | 400 | Problem essence, solution choice, application scenarios |
| 3. Core Concepts | 600 | 3 WHYs per concept, relationship matrix |
| 4. Algorithm & Theory | 500 | Complexity, WHY, references |
| 5. Design Patterns | 400 | Pattern name, WHY, standard references |
| 6. Key Code Analysis | ≥1000 words per segment (3 segments minimum = ≥3000 words) | Segment inventory, each segment 6 sections (real code ≥30 lines, three contrasting examples) |
| 7. Test Case Analysis | 400 | Test coverage, boundary conditions, test discoveries |
| 8. Application Transfer | 500 | ≥2 scenarios, constant principles, modified parts |
| 9. Dependencies | 300 | WHY per dependency, usage examples |
| 10. Quality Verification | 200 | Verification checklist, four abilities test |
**Deep Mode document should be ≥ 8000 words (including code comments)**
**⚠️ Critical reminder: Chapter numbering must be continuous — do NOT use Phase/Module/Stage etc. to break the numbered sequence**
Token-Optimized Output Strategy
| Mode | Generation Method | Number of Files |
|---|
| Quick | Single Write | 1 |
| Standard | Single Write | 1 |
| Deep ≤ 2000 lines (Strategy A) | Progressive Write (framework first, then fill sections) | 1-2 |
| Deep > 2000 lines (Strategy B/C) | Parallel sub-agents → aggregated Write | Multiple temp chapters → 1 final document |
Core principle: Write complete analysis directly to file, output only summary in conversation.
## Analysis Complete
**Mode:** [Quick/Standard/Deep]
**Key Findings:**
- Code implements [core functionality]
- Uses [algorithm/pattern] to solve [problem]
- Key optimization: [optimization point]
- Potential issues: [issue]
**Complete document:** `[code-name]-deep-analysis.md`
File naming:
- Single file:
[code-name]-deep-analysis.md
- Multi-file project:
[project-name]-overview.md + [module-name]-analysis.md
- Large project:
work/project-map.md + work/chapters/chapter-N.md + [project-name]-complete-mastery-analysis.md
Human-Friendly Writing Guidelines
Analysis documents must read like an experienced engineer explaining to someone, not a textbook stacking jargon.
Core requirements:
- Conversational lead-in, not direct definitions — Use "this function is the system's gatekeeper — every login passes through it" instead of "this function is responsible for executing the authentication flow"
- Conclusion first, then reasoning — Use "bcrypt instead of MD5, because MD5 is simply too fast" instead of "due to bcrypt's adaptive hashing function properties..."
- Use analogies freely — Explain locking mechanisms like library reading room rules, explain caching like keeping frequently-used items on your desk
- Code comments in plain language — Explain intent and reason, not repeat the literal meaning of the code
- Layered explanation for complex concepts — Start with a one-sentence intuitive understanding, then add technical details
- Annotate error-prone points proactively — Use ⚠️ to mark common misconceptions
Prohibited writing styles:
- Long lists of jargon without explanation
- "This function implements X functionality" (the reader already knows)
- WHY explanation with only one sentence
- Copy-pasting official documentation wording
Self-check question: Can a junior engineer understand this? Does it give readers an "aha!" moment?
