The Four Spec Types

Core Concepts

Spec-driven development organises work into four spec types that map to a chain: intent to design to implementation to verification. Each type is defined by what question it answers and what the agent does with it.

Product Spec

A product spec defines what needs to be built from the perspective of business goals and user needs. It answers the question: what problem are we solving, for whom, and how will we know we have solved it?

Primary content:

• User needs and the problem being addressed
• Features and scope (what is in, what is out)
• High-level acceptance criteria

Use it when: you are establishing shared understanding of a feature before any design or implementation begins. The product spec is the document that tells the agent -- and the team -- what success looks like at the user level.

Example in context: The My-Calendar team decides to add group booking. The product spec defines the user need (event organisers need to offer a single time slot to multiple attendees), the scope (a host can create a group session with a maximum attendee count; clients book individually until the cap is reached; the feature does not include waitlisting in this version), and the acceptance criteria (a confirmed group booking is visible to all attendees; the slot closes automatically when the cap is reached; the host receives a single consolidated notification).

A product spec does not describe how the system will behave step-by-step, how it will be built, or how it will be tested. Those belong to the three spec types that follow.

Functional Spec

A functional spec describes how the system should behave in terms of functionality. It answers the question: what does the system do, in what sequence, under what conditions?

Primary content:

• User flows and interaction paths
• System behaviour per feature (what the system does at each step)
• Business rules and edge cases

Use it when: you are translating a product requirement into a precise description of system behaviour. The functional spec is what an agent uses to understand the rules the system must enforce, including the cases that break the happy path.

Example in context: The My-Calendar functional spec for group booking defines the full user flow (client views the booking page, sees remaining spots, selects a time, submits their details, receives confirmation), the system behaviour at each step (spot count decrements on submission, not on page load; the slot locks for 60 seconds during checkout to prevent overselling), and the business rules (a client who has already booked cannot book again for the same session; a host can manually close a group slot before the cap is reached).

A functional spec does not describe the database schema, the API design, or which service handles the email. Those are implementation decisions that belong in the technical spec.

Technical Spec

A technical spec defines how the system will be implemented. It answers the question: what is the architecture, what are the interfaces, and what technology decisions govern the build?

Primary content:

• Architecture and system components
• APIs and data models
• System integrations and dependencies
• Technology stack decisions

Use it when: you are directing an agent to generate, review, or reason about code, configuration, or system design. The technical spec is the document a coding agent works from. Without it, the agent will make architectural decisions on its own, and those decisions may conflict with the existing system.

Example in context: The My-Calendar technical spec for group booking defines the data model (a GroupSession record linked to a Booking with a max_attendees integer and an attendee_count maintained via database trigger), the API surface (POST /group-sessions, POST /group-sessions/{id}/bookings, GET /group-sessions/{id}), the concurrency approach (row-level lock on the GroupSession record during the reservation transaction to prevent race conditions on the attendee count), and the integration dependency (SendGrid for confirmation email; existing BookingMailer service extended rather than replaced).

A technical spec does not contain test cases or QA scenarios. It describes what is being built, not how correctness is verified.

Test Spec

A test spec defines how correctness is validated. It answers the question: what scenarios prove the system behaves as specified, and what outcomes confirm each scenario passes?

Primary content:

• Test cases derived from the functional requirements
• QA scenarios covering UI, API, and integration paths
• Expected outcomes and validation rules

Use it when: you are asking an agent to generate test cases, review test coverage, or validate that an implementation satisfies the functional spec. A test spec turns acceptance criteria into executable verification.

Example in context: The My-Calendar test spec for group booking includes a UI scenario (a client navigates to a group session with one spot remaining, two clients attempt to book simultaneously, only one receives a confirmation and the other sees a "session full" error), an API scenario (POST /group-sessions/{id}/bookings returns 409 when attendee_count equals max_attendees), an integration scenario (the confirmation email is delivered within 10 seconds of a successful booking), and a validation rule (the attendee_count in the database must not exceed max_attendees under any concurrent load pattern, including retried requests).

A test spec is derived from the functional spec. If the functional spec changes, the test spec must be updated to match. An agent generating tests from a test spec will produce verification that is only as good as the spec it reads.

Key Points

• The four spec types map to a chain: Product (what and why) to Functional (how it behaves) to Technical (how it is built) to Test (how correctness is verified).
• Each type answers a different question. Using the wrong type means the agent has the wrong kind of information for the task.
• Functional specs and technical specs are commonly confused. Functional specs describe system behaviour from a user and business perspective. Technical specs describe implementation decisions.
• A test spec is derived from the functional spec, not the technical spec. It verifies behaviour, not implementation.
• All four types may exist for the same feature. They are not alternatives: they are layers.

---

Tools, Prompts, or Templates

Spec Type Decision Table

Before writing any spec, identify what question you are trying to answer. The table below maps each question to the correct spec type and shows how the decision applies to the My-Calendar scheduling platform. Use this table at the start of every AI task, not after the fact.

How to Use It

Work through the decision in this order:

1. Are you defining what to build and whether it solves a user problem? Use a product spec. Stop.
2. Are you describing how the system should behave, including rules and edge cases? Use a functional spec. Stop.
3. Are you specifying architecture, APIs, data models, or technology decisions? Use a technical spec. Stop.
4. Are you defining test cases, QA scenarios, or validation rules? Use a test spec. Stop.

If a task spans more than one type, split it into separate documents. A spec that tries to define system behaviour and implementation details at the same time will produce ambiguous agent output. Each layer should be readable independently.

Discussion Prompt Take one feature your team is currently working on. Which of the four spec types exists for it? Which ones are missing? Where is the agent filling gaps with assumptions because a layer has not been written?

---

Actionable Takeaways

• Before writing any spec, identify which of the four types applies and write the type at the top of the document.
• Use product specs to establish shared scope before design or implementation begins. An agent handed a feature without a product spec will define scope on its own.
• Keep functional specs and technical specs separate. Mixing behaviour and implementation in one document is the most common cause of agent output that is technically correct but functionally wrong.
• Derive test specs from the functional spec, not from the implementation. Tests that verify code rather than behaviour drift when the implementation changes.
• Share the decision table with your team and agree on a shared vocabulary. When everyone calls every document a "prompt" or a "brief", the distinctions collapse in practice and spec quality degrades.

---

Practical Examples

Example 1: Product Manager (Product Spec)

The My-Calendar product team is expanding into team accounts. A product manager is asked to scope the first release: shared calendar access for teams.

She writes a product spec. It defines the user need (a team administrator needs to give team members visibility into each other's booking pages without sharing credentials), the scope (read access to other members' availability, not write access; the feature does not include cross-member booking in this version), and the acceptance criteria (a team member can view another member's public availability; a team administrator can add and remove members from the team; removing a member immediately revokes their access).

The scope boundary in the product spec -- no cross-member booking -- prevents the agent from building a more complex system than the team has decided to ship. Without it, the agent would likely interpret "shared calendar access" to include booking on behalf of other members.

Example 2: Engineering Lead (Functional Spec)

An engineering lead needs to hand off the cancellation flow to a developer working with a coding agent. Before any code is written, she writes a functional spec.

It defines the user flow (a client navigates to their booking, selects cancel, confirms, and receives a cancellation email), the system behaviour at each step (the slot is marked available immediately on cancellation, not on email delivery; the host receives a notification within 30 seconds), and the business rules (cancellations within 24 hours of the booking start time trigger a late-cancellation flag on the client's account; a host can waive the flag manually).

The agent working from this spec generates the cancellation handler with the correct sequencing: slot release before notification, not after. The late-cancellation rule is implemented as an explicit check, not inferred.

Example 3: Senior Engineer (Technical Spec)

A senior engineer is responsible for the My-Calendar integration with Google Calendar. She writes a technical spec before directing the coding agent.

It defines the architecture (a CalendarSyncAdapter class isolated from the booking domain, called via an internal event after booking confirmation), the API used (Google Calendar Events API v3; OAuth 2.0 with offline access for token refresh), the data model (a CalendarSync record storing the external event ID mapped to the internal booking ID for idempotency), and the error handling approach (failures are retried up to three times with exponential backoff; after three failures, the booking is flagged in the admin dashboard rather than surfacing an error to the client).

Because the technical spec defines the idempotency approach explicitly, the agent does not generate a naive implementation that creates duplicate calendar events on retry.

Example 4: QA Lead (Test Spec)

A QA lead writes a test spec for the group booking feature before the implementation is handed to the QA team and a test-generation agent.

It includes a UI scenario (two clients attempt to book the last spot in a group session; one completes the booking and sees a confirmation; the other sees a real-time "session full" message without completing checkout), an API test case (POST /group-sessions/{id}/bookings with a concurrent load of 10 simultaneous requests returns exactly one 200 and nine 409 responses), an integration test (the host's Google Calendar event is created within 5 seconds of the first confirmed booking), and a validation rule (the attendee_count field in the database never exceeds max_attendees, verified by querying after each API test run).

The test spec is derived from the functional spec. Each test case maps back to a specific behaviour or business rule. The agent generating test code from this spec produces tests that verify behaviour, not implementation internals.

---

Implementation Workflow

Work through the following steps using the scheduling platform as your context. By the end, you will have matched real tasks to the correct spec type and written one opening section.

1. Read the four tasks below. Each one is a task from the My-Calendar team.

   • Task A: "Define what the waitlist feature needs to do for clients who miss out on a full group session."
   • Task B: "Describe the system behaviour when a waitlisted client is offered a newly available spot."
   • Task C: "Specify the database schema and API endpoint for the waitlist queue."
   • Task D: "Write the test cases that confirm a waitlisted client receives exactly one offer notification per available spot."

2. Apply the decision table to each task. Work through the four decision questions in order. Write down which spec type applies and one sentence explaining why.

3. Check your answers. Task A is a product spec (defining what the feature does and for whom). Task B is a functional spec (describing system behaviour and rules). Task C is a technical spec (architecture and data model). Task D is a test spec (QA scenarios and validation rules).

4. Pick one task. Choose the one closest to work your team is actually doing right now.

5. Write the opening section of the spec. For a product spec, write the user need and scope. For a functional spec, write the user flow and first two business rules. For a technical spec, write the data model and the API endpoint it exposes. For a test spec, write two test cases with expected outcomes.

6. Review what you wrote against the spec type definition. Does your opening section contain only the information that type of spec requires? If you included behaviour in a technical spec, or implementation details in a functional spec, move them to the correct document.

7. Keep this draft. You will extend it in the next lesson when you apply the full spec structure for all four types.