Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions src/docs/Ways-of-Working/Spec-Driven-Development.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ A spec **contains**:
- **Outcomes and impact** β€” the result in the world, and its expected effect on delivery (see [Impact](#impact)).
- **Users and jobs** β€” who uses this and the job it gets done.
- **Scope** β€” what is included, and an explicit list of what is out of scope.
- **Non-goals** β€” outcomes it deliberately does not pursue, named so its intent is not misread; distinct from out of scope, which bounds this change.
- **Requirements** β€” what the capability does and the qualities it must hold, functional and non-functional (see [Requirements](#requirements)).
- **Acceptance criteria** β€” observable behavior that verifies the requirements (see [Acceptance criteria](#acceptance-criteria)).
- **Constraints, assumptions, and dependencies** β€” the boundaries it respects and the work, access, or decisions it waits on.
Expand All @@ -57,6 +58,12 @@ A spec **excludes** β€” this is the design's job:

The altitude test: push detail *down* into the design, and push scope *up* into the epic. If a sentence would change when the team picks a different library, it belongs in the design, not the spec. This is the same rule the [Issue Format](Issue-Format.md) applies to issues β€” describe the *what* and *why*, never the *how*.

## Specify the minimum

A spec fixes the smallest set of requirements that make the capability correct and verifiable, and leaves every other choice to the design and the people building it. Over-specification is waste: it commits the team to decisions before they must be made, and every detail the spec pins is one more thing that rots when the implementation moves. Fix what must be agreed; leave the rest open.

This is [Lean Software Development](Principles/Planning-and-Delivery.md#lean-software-development) and YAGNI applied to intent β€” the fewer things a spec pins, the longer it stays true and the more freedom the people building it keep. The altitude test above is how the principle is applied in practice.

## Requirements

Requirements are testable statements of what must be true β€” never how it is built. Write them with the [BCP 14](https://www.rfc-editor.org/info/bcp14) keywords β€” **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, **MAY**, and the rest of the set β€” in uppercase, where they carry their normative meaning ([RFC 2119](https://www.rfc-editor.org/rfc/rfc2119), [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174)).
Expand Down Expand Up @@ -164,6 +171,10 @@ Copy these skeletons to start a `spec.md` and its `design.md`. Every section is

- <...>

## Non-goals

- <an outcome someone might expect this to pursue that it deliberately does not β€” and why>

## Functional requirements

### FR1 β€” <what the capability does, behavioral, testable, no technology> { #fr1 }
Expand Down