Project Specification:
How to use this template: Copy this file to docs/PROJECT_SPECIFICATION.md in your new
project, then work through it top to bottom. Every <placeholder> should be replaced or
removed. Sections marked (optional) can be deleted if they genuinely don't apply — don't
delete them just because they're hard to answer. Keep this document updated as the project
evolves; it is the single source of truth for what the project is and why.
|
|
| Status |
Draft / In Review / Approved |
| Owner |
|
| Created |
|
| Last updated |
|
| Version |
0.1 |
1. Summary
A short (3–5 sentence) description of the project, written so that someone outside the
project can understand what it is and why it exists without reading further.
2. Problem Statement
- What problem are we solving?
- Who has this problem, and how do they experience it today?
- What happens if we do nothing?
3. Goals
Concrete, testable statements of what success looks like. Prefer measurable outcomes over
vague aspirations.
4. Non-Goals
Explicitly out of scope. This section prevents scope creep and mismatched expectations —
it is as important as the goals section.
5. Stakeholders
| Role |
Name |
Interest / Responsibility |
| Sponsor |
|
|
| Product owner |
|
|
| Tech lead |
|
|
| End users |
|
|
| Other |
|
|
6. Background & Context (optional)
Relevant history, prior attempts, related systems, or decisions that shape this project.
Link to the Value Stream Map if one has been produced —
it often surfaces the problem this project addresses.
7. Scope
7.1 In Scope
7.2 Out of Scope
8. Requirements
8.1 Functional Requirements
| ID |
Requirement |
Priority (Must/Should/Could/Won't) |
| FR-1 |
|
Must |
| FR-2 |
|
Should |
8.2 Non-Functional Requirements
Consider at least: performance, scalability, security, privacy, accessibility,
reliability/availability, maintainability, observability, compliance.
| ID |
Requirement |
Notes |
| NFR-1 |
|
|
| NFR-2 |
|
|
9. Users & Use Cases (optional)
Describe the primary user(s)/persona(s) and the key use cases or user stories.
- As a
<user type>, I want to <action>, so that <benefit>.
10. Architecture & Design
- High-level architecture (diagram, or link to one).
- Key components and their responsibilities.
- Technology choices and why they were made.
- Data model / schema, if applicable.
- External interfaces / APIs / integrations.
11. Constraints & Assumptions
| Type |
Description |
| Constraint |
e.g. must run on existing infrastructure, fixed deadline, budget cap |
| Assumption |
e.g. third-party API will remain stable, expected data volume |
12. Risks
| Risk |
Likelihood |
Impact |
Mitigation |
|
Low/Med/High |
Low/Med/High |
|
13. Milestones & Timeline
| Milestone |
Target date |
Notes |
| Project kickoff |
|
|
| Specification approved |
|
|
| MVP / first working version |
|
|
| Release |
|
|
14. Success Metrics / Acceptance Criteria
How will we know the project succeeded? Prefer measurable, falsifiable criteria over
"it works."
15. Open Questions
Track unresolved questions here so they don't get lost. Move resolved items to a decision
log or into the relevant section above.
| Question |
Owner |
Status |
|
|
Open |
16. Glossary (optional)
17. Revision History
| Version |
Date |
Author |
Summary of changes |
| 0.1 |
|
|
Initial draft |
