What if we stopped trusting code and started trusting outcomes? A practical framework for software development where contracts define reality and implementation becomes irrelevant.

Contract Driven Development

Systems design for multi-agent coordination — evolving from single-agent PRD executor to a full team system with SOUL-based personalities, filesystem-native state, and observable dashboards.

AI Agent System Architecture


### I. The Problem

We've been staring at the wrong thing.

For decades, software development has been about **code**. Write it. Review it. Test it. Refactor it. Debate it in pull requests. Argue about tabs vs spaces.

Meanwhile, the actual question—*does this thing deliver value?*—gets answered months later. Maybe never.

We trust code. We should trust outcomes.

---

### II. The Inversion

Imagine Maslow's hierarchy, but upside down.

At the top: **Value**. Does it make money? Does it scale? Does it matter?

At the bottom: **Resources**. Servers. Databases. Pods. The metal.

In between: layers of abstraction. Each layer depends on the one below it. Each layer makes promises to the one above it.

These promises are **contracts**.

---

### III. The Hierarchy

**Layer 5: Value**
- Is it profitable?
- Is it scalable?
- Is it sustainable?
- Does it matter?

**Layer 4: Capability**
- Can users do the thing?
- Can they pay?
- Can they leave with their data?

**Layer 3: Behavior**
- When X happens, does Y follow?
- Is it fast enough?
- Does it break?

**Layer 2: Components**
- Are the services alive?
- Do they talk to each other?
- Do they keep their promises?

**Layer 1: Resources**
- Is the server running?
- Is the database reachable?
- Is DNS resolving?

---

### IV. The Contract

A contract is not a test.

A test asks: "Does this code work?"

A contract asks: "What does 'work' mean at this level of abstraction?"

Tests verify implementation. Contracts **define reality**.

---

### V. The Cascade

Trust flows upward.

If Layer 1 contracts pass → trust the infrastructure.
If Layer 2 contracts pass → trust the components.
If Layer 3 contracts pass → trust the behavior.
If Layer 4 contracts pass → trust the capabilities.
If Layer 5 contracts pass → trust the value.

If all layers pass, you've **proven** the system delivers value.

Without reading a single line of implementation code.

---

### VI. The Two Kinds of Truth

Some contracts are **facts**. Code can check them.

- `revenue > costs`
- `latency.p99 < 200ms`
- `healthCheck(endpoint) === true`

Some contracts are **vibes**. Only humans can judge them.

- "Is this intuitive?"
- "Does this feel trustworthy?"
- "Is this copy compelling?"

For decades, vibes couldn't be contracted. They stayed in the realm of opinions, design reviews, gut feelings.

Not anymore.

---

### VII. LLM-as-Judge

An LLM can judge vibes. And return a boolean.

"Is this UI intuitive?" → yes/no
"Does this copy build trust?" → yes/no
"Is this experience delightful?" → yes/no

The judge is probabilistic, not deterministic. It has confidence, not certainty.

But it can be calibrated.

50 labeled examples. Run the judge. Measure accuracy. Tweak until 90%+.

A calibrated judge is good enough to ship on.

---

### VIII. The Expanded Contract Space

Before LLMs: contracts could only encode what computers could measure.

After LLMs: contracts can encode what humans can judge.

Brand consistency. Emotional resonance. Ethical compliance. Accessibility. Tone.

All contractable now.

The space of "things you can formally verify" just exploded.

---

### IX. The Implication

If contracts define reality, and all contracts pass, then reality is correct.

By definition.

Implementation becomes **irrelevant**.

- Ralph writes it? Fine.
- A human writes it? Fine.
- GPT-7 writes it? Fine.

Same contracts. Different shadows on the cave wall.

You don't review implementation. You validate contracts.

---

### X. The Development Loop

Old way:
```
Idea → Code → Test → Deploy → Hope
```

CDD:
```
Value Contract → Capability Contract → Behavior Contract → Component Contract → Resource Contract
                                                                                        ↓
                                                                              Implementation
                                                                                   (whatever)
                                                                                        ↓
                                                                              Validate Cascade
                                                                                        ↓
                                                                                All pass? Ship.
```

You iterate on **contracts**, not code.

If value isn't being delivered, you don't debug implementation. You ask: which layer's contract is failing? Fix that contract. Regenerate implementation.

---

### XI. The Axioms

At the foundation, you need things you trust without proof.

- Network reachability implies existence.
- Arithmetic is valid.
- Money in the bank is real.
- Retention correlates with value.

CDD doesn't eliminate trust. It makes trust **explicit**.

Name your axioms. Derive everything else.

---

### XII. The Promise

If you adopt CDD:

1. **No more code review.** Contracts are the review.
2. **No more implementation debates.** If it passes, it's correct.
3. **No more "does it work?" anxiety.** The cascade answers that.
4. **No more hoping value gets delivered.** Value is contracted.

The implementation becomes disposable. Generate it. Throw it away. Generate again.

The contracts are the product.

---

### XIII. The Risk

LLM judges can be wrong.

Deterministic checks can have bugs.

Contracts can be poorly specified.

CDD doesn't guarantee correctness. It guarantees **explicitness**.

When something fails, you know exactly where. Which layer. Which contract. Which field.

That's worth everything.

---

### XIV. The Bet

We bet that:

1. Outcomes can be contracted.
2. Contracts can be validated.
3. Validation can be trusted.
4. Implementation can be ignored.

If true, we've just made 90% of software development—the implementation part—a commodity.

The remaining 10%? Defining what "value" means.

That's the hard part.

That's the human part.

That's the only part that matters.

---

*Contracts are the product. Implementation is a shadow.*


What if we stopped trusting code and started trusting outcomes? A philosophical framework for software development where contracts define reality and implementation becomes irrelevant.

Contract-Driven Development: An Armchair Manifesto


I've recently jumped into prompt engineering with both feet, but found myself rewriting a lot of the same
boilerplate code when engineering new prompts. If you take a look at 2 of the tools I've added to this site:

1. [TailwindCSS + React Hook Form Generator](/tools/tailwindcss-forms-ai-generator)
2. [AI Spec Generator](/tools/ai-spec-generator)

They are pretty close to the same UI, but the API code for them was almost identical. So? DRY.

# tldr;

Vercel AI + Open AI makes building new AI experiences fast. Adding a little abstraction makes it even faster. 💥

### The Original Vercel AI API Route

To get started with Vercel AI, I basically just ripped their code from the docs [here](https://sdk.vercel.ai/docs/concepts/caching). No biggie. I added a little
training data, and some code examples, so that my first attempt at a streaming AI API route looked like this:

```js:/api/ai/code/index.js
import { OpenAIStream, StreamingTextResponse } from 'ai'
import OpenAI from 'openai'
import { kv } from '@vercel/kv'

const DEV = process.env.NODE_ENV === 'development'

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
})

const modelOptions = {
  model: 'gpt-3.5-turbo',
  stream: true,
}

const training = [
  { role: 'system', content: '...' },
  { role: 'user', content: '...' },
  { role: 'assistant', content: '...' },
  { role: 'user', content: '...' },
  { role: 'assistant', content: '...' },
];

export default async function handler(req) {
  const { messages } = await req.json()
  const key = `${prefix}-${JSON.stringify(messages)}`

  // Check if we have a cached response in production
  const cached = DEV ? null : await kv.get(key)

  if (cached) {
    const chunks = cached.split(' ')
    // Emulate the "stream" interface, even if we're cached
    const stream = new ReadableStream({
      async start(controller) {
        for (const chunk of chunks) {
          const bytes = new TextEncoder().encode(chunk + ' ')
          controller.enqueue(bytes)
          await new Promise((r) =>
            setTimeout(
              r,
              // get a random number between 10ms and 50ms to simulate a random delay
              Math.floor(Math.random() * 40) + 10
            )
          )
        }
        controller.close()
      },
    })
    return new StreamingTextResponse(stream)
  }

  const response = await openai.chat.completions.create({
    ...modelOptions,
    messages: [...training, ...messages],
  })

  const stream = OpenAIStream(response, {
    async onCompletion(completion) {
      // Cache the response. Note that this will also cache function calls.
      if (DEV) {
        return;
      }

      await kv.set(key, completion)
      await kv.expire(key, 60 * 60)
    },
  })

  return new StreamingTextResponse(stream)
}

```

Not bad, considering it even implements caching for cost savings on responses.  But then,
when I went to build the second AI API route (the one for my [spec tool](/tools/ai-spec-generator)), I realized I was
basically identically copying all the meat of this handler, with the exception of the training
data.

There are a couple of ways you could handle this:

1.  Add the training data in an api request to a single ChatGPT completion endpoint
2.  Abstract the creation of AI api handlers into a function that accepts additional training data

Ultimately, I opted for #2, simply because having all that training data in React components
seemed like a weird place for it to live, and I like the flexibility of different API endpoints per bot 🤖.

Maybe I want to extend them, or chain them... who knows.  This is all new to me.

Anyway, here's the simple abstraction, and a sample implementation, for your reusing pleasure.

```js:/lib/createAIHandler.js
import { OpenAIStream, StreamingTextResponse } from 'ai'
import OpenAI from 'openai'
import { kv } from '@vercel/kv'

const DEV = process.env.NODE_ENV === 'development'

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
})

const defaultModelOptions = {
  model: 'gpt-3.5-turbo',
  stream: true,
}

export default function createAIHandler({
  prefix,
  training = [],
  modelOptions = defaultModelOptions,
}) {
  // Return a function, that is the handler
  return async function (req) {
    const { messages } = await req.json()
    const key = `${prefix}-${JSON.stringify(messages)}`
    // Check if we have a cached response
    const cached = DEV ? null : await kv.get(key)

    if (cached) {
      const chunks = cached.split(' ')
      const stream = new ReadableStream({
        async start(controller) {
          for (const chunk of chunks) {
            const bytes = new TextEncoder().encode(chunk + ' ')
            controller.enqueue(bytes)
            await new Promise((r) =>
              setTimeout(
                r,
                // get a random number between 10ms and 50ms to simulate a random delay
                Math.floor(Math.random() * 40) + 10
              )
            )
          }
          controller.close()
        },
      })
      return new StreamingTextResponse(stream)
    }

    const response = await openai.chat.completions.create({
      ...modelOptions,
      messages: [...training, ...messages],
    })

    const stream = OpenAIStream(response, {
      async onCompletion(completion) {
        // Cache the response. Note that this will also cache function calls.
        if (DEV) {
          return;
        }
        
        await kv.set(key, completion)
        await kv.expire(key, 60 * 60)
      },
    })

    return new StreamingTextResponse(stream)
  }
}
```

Pretty simple wrapper, eh?

Now, here's how you use it in a sample AI route for generating animal names:

```js:/api/ai/animal-names/index.js
import createAIHandler from '@/lib/createAIHandler'

export const runtime = 'edge'

const training = [
  { role: 'system', content: `
You are a bot that can ONLY respond with made up animal names.
Include a person's name, an adjective, a color, and an animal name.

<example>
Bart, the Slippery Green Walrus.
</example>
` },
  { role: 'user', content: 'Give me an animal name'  },
  { role: 'assistant', content: 'Sue, the Hilarious Yellow Antelope.' },
  { role: 'user', content: 'How are you?'  },
  { role: 'assistant', content: 'Jeff, the Angry Red Hare.' },
]

export default createAIHandler({
  prefix: 'animal-bot',
  training,
})
```

Lastly, wire it up in your component:

```jsx:/pages/animal-name-generator.jsx
import { useChat } from 'ai/react'

export default function Page() {
  
  const { messages, handleSubmit, input, handleInputChange } = useChat({
    api: '/api/ai/animal-names',
  });

  return (
    <>
      // Your chat UX
    </>
  )
}
```

I'm not gonna go into building forms and chat UX here, but good starting places are:

- [TailwindUI Feeds](https://tailwindui.com/components/application-ui/lists/feeds)
- [How I build forms](/articles/react-fast-performant-forms)
- [My AI Tailwind Form Generator](/tools/tailwindcss-forms-ai-generator)

Hope this helps you ramp up on your AI skillz, and happy coding! 😎

Learn how to abstract a Vercel OpenAI handler to quickly build and deploy AI-powered tools and applications.