Chapter 1: Introduction to Intent-Driven Development
The chapter introduces why coding agents make intent articulation more important and defines Intent-Driven Development as a way to guide their work.
After this chapter you will be able to
- The intent articulation bottleneck. Explain why faster, more autonomous coding agents shift the bottleneck from writing code to articulating the intent that guides their work, especially during continued development.
- Intent-Driven Development approach. Describe Intent-Driven Development as translating implicit human intent into consistent, usable language and systems for agents, with intent at the center of the context that guides implementation.
- Durable intent artifacts. Explain how specifications and tests capture shared human–AI intent and serve as a source of truth for generating or regenerating implementations.
- Unstated intent in requirements. Explain how the password-reset prompt can be implemented as written yet fail its purpose if the goal is recovery from a potentially compromised account.
- Explicit intent over model inference. Justify articulating intent rather than relying on a more capable model or execution system to infer what a request leaves unsaid.
- Purpose Made Actionable. Explain how intent turns a broader purpose into a concrete approach while keeping the reason for that approach explicit. Distinguish the purpose of helping users regain access to potentially compromised accounts from the approach of building a password reset workflow.
- Purpose Guiding Downstream Decisions. Describe how explicitly stating account recovery as the purpose can guide technical design, verification, and user experience, rather than leaving an agent to assume that changing the password is sufficient.
- Intent versus vague directions. Distinguish intent from an intuition, an idea, or a broad objective using the account-security examples. Explain why none of those, by itself, tells a teammate or coding agent what specific change to make.
- Actionable intent articulation. Explain how intent articulation turns vague ideas, objectives, and unstated assumptions into something concrete enough to guide people and agents.
- One-way instruction limitations. Explain why a requirements document or a direct agent instruction can fail to establish shared understanding, and why a successful result from an unexamined prompt may be luck rather than reliable alignment.
- Plan review and interview limits. Describe how reviewing an agent's plan exposes its interpretation before coding, and why asking it to interview you can surface further considerations without removing the need for initial intent.
- Focused interview seed. Explain how stating both the intended change and its purpose focuses an agent interview, using the compromised-account password reset example.
- BDD as shared dialogue. Explain why BDD scenarios are valuable as shared artifacts of conversation between business and technology, rather than merely requirements translated into Gherkin.
- Tests before implementation. Explain how writing a unit test first makes a system rule visible and verifiable before implementation, and why tests written afterward may instead preserve a mistaken implementation.
- Human practices and durable specifications. Describe what these earlier practices have in common and how Spec-Driven Development uses specifications within Intent-Driven Development.
- Context Limits and Durable Decisions. Explain how context-window limits and compaction can cause an agent to lose important constraints, and why IDD preserves those decisions in artifacts that can be loaded into later sessions.
- Discovery and Verifiable Intent. Trace how structured discovery becomes durable specifications or tests that state capabilities and provide a way to judge completion.
- Progressive Context for Independent Execution. Explain how IDD organizes intent artifacts and other information so an agent can find relevant context as needed and execute without constant human guidance.
- Intent and execution layers. Describe how the intent harness sits above the execution harness and turns human ideas into context for implementation.
- Durable artifacts as control. Explain why the intent harness produces durable artifacts and how those artifacts relate to the code.
- Specification dialogue and artifacts. Describe how spec-driven development structures human–AI dialogue around what to build, how to build it, and actionable tasks, producing durable specifications before implementation begins.
- Constraint-guided iteration and learning. Trace how an autonomous iteration workflow uses a success constraint to guide repeated execution and carries learning from unsuccessful attempts into later iterations.
- Specification and loop fit. Distinguish when to use a specification versus a governing loop, and explain how they can complement one another.
- Intent articulation bottleneck. Explain why a human-centric workflow can tolerate some poorly articulated intent but struggles when coding agents produce implementations faster.
- Agent review bottleneck. Trace the dilemma created when coding agents shift engineers from writing code to reviewing it, and explain why the section points upstream to intent articulation.
- Correction of incomplete intent. Describe why a misaligned implementation should prompt a team to find and clarify the missing intent in its dialogue, specification, or acceptance tests rather than only fix the code.
- Regeneration versus code patching. Justify discarding and regenerating a faulty agent-produced implementation from revised intent instead of preserving it through patches.
- Time horizon and investment tradeoff. Distinguish when vibe coding may be preferable from when Intent-Driven Development is better suited, including the ongoing investment IDD requires.
- Collaborative adoption and Specfall. Explain why IDD adoption must extend beyond individual developer tooling and what goes wrong in Specfall.
- Exercise toolchain requirements. Describe the practical setup for the exercises: access to an agentic coding tool, Git and a free GitHub account, plus comfort with CLI workflows and a text editor.
Section by section
Introduction
The chapter introduces why coding agents make intent articulation more important and defines Intent-Driven Development as a way to guide their work.
- The intent articulation bottleneck: Explain why faster, more autonomous coding agents shift the bottleneck from writing code to articulating the intent that guides their work, especially during continued development.
Why it matters: It explains why faster code generation alone does not solve the challenge of ongoing development. - Intent-Driven Development approach: Describe Intent-Driven Development as translating implicit human intent into consistent, usable language and systems for agents, with intent at the center of the context that guides implementation.
Why it matters: It identifies what must guide an agent if independent implementation is to match what people intended.
Key terms: coding agents, intent articulation, intended outcomes, Intent-Driven Development, implicit human intent, effective context
1.1 Understanding intent
This section explains why IDD preserves articulated intent in durable artifacts that can outlast any one implementation.
- Durable intent artifacts: Explain how specifications and tests capture shared human–AI intent and serve as a source of truth for generating or regenerating implementations.
Why it matters: A durable statement of what you wanted can guide a new implementation even when the old code is no longer suitable. - Regeneration instead of code translation: Explain why returning to the original intent is more direct than adapting an existing platform-specific implementation in the log-deletion example.
Why it matters: The example shows why a clear statement of intent can outlast the platform-specific code it produces.
Key terms: IDD, shared intent, durable artifacts, specifications, tests, source of truth, intent, translation loss, original prompt, implementation
1.1.1 Stating requirements without making intent explicit
Shows how a coding agent can satisfy stated requirements yet miss the intended outcome when important context remains unstated, and argues for making that intent explicit.
- Unstated intent in requirements: Explain how the password-reset prompt can be implemented as written yet fail its purpose if the goal is recovery from a potentially compromised account.
Why it matters: Meeting the words of a request is not necessarily the same as achieving its purpose. - Implicit knowledge transfer gap: Trace the parallel between a product owner's ticket and an engineer's coding-agent prompt, identifying who holds the missing context and why the implementer does not receive it.
Why it matters: Recognizing who holds the missing context helps explain why a competent implementer can still deliver the wrong outcome. - Explicit intent over model inference: Justify articulating intent rather than relying on a more capable model or execution system to infer what a request leaves unsaid.
Why it matters: Making the purpose explicit is more dependable than hoping an agent guesses the context behind a request.
Key terms: requirements, underlying intent, interpretation gap, session invalidation, implicit-knowledge holder, coding agent, model capability, model training, intent articulation
1.1.2 What is “Intent”?
Defines intent as an actionable expression of purpose and shows how making that purpose explicit guides decisions about a feature.
- Purpose Made Actionable: Explain how intent turns a broader purpose into a concrete approach while keeping the reason for that approach explicit. Distinguish the purpose of helping users regain access to potentially compromised accounts from the approach of building a password reset workflow.
Why it matters: A request that names only the feature can leave its real purpose open to interpretation. - Purpose Guiding Downstream Decisions: Describe how explicitly stating account recovery as the purpose can guide technical design, verification, and user experience, rather than leaving an agent to assume that changing the password is sufficient.
Why it matters: Keeping the purpose visible helps prevent a plausible implementation from missing the outcome users need.
Key terms: intent, purpose, intent articulation, downstream decision, verification criteria, active sessions, intent surfacing
1.1.3 What "Intent" is not?
This section distinguishes intent from vague feelings, possible ideas, and broad objectives, and places intent within the wider context needed to achieve an outcome.
- Intent versus vague directions: Distinguish intent from an intuition, an idea, or a broad objective using the account-security examples. Explain why none of those, by itself, tells a teammate or coding agent what specific change to make.
Why it matters: A plausible direction is not yet clear enough for someone else to act on. - Intent within wider context: Explain that intent is one part of context, not the whole of it, and that it helps determine which other information is relevant to the intended outcome.
Why it matters: A clear intent helps focus the supporting information without being mistaken for all of that information.
Key terms: intent, intuition, ideas, objective, context, intended outcome
1.1.4 Intent articulation for AI
This section explains why AI coding needs explicit, conversational intent articulation, and why even agent interviews need a focused starting point.
- Actionable intent articulation: Explain how intent articulation turns vague ideas, objectives, and unstated assumptions into something concrete enough to guide people and agents.
Why it matters: An agent needs more than a request if it is to act on what you actually mean. - One-way instruction limitations: Explain why a requirements document or a direct agent instruction can fail to establish shared understanding, and why a successful result from an unexamined prompt may be luck rather than reliable alignment.
Why it matters: A seemingly clear instruction can still hide a mismatch until after the agent has acted. - Plan review and interview limits: Describe how reviewing an agent's plan exposes its interpretation before coding, and why asking it to interview you can surface further considerations without removing the need for initial intent.
Why it matters: Earlier conversation helps reveal interpretation, but it cannot compensate for having no starting direction. - Focused interview seed: Explain how stating both the intended change and its purpose focuses an agent interview, using the compromised-account password reset example.
Why it matters: A focused seed helps the agent ask about consequences of the change you actually intend to make. - Limits of ad hoc articulation: Describe why the section treats ad hoc intent-articulation interactions as more manageable for prototypes than for sophisticated applications maintained over years.
Why it matters: The scale and duration of the work change how much an improvised conversation can carry.
Key terms: intent articulation, intent, requirements document, shared understanding, vibe coding, assumptions, outcome alignment, plan mode, initial prompt, interview
1.2 Intent articulation before AI coding
The section shows how user stories, BDD, and TDD made intent explicit before AI coding, and how Spec-Driven Development builds on that practice.
- User stories and acceptance criteria: Explain how a user story expresses a person's need and purpose, and how acceptance criteria add concrete, verifiable facets of that intent.
Why it matters: Stating the user's purpose and checkable outcomes helps keep important intent from being lost between people. - BDD as shared dialogue: Explain why BDD scenarios are valuable as shared artifacts of conversation between business and technology, rather than merely requirements translated into Gherkin.
Why it matters: A formatted scenario cannot substitute for the shared understanding created while people work out what it should mean. - Tests before implementation: Explain how writing a unit test first makes a system rule visible and verifiable before implementation, and why tests written afterward may instead preserve a mistaken implementation.
Why it matters: A test can guide implementation toward intent only if that intent is made explicit before the code establishes the behavior. - Human practices and durable specifications: Describe what these earlier practices have in common and how Spec-Driven Development uses specifications within Intent-Driven Development.
Why it matters: Spec-driven work builds on established ways to expose intent rather than replacing the need for shared, verifiable understanding.
Key terms: user stories, so that, acceptance criteria, intent, Behavior-Driven Development, BDD, Gherkin, shared understanding, shared artifacts, Test-Driven Development
1.3 How intent-driven development works
The section explains how intent-driven development turns structured dialogue into durable intent and organized context so an agent can execute independently despite context-window limits.
- Context Limits and Durable Decisions: Explain how context-window limits and compaction can cause an agent to lose important constraints, and why IDD preserves those decisions in artifacts that can be loaded into later sessions.
Why it matters: Preserving decisions outside the conversation prevents a later agent session from silently dropping a critical constraint. - Discovery and Verifiable Intent: Trace how structured discovery becomes durable specifications or tests that state capabilities and provide a way to judge completion.
Why it matters: An agent can work toward and check a stated outcome when the team's decisions are captured beyond the discovery conversation. - Progressive Context for Independent Execution: Explain how IDD organizes intent artifacts and other information so an agent can find relevant context as needed and execute without constant human guidance.
Why it matters: Giving the agent a way to find the right information at the right time supports progress without repeatedly asking a human for direction.
Key terms: context window, compaction, durable artifacts, intent articulation, structured dialogue, discovery, durable intent artifacts, verifiable intent, context engineering, hierarchy of information
1.4 Harnessing intent
This section explains how an intent harness turns ideas into durable artifacts that guide an execution harness to produce aligned software.
- Harness and execution roles: Explain what a harness contributes to an agent and why a harness focused on carrying out tasks is called an execution harness.
Why it matters: Separating the model from its harness makes it easier to see what enables an agent to do useful work. - Intent and execution layers: Describe how the intent harness sits above the execution harness and turns human ideas into context for implementation.
Why it matters: The distinction shows why getting the context right is a separate responsibility from generating code. - Durable artifacts as control: Explain why the intent harness produces durable artifacts and how those artifacts relate to the code.
Why it matters: Persistent intent gives a team a source of guidance that is not confined to one agent session or one version of the code. - Tool capability boundaries: Explain why a tool should be assessed for both intent-harness and execution-harness capabilities rather than by its packaging.
Why it matters: A tool that executes well may still leave intent articulation unsupported.
Key terms: agent, model, harness, execution harness, intent harness, structured dialogue, intent artifacts, context, durable intent artifacts, specifications
1.4.1 Intent articulation mechanisms
This section explains how an intent harness uses specifications or autonomous iteration loops to connect articulated intent with execution, and when each approach fits.
- Specification dialogue and artifacts: Describe how spec-driven development structures human–AI dialogue around what to build, how to build it, and actionable tasks, producing durable specifications before implementation begins.
Why it matters: The specification gives the agent an agreed target to implement rather than relying on an unstructured conversation. - Constraint-guided iteration and learning: Trace how an autonomous iteration workflow uses a success constraint to guide repeated execution and carries learning from unsuccessful attempts into later iterations.
Why it matters: This approach lets execution reveal information that could not have been specified in advance. - Specification and loop fit: Distinguish when to use a specification versus a governing loop, and explain how they can complement one another.
Why it matters: The choice depends on whether the path is knowable beforehand, not on treating specs and loops as competing defaults.
Key terms: Spec-Driven Development, What (Discover), How (Design), Tasks, durable intent artifacts, autonomous iteration workflows, governing constraint, Ralph Loop, learning input, intent harness
1.5 Intent articulation is the new bottleneck
The section explains why poorly articulated intent becomes a bottleneck when coding agents increase the pace of implementation.
- Intent articulation bottleneck: Explain why a human-centric workflow can tolerate some poorly articulated intent but struggles when coding agents produce implementations faster.
Why it matters: Faster implementation makes unclear intent more costly rather than simply making delivery faster.
Key terms: intent articulation, human-centric workflows, misaligned outcomes, coding agents
1.5.1 No mental model of the code
The section explains why agent-generated code can leave engineers without a mental model of their application, turning review into a bottleneck despite faster code generation.
- Application mental model: Explain what a mental model of an application is and how writing and fixing code develops it.
Why it matters: It explains why experience with a particular codebase helps an engineer change it safely. - Agent review bottleneck: Trace the dilemma created when coding agents shift engineers from writing code to reviewing it, and explain why the section points upstream to intent articulation.
Why it matters: Generating code faster does not help much if reviewing it and recovering from defects consume the gains.
Key terms: mental model of the application, coding agents, mental model, review, intent-articulation problem
1.5.2 Fix intent articulation, not the implementation
The section argues that when an agent builds the wrong thing because intent was incomplete, teams should clarify the intent and regenerate the implementation rather than rely on more review or patch the faulty code.
- Limits of same-prompt review: Explain why adding a review agent using the coding agent’s prompt may not catch an omitted requirement, using session invalidation in the password-reset example.
Why it matters: More review cannot reliably recover intent that was never communicated to the agents. - Correction of incomplete intent: Describe why a misaligned implementation should prompt a team to find and clarify the missing intent in its dialogue, specification, or acceptance tests rather than only fix the code.
Why it matters: Correcting what the agent was told can address future instances of a gap, not just the current defect. - Regeneration versus code patching: Justify discarding and regenerating a faulty agent-produced implementation from revised intent instead of preserving it through patches.
Why it matters: Keeping defective code can burden an agent with conflicting guidance instead of saving work.
Key terms: review agent, original intent, session invalidation, incomplete intent articulation, specification, acceptance tests, regenerate, revised intent, context burden, source of truth
1.6 When not to use Intent-Driven Development
This section explains when a quick vibe-coding approach may be preferable to IDD and why effective IDD adoption requires organizational collaboration.
- Time horizon and investment tradeoff: Distinguish when vibe coding may be preferable from when Intent-Driven Development is better suited, including the ongoing investment IDD requires.
Why it matters: The right approach depends on whether the immediate need outweighs the cost of sustaining the software. - Collaborative adoption and Specfall: Explain why IDD adoption must extend beyond individual developer tooling and what goes wrong in Specfall.
Why it matters: Installing a spec tool alone does not create the shared intent that makes IDD valuable.
Key terms: Intent-Driven Development, IDD, Vibe Coding, stakeholders, organizational capability, cultural alignment, Specfall, shared control surfaces
1.7 What do you need for the rest of this book
This section explains the tools and experience needed to complete the book’s exercises, while emphasizing that no particular coding agent or prior SDD practice is required.
- Exercise toolchain requirements: Describe the practical setup for the exercises: access to an agentic coding tool, Git and a free GitHub account, plus comfort with CLI workflows and a text editor.
Why it matters: Having this setup lets you follow and reproduce the exercises. - Flexible starting prerequisites: Explain why readers can start without a prescribed operating system, enterprise setup, prior SDD practice, or advance installation of every chapter-specific tool.
Why it matters: You can begin with your existing development setup and add chapter-specific tools when needed.
Key terms: agentic coding tool, Git, GitHub, CLI, text editor, SDD, coding agent, containerized options
1.8 Summary
The chapter summary connects actionable intent, durable human–AI articulation, and intent-guided agent execution to the bottleneck created by faster code generation.
Where this is used later
- What is a specification (chapter 2) · The discussion of specifications builds on their role as durable records of intent.
- Spec-driven development workflow (chapter 2) · The need to make intent explicit.
- Intent Loss in Surfacing (chapter 3) · Revisits the risk of losing intent when the underlying purpose is not surfaced.
- (chapter intro) (chapter 2) · Articulating intent for AI.
- Characteristics of a good specification (chapter 2) · Articulating intent for AI.
- How does SDD work (chapter 2) · Establishes the specification's control role for the later SDD workflow.
- Tactical vs strategic context engineering (chapter 2) · Develops approaches to engineering context for spec-driven work.
- Control Authority (chapter 3) · Provides the idea of an intent artifact as a control surface.
Concepts explained in this chapter
- intent articulationIntent articulation is the practice of making a feature's underlying purpose explicit and connecting it to the required approach.
- Intent-Driven DevelopmentAn AI-native software engineering approach that translates implicit human intent into consistent language and systems that agents can use to guide software development.
- durable artifactA durable artifact that records articulated intent to guide implementation.
- intentIntent is the actionable expression of purpose for a specific change, concrete enough to guide implementation and verification.
- structured conversationAn interaction structured to elicit missing information and capture software intent in a specification.
- context engineeringContext engineering is the deliberate organization of relevant information so that a participant or system can understand and act on it effectively.
- ai coding assistantAn AI-powered tool that interprets development instructions and performs coding tasks.
- execution harnessAn agent harness specialized for independently carrying out tasks and generating implementations or other work products.
- intent harnessA higher-level harness that helps humans and agents articulate intent and produce durable artifacts that guide execution.
- specification-driven developmentA software development approach in which specifications produced through human–AI dialogue guide implementation.
- vibe codingVibe coding is software development guided primarily by natural-language direction and an informal sense that the generated result matches the developer's intent.
- autonomous actionAn AI agent's ability to complete an implementation task without continuous human intervention.
- compactionThe process of replacing earlier interaction content with a shorter summary when an AI agent approaches its context limit.
- context windowA context window is the bounded amount of information an AI model can consider during one interaction.
- acceptance criteriaA verifiable condition used to determine whether a requirement or feature has been satisfied.
- behavior-driven developmentBehavior-driven development is a software development practice that specifies system behavior collaboratively using examples and shared language.
- test-driven developmentTest-driven development is a software development practice in which an automated test is written before the implementation that makes it pass.
- user storyA user story is a concise requirement expressed from the perspective of a person who needs a capability and its purpose.
- plan modePlan mode is an agent interaction pattern in which an AI agent presents its intended implementation approach before modifying code.
- specfallA dysfunctional adoption pattern in which specifications become documents to produce and circulate instead of shared control surfaces for intended software behavior.
- autonomous iteration workflowAn autonomous iteration workflow is a repeated execution process steered by governing constraints toward learning and convergence.
- contextInformation supplied to an AI coding agent to guide its understanding and work.
- specificationA structured description of software intent, requirements, implementation constraints, and expected outcomes.
- governing constraintA governing constraint is a rule or boundary that directs repeated execution, learning, and convergence in an autonomous workflow.
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.
