Why Every Product Needs a Constitution
A short, opinionated document that defines what your project believes. It sounds grandiose — it's actually the most practical thing I do.
Every project I build starts with a constitution. Not a brief, not a PRD, not a Notion doc full of bullet points — a constitution. A short, opinionated document that defines what the project believes, what it refuses to compromise on, and how decisions should be made when nobody's looking.
It sounds grandiose. It's actually the most practical thing I do.
What a project constitution is
A constitution is typically one page. It contains:
3-5 core principles that guide every decision
A clear statement of what the project is NOT
Quality thresholds that are non-negotiable
A decision-making framework for ambiguous situations
Here's an example from this portfolio site's actual constitution: "Performance is non-negotiable. Lighthouse scores stay above 90. If an animation drops the score, the animation goes." That's not aspirational — it's a rule. It's saved me from myself at least three times already.
Why it works
Most projects don't fail because of bad ideas. They fail because of scope drift — the slow accumulation of "while we're at it" decisions that pull the work away from its original intent.
A constitution fights scope drift in three ways:
1. It makes trade-offs explicit
When you write down "content is data, not code", you've made a decision that echoes through every technical choice. Should blog posts be MDX files or database records? The constitution already answered that. No meeting required.
2. It gives contributors a shared compass
Whether it's a collaborator, a client, or an AI assistant, everyone working on the project can reference the same principles. I include the constitution in my Claude Code context — the AI literally reads it before writing any code. This isn't theoretical; it measurably improves the coherence of the output.
3. It makes saying no easier
"That's a great idea, but it conflicts with principle #2" is much easier to say than "I just don't think we should do that". The constitution depersonalises disagreement. It's not my opinion — it's the project's principles.
How I write one
I spend 30-60 minutes at the start of every project writing the constitution. The process:
Write down every quality you want the project to embody. Don't filter yet.
Cross out anything that could apply to any project. "Well-tested" is not a principle, it's a baseline.
Reduce to 3-5 statements that are genuinely specific and opinionated.
For each principle, write one concrete example of a decision it would resolve.
Add the "what this project is NOT" section. This is often more useful than the principles themselves.
Spec-driven development
The constitution sits at the top of a hierarchy I call spec-driven development. Below the constitution are feature specifications — detailed documents that describe what to build and how. Below those are task lists that break specs into shippable increments.
The structure looks like this:
Constitution → Principles (changes rarely)
Spec → Feature design and decisions (changes per feature)
Tasks → Implementation steps (changes daily)
Each level inherits from the one above. A task can never contradict a spec. A spec can never contradict the constitution. This hierarchy prevents the chaos that happens when implementation details start driving architectural decisions.
A real example
When I was building the CMS for this portfolio, I had a decision to make: should I use a headless CMS like Sanity, or build on Convex? The constitution said: "Type-safe everything" and "Content as data, not code."
Convex gives me end-to-end type safety from the database schema to the React component. Sanity gives me a nicer content editing UI out of the box but weaker type guarantees. The constitution made the decision obvious. I chose Convex and built the admin UI myself.
Was that more work? Yes. Was it the right call for this project, given these principles? Absolutely.
Start with principles
If you take one thing from this post: start your next project by writing down what it believes. Not what it does — what it believes. The rest follows from there.
A project without principles will absorb every opinion it encounters. A project with principles will make decisions while you sleep.