Fact Driven Development

Fact-Driven Development

Fact-driven development is a methodology for keeping software projects aligned with their intended behavior using atomic, verifiable facts instead of traditional lengthy specification documents.

It is particularly powerful when working with AI coding agents (Claude Code, Cursor, Windsurf, Aider, etc.) because it gives agents a concise, trustworthy source of truth that they can both read and update themselves.

Core Principles

1. Atomicity
   Every fact is a single, independent claim. No "and" or "or" in the same bullet unless the whole thing is one verifiable unit.

2. Verifiability
   A fact either has a command: that exits 0 when true, or it is marked for manual review by a user or agent. facts check runs every command and reports clear pass / fail / manual status.

3. Lifecycle
   Facts move through a deliberate pipeline:

   • @draft — rough idea, needs refinement
   • @spec — precise, actionable, ready for implementation
   • @implemented — backed by code and passing its check

4. Flat & Fast
   The entire spec for a project should be readable in under a minute (facts ll). This is the opposite of thousand-line PRDs or Notion pages that agents never fully internalize.

How It Differs from Traditional Spec-Driven Development

Traditional "spec-driven development" often produces beautiful but bloated documents. Agents tend to:

• Hallucinate details that weren't in the spec
• Ignore sections buried deep in the file
• Implement the wrong behavior because the spec was ambiguous

Fact-driven development replaces volume with precision and machine checks. The spec is both documentation and executable contract.

Example Fact Sheet

# auth
- users authenticate via OAuth2 @implemented
- sessions expire after 24 hours @implemented
- label: failed logins are rate-limited to 5 per minute
  command: grep -q 'rate_limit.*5' src/auth.ts
  tags: [security, mvp]
  @spec

# data
- all timestamps stored in UTC @implemented
- PII is encrypted at rest @draft

An agent can read this in seconds, pick up the @spec items, implement them, run facts check --tags "spec", and tag the completed work @implemented.

Tooling

The facts CLI (written in Rust, single binary) provides:

• init — scaffold .facts + agent skills
• check / list / ll — inspect and verify
• add, edit, remove, move — maintain the sheet
• Powerful boolean filters on tags and full-text search
• A full terminal UI (facts tui)

Companion skills (facts-discover, facts-refine, facts-implement) let agents autonomously classify, sharpen, and deliver work against the spec.

When to Use Fact-Driven Development

• New projects where you want the spec to evolve with the code
• Teams (users + AI) that need a single source of truth
• Projects with strict behavioral requirements (auth, billing, compliance)
• Any codebase where "it works on my machine" is no longer acceptable

Start with facts init in any git repo and experience the difference.

See also: Fluffy Specs, Facts Lifecycle, Facts with AI Agents.