# Table of contents

> Every chapter and all 359 sections, read from the manuscript's own contents file.

- **Source:** https://ainativesoftware.engineering/book/toc
- **Site:** AI-Native Software Engineering — https://ainativesoftware.engineering/book

11 chapters and 359 sections, read from the manuscript's own contents file. Front matter is included, so the numbering below is the book's, not this list's.

## Foreword

_No sections listed._

## Chapter 1: The AI-Native Engineer

The shift from implementer to orchestrator, the vibe-coding trap, and what makes an engineer irreplaceable.

- The Vibe-Coding Trap
- Two Engineers, One Task
- What AI-Native Engineering Is Not
- The Role Transformation: From Implementer to Orchestrator
- Why the Traditional Workflow No Longer Scales
- The New Center of Gravity: Intent, Constraints, and Verification
  - Intent
  - Constraints
  - Verification
- Human-in-the-Loop: The Nonnegotiable Checkpoint
- What AI-Native Engineers Actually Do
  - Before the work
  - During the work
  - Throughout
- The New Skill Stack: Eight Skills That Make You Irreplaceable
- The Cost of Not Adapting
- Career Implications: Why Software Engineering Is Becoming a Leadership Role
- Starting Out: How Junior Engineers Grow When AI Writes the Basics
- Summary

## Chapter 2: From LLMs to Agents

How LLMs work from an engineer's-eye view, why they are good at code, and how tools, context, and a loop turn a model into an agent.

- How LLMs Work: An Engineer's-Eye View
  - Tokens
  - The Transformer and attention
  - In-weights knowledge versus in-context knowledge
  - The context window is your working-memory budget
- Why LLMs Are Good at Code
  - Training with verifiable outcomes: RLHF and RLVR
  - Chain-of-thought and reasoning models
- Nondeterminism, Temperature, and Sampling
- The Model Landscape
  - Open source versus closed source
  - Small language models
  - Multimodal models
  - Embeddings and semantic search
- Where LLMs Excel and Where They Fail
- Benchmarks: What They Do and Don't Measure
- The API Layer: How Engineers Talk to LLMs
- What Makes an Agent: LLM, Tools, Context, Loop
  - The LLM: The reasoning core
  - Tools: How agents act on the world
  - Context: Accumulated state
  - The agentic loop: Reason, act, observe, adjust
  - Beyond single agents
- Building an Agent in 50 Lines of Code
  - Stopping conditions and iteration limits
  - Agent frameworks
  - Why this matters for users of coding agents
- The Agent Execution Model: Reason, Act, Observe
  - The self-correction loop: Tests as observations
- Tool Use and Function Calling
  - How function calling works under the hood
- Memory and State
  - In-context memory
  - Long-term memory through files
  - Retrieved memory with RAG
  - Agent-generated memory
  - Context rot
- Agent Economics: Cost, Latency, and Scope
- Human-in-the-Loop
  - HITL as a design principle
  - Feedback as context enrichment
  - The agent decides when it needs you
  - Calibrating HITL to risk
- The AI Tool Landscape
  - IDE-integrated coding assistants
  - CLI and terminal-native agents
  - Cloud and background agents
  - Code review assistants
  - Design and UI generation tools
  - Choosing tools without chasing hype
- Summary

## Chapter 3: Context Engineering Fundamentals

Moving from prompt engineering to assembling the right context at the right time, so AI tools produce consistent outputs, not lucky ones.

- From Prompt Engineering to Context Engineering
- The Core Problem: Right Context, Right Time, Limited Window
  - The attention problem
  - The lost-in-the-middle phenomenon
  - Context rot
  - The human working-memory parallel
  - The right-time problem
  - The two failure modes
- Mandatory and Optional Context Components
- A Taxonomy of Context Components
  - System prompts
  - User input and user-provided context
  - Rules, style guides, and constraints
  - Skills
  - Tools
  - Custom agents
  - Environment context: runtime and metadata
  - Conversation history and memory management
- The Context Assembly Process
- Autonomous Context Discovery: How Agents Explore Before They Write
  - Code indexing and semantic search
  - CLI-based exploration
  - Language servers and symbolic code understanding
  - What autonomous discovery does and doesn't replace
- The Agent Runtime Pipeline: From Request to Action
  - Context assembly, planning, and tool execution
  - The iterative loop: reason, act, observe, adjust
- The Golden Balance: Too Little Focus, Too Much Distraction
- Avoiding Context Rot
  - Session management
  - Token efficiency for large payloads
- Summary

## Chapter 4: Model Context Protocol

What MCP is and why it matters, its client/server/transport architecture, and how to operate MCP servers safely.

- What MCP Is and Why It Matters
  - What MCP actually does
  - Why the MCP standard matters for engineers
- The MCP Architecture: Clients, Servers, and Transports
  - Hosts, clients, and servers
  - Transports
  - Local servers versus remote servers
  - How it connects in your daily workflow
- The MCP Ecosystem
  - Configuring a server: a typical example
- The Economics of MCP
  - What you pay for in an MCP session
  - Controlling tool output size
- MCP Security Model
  - Threats
  - What Real Incidents Teach Us About MCP Security
  - MCP Security Best Practices
  - Four Security Principles
- Operating MCP in Production
  - MCP Approved Registry
- Debugging MCP
  - The server won't start
  - The server connects but shows no tools
  - The agent doesn't use the tool you expect
  - A tool call fails with an error
  - Reading tool-call logs
- MCP and Context Pollution
  - Why Too Many MCP Servers Degrade Performance
  - Agent-Specific MCP Server Configuration
- Building Your Own MCP Server
  - When to build your own
  - How hard is it?
  - Writing good tool descriptions
- MCP in Agentic Pipelines
  - What changes when there's no human in the loop
  - Practical use cases for MCP in pipelines
  - The reliability constraint
- Skills and CLI Scripts: When You Don't Need an MCP Server
  - The pattern
  - Skills that reference project scripts
  - The CLI-first movement
  - When to use skills and CLI tools versus MCP
- Advanced Tool Use: Scaling Beyond Static Tool Lists
  - The three bottlenecks
  - Tool search: Loading tool definitions on demand
  - Programmatic tool calling: Code as orchestration
  - Tool-use examples: Teaching by showing
  - Matching the solution to the bottleneck
  - Where the industry is heading
- Summary

## Chapter 5: Spec-Driven Development

Why specs are the durable artifact that keeps AI-generated code aligned with intent, and how you already write them without realising it.

- The Root Problem: Why Do We Need SDD?
  - Garbage In, Garbage Out: At Scale
  - The Compounding Problem
  - The Human Parallel
- You Already Write Specs
  - When These Documents Are Missing
- The Case for Spec-Driven Development
  - The Power of Learning by Writing a Spec
  - Uncovering Unclear Requirements with a Spec
- The Economics of Writing Specs
- When SDD Is Not the Right Fit
- Specs as Durable Artifacts That Survive Tool Changes
  - Specs and Organizational Knowledge
- SDD and Human-in-the-Loop
- Why Engineers Resist Writing Specs
- Plan Mode: The Bridge Between Vibe Coding and SDD
  - Plan Mode in Practice
  - Plan Mode and Spec-Driven Development
- Three Levels of SDD Maturity
  - 1. Spec-First: Writing Specs Before Implementation
  - 2. Spec-Anchored: Keeping Specs During Evolution
  - 3. Spec-as-Source: The Spec as Primary Artifact
- What Good Specs Look Like
- Summary

## Chapter 6: The SDD Workflow

The canonical loop — Specify, Plan, Execute, Verify, Integrate, Learn — and exactly where humans must stay in it.

- The Canonical Loop: Specify, Plan, Execute, Verify, Integrate, Learn
  - Where Humans Must Stay in the Loop
  - Stop Conditions and Escalation Rules
- Before the Loop: When You Need a Prototype First
  - The Throwaway Branch Pattern
  - Scratch Repo Prototypes
  - A Concrete Example
  - Consolidating Learnings into the Spec
  - When to Skip the Prototype
- The Core Artifact Set
  - spec.md: Intent, Constraints, Acceptance Criteria
  - plan.md: Approach, Trade-Offs, Sequencing
  - tasks.md: Atomic Tasks with Done Checks
  - Optional Artifacts: risks.md, rollback.md, adr.md
- From Idea to Spec: Turning Intent into a Document
- From Spec to Plan: Turning Intent into Action
- From Plan to Tasks: Decomposition and Dependency Management
- Execution Patterns and Prompts
- Verification as Hard Rails: CI Gates That Make Output Shippable
- Integration and Deployment
- Learning and Iteration: Closing the Loop
- The Spec Lifecycle: What Happens After Implementation?
  - The Two-Tier Model: What Works in Practice
  - The Learning Phase as the Bridge
- SDD in Brownfield Projects
  - The Core Challenge: Specs for Code That Was Never Specified
  - Starting Small: The Spec Island Strategy
  - Reverse-Engineering Intent with AI Assistance
  - Handling Undocumented Behavior and Implicit Contracts
  - Prioritizing What Gets Specified First
- Summary

## Chapter 7: SDD Frameworks Compared

Why frameworks exist and how to choose between them — or when no framework is the right answer.

- Why Frameworks Exist: Structure, Consistency, Team Alignment
- GitHub Spec Kit
- OpenSpec
- BMAD Method
  - Roles, Personas, and Guided Workflows
  - BMAD in Practice
  - BMAD in Brownfield Projects
  - Custom Workflows, Custom Agents, and Adapting BMAD for Your Use Case
- Other Tools Worth Knowing
  - Kiro
  - Agent Skills
- Choosing the Right Framework
- Frequently Asked Questions on Using SDD in Production
- Summary

## Chapter 8: Verification and Quality Gates

Where the bottleneck moves once coding is cheap, and the four layers that let AI-generated code meet the same bar as human-written code.

- The Bottleneck Moves
  - Why Manual Review Doesn't Scale
  - What This Chapter Promises
  - The Two Big Questions
  - Harness Validations and Self-Check Loops
- Before Merge, Layer 1: Deterministic Guardrails
  - Linting and Formatting as a Baseline
  - Dead Code and Unused Dependencies
  - Type Checks and Compilation
  - The Test Suite
  - Mutation Testing as a Test Quality Gate
  - Property-Based Testing for Invariants
  - Static Application Security Testing (SAST)
  - Dependency and Container Scanning
  - Secrets Scanning
  - Infrastructure as Code Scanning
  - Supply-Chain Integrity
  - Architecture Fitness Functions
  - Performance and Bundle Budgets
  - Query and Data-Access Performance
  - Dependency Updates
  - Contract Gates: API and Schema Breakage
  - Accessibility and Internationalization
  - Pull-Request Size and Scope Discipline
- Before Merge, Layer 2: LLM-Based Review
  - Why Deterministic Checks Are Not Enough
  - Adversarial Review Before the PR
  - How an LLM Reviewer Works
  - Two Ways to Organize the Review
  - What to Look For
  - Tuning the Reviewer to Your Codebase
- After Merge, Layer 3: Safe Deployment Strategies
  - Feature Flags as the Default
  - Blue-Green Deployments
  - Canary Deployments
  - Shadow Traffic and Dark Launches
  - Progressive Delivery by User Segment
  - Automated Rollback on Error Budget Burn
  - Choosing Strategies
  - Data Safety
- After Merge, Layer 4: Runtime Safety and AI-Powered Ops
  - The Three Pillars, Briefly
  - OpenTelemetry as the Common Substrate
  - SLOs and Error Budgets
  - Reducing Alert Fatigue
  - Where AI Changes the Game
  - AI Anomaly Detection on Metrics and Logs
  - Post-Deploy Observability Analysis
  - AI-Driven Root-Cause Analysis
  - The Bug-Resolution Pipeline
  - Closing the Loop Back to the Coding Agent
  - Synthetic Monitoring and Chaos Engineering
- The Human in the Loop: Deciding What Needs You
  - Two Mechanisms to Decide What Needs a Human
  - The Deterministic Gate: Changes That Always Need a Human
  - The AI Risk Scorer
  - How Human Review Is Changing
  - Reviewing the Reviewer
- Putting It Together
  - A Reference Pipeline, End to End
  - What to Adopt First
  - Metrics for the System Itself
  - Failure Modes
  - The Trust Ladder
- Further Reading
- Summary

## Chapter 9: Agent Orchestration Patterns

Scaling one agent with compaction and scratchpads, then coordinating many agents while avoiding cascading failures.

- Why Software Engineers Need to Understand Agent Orchestration Patterns
  - Why Using a Single Agent Doesn't Scale
  - The Tradeoffs of Orchestrating Multiple Agents
- One Agent, Bigger Jobs: Compaction and Scratchpads
  - Compaction: The Automatic Fix That Gets Messy
  - Scratchpads: Memory in a File You Control
- SDD as an Orchestration Pattern
  - Using Different Models in Different SDD Phases
- The Generator-Critic Loop
  - Worked Example: Adversarial Code Review
- The Goal Pattern: Looping Until the Goal Is Met
- The Ralph Loop
  - How It Works
  - What Makes It Work, and What Keeps It Safe
  - Tools
- Running Multiple Agents in Parallel on the Same Codebase
  - Context-Window Isolation
  - Git Worktrees
  - Isolated Cloud VMs
- The Subagent Pattern
  - Ways to Arrange Work
  - The Advisor: A Stronger Model for the Hard Parts
- Workflows: Orchestration as Code
  - A Fixed Script: Letting the Agent Decide
- The Dark Factory: Where This Is All Going
  - Two Modes of Working
- Final Considerations

## Chapter 10: Scaling AI-Native Engineering in Teams

Why buying licences changes nothing, what actually shifts when a team goes AI-native, and how to scale without burning out your best people.

- Why Scaling to the Team Level Is a Different Problem
  - The Bottleneck Moves, It Doesn't Disappear
  - New Failure Modes That Only Show Up at Team Scale
  - AI Is a Mirror and a Multiplier
- The AI-Native Team Canvas: Design How Your Team Adopts AI
  - A Business Model Canvas, but for AI Adoption
  - How to Run It
  - The Eight Boxes
  - Skill Gaps and System Gaps
  - Usage Is Not Readiness
- Resistance Is Rational: Why Engineers Push Back
  - The Three Objections You Will Hear
  - Reframing the Craft
  - What This Means for Leaders
- Standardize the Team Stack
  - Standardize What Matters
  - The Shared Context Is the Real Stack
  - The Harness Gets Better Over Time
  - Someone Has to Own It
  - Leave Room to Experiment
- How an AI-Native Team Works
  - Pair on the Agent, Not Just the Code
  - Write and Review Specs as a Team
- The Team Gets Smaller and Tighter
  - The Human Cost of Running a Fleet
  - Agents That Work Overnight
  - Product and Design Move Closer to the Code
- Measuring Adoption
- Summary

## Chapter 11: AI-Native in Practice at Cogwheel

Nine weeks at Cogwheel: one team applies every practice in the book to ship the bet the company was too slow to ship.

- Gridlock at Cogwheel
- The Mission: A Greenfield Service Inside a Brownfield World
- Week 1: Everything Except Signals
  - A PRD, Written Together
  - The AINE Canvas: How the Team Will Work
  - Building the User Harness
  - Wiring In Cogwheel's World
- Week 2: Splitting Into Stories
  - Prototyping in Code, Not Pictures
  - The Loop in Motion
- Weeks 3–4: Trusting the Code
  - Watch One PR Go Through
- Weeks 5–8: A Fleet, Not a Hero
  - Making It the Team's Way
  - Measuring Honestly
- Week 9: Cogwheel Ships Pulse

---

_AI-Native Software Engineering by Alfonso Graziano (O'Reilly Media, Early Release; print edition February 2027). Every page of ainativesoftware.engineering is also served as Markdown: append `.md` to any URL. Index: https://ainativesoftware.engineering/llms.txt — whole site in one file: https://ainativesoftware.engineering/llms-full.txt._