Codebase Study Guide

Generate a study guide that builds durable understanding of a codebase using evidence-based learning techniques. The guide helps readers grasp not just what the code does, but why it exists and how its parts relate.

Guiding Pedagogy

These principles shape every section of the guide. See references/pedagogy.md for the full research basis.

• Purpose before structure. Start with the problem being solved, not the file tree. Readers who understand the "why" form stronger schemas for the "how" (Ausubel's meaningful learning).
• Threshold concepts first. Identify the 2-3 ideas that, once grasped, make everything else click. Front-load these (Meyer & Land).
• Progressive disclosure. Layer complexity: overview -> systems -> interfaces -> internals. Never introduce more than one unfamiliar subsystem at a time (Cognitive Load Theory).
• Active over passive. Include prediction prompts, elaborative interrogation questions, and exploration tasks — not just descriptions. Active techniques outperform passive reading by d = 0.5-0.7 (Dunlosky et al.).
• Dual coding. Pair every textual explanation with a visual (diagram, map, flow). Dual-channel encoding roughly doubles recall (Paivio).
• Name the patterns. Explicitly identify architectural patterns and link to resources. Pattern recognition is the mechanism of expert code comprehension (Brooks, Soloway).

Workflow

Step 1: Scope the Guide