Agent-Driven Development: Contract Files as Architecture Policy

There’s a failure mode that only shows up when a team builds with AI, and it’s subtler than broken code. Every developer’s agent makes reasonable architectural choices, reasonable, and different. One puts data access in route handlers, another invents a service layer, a third has opinions about where migrations live. Six months in, you’re not maintaining a codebase. You’re maintaining five architectures wearing one repository as a trench coat.

Nobody did anything wrong. That’s what makes it insidious: every individual PR looked fine. The drift lives between the PRs.

The rules have to live where the agents read

Teams already solved this problem once, for humans: style guides, ADRs, onboarding docs. The catch is that agents don’t read your Notion. They read the repo. So the conventions have to move into files agents actually load: CLAUDE.md for Claude Code, AGENTS.md as the vendor-neutral version, a rules file for Cursor, a skill for OpenClaw.

I’ve started calling these contract files, because that’s the role they play: this is where migrations go, this is how routes are named, these invariants are load-bearing and you may not touch them. Whirlwind ships all of them pre-written for its architecture, but the pattern matters more than my product: architecture policy as code.

And because they’re files in the repo, they get the whole software lifecycle for free. Versioned. Reviewed. When the team agrees on a new convention, it lands as a PR to the contract, and every developer’s agent picks it up on the next session, simultaneously. Compare that to updating a wiki page and hoping.

Contracts steer, gates enforce

A contract file makes agents likely to follow the architecture. Likely isn’t a guarantee. Agents drift, contexts truncate, someone’s agent has a weird afternoon. So the second half is a merge gate that doesn’t care about likelihood. Whirlwind’s checks are plain npm scripts, which means the gate is one workflow file:

# .github/workflows/whirlwind-checks.yml
name: whirlwind-checks
on: [pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run audit
      - npx playwright install --with-deps chromium
      - run: npm test

The audit needs no secrets. It’s static analysis, so it runs on any fork immediately. The e2e appearance suite runs without credentials too. The flow suite (signup, checkout, credit atomicity) activates when you add test-mode keys as CI secrets and skips itself cleanly when you don’t. Pair the workflow with branch protection and the sentence every engineering lead wants becomes literally true: agent-written code cannot merge without passing the checks.

The longer writeup, including how to review contract-file changes like style-guide changes, and the full team workflow, is in the Teams & CI docs, and if you’re rolling this out across an org, the Teams page covers licensing.