AI-Driven Development

A complete, practical book on building software when AI writes the code

Edition: 1.0 · Type: Methodology + operating manual

---

What this book is

This is a complete guide to AIDD (AI-Driven Development) — a way of building software in which an AI agent writes most of the code and people do the two things AI cannot reliably do alone: decide what to build, and verify that what was built is correct.

It is written to be read once front to back, then kept open beside you as a working manual. The early chapters explain why the method has the shape it does; the middle chapters explain each step in detail; the later chapters explain how to operate it across a real team and product; the appendices are copy-paste reference material.

A single worked example — transferring money between a user's own accounts — runs through the entire book so that every abstract step has a concrete form you can see.

Who it is for

Anyone who builds software with AI in the loop: engineers, architects, testers, designers, product owners, and the managers who lead them. No part assumes you have read the others; cross-references point you to what you need.

The method in one paragraph

For every feature, before AI writes any code, you write four short artifacts in order — the rules it must obey, those rules as pass/fail scenarios, the data and interface contract, and the failing tests — and then you direct the AI to make the tests pass without changing them, and finally you verify the result through evidence rather than inspection. That ordered set of artifacts is the method. The code is disposable; the artifacts are the durable asset. Direction comes before speed, and trust comes from passing tests rather than from reading code and finding it plausible.

The flow

Specify → Scenarios → Contract → Tests → Build → Verify → observe, then repeat.

---

Install and run your first feature

ADD ships as an installable Claude Code skill — you install it once, then talk to the agent and it drives the method. Here is the whole path, from nothing to your first running feature.

Prerequisites: Node ≥ 18 (npm path) or Python ≥ 3.10 (pip path) — the tool itself is Python stdlib-only — plus Claude Code.

1 · Install into your project

From your project root (an empty folder or an existing repo), pick either ecosystem:

# Node / npm
npx @pilotspace/add init

# Python / pip
pip install pilotspace-add && pilotspace-add init

2 · Spawn your first feature — talk to the agent

In Claude Code, run /add and say what you want to build:

/add — "I want to let users transfer money between their own accounts."

From there the agent runs the on-ramp for you:

1. Orients from add.py status (the resume point) — never re-reading your repo.
2. Sizes your request into a milestone (goal · scope · breadth-first tasks · exit criteria) — you confirm the shape.
3. Drafts each feature's one-approval front — Spec + Scenarios + Contract + Tests as one bundle — you give one approval at the frozen contract.
4. Runs build → verify to green; a security finding always stops back to you.

So your first feature is: describe it → confirm the milestone → approve the contract → review the result. Everything in between is the agent.

3 · Resume anytime

/add — how are current status of this project?"

State lives on disk, not in the chat — close your laptop, come back tomorrow, and this tells you exactly where you left off. No context rot.

Go deeper: the 2-minute Getting Started · the full hands-on walkthrough (one real feature, end to end) · package source · CHANGELOG. Releases: @pilotspace/add (npm) · pilotspace-add (PyPI) — one tag publishes both (see .github/workflows/publish.yml).

---

Table of contents

Part I — Foundations

• 00 · The shift: why AIDD exists
• 01 · Core principles
• 02 · The flow, and what is disposable

Part II — The method, step by step

• 03 · Step 1 — Specify
• 04 · Step 2 — Scenarios
• 05 · Step 3 — Contract
• 06 · Step 4 — Tests
• 07 · Step 5 — Build
• 08 · Step 6 — Verify
• 09 · The loop — observe and learn

Part III — Operating the method

• 10 · Project setup and stages
• 11 · Governance
• 12 · Roles and responsibilities
• 13 · Adoption and onboarding
• 14 · The foundation: project context across milestones

Lineage

• 15 · Foundations & Lineage

Part IV — Reference

• Appendix A · Templates
• Appendix B · Prompt library
• Appendix C · Glossary
• Appendix D · The worked example, end to end
• Appendix E · Checklists
• Appendix F · Document requirements matrix (Project → Milestone → Task)
• Appendix G · References & lineage

---

Conventions used in this book

• ▶ Example marks the running worked example.
• Do / Don't boxes give the rule in its shortest form.
• A gate is a checkpoint with an explicit pass/fail exit. Its outcome is always one of PASS, RISK-ACCEPTED (a signed waiver), or HARD-STOP.
• File names like SPEC.md, features/*.feature, contracts/* refer to the artifacts you create per feature; see Appendix A.
• Where this book uses a plain step name, the formal phase name (for teams mapping to a larger standard) appears once in Appendix C.