Chapter 3: Context fabric: optimizing context for AI agents
The introduction explains why agents often fail because of the context they receive, distinguishes context engineering from prompt engineering, and defines a shared Context Fabric.
After this chapter you will be able to
- Recognizable context failure modes. Explain why an agent can produce the wrong result because of the context it receives, and name the four forms of context failure described here.
- Context versus prompt engineering. Distinguish context engineering from prompt engineering by describing what each focuses on and what information context engineering considers.
- Shared Context Fabric. Describe what a Context Fabric is and why a project needs one when agents do not automatically see its full context.
- Context Determines Code Quality. Explain why asking an AI to fix a bug without concrete project and bug details is likely to produce an unsuitable answer, and why the developer must supply context even if the model asks clarifying questions.
- Context vacuum failure. Explain how an isolated code snippet can leave a model guessing about project dependencies and produce plausible but incorrect changes. Describe the authentication example's security and consistency failures.
- Agent context blindness. Distinguish an agent's context blindness from a human developer's awareness of missing information, and explain why automatic retrieval reduces but cannot eliminate the vacuum.
- Multishot and Multifile References. Distinguish multishot examples from multifile context, and explain what Bob's additional project files are meant to provide.
- Framed and Curated Context. Explain why pasted fragments need to be selected, annotated, and identified by their roles in the system.
- Framed multishot code examples. Explain how labeling and briefly explaining each code snippet helps an LLM interpret its role and generate code that follows a codebase’s conventions, whereas unlabeled snippets leave it guessing.
- Pre-fix gap analysis. Explain why asking the model what it needs to see before writing a fix can reduce unsupported assumptions, and describe the instruction to request its top three missing items without generating code yet.
- Limits of visible gaps. Describe why the gap list should be ranked and capped, and distinguish gaps the model can infer from context from ones it cannot see.
- Manual context assembly risks. Explain why a large, manually assembled multi-source prompt can still lead an LLM to generate faulty code.
- Uncertain context quantity. Describe why deciding how much context to provide is difficult and how the section proposes probing for gaps.
- Connected sources of truth. Justify the shift from hand-curated prompts toward tools that connect an LLM to relevant sources of truth.
- Standardized external tool access. Explain why MCP is used instead of building a separate integration for every database, API, or service.
- MCP client server roles. Describe where the MCP client and servers sit and how they let an agent invoke tools across different data sources.
- MCP-assisted component context gathering. Trace how Bob delegates context gathering for UserProfileCard: the agent retrieves design details from Figma, inspects BaseCard and repository conventions, and checks the current API schema before implementing the component.
- Design token update boundary. Distinguish what retrieving Figma variables through MCP accomplishes from what keeps a generated component's token values current after generation.
- External library research workflow. Trace how an agent can use MCP when a requested file picker has no existing implementation or usage pattern in the repository: discover candidate packages, select one, retrieve version-specific documentation, and integrate it using those examples.
- Limits of retrieved documentation. Explain why retrieving library documentation improves the agent's basis for integration without guaranteeing that its answer or library choice is right. Distinguish an official API description from evidence of how the API behaves with the project's build, dependencies, and type system.
- Compiler-level project context. Explain how connecting an agent to an LSP server through MCP gives it the compiler’s view of a project rather than only raw files, and distinguish that build-time view from runtime or deployment behavior.
- Source-grounded prompt safeguards. Explain why the example prompt names its context sources, tells the agent to stop when a source fails or is ambiguous, and still leaves the result for a human to check.
- Curated MCP access. Explain why an agent should receive only the integrations and capabilities its task needs, and describe how a team can manage approved servers.
- MCP governance layers. Distinguish the roles of registries, proxies, and gateways in discovering, limiting, and governing MCP access.
- Limits of MCP standardization. Explain what MCP standardizes and identify the important problems it does not solve.
- Procedures versus tool definitions. Distinguish a tool definition from a skill, and describe the basic contents of a skill folder.
- Progressive skill disclosure. Trace when a skill's description, instruction body, and referenced files enter the agent's context, and explain why the description needs careful wording.
- Skill versus MCP context cost. Compare what an MCP server and a skill advertise on each request, and explain the resulting context-cost trade-off.
- Plugins as team distribution. Distinguish a plugin from an individual skill and explain how plugins make a team's agent setup transferable.
- Context window capacity and limits. Explain that a context window is the amount of data a model can process at once, and describe how larger windows can theoretically fit much more material without eliminating context-related problems.
- Effective versus advertised context. Explain why a model’s advertised context window is not a reliable budget for a prompt, and describe the accuracy and operating costs of filling it.
- Lost in the middle effect. Describe how a critical detail’s position in a long prompt affects retrieval, and illustrate the consequence with the user-data endpoint example.
- Automation of context engineering. Explain that AI coding tools reduce manual work in context engineering rather than replacing context engineering itself.
- Manual control of retrieved context. Apply manual context controls when an assistant repeatedly retrieves the wrong material: pin files, mention a directory, exclude paths, or start a clean session.
- Embedding-based RAG retrieval flow. Trace how RAG indexes codebase chunks as embeddings, matches a developer query against that index, and adds the retrieved chunks to the prompt before the LLM responds. Explain why using a relevant slice avoids overloading the context window.
- Agentic search versus indexed retrieval. Distinguish agentic repository search from embedding-based retrieval and describe their trade-off: live, reference-following reads cost more time and tokens, while fast indexed retrieval can return stale or poorly bounded chunks. State that agentic search does not guarantee complete coverage and that embedding-based RAG remains useful for external knowledge.
- Retrieval versus task continuity. Distinguish finding information relevant to the current request from retaining decisions across a long task. Explain how a limited, increasingly crowded context window can make an agent repeat errors or contradict earlier choices.
- Execution plan as context anchor. Describe how a maintained to-do list can act as an external memory and guide for an agent. Explain both why bringing the plan back into context helped preserve focus and why forced reminders could become restrictive.
- Compaction and durable instructions. Explain the trade-off in compacting a long conversation and why important project rules should live in reloadable files rather than only in chat history. Distinguish the cross-tool role suggested for AGENTS.md from Claude-specific guidance in CLAUDE.md.
- State externalization pattern. Explain why GSD and Superpowers persist project knowledge outside a conversation and give fresh agents only the context needed for each task.
- GSD task lifecycle. Trace GSD’s Discuss → Plan → Execute workflow from recorded product decisions to small tasks carried out by fresh subagents.
- Superpowers loadable discipline. Describe how Superpowers uses skills and subagents to enforce an engineering process rather than merely supply domain facts.
- Context Fabric pyramid. Describe the five layers of the Context Fabric pyramid and explain why foundational system context and captured rationale matter.
- Automated context work and limits. Explain which context-engineering tasks agents take over and why that automation still needs human oversight.
- Project knowledge as infrastructure. Explain why developers must curate the project knowledge an agent retrieves, and why documentation becomes an immediate engineering concern.
- Developer direction and context debugging. Describe the developer's strategic role in directing an agent and correcting context failures.
- Two context corruption failures. Distinguish Conflicting Signals from Poisoning the Context and describe the kind of faulty code each can produce.
- Shift toward context critique. Explain why better retrieval or larger context windows alone cannot solve context corruption, and state the capability the section calls for instead.
- Evolving reasoning trace. Explain how Chain-of-Thought turns a coding request into step-by-step reasoning before an answer or code change, and distinguish that evolving trace from a static context anchor.
- Visible assumptions and auditability. Explain how an explicit plan can expose an agent’s choice between conflicting signals and make AI-generated code easier to review.
- Chain-of-Verification workflow. Trace how the model drafts a baseline answer, creates questions that challenge its assumptions, answers those questions separately from the draft, and uses the checks to decide what answer to deliver.
- Limits of self-grading. Explain why an LLM evaluating its own output may repeat the mistake it made while generating it, and why the quality of what it is graded against matters more than the choice of model.
- Engineering feedback infrastructure. Describe the feedback channels that help agents detect bad changes, and explain why they require the same engineering care as a productive human-development environment.
- Reasoning versus direct recognition. Explain how the emulator debugging example illustrates the limits of elaborate agent reasoning and the value of a simple prompt when an answer is already well documented. Describe the judgment needed to choose between retrieval, reasoning, and checking the model's answer.
What it builds on
- Testing (chapter 2) · The role of tests in checking code changes.
Section by section
Introduction
The introduction explains why agents often fail because of the context they receive, distinguishes context engineering from prompt engineering, and defines a shared Context Fabric.
- Recognizable context failure modes: Explain why an agent can produce the wrong result because of the context it receives, and name the four forms of context failure described here.
Why it matters: Recognizing a context failure helps you address what the agent was given rather than treating every wrong result as a model failure. - Context versus prompt engineering: Distinguish context engineering from prompt engineering by describing what each focuses on and what information context engineering considers.
Why it matters: A well-worded request cannot compensate for an information environment that leaves the agent without what it needs. - Shared Context Fabric: Describe what a Context Fabric is and why a project needs one when agents do not automatically see its full context.
Why it matters: A shared project context helps agents work from more than whichever files happen to be visible.
Key terms: context failure, context vacuum, context rot, poisoning, lost in the middle, prompt engineering, context engineering, context, Context Fabric, agent-consumable context
3.1 Vibe Coding traps: garbage in, garbage out
The section uses a vague login-fix request to show how missing context leads to unreliable AI-generated code and why developers remain responsible for supplying relevant information.
- Context Determines Code Quality: Explain why asking an AI to fix a bug without concrete project and bug details is likely to produce an unsuitable answer, and why the developer must supply context even if the model asks clarifying questions.
Why it matters: A useful fix starts with enough information about the real problem, not just a request for the AI to solve it. - Missing Context Failure Modes: Distinguish the kinds of faulty code the section says a context-starved model may produce, including semantic errors, incomplete implementations, and invented project elements.
Why it matters: A plausible-looking answer can still break requirements, leave work undone, or refer to code that does not exist.
Key terms: context, garbage in, garbage out, clarifying questions, logical and semantic errors, incomplete code, hallucinations, invariants
3.2 Context vacuum: first potential mistake
This section explains how sharing code without its project context can lead an AI agent to make confident but unsuitable changes, while noting when a narrow context is useful.
- Context vacuum failure: Explain how an isolated code snippet can leave a model guessing about project dependencies and produce plausible but incorrect changes. Describe the authentication example's security and consistency failures.
Why it matters: Code that looks plausible in isolation can be insecure or incompatible with the actual project. - Deliberate focused context: Distinguish useful work on a self-contained snippet from sharing an isolated snippet by default despite dependencies on the rest of the project.
Why it matters: The point is to choose context deliberately, not to paste the entire project for every task. - Agent context blindness: Distinguish an agent's context blindness from a human developer's awareness of missing information, and explain why automatic retrieval reduces but cannot eliminate the vacuum.
Why it matters: Automatic context gathering does not make an agent aware of every convention or dependency it has missed.
Key terms: Context Vacuum, invisible dependencies, hallucinate, focused context, context-ignorant, context-blind, automated context retrieval
3.2.1 From a single-shot to multi-shot examples
The section shows why adding files to a coding prompt is not enough: useful context needs relevant examples and clear labels for each fragment’s role.
- Limits of More Code: Explain why supplying the full auth class and its dependencies still leaves the model without information it needs, and why pasting more files has limits.
Why it matters: It explains why a bigger paste is not necessarily a better prompt. - Multishot and Multifile References: Distinguish multishot examples from multifile context, and explain what Bob's additional project files are meant to provide.
Why it matters: Relevant project examples can show the model conventions that the target file alone cannot reveal. - Framed and Curated Context: Explain why pasted fragments need to be selected, annotated, and identified by their roles in the system.
Why it matters: Clear framing helps the model use project examples as a coherent picture rather than misread disconnected snippets.
Key terms: dependencies, dependency graph, multishot, multifile, reference points, context engineering, curating examples, annotating, framing
3.2.2 Good multishot prompt vs bad multishot prompt
This section shows why labeled, explained code examples give an LLM more useful context than the same snippets presented without structure.
- Framed multishot code examples: Explain how labeling and briefly explaining each code snippet helps an LLM interpret its role and generate code that follows a codebase’s conventions, whereas unlabeled snippets leave it guessing.
Why it matters: A few words of framing can prevent an incorrect assumption that would otherwise require review and correction.
Key terms: multishot prompt, context engineering, Service Layer Example, Domain Model Example, Error Handling Example
3.2.3 Let the model do the gap analysis
The section shows how to ask an AI model for a prioritized list of missing context before it writes code, while recognizing the limits of that gap analysis and using it as part of a short exchange.
- Pre-fix gap analysis: Explain why asking the model what it needs to see before writing a fix can reduce unsupported assumptions, and describe the instruction to request its top three missing items without generating code yet.
Why it matters: A question about missing context can prevent the model from silently inventing details in a fix. - Limits of visible gaps: Describe why the gap list should be ranked and capped, and distinguish gaps the model can infer from context from ones it cannot see.
Why it matters: The model's questions are useful leads, not proof that all relevant context has been found. - Two-way prompt refinement: Describe how a short exchange can replace a single hand-built prompt: give the model rough notes and constraints, then ask it to restructure the prompt and identify what is missing.
Why it matters: A brief back-and-forth can make context preparation less laborious than trying to perfect the first prompt alone.
Key terms: gap analysis, unknowns, hallucinations, context vacuum, User schema, rate limiter, rough notes, constraints, proper prompt, short exchange
3.3 Building context together with LLMs
The section explains why manually assembling context for complex coding tasks is slow and risky, why the right amount of context is hard to judge, and why connected tools are needed.
- Manual context assembly risks: Explain why a large, manually assembled multi-source prompt can still lead an LLM to generate faulty code.
Why it matters: A prompt can look comprehensive while still giving the model a misleading picture of the system. - Uncertain context quantity: Describe why deciding how much context to provide is difficult and how the section proposes probing for gaps.
Why it matters: More context is not automatically better; asking about gaps can help avoid a habitual guess. - Connected sources of truth: Justify the shift from hand-curated prompts toward tools that connect an LLM to relevant sources of truth.
Why it matters: Direct access to relevant sources addresses both the pace and fragility of copying context by hand.
Key terms: multi-shot, multi-entity context, poisons the context, gap-analysis prompt, minimalists, maximalists, automated tooling, sources of truth, live data, lineage
3.3.1 Using Model Context Protocol to instrument LLMs
This section explains how MCP gives AI agents a standard way to access external tools and data, and why its architecture and newer features make those integrations practical.
- Standardized external tool access: Explain why MCP is used instead of building a separate integration for every database, API, or service.
Why it matters: A common interface lets an agent work with many integrations without each one requiring a bespoke connection. - MCP client server roles: Describe where the MCP client and servers sit and how they let an agent invoke tools across different data sources.
Why it matters: The client-server split explains how one agent can use tools backed by different systems. - Enterprise readiness features: State which additions to MCP the section identifies as helping make it viable in enterprise environments.
Why it matters: These additions show that a common tool interface also needs features for safer and more practical use.
Key terms: Model Context Protocol, MCP, JSON-RPC, universal interface, MCP client, MCP server, tools, OAuth 2.1, tool annotations, readOnlyHint
3.3.2 Building context for a UI component with MCPs
Shows how an MCP-enabled agent gathers design, codebase, and API context for a UI component, while distinguishing retrieved design tokens from a live design-system connection.
- MCP-assisted component context gathering: Trace how Bob delegates context gathering for UserProfileCard: the agent retrieves design details from Figma, inspects BaseCard and repository conventions, and checks the current API schema before implementing the component.
Why it matters: The component can be grounded in the actual design, existing code, and current API contract rather than the model's guesses. - Design token update boundary: Distinguish what retrieving Figma variables through MCP accomplishes from what keeps a generated component's token values current after generation.
Why it matters: It prevents teams from mistaking accurate token references in generated code for automatic design-system synchronization.
Key terms: MCP, Figma Dev Mode, BaseCard, API response schema, design tokens, Figma variables, CSS custom properties, token export step, snapshot
3.3.3 Accessing external knowledge through MCPs
The section shows how MCP lets an agent discover and document a new library needed for a component, while leaving the developer responsible for checking the choice and its fit.
- External library research workflow: Trace how an agent can use MCP when a requested file picker has no existing implementation or usage pattern in the repository: discover candidate packages, select one, retrieve version-specific documentation, and integrate it using those examples.
Why it matters: This gives an agent a stronger basis for using a library the project has never used before. - Limits of retrieved documentation: Explain why retrieving library documentation improves the agent's basis for integration without guaranteeing that its answer or library choice is right. Distinguish an official API description from evidence of how the API behaves with the project's build, dependencies, and type system.
Why it matters: Retrieved documentation is useful evidence, not a substitute for judging whether a library works in your project.
Key terms: MCP, library research MCP, Context7 MCP, UserProfileCard, documentation server, official API contract
3.3.4 Deep integration with Language Server Protocol
The section shows how MCP access to an LSP server adds compiler-level context to an agent’s work, then uses a component prompt to show why source checks and explicit failure handling matter.
- Compiler-level project context: Explain how connecting an agent to an LSP server through MCP gives it the compiler’s view of a project rather than only raw files, and distinguish that build-time view from runtime or deployment behavior.
Why it matters: It helps you use compiler-backed facts without mistaking them for facts about production. - Verifiable coding references: Describe how compiler-level semantics can make coding prompts more specific and checkable.
Why it matters: Concrete references make an agent’s choices easier to reproduce and review. - Source-grounded prompt safeguards: Explain why the example prompt names its context sources, tells the agent to stop when a source fails or is ambiguous, and still leaves the result for a human to check.
Why it matters: An explicit stop rule makes missing evidence visible before a confident-looking guess reaches review.
Key terms: Language Server Protocol, MCP, build-time truth, runtime truth, ClassPath, referenceable prompts, fully qualified type names, artifact versions, definition paths, Assumptions
3.3.5 MCP governance
This section explains how to govern MCP integrations so agents can reach live information without being overwhelmed by tools, wasting context, or gaining unsafe access.
- Curated MCP access: Explain why an agent should receive only the integrations and capabilities its task needs, and describe how a team can manage approved servers.
Why it matters: A smaller, approved set of capabilities gives the agent useful access without making every connection a source of noise or risk. - MCP governance layers: Distinguish the roles of registries, proxies, and gateways in discovering, limiting, and governing MCP access.
Why it matters: These layers address different problems, so discovering a server or hiding tool definitions must not be mistaken for securing its use. - Limits of MCP standardization: Explain what MCP standardizes and identify the important problems it does not solve.
Why it matters: A standardized connection does not by itself make an agent's information trustworthy, well chosen, visible, or secure. - Task-sized capability exposure: Describe why full tool exposure is costly and compare the section's three alternatives for giving an agent access to capabilities.
Why it matters: The agent can reach live sources without paying to display every possible tool and intermediate result on each request.
Key terms: MCP servers, production dependencies, team-approved allowlist, deterministic context assembly, MCP registries, MCP Proxies, MCP Gateways, discovery and invocation, tool annotations, readOnlyHint
3.3.6 Agentic skills: procedure as loadable context
This section explains how agent skills load team-specific procedures only when needed, and how plugins package those procedures into a reusable team context fabric.
- Procedures versus tool definitions: Distinguish a tool definition from a skill, and describe the basic contents of a skill folder.
Why it matters: The distinction lets a team give agents its working conventions without treating those conventions as tool capabilities. - Progressive skill disclosure: Trace when a skill's description, instruction body, and referenced files enter the agent's context, and explain why the description needs careful wording.
Why it matters: Progressive disclosure makes many procedures available without loading all their instructions into every request. - Scripts for exact checks: Explain why a skill can put checks with exact answers in scripts rather than prose instructions.
Why it matters: A script can make an exact check repeatable while keeping its implementation out of the context window. - Skill versus MCP context cost: Compare what an MCP server and a skill advertise on each request, and explain the resulting context-cost trade-off.
Why it matters: The comparison helps a team avoid paying context costs for capabilities an agent is not using. - Portable skills and installation risk: Describe why team skills are not tied to one agent product, and state the installation risks and safeguards given here.
Why it matters: Portability makes skills useful across tools, but easy installation must not bypass dependency review. - Plugins as team distribution: Distinguish a plugin from an individual skill and explain how plugins make a team's agent setup transferable.
Why it matters: A versioned plugin turns one person's carefully assembled agent context into a repeatable team setup.
Key terms: tool description, Agent Skills, SKILL.md, YAML frontmatter, progressive disclosure, frontmatter, description field, Markdown body, references, scripts
3.4 Context rot: is too much context a bad thing?
This section defines the context window, illustrates how much it has grown, and cautions that larger windows still have drawbacks.
- Context window capacity and limits: Explain that a context window is the amount of data a model can process at once, and describe how larger windows can theoretically fit much more material without eliminating context-related problems.
Why it matters: A larger input capacity changes what you can submit at once, but it is not a promise that more context is always better.
Key terms: context window, tokens, 1M-token modes
3.4.1 “Lost in the middle” problem
This section explains why large context windows can reduce an AI coding agent’s accuracy, especially when a critical instruction is buried in the middle of a long prompt.
- Effective versus advertised context: Explain why a model’s advertised context window is not a reliable budget for a prompt, and describe the accuracy and operating costs of filling it.
Why it matters: Fitting a whole project into a prompt does not mean the agent can use it accurately or economically. - Lost in the middle effect: Describe how a critical detail’s position in a long prompt affects retrieval, and illustrate the consequence with the user-data endpoint example.
Why it matters: An instruction can be in the prompt and still fail to shape the agent’s answer.
Key terms: advertised context window, effective context window, context rot, lost in the middle, U-shaped performance curve
3.4.2 Manual reordering: "Sandwich" Method
3.5 Using AI coding tools to manage context
AI coding tools can automate tedious parts of context engineering without replacing the need to manage context.
- Automation of context engineering: Explain that AI coding tools reduce manual work in context engineering rather than replacing context engineering itself.
Why it matters: It sets the right expectation: a coding assistant can help manage context, but it does not make context engineering unnecessary.
Key terms: AI coding tools, context engineering
3.5.1 Automated retrieval: from RAG to agentic search
Explains how coding assistants select repository context, how developers can correct poor retrieval, and why agentic search is increasingly used alongside or instead of embedding-based RAG.
- Manual control of retrieved context: Apply manual context controls when an assistant repeatedly retrieves the wrong material: pin files, mention a directory, exclude paths, or start a clean session.
Why it matters: You can correct unhelpful context without waiting for the retrieval system to infer what you meant. - Embedding-based RAG retrieval flow: Trace how RAG indexes codebase chunks as embeddings, matches a developer query against that index, and adds the retrieved chunks to the prompt before the LLM responds. Explain why using a relevant slice avoids overloading the context window.
Why it matters: This flow explains both the usefulness of automatic context selection and where a bad selection can enter the answer. - Agentic search versus indexed retrieval: Distinguish agentic repository search from embedding-based retrieval and describe their trade-off: live, reference-following reads cost more time and tokens, while fast indexed retrieval can return stale or poorly bounded chunks. State that agentic search does not guarantee complete coverage and that embedding-based RAG remains useful for external knowledge.
Why it matters: Knowing the trade-off helps you judge whether automatically supplied context is timely, complete, and worth its cost.
Key terms: pinning specific files, @-mentioning a directory, ignore file, clean session, Retrieval-Augmented Generation (RAG), chunks, embeddings, similarity search, augmentation, agentic search
3.5.2 Context anchor: todo list for LLM
This section explains why retrieval alone cannot preserve an agent’s focus across a long coding task and how plans, durable instructions, compaction, and subagents address different forms of context loss.
- Retrieval versus task continuity: Distinguish finding information relevant to the current request from retaining decisions across a long task. Explain how a limited, increasingly crowded context window can make an agent repeat errors or contradict earlier choices.
Why it matters: A good search result cannot by itself stop an agent from forgetting a decision made earlier in the task. - Execution plan as context anchor: Describe how a maintained to-do list can act as an external memory and guide for an agent. Explain both why bringing the plan back into context helped preserve focus and why forced reminders could become restrictive.
Why it matters: A plan can keep long-running work oriented, provided the agent can still revise it. - Compaction and durable instructions: Explain the trade-off in compacting a long conversation and why important project rules should live in reloadable files rather than only in chat history. Distinguish the cross-tool role suggested for AGENTS.md from Claude-specific guidance in CLAUDE.md.
Why it matters: Rules that prevent bugs need a more durable home than a conversation summary that might omit them. - Subagent context isolation: Describe how a subagent’s separate context window keeps task-specific exploration out of the parent conversation. Distinguish preventing context bloat this way from compacting an already bloated history.
Why it matters: Isolating exploratory work can preserve the main agent’s context before it needs compression.
Key terms: RAG, amnesiac coder, sliding window of tokens, context rot, Context Anchor, Focus Engineering, to-do tool, execution plan, Context Compaction, lossy summarization
3.5.3 Beyond compaction: meta-prompting and state externalization
This section explains how meta-prompting frameworks counter context rot by storing project knowledge outside conversations, giving fresh agents focused context, and enforcing engineering workflows.
- State externalization pattern: Explain why GSD and Superpowers persist project knowledge outside a conversation and give fresh agents only the context needed for each task.
Why it matters: It changes context management from preserving one long chat to making project knowledge available across fresh sessions. - GSD task lifecycle: Trace GSD’s Discuss → Plan → Execute workflow from recorded product decisions to small tasks carried out by fresh subagents.
Why it matters: Explicit decisions and self-contained tasks let work continue without depending on a previous agent’s chat history. - GSD verification and commits: Explain how GSD attaches checks to requirements before coding, verifies output against the plan, and uses per-task commits to locate regressions.
Why it matters: Early checks and narrow commits make failures easier to detect and investigate. - Superpowers loadable discipline: Describe how Superpowers uses skills and subagents to enforce an engineering process rather than merely supply domain facts.
Why it matters: The framework makes engineering discipline available and enforceable when an agent needs it. - Context Fabric pyramid: Describe the five layers of the Context Fabric pyramid and explain why foundational system context and captured rationale matter.
Why it matters: A richer fabric helps agents act on the system’s architecture and intent, not just the code they can read. - Orchestration cost trade-off: Justify when externalized, multi-agent workflows are worth their overhead and explain the unreliability tax from missing context.
Why it matters: The cheapest-looking workflow may cost more if poor context causes repeated failed attempts.
Key terms: state externalization, context window, Context Fabric, GSD, Discuss → Plan → Execute → Verify, CONTEXT.md, .planning/, Nyquist validation layer, git bisect, Verify phase
3.5.4 …can I be lousy again if I’m using coding AI?
Coding agents automate much of the work of assembling context, but developers remain responsible for the quality, direction, and correction of that context.
- Automated context work and limits: Explain which context-engineering tasks agents take over and why that automation still needs human oversight.
Why it matters: Automation saves prompt-assembly work, but it does not guarantee that the agent is working with the right context. - Project knowledge as infrastructure: Explain why developers must curate the project knowledge an agent retrieves, and why documentation becomes an immediate engineering concern.
Why it matters: The material available to an agent affects both the quality and the cost of its work. - Developer direction and context debugging: Describe the developer's strategic role in directing an agent and correcting context failures.
Why it matters: An agent can search effectively yet pursue the wrong task or rely on the wrong source unless the developer steers it. - Persistent agent identity: Describe what the developer defines in an Agent Manifest and its role as persistent context.
Why it matters: The developer can set enduring guidance rather than repeating the same expectations in each task prompt.
Key terms: Automated Retrieval, Automated Reordering, Memory Management, compaction, Garbage In, Garbage Out, knowledge base, context poisoning, Context Fabric, navigator, context failure
3.6 Context through reasoning
This section explains why aging codebases can corrupt an AI agent’s context and why reliable coding requires the agent to critique that context, not merely consume more of it.
- Codebase aging and inconsistency: Explain how both failure to change and ongoing change can leave a codebase inconsistent, making its context less reliable for AI agents.
Why it matters: A codebase can supply misleading context even when nobody has deliberately written bad instructions. - Two context corruption failures: Distinguish Conflicting Signals from Poisoning the Context and describe the kind of faulty code each can produce.
Why it matters: These failure modes explain why giving an agent more repository material does not necessarily improve its code. - Shift toward context critique: Explain why better retrieval or larger context windows alone cannot solve context corruption, and state the capability the section calls for instead.
Why it matters: Recognizing bad context is a different challenge from finding or fitting enough context.
Key terms: Software Aging, entropy, pockets of inconsistency, Conflicting Signals, Poisoning the Context, context vacuum, context overload, context corruption, critique
3.6.1 Chain-of-Thought: forcing the LLM to “show its work”
This section explains how stepwise reasoning and visible plans help AI coding agents handle complex tasks while giving developers a chance to inspect their assumptions before code is written.
- Evolving reasoning trace: Explain how Chain-of-Thought turns a coding request into step-by-step reasoning before an answer or code change, and distinguish that evolving trace from a static context anchor.
Why it matters: A visible, adaptable plan makes a complex coding request easier to reason through than a direct leap to code. - Modern reasoning controls: Describe how the developer’s role changes when a model has built-in reasoning, and state why the section still treats Chain-of-Thought as a useful mental model.
Why it matters: It helps you apply the section’s advice without assuming every model needs the same prompting trick. - Visible assumptions and auditability: Explain how an explicit plan can expose an agent’s choice between conflicting signals and make AI-generated code easier to review.
Why it matters: Seeing why an agent chose a path can reveal a bad assumption sooner than inspecting an unexplained block of code. - Plan and Act workflow: Trace the Plan and Act rhythm illustrated by Cline, including opportunities to validate or revise the approach and the option to use different models for planning and execution.
Why it matters: Separating planning from action creates points to check direction and lets teams match a model to each kind of work.
Key terms: Chain-of-Thought, Context Anchoring, reasoning trace, intermediate steps, frontier models, reasoning effort, thinking budgets, visible trace, conflicting signals, auditability
3.6.2 Chain-of-Verification: internal fact-checking loop
This section explains how Chain-of-Verification challenges an agent’s first answer so that a plausible but mistaken line of reasoning does not become the final result.
- Chain-of-Verification workflow: Trace how the model drafts a baseline answer, creates questions that challenge its assumptions, answers those questions separately from the draft, and uses the checks to decide what answer to deliver.
Why it matters: A structured first answer can still rest on a false assumption, so the agent needs a way to challenge it. - Poisoned context and grounded checks: Explain how CoVe can expose an outdated or unsafe retrieved example, using the section’s SQL example, and why its checks need grounding in objective outcomes.
Why it matters: Checking an agent’s assumptions can prevent an old code example from being carried into new code.
Key terms: Chain-of-Verification, CoVe, baseline answer, verification questions, falsification, context poisoning, prepared statements, parameterized queries, objective outcomes
3.6.3 How to introduce self correction?
This section explains why AI self-correction needs an independently checkable specification and strong engineering feedback loops, not just another pass by the model.
- Limits of self-grading: Explain why an LLM evaluating its own output may repeat the mistake it made while generating it, and why the quality of what it is graded against matters more than the choice of model.
Why it matters: A confident self-review is not reliable evidence that the generated work meets the requirement. - Engineering feedback infrastructure: Describe the feedback channels that help agents detect bad changes, and explain why they require the same engineering care as a productive human-development environment.
Why it matters: Dependable AI assistance rests on maintained engineering feedback, not on reasoning features alone.
Key terms: LLM-as-a-Judge, machine-checkable specification, self-correction, feedback loops, meaningful assertions, continuous integration, ADRs
3.6.4 Is reasoning always THE solution?
A debugging anecdote shows that elaborate AI reasoning is not always the best route to an answer, and that engineers must judge when to use it.
- Reasoning versus direct recognition: Explain how the emulator debugging example illustrates the limits of elaborate agent reasoning and the value of a simple prompt when an answer is already well documented. Describe the judgment needed to choose between retrieval, reasoning, and checking the model's answer.
Why it matters: More reasoning can cost time and tokens without improving an answer that the model can recognize directly.
Key terms: Minus World glitch, reasoning chains, verification loops, retrieval
3.7 Summary
Where this is used later
- The uncomfortable truth about this book (chapter 10) · The earlier treatment of context for individual developers.
- Agent handoff: passing context between agents (chapter 5) · Addresses passing context between agents.
- Token economics 101 (chapter 9) · The problem of supplying useful context rather than leaving the model without what it needs.
- When NOT to optimize (chapter 9) · The earlier discussion of building context for AI work.
- (chapter intro) (chapter 10) · Assumes the value of supplying context to LLMs.
- MCP vs. CLI, the hidden context tax (chapter 9) · Provides the tool-definition and token-cost concern behind MCP's context tax.
- From .cursorrules to AGENTS.md (chapter 5) · Team workflow instructions build on the distinction between available tools and the conventions for using them.
- Standardizing team workflows with agents (chapter 5) · Standardizing team workflows with agents depends on making procedures and integrations shareable.
Concepts explained in this chapter
- context windowThe finite amount of input information a language model can consider during a single inference or conversation state.
- MCPMCP is a protocol standard that lets AI agents discover and invoke external tools and services through a uniform interface.
- subagentA subagent is a specialized AI assistant that independently performs a delegated task with its own context, prompt, tools, and permissions.
- information retrievalRetrieval is the process of selecting relevant information from an indexed or accessible knowledge source.
- context rotContext rot is the degradation of an AI agent's performance as an overloaded or stale conversation context accumulates irrelevant or conflicting information.
- context poisoningContext poisoning is the inclusion of misleading, outdated, unsafe, or otherwise harmful information in model context that biases an AI system toward incorrect output.
- SKILL.mdA skill file is a loadable instruction artifact that defines a reusable process or discipline for an AI agent to follow.
- Context FabricContext Fabric is a persistent layer of specifications, conventions, documentation, and structured knowledge surrounding a software project that supplies agents with project-specific working context.
- lost in the middleLost in the middle is a long-context failure pattern in which a language model retrieves information near the beginning or end more reliably than information placed in the middle.
- compactionAutomatic context compaction is the automatic summarization of an AI conversation's accumulated history to reduce retained context.
- context engineeringContext engineering is the discipline of designing, selecting, structuring, and maintaining the information supplied to an AI system so it can perform tasks effectively.
- retrieval-augmented generationRetrieval-augmented generation is a technique that retrieves relevant external information and supplies it as context for a language model's generated response.
- MCP serverAn MCP server is a service that exposes structured, executable tools and data-access capabilities through the Model Context Protocol.
- context failureA context problem is a deficiency or mismatch in the information supplied to an AI model for a task.
- GSDGSD is a spec-driven AI-agent development workflow that externalizes project information and coordinates task-oriented agents.
- SuperpowersSuperpowers is an AI-agent development framework that supplies selectively loaded skill files to enforce engineering processes.
- meta-prompting frameworkA meta-prompting framework is a structured system that manages prompts, agent workflows, and persistent task information around an AI model.
- state externalizationState externalization is an agent-workflow pattern that persists project information outside ephemeral conversation sessions in durable artifacts such as files.
- subagent architectureSubagent orchestration is the coordination of specialized AI agents that independently perform parts of a larger workflow.
- context anchoringA context-management pattern that preserves an AI agent's focus by maintaining stable objectives or task information.
- agent skillAn Agent Skill is a directory-based format for packaging procedural instructions and optional supporting resources as loadable context for an AI agent.
- documentationSoftware documentation is written reference material describing a software product's installation, interfaces, behavior, design, or usage.
- conflicting contextA conflicting signal is a context failure in which instructions or guidance are contradictory, ambiguous, or inconsistently presented.
- AGENTS.mdAGENTS.md is a tool-agnostic convention for a repository-root Markdown file that supplies project context and instructions to AI agents.
- CLAUDE.mdCLAUDE.md is a Claude Code project instruction file containing persistent guidance that is loaded for agent sessions.
- amnesiac coder issueThe amnesiac coder issue is an AI-agent failure mode in which the agent loses prior task decisions, interactions, and code context over a long task.
- to-do listA to-do list is an ordered collection of tasks, often annotated with completion status and priority.
- pluginAn agentic plugin is a versioned distributable package that bundles AI-agent skills with workflow integrations and configuration.
- progressive disclosureProgressive disclosure is a technique that reveals information in successive levels only when it becomes relevant or requested.
- shell scriptA shell script is a text file containing commands interpreted and executed by an operating-system command shell.
- chain-of-thought promptingChain-of-thought prompting is a technique in which a language model generates intermediate reasoning steps before producing its final answer.
- accuracyCorrectness is the degree to which software behavior satisfies its intended specification and real-world requirements.
- language server protocolLanguage Server Protocol is a JSON-RPC-based standard through which editors and development tools obtain language-aware services from language servers.
- AI agentAn AI agent is a software system that uses artificial intelligence to autonomously or semi-autonomously perform tasks on behalf of a user or application.
- many-shot promptingMultishot is a prompting technique that provides multiple examples of similar patterns so a language model can generalize from them.
- promptA prompt is an input instruction or request supplied to an AI model to elicit a response or action.
- CLI-first approachA CLI-first approach gives an AI agent command-line interfaces for applicable operations instead of protocol-specific tool schemas.
- MCP gatewayAn MCP gateway is a centralized control plane between AI agents and MCP servers that governs access and monitors requests.
- code executionCode execution is an approach in which an AI agent writes and runs a program against an API to perform multiple data operations in one execution.
- deterministic context assemblyDeterministic context assembly is the repeatable selection and preparation of task-relevant context before an AI agent begins work.
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.
