Chapter 3: Workflow: Build your own codebase knowledge builder
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
- Codebase Knowledge Builder purpose. Explain why a Codebase Knowledge Builder is needed for a large, unfamiliar repository and what it produces. State that it reads the codebase, identifies core concepts, and explains them in a logical order with their dependencies rather than relying on ad hoc chat questions.
- Reusable workflow techniques. Describe the three techniques this chapter introduces: forcing structured LLM output, decomposing work with an overview-then-zoom-in strategy, and encoding domain knowledge in instruction files. Explain that these techniques are reused throughout the book.
- Generated codebase learning artifacts. Describe the two artifacts the Codebase Knowledge Builder generates: a single-page diagram of core abstractions and a linked tutorial chapter for each abstraction. Explain how the diagram's dependency arrows provide a recommended learning order.
- Bounded workflow cost model. Distinguish the workflow's small fixed set of fresh-context LLM calls from an agent's many calls with growing re-sent context. State that the example generator uses roughly 12 calls for triage, abstractions, relationships, and chapters, allowing a large codebase tutorial to cost about $2 with a cheap long-context model.
- Automated comprehension bottlenecks. Explain that unfamiliar-codebase exploration is slowed by finding relevant files, tracing dependencies, and assembling scattered findings into a mental model, and describe how the Knowledge Builder automates each task through collection and concept selection, relationship mapping, and a persistent shareable tutorial.
- Three-step tutorial pipeline. Describe the pipeline that turns a repository into tutorial chapters: crawl the repository into a single string, analyze it for core abstractions, and write a chapter for each abstraction.
- Crawl context selection. Explain why the crawl step determines the quality and subject of the output: the included files are the LLM's available context and set a hard ceiling on what architecture it can analyze and what it will emphasize.
- Repository size tiers. Explain why a small repository can be sent to an LLM in one prompt, while a larger repository may require a different strategy. State that the relevant decision starts with measuring the repository's size and file count.
- Architectural noise sources. Describe why large repositories commonly overflow an LLM context window: much of their size is non-core material rather than application logic. Identify examples of low-value architectural input such as tests, documentation and examples, vendored dependencies, localization files, media assets, lock files, or bot integrations.
- Two-phase repository filtering. Describe the two-phase approach for repositories that exceed an LLM context window: mechanically remove obviously irrelevant or oversized files first, then have the LLM choose relevant files from the remainder.
- Preview-based file triage. Explain how the workflow sends a short beginning-of-file preview for every remaining file so the LLM can select relevant paths, then retrieves the complete contents only for the selected files.
- Context-window selection problem. Explain why codebase understanding depends on selecting a tiny relevant file slice rather than giving an LLM as many files as possible. State that unguided selection can consume context on generic documentation, configuration, plumbing, or an unrepresentative subsystem instead of the files that reveal the product architecture.
- Architectural anchor files. Describe how to select entry points and concrete implementations as architectural anchors. Explain that an application's boot files and their imports reveal major components, while an abstract base class should be paired with one real implementation to show how its interface is actually used.
- Representative pattern filtering. Apply the remaining selection rules: choose one representative from repeated similar directories or variants, and skip generic plumbing such as utilities, telemetry, retries, lock files, and tooling configuration. State that the chosen representative should be the most popular or complete example, and that all four rules should be encoded in the prompt sent with the file manifest.
- Breadth-depth context tradeoff. Explain why asking an LLM to explain an entire codebase in one call produces a shallow, unusable result. Describe how a finite context window forces a tradeoff: tokens spent covering more components cannot be spent explaining any one component deeply.
- Overview-then-zoom-in workflow. Describe the overview-then-zoom-in pattern: make one API call to identify the codebase's important concepts or high-level map, then make separate calls that investigate each component in depth. Explain that separating the calls lets each focused investigation use its context window for its specific task.
- Structured codebase overview. Describe the YAML overview produced by the first analyze() call: a list of core abstractions, a summary, and a recommended learning order. Explain that machine-readable output can be parsed by the script and passed directly to the next pipeline step.
- Schema-guided prompt design. Explain how the prompt makes the YAML output more reliable: it explicitly requests YAML, supplies a concrete example of the desired format, and asks for beginner-friendly explanations with simple analogies. Describe how the example leverages the LLM's ability to mirror structure and how analogies can be reused in the final tutorial.
- Separate relationship-mapping call. Explain why relationship mapping is performed in a second LLM call after identifying the codebase abstractions. Distinguish the first question, "What are the pieces?", from the second question about which pieces call or pass parameters to other pieces.
- Structured relationship diagram pipeline. Describe the relationship data returned by get_relationships() and how it becomes a Mermaid diagram. State that the LLM returns a list of {from, to, label} objects, after which code formats the parsed output into a diagram without another LLM call or manual drawing.
- Overview-then-zoom-in pattern. Describe the overview-then-zoom-in pattern as one high-level LLM query that maps a terrain followed by focused queries that inspect individual features or flows.
- Focused context allocation. Explain why a zoom-in call can produce deeper answers: it dedicates the LLM's entire context window to one narrow question rather than spreading attention across unrelated tasks.
- Sequential tutorial chapter generation. Describe how the workflow creates one chapter for each ordered abstraction while making the chapters read as a single tutorial rather than disconnected articles.
- Previous-chapter context. Explain that the full text of every previous chapter is passed as context when generating the next chapter, so later chapters can continue the tutorial coherently.
- Sequential chapter context. Describe how sequential context works when generating tutorial chapters: each new LLM call receives the full text of every chapter written before it, while the first chapter receives only a first-chapter instruction. Explain that the workflow appends each completed chapter to prev_chapters so the context grows on every iteration.
- Full-text narrative continuity. Explain why the workflow passes full preceding chapters rather than summaries: the LLM can accurately reference what it has actually read, reuse analogies and specific code examples, and create transitions and a consistent narrative. State the trade-off that this costs a few extra pennies per workflow but substantially improves quality.
- Injected chapter instructions. Describe how chapter_instructions.md is read once at startup and injected into every chapter-writing prompt through the {CHAPTER_INSTRUCTIONS} slot. Distinguish its role of telling the LLM how to write from file-selection rules that tell it which source files to use.
- Tutorial writing rules. Explain the main rules encoded in the instructions file: begin with a motivating problem rather than a definition, keep code blocks under ten lines with explanation between small examples, and use a Mermaid sequence diagram for each internal flow with roughly four or five participants. State that these rules prevent jargon-heavy prose and unexplained large code dumps.
- Instructions-file leverage. Justify why the instructions file is the part of the system that should keep evolving: changing one rule and rerunning the pipeline changes the style of the entire tutorial, whereas the crawler, YAML parser, and diagram builder are plumbing written once and largely forgotten.
- End-to-end build pipeline. Describe how the build() function runs the four main stages in order: crawling, analyzing, mapping relationships, and writing chapters. State that one command executes the complete pipeline.
- Fixed infrastructure and variable instructions. Distinguish the fixed crawl and analyze steps, which produce the same codebase analysis and relationships, from the instructions file, which is the part changed to alter the output.
- Instruction-file lenses. Explain how an instruction file changes an AI pipeline's output without changing the codebase abstractions or their relationships. Describe that the file defines the lens—such as what a security reviewer versus a new hire should learn—through which the AI examines the same material.
- Domain expertise in prompts. Justify why specific expert instructions outperform broad generalist requests. State that the strongest prompts express domain knowledge plainly by naming the concrete concerns an expert knows to investigate, such as trust boundaries and input-validation gaps.
- Layer-specific analysis questions. Explain why a broad question such as "What are the core abstractions?" is a useful starting point but insufficient for every layer of a system. Describe how different layers require different domain-specific questions and relevant files to reveal the insight for that layer.
- Reusable pipeline inputs. Describe the reusable workflow for the rest of the book: keep the analysis process the same, then feed the pipeline a chapter's domain-specific instructions and the files it identifies. State that changing those inputs produces a different kind of insight.
What it builds on
- Chat can't scale past five files. That's not a bug. (chapter 2) · Chat alone does not scale past a handful of files, motivating a workflow.
- Chained together, each tool covers the next one's weakness (chapter 2) · Chaining tools lets each stage address another tool's weakness.
- The reframe: From reading code to architectural thinking (chapter 1) · The shift from reading individual files toward understanding a codebase's architecture.
- What's a workflow? (chapter 2) · The definition of a workflow as a sequence of tools or steps.
- What's an agent? (chapter 2) · The definition of an agent.
- The problem: Comprehension debt is the silent killer (chapter 1) · The problem of comprehension debt caused by insufficient understanding of a codebase.
- One file can't answer cross-file questions. 20 lines fix that. (chapter 2) · The limitation that a model cannot answer cross-file questions when it lacks the relevant files.
- What you cut matters as much as what you keep (chapter 2) · The idea that what is omitted from LLM input matters as much as what is retained.
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.
- Codebase Knowledge Builder purpose: Explain why a Codebase Knowledge Builder is needed for a large, unfamiliar repository and what it produces. State that it reads the codebase, identifies core concepts, and explains them in a logical order with their dependencies rather than relying on ad hoc chat questions.
Why it matters: The builder gives you a systematic way to gain orientation when you do not yet know what questions the codebase requires. - Reusable workflow techniques: Describe the three techniques this chapter introduces: forcing structured LLM output, decomposing work with an overview-then-zoom-in strategy, and encoding domain knowledge in instruction files. Explain that these techniques are reused throughout the book.
Why it matters: These techniques make LLM-based codebase analysis repeatable and adaptable instead of dependent on a one-off conversation. - Tutorial generation scale: State the example scale and cost claimed for the builder: when pointed at VS Code, it can turn roughly 10,000 files into a multi-chapter tutorial in about eight minutes for about $2 in API calls.
Why it matters: The example makes the workflow's practical cost and scale concrete.
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.
- Generated codebase learning artifacts: Describe the two artifacts the Codebase Knowledge Builder generates: a single-page diagram of core abstractions and a linked tutorial chapter for each abstraction. Explain how the diagram's dependency arrows provide a recommended learning order.
Why it matters: These artifacts turn an overwhelming repository into a navigable path for building an architectural mental model. - Tutorial chapter structure: Describe what makes each generated chapter a walkthrough rather than a generic summary: it starts from a concrete problem, uses a small code example and a diagram, and links or builds on related concepts already introduced.
Why it matters: Problem-led, connected chapters give readers an understandable route through code instead of isolated explanations. - Bounded workflow cost model: Distinguish the workflow's small fixed set of fresh-context LLM calls from an agent's many calls with growing re-sent context. State that the example generator uses roughly 12 calls for triage, abstractions, relationships, and chapters, allowing a large codebase tutorial to cost about $2 with a cheap long-context model.
Why it matters: Understanding the cost structure lets you use broad repository context without treating codebase comprehension as prohibitively expensive. - Automated comprehension bottlenecks: Explain that unfamiliar-codebase exploration is slowed by finding relevant files, tracing dependencies, and assembling scattered findings into a mental model, and describe how the Knowledge Builder automates each task through collection and concept selection, relationship mapping, and a persistent shareable tutorial.
Why it matters: The workflow is valuable because it removes the repetitive exploration work that consumes developers' time and leaves them with a durable explanation. - Instruction files as lenses: Explain that the same codebase pipeline can produce different outputs when given a different instructions file, such as a tutorial, security audit, architecture review, or onboarding guide. Describe the instructions as the lens that re-aims one understanding engine without changing the codebase.
Why it matters: Reusable instructions let the workflow answer the different kinds of questions developers need across systems and engineering tasks.
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.
- Three-step tutorial pipeline: Describe the pipeline that turns a repository into tutorial chapters: crawl the repository into a single string, analyze it for core abstractions, and write a chapter for each abstraction.
Why it matters: Knowing the pipeline shows where later analysis and writing outputs come from. - Crawl context selection: Explain why the crawl step determines the quality and subject of the output: the included files are the LLM's available context and set a hard ceiling on what architecture it can analyze and what it will emphasize.
Why it matters: The LLM can only form conclusions from the portion of the codebase the workflow puts in front of it.
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.
- Repository size tiers: Explain why a small repository can be sent to an LLM in one prompt, while a larger repository may require a different strategy. State that the relevant decision starts with measuring the repository's size and file count.
Why it matters: Choosing a workflow based on the repository's actual size prevents unnecessary complexity or context-window failures. - Architectural noise sources: Describe why large repositories commonly overflow an LLM context window: much of their size is non-core material rather than application logic. Identify examples of low-value architectural input such as tests, documentation and examples, vendored dependencies, localization files, media assets, lock files, or bot integrations.
Why it matters: Recognizing noise lets you preserve the files that explain architecture instead of spending context on material that usually does not. - Repository measurement commands: State how to measure a repository before selecting a strategy: use `du -sh path/to/repo` for total disk size and `git ls-files | wc -l` for the number of Git-tracked files.
Why it matters: These two quick measurements give you the evidence needed to place a repository in a workable size tier.
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.
- Two-phase repository filtering: Describe the two-phase approach for repositories that exceed an LLM context window: mechanically remove obviously irrelevant or oversized files first, then have the LLM choose relevant files from the remainder.
Why it matters: This makes a repository small enough to analyze without discarding selection decisions that require understanding the code. - Preview-based file triage: Explain how the workflow sends a short beginning-of-file preview for every remaining file so the LLM can select relevant paths, then retrieves the complete contents only for the selected files.
Why it matters: Previews let the model compare many files at once while reserving scarce context for the files worth reading deeply. - Structured LLM response handling: Describe the roles of call_llm and parse_yaml: call_llm returns the model's raw text response, while parse_yaml extracts a fenced YAML block and converts it into a Python dictionary for the pipeline to use.
Why it matters: Converting a free-form model reply into structured data lets subsequent code reliably act on the selected files. - Context window triage limits: Explain why file previews must become shorter as file count grows within a fixed context window, and why context-window size is more important than model reasoning ability for this codebase-crawl task.
Why it matters: Choosing a model with sufficient context determines whether it can compare enough of the repository to triage it effectively.
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.
- Context-window selection problem: Explain why codebase understanding depends on selecting a tiny relevant file slice rather than giving an LLM as many files as possible. State that unguided selection can consume context on generic documentation, configuration, plumbing, or an unrepresentative subsystem instead of the files that reveal the product architecture.
Why it matters: An LLM can only give an architectural explanation if its limited context contains the files that actually define the system. - Architectural anchor files: Describe how to select entry points and concrete implementations as architectural anchors. Explain that an application's boot files and their imports reveal major components, while an abstract base class should be paired with one real implementation to show how its interface is actually used.
Why it matters: Entry points reveal how major pieces are assembled, and concrete code turns an abstract component shape into observable behavior. - Representative pattern filtering: Apply the remaining selection rules: choose one representative from repeated similar directories or variants, and skip generic plumbing such as utilities, telemetry, retries, lock files, and tooling configuration. State that the chosen representative should be the most popular or complete example, and that all four rules should be encoded in the prompt sent with the file manifest.
Why it matters: Representative examples preserve context for the code that makes the project distinctive instead of repeating the same pattern or explaining reusable infrastructure.
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.
- Breadth-depth context tradeoff: Explain why asking an LLM to explain an entire codebase in one call produces a shallow, unusable result. Describe how a finite context window forces a tradeoff: tokens spent covering more components cannot be spent explaining any one component deeply.
Why it matters: Recognizing this tradeoff prevents you from expecting one giant prompt to produce actionable understanding. - Overview-then-zoom-in workflow: Describe the overview-then-zoom-in pattern: make one API call to identify the codebase's important concepts or high-level map, then make separate calls that investigate each component in depth. Explain that separating the calls lets each focused investigation use its context window for its specific task.
Why it matters: This pattern turns a broad codebase inventory into explanations you can actually use to navigate and work in the system.
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.
- Structured codebase overview: Describe the YAML overview produced by the first analyze() call: a list of core abstractions, a summary, and a recommended learning order. Explain that machine-readable output can be parsed by the script and passed directly to the next pipeline step.
Why it matters: A structured overview turns an LLM response into usable pipeline data rather than a one-off explanation. - Schema-guided prompt design: Explain how the prompt makes the YAML output more reliable: it explicitly requests YAML, supplies a concrete example of the desired format, and asks for beginner-friendly explanations with simple analogies. Describe how the example leverages the LLM's ability to mirror structure and how analogies can be reused in the final tutorial.
Why it matters: Clear output constraints make the model's response predictable enough to automate and useful enough to teach from. - Learning-order validation: Describe the internal-consistency check assert names == set(result["learning_order"]), including the error it catches: an abstraction that is misspelled or missing from the learning order. Explain that the LLM derives the order from code dependencies, putting foundational patterns before visible features.
Why it matters: Validation catches a common model-output mistake before later pipeline steps depend on an incomplete learning plan.
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.
- Separate relationship-mapping call: Explain why relationship mapping is performed in a second LLM call after identifying the codebase abstractions. Distinguish the first question, "What are the pieces?", from the second question about which pieces call or pass parameters to other pieces.
Why it matters: Separating component discovery from connection mapping gives the model a clear task and produces better analysis. - Structured relationship diagram pipeline: Describe the relationship data returned by get_relationships() and how it becomes a Mermaid diagram. State that the LLM returns a list of {from, to, label} objects, after which code formats the parsed output into a diagram without another LLM call or manual drawing.
Why it matters: Structured relationship output makes the diagram reproducible: the LLM analyzes connections and ordinary code renders them.
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.
- Overview-then-zoom-in pattern: Describe the overview-then-zoom-in pattern as one high-level LLM query that maps a terrain followed by focused queries that inspect individual features or flows.
Why it matters: This pattern turns a large codebase question into a sequence of answers that can be explored in useful detail. - Focused context allocation: Explain why a zoom-in call can produce deeper answers: it dedicates the LLM's entire context window to one narrow question rather than spreading attention across unrelated tasks.
Why it matters: Keeping a call narrow helps avoid shallow, scattered explanations of a complex codebase. - Independent-response stitching problem: State the trade-off created by splitting analysis into focused LLM calls: the answers are deeper, but ten independent responses still need to be stitched into one coherent tutorial.
Why it matters: Recognizing this handoff problem explains why the next workflow stage must organize individual analyses into a connected learning experience.
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.
- Sequential tutorial chapter generation: Describe how the workflow creates one chapter for each ordered abstraction while making the chapters read as a single tutorial rather than disconnected articles.
Why it matters: A tutorial is useful only when each new explanation builds on the reader's understanding from earlier ones. - Previous-chapter context: Explain that the full text of every previous chapter is passed as context when generating the next chapter, so later chapters can continue the tutorial coherently.
Why it matters: Giving the model prior chapters prevents it from treating every new abstraction as a fresh, isolated explanation. - Per-abstraction LLM calls: State that each abstraction receives its own LLM call and that the chapter-writing prompt is designed more carefully than the earlier prompts in the workflow.
Why it matters: Separate calls and deliberate prompts give the workflow control over how each abstraction is explained.
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.
- Sequential chapter context: Describe how sequential context works when generating tutorial chapters: each new LLM call receives the full text of every chapter written before it, while the first chapter receives only a first-chapter instruction. Explain that the workflow appends each completed chapter to prev_chapters so the context grows on every iteration.
Why it matters: This is what lets separately generated chapters behave like parts of one continuous explanation. - Full-text narrative continuity: Explain why the workflow passes full preceding chapters rather than summaries: the LLM can accurately reference what it has actually read, reuse analogies and specific code examples, and create transitions and a consistent narrative. State the trade-off that this costs a few extra pennies per workflow but substantially improves quality.
Why it matters: A tutorial feels coherent only when later explanations can reliably build on the actual earlier explanations. - Exact cross-chapter links: Describe how supplying a pre-formatted Markdown chapter_list with the exact filenames lets the LLM copy cross-chapter links verbatim. Explain that giving the model this known answer avoids guessed filenames, broken links, and post-processing.
Why it matters: Providing exact link targets makes generated documentation reliable without a cleanup pass.
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.
- Injected chapter instructions: Describe how chapter_instructions.md is read once at startup and injected into every chapter-writing prompt through the {CHAPTER_INSTRUCTIONS} slot. Distinguish its role of telling the LLM how to write from file-selection rules that tell it which source files to use.
Why it matters: Separating content selection from writing guidance lets the same pipeline produce explanations a new developer can actually learn from. - Tutorial writing rules: Explain the main rules encoded in the instructions file: begin with a motivating problem rather than a definition, keep code blocks under ten lines with explanation between small examples, and use a Mermaid sequence diagram for each internal flow with roughly four or five participants. State that these rules prevent jargon-heavy prose and unexplained large code dumps.
Why it matters: These constraints turn technically correct generated text into a tutorial that a new developer can follow and remember. - Cross-chapter narrative coherence: Describe how exact links to prior chapters, consistent analogies carried from the analysis output, and a transition to the next chapter make generated chapters read as one tutorial rather than disconnected articles. Explain that chapter filenames can be precomputed and supplied to the prompt so links are correct.
Why it matters: Readers can follow connections between concepts without searching for vague references or relearning a changing metaphor. - Instructions-file leverage: Justify why the instructions file is the part of the system that should keep evolving: changing one rule and rerunning the pipeline changes the style of the entire tutorial, whereas the crawler, YAML parser, and diagram builder are plumbing written once and largely forgotten.
Why it matters: Editing the highest-leverage component lets you improve every generated chapter instead of polishing them one at a time.
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.
- End-to-end build pipeline: Describe how the build() function runs the four main stages in order: crawling, analyzing, mapping relationships, and writing chapters. State that one command executes the complete pipeline.
Why it matters: A single repeatable command turns codebase exploration into a workflow you can rerun instead of a manual investigation. - Practical pipeline economics: State the practical result claimed for the pipeline: it converts a 146 MB repository into a tutorial readable in an afternoon, runs in minutes, and costs about two dollars on a budget model such as Gemini Flash.
Why it matters: These constraints make the workflow practical to use routinely on unfamiliar repositories. - Deliberately small tool design: Describe the tool as eight functions with no classes, framework, or inheritance, including build() and the reused crawl and call_llm pieces from chapter 2. Explain that this small design means you wrote and can understand the entire system.
Why it matters: A workflow you can fully understand is easier to adapt, trust, and maintain for your own codebase investigations.
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.
- Fixed infrastructure and variable instructions: Distinguish the fixed crawl and analyze steps, which produce the same codebase analysis and relationships, from the instructions file, which is the part changed to alter the output.
Why it matters: This distinction lets you reuse one analysis pipeline while producing different kinds of understanding from the same codebase.
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.
- Instruction-file lenses: Explain how an instruction file changes an AI pipeline's output without changing the codebase abstractions or their relationships. Describe that the file defines the lens—such as what a security reviewer versus a new hire should learn—through which the AI examines the same material.
Why it matters: The instruction file lets one codebase knowledge pipeline serve different readers and purposes. - Domain expertise in prompts: Justify why specific expert instructions outperform broad generalist requests. State that the strongest prompts express domain knowledge plainly by naming the concrete concerns an expert knows to investigate, such as trust boundaries and input-validation gaps.
Why it matters: Writing down what an expert would ask helps the AI produce a more useful and targeted analysis. - Available instruction examples: State the four companion-repository instruction-file examples and describe how comparing tutorial and security instructions reveals different explanations of the same core abstractions for different readers.
Why it matters: The companion examples provide concrete models for adapting the pipeline to a particular lens.
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.
- Layer-specific analysis questions: Explain why a broad question such as "What are the core abstractions?" is a useful starting point but insufficient for every layer of a system. Describe how different layers require different domain-specific questions and relevant files to reveal the insight for that layer.
Why it matters: Asking questions that match the layer prevents a general-purpose analysis from overlooking what that part of the system is really doing. - Reusable pipeline inputs: Describe the reusable workflow for the rest of the book: keep the analysis process the same, then feed the pipeline a chapter's domain-specific instructions and the files it identifies. State that changing those inputs produces a different kind of insight.
Why it matters: This lets you reuse one knowledge-building workflow instead of inventing a new process for each codebase question.
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
- (chapter intro) (chapter 4) · the workflow that turns a codebase into a tutorial
- Broad questions: Your agent skimmed 25 files and missed everything (chapter 4) · The idea that a workflow can turn a codebase into a tutorial.
- Four sources hold the architecture (chapter 9) · Adapting repository analysis when the relevant material does not all fit or appear in one obvious place.
- Summary (chapter 8) · Selecting relevant repository material before asking the LLM to analyze it.
- Ask the LLM to draw the schema and tour it (chapter 7) · Schema exploration uses an initial schema-wide view before investigating particular tables.
- Trace one endpoint from request to response (chapter 8) · Endpoint tracing begins with an identified endpoint and follows its focused request flow.
- Skill file: Make the agent document what it learned (chapter 4) · The idea that an instructions file contains the important guidance shaping generated tutorials.
- (chapter intro) (chapter 5) · Changing instructions to analyze the same codebase through different lenses.
Concepts explained in this chapter
- pipelineA workflow is a repeatable sequence of predefined steps that systematically transforms inputs into consistent outputs.
- tutorialA guided tour is a narrative explanation that walks a reader through related product features in a meaningful sequence.
- language modelA large language model is a machine-learning model trained on large amounts of text to generate and transform language from prompts.
- context windowA context window is the finite token capacity available to a language model for processing input, tool results, and generated reasoning or output.
- URI abstractionA URI abstraction represents resources through uniform addresses independent of whether they are local files, remote locations, or unsaved buffers.
- context keysContext keys are boolean or other state flags that determine which editor commands and menu items are active.
- dependency injectionDependency injection is a technique in which an object's required collaborators are supplied from outside rather than created or imported directly.
- eventingEventing is a software pattern in which an event emitted by one operation enables multiple responding operations.
- file system abstractionA file system abstraction provides a uniform interface for accessing files across physical, remote, and virtual storage systems.
- language intelligenceLanguage intelligence is a set of programming-language services that provide features such as completion, definition navigation, and diagnostics.
- mental modelA mental model is an internal conceptual representation of a system, its structure, and its behavior.
- resource cleanupResource cleanup is the systematic release of memory, watchers, connections, and other resources when they are no longer needed.
- workbench layoutA workbench layout is the arrangement and behavior of an editor's panels, sidebars, tabs, and split views.
- overview-then-zoom-in patternThe overview-then-zoom-in pattern is an analysis approach that first establishes a high-level map and then examines individual features with focused questions.
- entry pointAn entry point is a file or function through which an application starts execution or initializes its major components.
- UML sequence diagramA sequence diagram is a diagram that represents interactions among participants in temporal order.
- schemaA schema is a formal description of the structure, relationships, and constraints of data or a data store.
- repositoryA repository is a structured collection of a software project's files and directories managed as a unit.
- promptA prompt is an instruction or input supplied to an AI model to elicit a particular response.
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.
