Project Spec

A project specification defines what you are building, why you are building it, and how you plan to deliver it. Writing one before development begins forces the team to align on goals and constraints early, which reduces costly rework later.

This page provides a guide and a reusable template.

What a Project Spec Should Cover

A good specification addresses the following questions without becoming a novel:

Goals -- What does the project aim to achieve? What problem does it solve for the user or the business?
Scope -- What is included, and what is explicitly out of scope? Drawing a clear boundary here prevents scope creep.
Tech Choices -- What technologies, frameworks, and services will the project use, and why? Link to an ADR or a tech-stack document if you have one.
Timeline -- Key milestones and target dates. Be honest about uncertainty; a range is better than a false precision.
Acceptance Criteria -- How will you know the project is done? Define measurable, observable outcomes.

Template

Copy the section below into your project repository (typically as docs/PROJECT-SPEC.md or similar) and fill in the placeholders.

Project Goals

State the primary objectives. Aim for three to five clear, measurable goals.

[Goal one]
[Goal two]
[Goal three]

Scope

In Scope

List the features, capabilities, or outcomes that this project will deliver.

[Feature or outcome]
[Feature or outcome]

Out of Scope

Explicitly state what this project will NOT deliver. This is just as important as the in-scope list.

[Item deliberately excluded and why]
[Item deliberately excluded and why]

Technology Choices

Summarise the key technology decisions. Link to ADRs or a tech-stack document where relevant.

Concern	Choice	Rationale
Backend language
Web framework
Database
Hosting / cloud
Frontend approach
Authentication

Timeline

List the major milestones in order. Include target dates where known. Mark anything uncertain.

Milestone	Target Date	Notes
Requirements signed off
Development start
First working prototype
Testing complete
Production launch

Acceptance Criteria

Define how each goal or feature will be verified as complete. Each criterion should be testable.

[Criterion one -- e.g. "A user can register and log in with a valid email address."]
[Criterion two]
[Criterion three]

Stakeholders

Identify who is involved and what their role is.

Name	Role
	Project owner
	Technical lead
	Designer
	Developer(s)

Tips

Revisit the spec at the end of each sprint or milestone. Circumstances change; the spec should reflect reality, not just the original plan.
Keep it in version control. A spec that lives in a shared document and never gets updated is worse than no spec at all.
Involve the whole team in writing the acceptance criteria. If everyone agrees on what "done" looks like, disputes are far less likely.