Engineering Constitution Template

Use this template to define the rules that every spec, design, task plan, and AI coding request must respect. It is the small policy layer that keeps SDD consistent across a team.

constitution.md

# Engineering Constitution

Owner:
Applies to:
Last reviewed:

## Principles
- Specs before risky implementation.
- Acceptance criteria must be observable.
- Evidence is required before merge for high-risk changes.
- AI-generated code must stay inside approved scope.

## Required Gates
- Spec review:
- Design review:
- Test evidence:
- Release stop signal:

## AI Coding Rules
- Allowed context:
- Allowed files:
- Non-goal handling:
- Evidence summary:

## Exceptions
- Allowed exception:
- Required approver:
- Follow-up review date:

When to use this template

A team wants SDD to be a working agreement, not only a set of templates.
AI coding tools are used by multiple people and need consistent guardrails.
Review quality varies because nobody knows which evidence is required.
Leads need a lightweight policy that can live in a repo.

What a filled version looks like

The template becomes useful after it carries a real decision, owner, and evidence. This is the level of specificity to aim for.

## Required Gates
- Payment, auth, migration, and public API changes require spec review.
- AI-generated code must include an evidence summary and test command.
- Release stops when the metric listed in evidence.md crosses the threshold.

Field note: turning team habits into enforceable rules

A team uses AI coding tools across several repositories, but each engineer gives different context, review expectations, and evidence requirements. The constitution is the shared agreement that makes the workflow repeatable.

Common failure: If the rules stay cultural instead of written, the first urgent release will skip spec review, accept broad generated diffs, and leave no evidence for the next reviewer.

Reviewer action: Ask leads to approve which change classes require spec review, which evidence gates are mandatory, and who can approve exceptions.
Evidence bar: A working constitution is visible in PR templates, agent instructions, and release gates; it is not only a policy page in a handbook.

How to adapt this template without making it generic

Do not only replace the title and date. A useful version turns every placeholder into a reviewable decision: who owns the change, which behavior must be true, which scope is explicitly excluded, and what evidence must exist before merge. If a field cannot be filled yet, keep it as an open question instead of burying the uncertainty in prose.

When you use this constitution.md, start with the part most likely to cause rework. For many teams that is not the implementation step; it is the boundary, exception, compatibility rule, or release evidence. The earlier the template exposes those decisions, the less room an AI coding tool or rushed engineer has to broaden the change silently.

Use it when: A team wants SDD to be a working agreement, not only a set of templates.
Review for: Principles are concrete enough to affect review behavior.
Strong wording target: Payment, auth, migration, and public API changes require a reviewed spec, a linked evidence log, and a release stop signal. AI-generated diffs must list allowed files, changed files, and acceptance criteria covered.

Suggested review path

Use the first pass to review scope: the goal should be singular, the non-goals should block common expansions, and the affected systems should be named. Use the second pass to review testability: acceptance criteria should describe state, trigger, and observable result, not a vague wish that the product feels better. Use the third pass to review evidence: tests, screenshots, logs, metrics, or manual checks should prove each criterion.

Before giving this template to an AI coding tool, ask a human reviewer to confirm allowed files, interfaces that must not change, migration order, and stop signals. The AI should receive an executable spec, not a prompt that looks complete while still leaving the risky decisions implicit.

Before implementation: confirm open questions do not block behavior decisions.
During implementation: map every task back to a criterion or constraint in this file.
Before merge: prove the result with evidence, not only with a "tests passed" sentence.

Review before implementation

Principles are concrete enough to affect review behavior.
Required gates distinguish low-risk and high-risk work.
AI rules name allowed context, files, and evidence.
Exceptions require an approver and follow-up date.

Weak vs strong wording

Weak

Write good specs and use AI responsibly.

Strong

Payment, auth, migration, and public API changes require a reviewed spec, a linked evidence log, and a release stop signal. AI-generated diffs must list allowed files, changed files, and acceptance criteria covered.

When the template stops being empty

The easiest way for a template page to become thin is to provide a clean skeleton without showing how to judge the filled result. A useful version answers three questions: why this change is worth doing now, which scope is explicitly excluded, and which evidence proves the implementation did not drift.

When you use the template for real work, attach the final file to the pull request and mark any section that changed during implementation. A spec is not a one-time document; it should move with the implementation evidence. Readers copying this template should also copy that habit: every sentence that sounds like a decision should be reviewable and traceable.

Minimum evidence: at least one automated test or contract fixture.
Higher-risk evidence: add screenshots, log queries, metrics, or rollback signals.
Follow-up evidence: give known gaps an owner and review date.

Where it fits in a complete SDD packet

Do not push every decision into the same file. constitution.md should own the layer it is best at: making one category of decision reviewable, linkable, and updateable. Scope, design, tasks, and evidence should connect to each other, but they should not swallow each other. When implementation reveals new facts, the team should know exactly which artifact needs to change.

In practice, use this template as one step in a short chain: write the spec or proposal, add design or tasks only when the work needs them, then feed evidence back into the pull request. Readers copying the template should copy that chain as well. A polished standalone template does not improve delivery by itself; a traceable set of artifacts does.

If the template becomes a team standard, keep one filled example in the repository instead of only publishing an empty skeleton. The example teaches new contributors what "specific enough" looks like and gives AI coding tools a better pattern to follow.

Upstream input: a concrete user problem, system constraint, and known failure mode.
Downstream output: executable tasks, review questions, test evidence, or release gates.
Maintenance habit: update the matching spec file whenever implementation changes a decision.

FAQ

Is this too formal for a small team?

It can be short. A useful constitution may be under one page if it names the few rules the team will actually enforce.

Where should it live?

Keep it in the repo or team handbook, then link it from templates, PR descriptions, and AI coding instructions.

How often should it change?

Review it after incidents, repeated review misses, or tooling changes. Do not rewrite it just for wording polish.

Related resources

Editorial note

This template is written for spec-driven development workflows. The example is illustrative and should be adapted to your domain.

Author: Daniel Marsh
Editorial policy: How we review and update content

Tip: keep it under /docs/specs/ or /.specs/, then update it in the same pull request as implementation changes. Last updated: May 19, 2026.