Blog

The Constitution Rules Before Code

5 min read

The Step That Feels Backwards

The first thing Spec-Driven Development asks you to do isn’t to describe a feature. It’s to write a constitution: the project’s non-negotiable principles, before any spec, plan, or line of code. The first time you meet it, it feels backwards — I came to build a portfolio, why am I writing a governing document?

Then you start working with an AI agent in earnest, and it clicks. A constitution is how you give the agent a spine — and how you stop yourself from re-deciding the same things, differently, every session.

What a Constitution Actually Is

It’s a short document of principles the project must obey — and crucially, that every spec, plan, and implementation must comply with. Not aspirations (“let’s keep it clean”), but rules an agent and a human can both be held to.

For this portfolio I wrote five, deliberately tailored to this project rather than generic boilerplate:

  1. Static-First & Performance — zero client-side JS by default; Core Web Vitals are a release gate, not a nice-to-have.
  2. Content as a Validated Contract — content is Markdown with schema-validated frontmatter; invalid metadata fails the build and never ships.
  3. SEO & Accessibility by Default — unique title, meta description, absolute canonical, OG/Twitter, JSON-LD, sitemap, robots, and semantic HTML are mandatory on every page.
  4. Spec-Driven, Sliced Delivery — every feature goes constitution → spec → plan → tasks → implement, cut into independently shippable slices.
  5. Simplicity & Zero-Maintenance (YAGNI) — the simplest thing that works; free, reproducible, static deploy; no servers or dependencies that don’t earn their keep.

Plus hard constraints (the stack, English-only, a private repo, the git identity) and a build gate. It’s the layer that everything downstream answers to.

Why This Matters More With an AI in the Loop

Here’s the part that turned me from skeptic to believer. An AI agent is a tireless, fast, literal producer with no memory of your taste. Without a written law, two things happen:

  • It drifts. Every session it re-decides small things — slightly differently each time — and the inconsistencies pile up into a codebase with no point of view.
  • You bikeshed. When it proposes something off-track, you’re stuck arguing style in prose: “no, more minimal,” “no, not like that.” Subjective, slow, and you’ll have the same argument again next week.

A constitution collapses both. The agent has a fixed reference to honour, so it drifts less. And when it does go off-track, you don’t argue taste — you point at a principle. “This adds a client-side framework for a static page → violates Principle I.” The conversation goes from opinion vs. opinion to output vs. rule. That’s the whole shift: you stop negotiating and start directing.

What Makes a Principle Enforceable, Not Decorative

This is where most constitutions fail — including the tempting auto-generated kind. A principle is only worth writing if you can test against it. Compare:

  • ❌ “The site should be fast and clean.” — Unenforceable. Fast by what measure? Clean to whom? An agent can’t be held to a vibe.
  • ✅ “Zero client-side JS by default; Core Web Vitals are a release gate.” — Testable. Either there’s an unjustified script or there isn’t; either the metrics pass the gate or they don’t.

The same logic gives “content as a validated contract” its teeth: invalid frontmatter doesn’t get a warning, it fails the build. A principle backed by a mechanism (a gate, a schema, a check) is law. A principle backed by good intentions is a comment.

Two more things I learned writing it:

  • Generic boilerplate is worse than nothing. A constitution copied from a template gives you the feeling of governance with none of the bite. Mine is short precisely so every line earns its place and is specific to this project.
  • It’s meant to be amended, formally. It’s versioned (it started at v1.0.0). When I later promoted the site’s visual identity into it, that was a real, semver’d amendment with a change report — not a silent edit. A living law, with an audit trail.

The Recurring Thread

This is the first instance of the pattern the whole series keeps hitting: the AI is fantastic at producing, but the deciding stays with me — and the highest-leverage move is to write those decisions down somewhere the agent is bound to obey. The constitution is the very first of those somewheres. Everything else (specs, wireframes, the design system) is a more specific decision made under its authority.

Takeaways

  • SDD starts by writing a constitution — the project’s non-negotiable principles — before any feature. It feels backwards; it isn’t.
  • With an AI in the loop it’s essential: it stops the agent drifting and stops you bikeshedding. Off-track output becomes “violates Principle X,” not an argument about taste.
  • A principle is only real if it’s testable and backed by a mechanism (a gate, a schema). “Be fast and clean” is decoration; “zero JS by default, CWV as a gate” is law.
  • Keep it short and project-specific; generic boilerplate is worse than nothing. And amend it formally — it’s a versioned, living document.

This blog is built slice by slice with Spec-Driven Development. Read the groundwork in “Before the First Line of Code,” see the whole system in “How I Built This Portfolio with SDD,” or browse the rest at /blog. Next in the series: writing the first spec — describing the WHAT and the WHY, with the technology deliberately left out.