Chapter 4: Writing Lean code
The introduction frames Lean coding as preventing unnecessary work by deciding what code is needed and keeping it easy to understand, change, or delete.
After this chapter you will be able to
- Lean code quality. Explain why writing Lean code is not simply writing fewer lines or letting AI write the code. Describe the qualities the introduction values instead.
- Judgment before implementation. Explain how the introduction’s examples show waste entering a codebase before its costs become obvious.
- Source of truth and waste. Explain what a source of truth is and how treating an artifact as authoritative affects decisions, completion, and where waste appears.
- Explicit specification as constraint. Explain why the section proposes an explicit specification to define intent before code exists and what it is meant to constrain.
- Waterfall overproduction and late rework. Explain why the section calls the waterfall approach overproduction from a Lean point of view.
- Upfront documentation as inventory. Describe why the proposed documentation-driven remedy did not solve the problem and what waste it created.
- Tests as pull signals. Explain how TDD defines what works before coding and why the section calls a test a Lean pull signal.
- BDD alignment trade-off. Explain when stakeholder-readable BDD scenarios justify their maintenance costs and when they become overprocessing.
- AI amplification of vague intent. Explain why AI makes vague intent especially risky: its broad capabilities can produce plausible-looking solutions to the wrong problem in seconds.
- Contract before implementation. Describe SDD as defining the contract, including what counts as done, before either a human or AI writes code; relate this to TDD's practice of defining behavior before implementation.
- Spec-first scope boundaries. Explain how writing a spec before implementation acts as a pull signal for an AI-assisted feature, admitting what users need while excluding unrequested additions.
- Explicit export design constraints. Describe how the export spec's privacy and streaming boundaries protect user and technical value, and how its stated requirements simplify review.
- Spec as quality signal. Explain why the spec, rather than the code alone, defines correctness and how a code–spec mismatch should be handled as an Andon moment.
- Code as costly inventory. Explain why the section compares code to inventory and what it costs to keep.
- Design for eventual removal. Justify designing code to be easy to remove when it stops providing value, rather than assuming it must last forever.
- Coupling and deletion cost. Explain why two similar-looking implementations can differ greatly in how safely and quickly they can be deleted, using the caching-layer example.
- Structure matched to lifespan. Distinguish how the section recommends designing short-lived code versus long-lived code, and explain why applying either approach to the wrong lifespan creates waste.
- Actionable software Andon. Explain why detecting a gap between code and intent is insufficient unless the team can safely intervene by disabling, bypassing, or removing the behavior.
- Deletion debt and code judgment. Explain how to assess ease of deletion before shipping and distinguish code to preserve from code to make reversible or discard.
- Lifetime cost of dependencies. Explain why Lean code treats each dependency as a deliberate decision rather than a default, even when adding it is easy.
- User value of dependencies. Explain when a dependency improves what users get and when it merely moves code outside the repository without changing their experience.
- Business value over time. Explain why faster delivery can justify a dependency initially but may not remain a good trade-off as maintenance costs accumulate.
- Dependency surface area. Explain how importing a library for one needed function can expand attack, maintenance, and cognitive surfaces through unused features and transitive dependencies.
- Convenience versus lasting surface area. Justify when writing a small function yourself is preferable to importing a library, and when a library provides enough value to warrant its surface area.
- Hidden Understanding and Cognitive Debt. Explain how AI-generated code can create cognitive debt and a cascade of unexamined assumptions.
- Nondeterministic Pattern Fragmentation. Trace how AI's variable implementations can fragment a codebase and increase maintenance costs even when each feature works.
- Standard Work Constrains AI. Explain how a shared coding standard constrains AI output and promotes consistency across features.
- AI-driven dependency spread. Trace how one accepted AI suggestion to use styled-components becomes a repeated pattern and creates costs beyond the original component.
- Standard work as filter. Explain how standard work prevents locally useful AI-generated code from creating waste across the project.
- Dependency evaluation checks. Apply the section's value, surface-area, and reversibility checks to an AI-suggested dependency, and explain when written justification is needed.
- Purpose of coding standard work. Explain that standard work is the documented best-known way to perform routine coding tasks, not bureaucracy, and describe how defining expectations before building or constraining dependencies puts it into practice.
- Decision to write a spec. Distinguish changes that warrant a spec from those that do not: substantial or ambiguous work, multiple possible approaches, or work others will review or maintain versus trivial fixes, mechanical changes, or early exploration.
- Clear behavioral spec boundaries. Explain how to judge whether a spec is precise enough: different developers or AI runs should produce functionally identical implementations because behavior, constraints, and boundaries are explicit, without prescribing incidental implementation details.
- Documented coding patterns. Describe how a team's standard work document guides choices about error handling, logging, validation, file structure, testing, and naming, and why it should link to real code.
- Reasoned exceptions to standards. Explain when departing from a coding standard is warranted, why the reason should be documented, and what repeated exceptions indicate.
- Objective merge decisions. Apply the spec, documented team standards, and waste checks to decide whether a PR should merge. Distinguish merge blockers from subjective suggestions.
- Review signals for Kaizen. Explain how code review reveals gaps between team standards and actual coding work, and how recurring findings should change the standards or coding checklist.
- Unconstrained webhook coding baseline. Describe how to generate and record the first version: ask AI for a payment webhook function that validates the signature, parses the event, and updates a subscription, then add no guidance or constraints. Save the output, count its lines, and note dependencies and imports without judging it yet.
- Plausible code expansion. Explain why the generated result can be concerning even when it looks professional: a requested webhook handler may expand into a larger event-processing architecture. Describe its size as a possible signal of waste in auto-generated code, not proof that every line is waste.
- Independent behavioral specification. Describe how to write the spec without looking at generated code: state valid inputs, required outputs and success behavior, forbidden outcomes, and failure behavior. Use the payment webhook example to illustrate these categories.
- Behavior versus architecture boundary. Distinguish required behavior from optional implementation choices, and explain when an architectural or tooling choice must nevertheless be stated as a constraint. Describe how the spec limits AI-generated complexity without prescribing details that do not matter.
- Spec-based waste comparison. Describe how to compare the generated and spec-based code line by line, marking additions the spec does not call for and looking for overproduction and other TIMWOODS wastes.
- Spec bounded code deletion. Explain how to refactor the handler to implement only what its spec requires, removing extra fields, libraries, abstractions, and speculative behavior rather than keeping them just in case.
- Deletion informed spec refinement. Describe how findings from deleting code should refine the spec—clarifying missing cases, ambiguities, constraints, and things never to add—before another round of code generation.
- Three value lenses. Apply user, business, and technical value lenses to compare the original bloated code with the refined version, including the effects of deleted code.
- Spec refinement through deletion. Explain how a clear spec limits unnecessary AI-generated code and how deleting code exposes gaps that can improve the spec.
What it builds on
- The unconstrained prompt (chapter 3) · The earlier example of an unconstrained AI prompt producing waste.
- The eight wastes in software development (chapter 2) · The idea of identifying different forms of waste in software development.
- Overproduction (chapter 2) · The Lean waste of overproduction.
- Inventory (chapter 2) · Inventory as a form of waste.
- Loop 2: The Lean lens (chapter 1) · The Lean lens for distinguishing work triggered by need from speculative work.
- Types of value in software (chapter 2) · The distinction among user, business, and technical value.
- Overprocessing (chapter 2) · Overprocessing as work that adds steps without sufficient value.
- User value (chapter 2) · Connects a feature's boundaries to user value.
Section by section
Introduction
The introduction frames Lean coding as preventing unnecessary work by deciding what code is needed and keeping it easy to understand, change, or delete.
- Lean code quality: Explain why writing Lean code is not simply writing fewer lines or letting AI write the code. Describe the qualities the introduction values instead.
Why it matters: This gives you a way to judge whether code earns its place in the system. - Judgment before implementation: Explain how the introduction’s examples show waste entering a codebase before its costs become obvious.
Why it matters: Catching unnecessary work before it enters the system can avoid later rework and risk.
Key terms: Lean code, deliberate reduction, intent, overproduction, dependencies, judgment
4.1 From code to spec: The evolution of defining intent
This section explains how a team’s chosen source of truth shapes its work and waste, and why explicit specifications can define intent before code is generated.
- Source of truth and waste: Explain what a source of truth is and how treating an artifact as authoritative affects decisions, completion, and where waste appears.
Why it matters: Naming what the team trusts helps reveal why its particular delays or defects arise. - Method shifts and tradeoffs: Describe how different approaches target different forms of waste without simply replacing earlier approaches.
Why it matters: A method is more useful when chosen for the problem it addresses than when followed as a ritual. - Explicit specification as constraint: Explain why the section proposes an explicit specification to define intent before code exists and what it is meant to constrain.
Why it matters: Stating intent before generation helps prevent unexamined assumptions and unnecessary work from becoming code.
Key terms: source of truth, authoritative, waste profile, TDD, BDD, SDD, waste, explicit specifications, specification, AI generation
4.1.1 The waterfall era: Code is truth
The section uses the waterfall era to show why code became the only reliable account of a system and why building everything—or documenting everything—up front created Lean waste.
- Code as the only reality: Explain why code, rather than requirements or design documents, was treated as the source of truth in the described waterfall approach.
Why it matters: It explains why written intent did not reliably describe the finished software. - Waterfall overproduction and late rework: Explain why the section calls the waterfall approach overproduction from a Lean point of view.
Why it matters: The cost comes from committing to a large amount of work before checking its value or correctness. - Upfront documentation as inventory: Describe why the proposed documentation-driven remedy did not solve the problem and what waste it created.
Why it matters: Writing more specifications is not automatically an improvement if the documents delay work or go unused.
Key terms: code was the truth, requirements, design, testing, overproduction, delayed customer feedback, rework, Documentation Driven Development (DDD), waiting, inventory
4.1.2 Evolving to shift the source of truth
The section compares ways to define correctness before implementation and uses a Lean lens to judge when their benefits justify their overhead.
- Tests as pull signals: Explain how TDD defines what works before coding and why the section calls a test a Lean pull signal.
Why it matters: A test can guide both correctness and how much code to write. - TDD value and limits: Distinguish the technical and user value attributed to TDD from its difficulty demonstrating business value.
Why it matters: Working software can still miss the reason stakeholders needed it. - BDD alignment trade-off: Explain when stakeholder-readable BDD scenarios justify their maintenance costs and when they become overprocessing.
Why it matters: Stakeholder review can be worth extra ceremony, but ceremony without that review adds waste. - Evidence for interface contracts: Explain the intended flexibility of Interface Oriented Design and why speculative interfaces count as inventory.
Why it matters: A useful extension point and an unused one can look identical until you ask what need justified it. - Earlier definitions and overhead: Describe the common aim and trade-off across the other approaches named in the section.
Why it matters: Defining intent earlier helps only if the chosen method solves more problems than it creates.
Key terms: Test-Driven Development (TDD), pull signal, done, technical value, user value, business value alignment, regressions, Behavior Driven Development (BDD), Gherkin, translation overhead
4.1.3 The AI era: Specs become explicit
AI can produce plausible code for the wrong problem very quickly, making it important to define the intended contract before implementation begins.
- AI amplification of vague intent: Explain why AI makes vague intent especially risky: its broad capabilities can produce plausible-looking solutions to the wrong problem in seconds.
Why it matters: Fast, convincing output is not evidence that the right problem was solved. - Contract before implementation: Describe SDD as defining the contract, including what counts as done, before either a human or AI writes code; relate this to TDD's practice of defining behavior before implementation.
Why it matters: An explicit definition of done gives implementation a target before code is produced.
Key terms: AI, intent, plausible solutions, Spec Driven Development (SDD), TDD, contract, done
4.1.4 Spec first: Define before you build
Shows how a spec written before coding constrains AI-generated work, protects value, and makes mismatches between intent and implementation visible early.
- Spec-first scope boundaries: Explain how writing a spec before implementation acts as a pull signal for an AI-assisted feature, admitting what users need while excluding unrequested additions.
Why it matters: Defining the boundary first helps you avoid maintaining code for features nobody has asked for. - Explicit export design constraints: Describe how the export spec's privacy and streaming boundaries protect user and technical value, and how its stated requirements simplify review.
Why it matters: A short requirement can expose a privacy or scalability risk before it becomes a production defect. - Spec as quality signal: Explain why the spec, rather than the code alone, defines correctness and how a code–spec mismatch should be handled as an Andon moment.
Why it matters: Spotting drift at the point of work lets the team correct it before the mismatch spreads.
Key terms: spec, pull signal, overproduction, server-side streaming, bounded batches, cursor, user privacy, source of truth, quality gate, Andon moment
4.2 Design for deletion
The section treats code as inventory with ongoing costs and argues for making it easy to remove, especially as AI makes code faster to generate.
- Code as costly inventory: Explain why the section compares code to inventory and what it costs to keep.
Why it matters: The cost of code continues after it is written. - Design for eventual removal: Justify designing code to be easy to remove when it stops providing value, rather than assuming it must last forever.
Why it matters: Making removal easier prevents code that no longer helps from remaining a burden. - AI amplified code inventory: Explain why rapid AI code generation makes the cost of keeping code, and the ability to delete it, more important.
Why it matters: Generating code faster can increase the amount the team must maintain.
Key terms: inventory, carrying costs, obsolescence, design for deletion, value, AI, cost of having code, deletion
4.2.1 Making code deletable
This section shows how coupling and expected lifespan should shape code so it can be removed safely without creating unnecessary structure.
- Coupling and deletion cost: Explain why two similar-looking implementations can differ greatly in how safely and quickly they can be deleted, using the caching-layer example.
Why it matters: Keeping an experiment isolated can make reversing it a small, safe change rather than a project. - Structure matched to lifespan: Distinguish how the section recommends designing short-lived code versus long-lived code, and explain why applying either approach to the wrong lifespan creates waste.
Why it matters: Proportional structure avoids both overbuilding an experiment and underbuilding a foundational capability. - Contextual lifespan signals: Describe how to judge whether code is likely to be short- or long-lived when its future is uncertain, and apply the section’s disappearance-cost question.
Why it matters: Context and removal cost are more useful design guides than calling every urgent request strategic.
Key terms: coupling, deletability, design input, speed and reversibility, change and understanding, proportional structure, longevity, design for deletion, design for endurance
4.2.2 Designing for intervention: Enabling the software Andon
The section explains how making behavior safe to disable or remove turns an Andon signal into a practical way to protect software quality.
- Actionable software Andon: Explain why detecting a gap between code and intent is insufficient unless the team can safely intervene by disabling, bypassing, or removing the behavior.
Why it matters: Finding a problem protects quality only if the team can act on it safely. - Intervention signals and learning: Describe the kinds of signals that call for intervention and how being able to stop behavior supports observation and learning.
Why it matters: An off switch makes it possible to learn from concerning behavior instead of leaving it running by default. - Deletion debt and code judgment: Explain how to assess ease of deletion before shipping and distinguish code to preserve from code to make reversible or discard.
Why it matters: Judging what must endure and what must be reversible keeps the team in control of future changes.
Key terms: Andon signal, pull the cord, designing for deletion, Andon moment, Gemba, Kaizen, off switch, deletion debt, ease of deletion, foundational
4.3 Managing dependencies and their hidden costs
The section weighs the immediate benefits of reusing libraries against the lifetime costs of accumulating dependencies.
- Benefits of library reuse: Explain why using existing, well-tested libraries has often been a Lean choice for software teams.
Why it matters: The section questions automatic reuse without dismissing the real value reuse provides. - Lifetime cost of dependencies: Explain why Lean code treats each dependency as a deliberate decision rather than a default, even when adding it is easy.
Why it matters: A dependency that saves work now can create maintenance and risk long after it is added.
Key terms: dependencies, well-tested libraries, domain-specific value, inventory, transitive dependencies, lifetime cost, AI-assisted development
4.3.1 The value of dependencies
This section evaluates dependencies through user, business, and technical value while accounting for inventory and maintenance costs.
- User value of dependencies: Explain when a dependency improves what users get and when it merely moves code outside the repository without changing their experience.
Why it matters: It helps you judge a dependency by its effect on users rather than by the fact that it saves you code. - Business value over time: Explain why faster delivery can justify a dependency initially but may not remain a good trade-off as maintenance costs accumulate.
Why it matters: It keeps a short-term shipping gain from obscuring the cost of maintaining the dependency later. - Technical value and hidden cost: Describe what technical value asks of a dependency and why an apparent improvement is not the whole assessment.
Why it matters: It prompts you to weigh an apparent code-quality improvement against a cost the section flags for further examination.
Key terms: user value, inventory, dependencies, business value, initial velocity gain, ongoing maintenance cost, foundational dependencies, technical value, surface area
4.3.2 Surface area
This section explains how dependencies expand a system’s exposure and how to weigh that lasting cost against the value of using a library.
- Dependency surface area: Explain how importing a library for one needed function can expand attack, maintenance, and cognitive surfaces through unused features and transitive dependencies.
Why it matters: The cost of a dependency can extend well beyond the function you use today. - Convenience versus lasting surface area: Justify when writing a small function yourself is preferable to importing a library, and when a library provides enough value to warrant its surface area.
Why it matters: Choosing a dependency means comparing its immediate convenience with both its lasting costs and the expertise it provides.
Key terms: surface area, attack surface, transitive dependencies, CVE, auditable code, cryptography, parsing, protocols
4.3.3 AI as a dependency
This section treats AI as a development dependency whose hidden costs grow when generated code is poorly understood or lacks shared standards.
- AI Dependency Value Tradeoffs: Explain why AI counts as a development dependency and distinguish its user, business, and technical value.
Why it matters: Delivery speed alone does not tell you whether AI has improved the software. - Hidden Understanding and Cognitive Debt: Explain how AI-generated code can create cognitive debt and a cascade of unexamined assumptions.
Why it matters: Code that appears familiar can conceal decisions the team will have to investigate when it fails. - Nondeterministic Pattern Fragmentation: Trace how AI's variable implementations can fragment a codebase and increase maintenance costs even when each feature works.
Why it matters: A collection of working features can still become expensive to understand and change. - Standard Work Constrains AI: Explain how a shared coding standard constrains AI output and promotes consistency across features.
Why it matters: A shared standard lets teams use AI without allowing every prompt to introduce another coding convention.
Key terms: dependency, User Value, Business Value, Technical Value, cognitive attack surface, cognitive debt, dependency cascade, transitive assumptions, non-deterministic, probabilistic generation
4.3.4 AI as a dependency generator
Shows how an AI-suggested library can spread into architectural lock-in, and how standard work can filter dependency choices before they create waste.
- AI-driven dependency spread: Trace how one accepted AI suggestion to use styled-components becomes a repeated pattern and creates costs beyond the original component.
Why it matters: A choice that looks reasonable for one component can become expensive when it sets an unintended precedent. - Standard work as filter: Explain how standard work prevents locally useful AI-generated code from creating waste across the project.
Why it matters: Standards help prevent waste before an AI-generated choice spreads through the codebase. - Dependency evaluation checks: Apply the section's value, surface-area, and reversibility checks to an AI-suggested dependency, and explain when written justification is needed.
Why it matters: Evaluating value, cost, and reversibility makes a dependency decision deliberate rather than automatic.
Key terms: external dependency, styled-components, architectural lock-in, stylistic dependency, standard work, local optimization, global waste, value check, surface area check, reversibility check
4.4 Standard work for coding
This section defines standard work for coding and shows how it reduces friction and creates consistency.
- Purpose of coding standard work: Explain that standard work is the documented best-known way to perform routine coding tasks, not bureaucracy, and describe how defining expectations before building or constraining dependencies puts it into practice.
Why it matters: Explicit standards help a team make routine coding decisions consistently without treating the standards as paperwork for its own sake.
Key terms: standard work, TDD, SDD, dependencies
4.4.1 To spec or not?
This section explains when to write a spec before coding and how to make it precise enough to prevent assumption-driven variation.
- Decision to write a spec: Distinguish changes that warrant a spec from those that do not: substantial or ambiguous work, multiple possible approaches, or work others will review or maintain versus trivial fixes, mechanical changes, or early exploration.
Why it matters: Choosing when to specify keeps clarification focused where it can prevent wasted work. - Minimum specification requirements: Describe the minimum requirements a spec should establish: valid inputs, required outputs, forbidden behavior, dependencies prohibited unless justified, and existing code patterns to follow.
Why it matters: Explicit requirements give implementers a shared target rather than leaving important choices to assumptions. - Clear behavioral spec boundaries: Explain how to judge whether a spec is precise enough: different developers or AI runs should produce functionally identical implementations because behavior, constraints, and boundaries are explicit, without prescribing incidental implementation details.
Why it matters: A clear boundary helps different implementers build the intended behavior without needless variation.
Key terms: spec, valid input, valid output, never statements, dependencies, existing patterns, clear boundary, functionally identical implementations, assumptions, variation
4.4.2 Writing code
This section explains how to use a team's coding standards to make consistent choices while documenting justified exceptions.
- Documented coding patterns: Describe how a team's standard work document guides choices about error handling, logging, validation, file structure, testing, and naming, and why it should link to real code.
Why it matters: Shared, concrete standards reduce avoidable inconsistency during coding. - Reasoned exceptions to standards: Explain when departing from a coding standard is warranted, why the reason should be documented, and what repeated exceptions indicate.
Why it matters: Explaining exceptions preserves judgment without leaving teammates to guess why the code differs.
Key terms: standard work doc, dependency cascade problem, standard, deviation, conscious trade-off, rationale
4.4.3 The code review
This section shows how Lean code review uses documented criteria to stop waste before merge and uses recurring review findings to improve team standards.
- Objective merge decisions: Apply the spec, documented team standards, and waste checks to decide whether a PR should merge. Distinguish merge blockers from subjective suggestions.
Why it matters: Consistent review catches costly waste before it reaches production without holding up a PR over personal taste. - Review signals for Kaizen: Explain how code review reveals gaps between team standards and actual coding work, and how recurring findings should change the standards or coding checklist.
Why it matters: Review findings can improve the team's way of working instead of causing the same discussion on every PR.
Key terms: spec, standard work, merge blockers, overproduction, coupling, deletable, Gemba, Kaizen, standards, checklist
4.5 Exercise: From vibe coding to Lean coding
Introduces an exercise comparing AI-generated code from a casual prompt with code constrained to the actual need.
4.5.1 Start with vibe coding
This exercise creates an unconstrained AI-generated webhook handler so the reader can observe how a plausible solution grows beyond the request.
- Unconstrained webhook coding baseline: Describe how to generate and record the first version: ask AI for a payment webhook function that validates the signature, parses the event, and updates a subscription, then add no guidance or constraints. Save the output, count its lines, and note dependencies and imports without judging it yet.
Why it matters: Keeping the first output unchanged gives you something concrete to examine later. - Plausible code expansion: Explain why the generated result can be concerning even when it looks professional: a requested webhook handler may expand into a larger event-processing architecture. Describe its size as a possible signal of waste in auto-generated code, not proof that every line is waste.
Why it matters: A polished-looking result can hide unnecessary scope that deserves scrutiny.
Key terms: vibe coding, dependencies, imports, event processing architecture, waste, code smell
4.5.2 Write the spec
This section shows how to write a minimal behavioral spec independently of AI-generated code, while making genuine constraints explicit.
- Independent behavioral specification: Describe how to write the spec without looking at generated code: state valid inputs, required outputs and success behavior, forbidden outcomes, and failure behavior. Use the payment webhook example to illustrate these categories.
Why it matters: Writing requirements independently makes it easier to spot gaps instead of accepting whatever the generated code happens to do. - Behavior versus architecture boundary: Distinguish required behavior from optional implementation choices, and explain when an architectural or tooling choice must nevertheless be stated as a constraint. Describe how the spec limits AI-generated complexity without prescribing details that do not matter.
Why it matters: Clear boundaries prevent AI from guessing important constraints or adding unnecessary implementation complexity.
Key terms: spec, Input, Behavior, Never, Errors, architecture, implementation details, constraints, Dependencies
4.5.3 Compare and contrast
This exercise compares AI-generated webhook code with spec-based code to identify unnecessary features, hidden assumptions, premature optimizations, and dependencies before changing anything.
- Spec-based waste comparison: Describe how to compare the generated and spec-based code line by line, marking additions the spec does not call for and looking for overproduction and other TIMWOODS wastes.
Why it matters: Comparing against the spec makes unnecessary work visible before you decide what to remove. - Unrequested implementation choices: Explain how to spot hidden assumptions and premature optimization in the generated code by checking choices against the spec and the team's standards.
Why it matters: Unexamined implementation choices can add complexity without serving the requested behavior. - Dependency and abstraction scrutiny: Describe how to count added packages, question whether each is needed, and record concrete cases where a simpler function or a few lines of code would suffice.
Why it matters: Naming specific avoidable dependencies and abstractions makes the cost of extra complexity easier to see.
Key terms: spec-based code, overproduction, TIMWOODS, hidden assumptions, premature optimization, dependency count, packages, dependency injection, repository pattern
4.5.4 Delete everything not in the spec
This exercise uses the spec to strip unnecessary code from a payment webhook handler, then updates the spec with what the deletion revealed before generating code again.
- Spec bounded code deletion: Explain how to refactor the handler to implement only what its spec requires, removing extra fields, libraries, abstractions, and speculative behavior rather than keeping them just in case.
Why it matters: A spec-bound deletion pass exposes code that adds maintenance cost without serving the feature. - Deletion informed spec refinement: Describe how findings from deleting code should refine the spec—clarifying missing cases, ambiguities, constraints, and things never to add—before another round of code generation.
Why it matters: Updating the spec turns what the deletion pass revealed into clearer guidance for the next implementation.
Key terms: spec, waste, queues, refined spec, Constraints, Never:
4.5.5 Reflect
This exercise uses a comparison of bloated and refined code to reveal waste, improve a spec, and identify where team standards need to be clearer.
- Three value lenses: Apply user, business, and technical value lenses to compare the original bloated code with the refined version, including the effects of deleted code.
Why it matters: The three lenses help you distinguish code that delivers value from code that merely adds work. - Rapid and plausible AI waste: Explain why a casual AI prompt can produce waste quickly and why that waste may be difficult to recognize at first.
Why it matters: Plausible-looking code needs scrutiny because AI can add it faster than you can assess its value. - Spec refinement through deletion: Explain how a clear spec limits unnecessary AI-generated code and how deleting code exposes gaps that can improve the spec.
Why it matters: Deletion is not just cleanup: it helps make the next spec more grounded in what the work actually requires. - Documented team coding standards: Describe how unfamiliar AI-invented patterns can reveal missing or unclear team standards and how documented standards help reject them.
Why it matters: Documented standards make it easier to prevent inconsistent AI-generated patterns from entering the codebase.
Key terms: User Value, Business Value, Technical Value, casual prompt, bloated code, waste, spec, boundaries, deletion process, refined spec
4.6 Summary
Where this is used later
- Tests as design constraints (chapter 5) · Tests as design constraints builds on the idea that tests can define expectations before implementation.
- Value-add versus wasteful testing (chapter 5) · Judging testing value depends on distinguishing technical assurance from the value a feature is meant to deliver.
- YAGNI as a Lean design principle (chapter 7) · YAGNI as a Lean design principle revisits the cost of building for an unproven future need.
- Andon for production systems (chapter 12) · Extends the idea of an Andon signal and the ability to stop when quality is at risk.
- When signals lose meaning (chapter 5) · The idea of an Andon signal that prompts intervention.
- Measurement for learning versus ranking (chapter 9) · The idea of making problems visible through a software andon signal.
- Building quality in (chapter 11) · The idea of making software failures visible and enabling intervention.
- What Kaizen actually means (chapter 10) · Revisits Kaizen as continuous learning and improvement.
Concepts explained in this chapter
- specificationA specification is a documented statement of required software behavior, constraints, or qualities.
- dependencyA software component or package that another component requires to build or operate.
- standard workA single prescribed method applied across teams regardless of differences in their work contexts.
- overproduction wasteLean waste caused by producing more, earlier, or sooner than demand requires.
- AI-generated codeSource code produced by an artificial-intelligence system from supplied inputs or instructions.
- standardA standard is an agreed rule or specification that expresses intended behavior or practice.
- wasteWork that creates no customer value and can be eliminated without harming delivery or its outcomes.
- behavior-driven developmentA development practice that specifies and tests software behavior in a form intended to be readable by both technical and non-technical stakeholders.
- interface-oriented designA software-design approach that organizes components around explicit interfaces separated from their implementations.
- test-driven developmentA development practice in which failing tests are written before implementation and then used to guide code until the tests pass.
- cognitive attack surfaceThe set of ways that AI-generated or AI-mediated information can introduce uncertainty, inconsistency, or harmful influence into human reasoning and software decisions.
- source of truthThe artifact or signal that a team treats as authoritative for determining correctness, completion, and resolving disagreements.
- couplingA dependency relationship in which one software component relies on another component's structure, behavior, or availability.
- code reviewThe practice of examining proposed source-code changes for correctness, design, and maintainability.
- artificial intelligenceArtificial intelligence is the field of computational methods that perform tasks associated with human perception, reasoning, learning, or goal-directed action.
- cognitive debtAccumulated difficulty caused by code and design decisions that developers do not fully understand or own.
- nondeterminismThe property of behavior that can produce different outcomes for the same input because of probabilistic processes or varying execution conditions.
- pattern fragmentationThe divergence of implementation patterns across features that should follow a consistent architectural or coding approach.
- ai coding assistantA software tool that uses artificial intelligence to help generate, transform, explain, or review code.
- continuous improvementA feedback loop is a process in which information about outcomes is returned to influence subsequent decisions or actions.
- GembaThe actual place where work occurs and value is created, viewed in Lean management as the location for direct observation.
- merge blockerA review criterion or condition that prevents a proposed code change from being merged until the issue is resolved.
- pull modelA Lean principle in which work is started in response to readiness or actual demand rather than being pushed into the system prematurely.
- Andon cordA cord that a worker pulls to signal an abnormality and prompt immediate attention or correction.
- quality gateA quality gate is a defined verification point that determines whether work satisfies specified quality conditions before proceeding.
- server streamingServer-side streaming is the incremental transmission of generated data from a server to a client rather than buffering the complete result.
- surface areaThe set of interfaces, behaviors, integration points, and change obligations exposed by a software component or dependency.
- AndonA visual management system that signals abnormal conditions so work can be stopped or corrected.
- abstractionA software-design technique that hides implementation details behind a simplified model or interface.
- contractAn application programming interface is a defined set of operations and rules through which software components interact.
- business valueBusiness value is the organizational benefit produced when software reliably supports business outcomes such as reduced support demand and lower operating cost.
- technical valueBenefit that software work provides to the maintainability, safety, operability, or evolvability of a technical system.
- valueThe benefit users receive from software that meets their needs through usable, reliable behavior.
- system boundaryA boundary is a separation between system parts, representations, ownership areas, or organizational responsibilities across which information or work passes.
- constraintA condition or limitation that restricts how work can proceed within a delivery system.
- intentThe desired outcome, requirements, and rationale that guide software implementation.
- lean principleA management and process-improvement philosophy focused on maximizing customer value, reducing waste, improving flow, and learning continuously.
- flow protectionAn upstream quality-control technique that prevents defects, variability, and waste from entering a software delivery flow.
- inventoryInventory is the waste of work items, information, or decisions that have been started or accumulated but are not yet needed downstream.
- code generationThe production of source code from a specification, model, template, or other structured input.
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.
