liveBook · Manning

Chapter 3: Workflow: Build your own codebase knowledge builder

What you will learn in chapter 3 of Crack Any Codebase with AI

This chapter introduces a Codebase Knowledge Builder workflow that turns an unfamiliar repository into a structured tutorial by fitting code into LLM context and guiding the model systematically.

After this chapter you will be able to

What it builds on

Section by section

Introduction

This chapter introduces a Codebase Knowledge Builder workflow that turns an unfamiliar repository into a structured tutorial by fitting code into LLM context and guiding the model systematically.

Key terms: Codebase Knowledge Builder, pipeline, context window, core concepts, dependencies, structured output, YAML, overview-then-zoom-in, instruction files, domain knowledge

3.1 Turn any codebase into a tutorial for $2

This section introduces a workflow that converts a large repository into a compact architecture map and linked tutorial, cheaply and repeatably, by using bounded LLM calls and reusable instructions.

Key terms: Codebase Knowledge Builder, core abstractions, dependency graph, tutorial chapters, Mermaid sequence diagram, walkthrough, 10-line code example, cross-referencing, workflow, agent

3.2 What the LLM sees determines everything

This section introduces a three-step codebase-tutorial pipeline and explains why the files selected during crawling determine the ceiling and focus of everything the LLM produces.

Key terms: pipeline, crawl, analyze, core abstractions, chapter, context window, included files, hard ceiling, architecture, tests

3.2.1 Most repos fit. The interesting question is what to do when they don't.

This section explains that most repositories fit in an LLM context window after accounting for noise, and shows how to measure a repository before choosing a strategy.

Key terms: context window, repository size tier, single prompt, core logic, tests, documentation, examples, vendored dependencies, localization files, du -sh

3.2.2 Prune the obvious, then let the LLM pick the rest

This section shows how to reduce an oversized repository to a few relevant full files through mechanical pruning followed by LLM triage of file previews.

Key terms: two-phase approach, mechanical pruning, LLM selection, skip list, context window, preview, first N characters, imports, class definitions, docstrings

3.2.3 The LLM needs guidance to pick well

This section teaches how to guide an LLM to select the small, architecturally meaningful set of files that explains a codebase rather than wasting context on generic or repetitive files.

Key terms: context window, file manifest, core architecture, entry points, imports, abstract base class, concrete implementation, similar directories, representative implementation, plumbing

3.3 Analyze: The overview-then-zoom-in pattern

This section introduces an overview-then-zoom-in workflow that uses separate LLM calls to turn a codebase-wide map into deep explanations of individual components.

Key terms: finite context window, breadth, depth, overview-then-zoom-in pattern, high-level map, API call, core-based strategy

3.3.1 Step 1: Get the overview (1 LLM call)

This step uses one LLM call to turn a crawled codebase into a validated YAML overview that can drive later tutorial-generation steps.

Key terms: analyze(), YAML, abstractions, summary, learning_order, machine-readable, prompt, concrete example, beginner-friendly explanation, simple analogy

3.3.2 Step 2: Map relationships (1 LLM call)

This section shows how a second focused LLM call maps connections among previously identified abstractions and converts its structured output into a Mermaid diagram.

Key terms: get_relationships(), abstractions, relationships, {from, to, label}, Mermaid, build_mermaid(), parsed YAML, relationship list

3.3.3 The pattern that scales

This section generalizes the overview-then-zoom-in workflow: map a codebase area broadly, investigate individual features with focused calls, and recognize the need to combine those responses into a coherent tutorial.

Key terms: overview-then-zoom-in pattern, high-level query, focused queries, context window, zoom-in call, narrow question, shallow, scattered answer, independent LLM responses, coherent tutorial, stitch

3.4 Write chapters that read as one tutorial, not ten

It introduces the workflow for turning ordered codebase abstractions into connected tutorial chapters through sequential LLM calls with prior chapters as context.

Key terms: abstractions, chapter, tutorial, full text, previous chapter, context, sequential context, LLM call, prompt

3.4.1 Sequential context: Each chapter knows what came before

This section shows how passing prior chapter text and exact link targets into each chapter-writing call turns independent LLM outputs into one coherent tutorial.

Key terms: sequential context, prev_chapters, full text, previous chapters, full chapters, summaries, transitions, consistent narrative, chapter_list, pre-formatted Markdown

3.4.2 The instructions file: Where the real engineering lives

This section shows how a reusable injected instructions file governs the tutorial-writing style and makes the chapter-generation pipeline coherent and easy to improve.

Key terms: chapter_instructions.md, CHAPTER_INSTRUCTIONS, write_chapter prompt, file selection rules, Open with a problem, not a definition, code blocks under ten lines, Mermaid sequence diagram, internal flow, exact links, chapter filenames

3.4.3 Putting it all together

This subsection assembles the small knowledge-builder functions into a single inexpensive build pipeline that turns a repository into a readable tutorial.

Key terms: build(), crawling, analyzing, mapping relationships, writing chapters, pipeline, 146 MB repository, Gemini Flash, budget model, smart_crawl

3.5 Swap the instructions, change the output

This introduction separates the fixed crawl-and-analyze infrastructure from the instructions file that changes the resulting output.

Key terms: crawl, analyze steps, underlying analysis, relationships, instructions file, output

3.5.1 Same codebase, different lenses

This subsection shows that changing the instruction file applies different expert lenses to the same codebase abstractions and produces audience-specific outputs.

Key terms: instruction file, lens, code abstractions, relationships, domain expertise, trust boundaries, input validation gaps, security issues, companion repo, tutorial

3.5.2 Different questions for different layers

This subsection explains that the same analysis pipeline can produce different kinds of codebase insight when supplied with layer-specific questions and the right files.

Key terms: core abstractions, layers, domain-specific questions, Table 3.5, pipeline, analysis process, inputs, instructions

3.6 Summary

This summary recaps a lightweight LLM workflow that selects useful repository context, analyzes it from overview to detail, and turns the results into adaptable coherent tutorials.

Where this is used later

Concepts explained in this chapter

← Chapter 2: Chat: "Explain this code" is the worst prompt in AI Chapter 4: Agent: Stop telling AI what to read. Let it decide. →

These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.