Spec Templates and Real-World Practice

Core Concepts

The Minimal Spec Template

A spec template is a pre-structured document with fixed sections and placeholder text. Its job is to remove blank-page friction and enforce the four fields agents need most: context, objective, constraints, and output format.

The minimal version covers every task type without becoming a bureaucratic burden. For a small bug fix, you fill in two sentences. For a complex feature, you expand each section. The structure stays the same.

Full Spec vs. Minimal Spec

Not every task needs the same level of specification. The difference between minimal and full format is scope and risk, not effort for its own sake.

The deciding question is: if the agent misunderstands one thing in this spec, how much do I need to redo? Small rework cost means minimal format is fine. Large rework cost means you invest in the full format.

Spec Libraries

A spec library is a folder in your repository (or shared workspace) that stores all your specs as named files. It serves two purposes: reuse and onboarding.

When a spec exists for a task you have done before, the next agent run starts from a tested foundation. When a new team member joins, the spec library shows them how the team works: not just what to build, but how to think about it.

The structure mirrors your product architecture. A scheduling platform organizes specs by domain: booking, availability, notifications, admin. This makes it easy to find the spec you need and to spot gaps.

Spec Versioning

Specs change. A functional spec written before a first implementation reflects assumptions. After the implementation, it should be updated to reflect what actually worked.

Treat spec files the same as code: commit them, diff them, and update them when the behaviour they describe changes. A spec that describes stale behaviour is worse than no spec, because agents will follow it faithfully in the wrong direction.

Key Points

• The minimal spec template removes blank-page friction and gives agents consistent structure on every task
• Choose minimal format for isolated, low-risk tasks; full format when misunderstanding costs significant rework
• A spec library organized by domain makes specs reusable and onboards new team members without extra documentation
• Spec files are versioned alongside code: update them when behaviour changes

---

Tools, Prompts, or Templates

Minimal Spec Template

Without a fixed starting point, every spec becomes a one-off. The minimal template below solves this by giving you the four fields that matter on every task: context, objective, constraints, and output format. Fill in what applies; remove what does not.

Use this template for any task that fits in a single agent session: a component, a function, a validation rule, a test case, or a scope definition.

---
spec_type: [product | functional | technical | test]
status: [draft | active | deprecated]
last_updated: YYYY-MM-DD
---

# Spec: [Task Name]

## Context
[One to three sentences describing the product area, the current state, and why this task exists now.]

## Objective
[One sentence: what the agent must produce or accomplish. Start with a verb.]

## Constraints
- [Hard constraint: technology, pattern, or rule the agent must not violate]
- [Scope boundary: what is explicitly out of scope for this task]
- [Style or convention: naming, formatting, or structural requirement]

## Output Format
[Describe the expected deliverable: file type, structure, level of detail, where it goes.]

## Acceptance Criteria
- [ ] [Specific, checkable condition the output must satisfy]
- [ ] [Second condition]
- [ ] [Edge case or error state that must be handled]

Scheduling platform example (booking page availability display):

---
spec_type: functional
status: active
last_updated: 2026-05-20
---

# Spec: Booking Page Availability Display

## Context
The scheduling platform shows a public booking page where clients select a time slot.
Availability windows are defined by the host and fetched from the availability service.
This spec covers the system behaviour for rendering those windows as selectable slots.

## Objective
Define how the booking page displays available slots, handles slot selection, and
responds when no slots exist for the selected date.

## Constraints
- Slots already booked must appear as disabled, not hidden
- A slot hold (60-second checkout window) must cause the slot to appear unavailable
  to other clients during that period
- No past-date slots may be selectable; the date picker must disable past dates

## Output Format
A functional behaviour description for the booking page slot display,
covering the happy path, the no-slots state, and the hold expiry behaviour.

## Acceptance Criteria
- [ ] Available slots render as selectable; booked and held slots render as disabled
- [ ] Clicking an available slot initiates a 60-second hold before checkout begins
- [ ] If the hold expires before the client confirms, the slot is released and
      the client sees an inline prompt to re-select
- [ ] When no slots are available for the selected date, the message
      "No available slots on this date. Try another day." is displayed
- [ ] Past dates are not selectable in the date picker

---

Spec Library Folder Structure

Without a named home for specs, they end up in scattered documents, Slack threads, or forgotten Notion pages. This folder structure gives your specs a permanent address in the repository, organized to match your product.

Create this folder at the root of your repository. Name each spec file after the task it describes, not after the date it was written. Dates belong in frontmatter, not filenames.

/specs
  /foundation
    mission.md
    style-guide.md
    tech-stack.md
  /booking
    slot-rescheduling.md             ← product spec
    client-booking-flow.md           ← functional spec
    booking-reservation-endpoint.md  ← technical spec
    booking-confirmation-tests.md    ← test spec
    booking-cancellation-policy.md
  /availability
    availability-window-crud.md
    calendar-sync-google.md
    conflict-detection-rules.md
  /notifications
    booking-confirmation-email.md
    reminder-email-24h.md
    cancellation-notification.md
  /admin
    dashboard-metrics-overview.md
    host-settings-page.md
  /group-booking
    group-booking-product.md         ← product spec
    group-booking-functional.md      ← functional spec
    group-session-endpoint.md        ← technical spec
    group-booking-tests.md           ← test spec
  _template.md

Usage rules:

• _template.md is the minimal spec template, kept at the root of /specs for quick copy
• Each domain folder matches a product domain: one folder per bounded context
• File names use lowercase kebab-case and describe the specific task, not the general area
• A feature with all four spec types in the same domain folder makes the coverage visible at a glance
• Archive deprecated specs by adding status: deprecated to frontmatter; do not delete them

---

Actionable Takeaways

1. Copy the minimal spec template into a _template.md file in your repository today. The first time you need a spec, it is already there.
2. Create a /specs folder with at least two domain subfolders that match your current project. Naming the structure is faster than you expect and pays off immediately.
3. Pick one task you are working on this week. Write a minimal spec for it before prompting the agent. Compare the output quality to your last unspecced prompt.
4. After your next agent session, update the spec to reflect what actually worked. One sentence is enough: add a note to the constraints or output format section.
5. If a task feels too complex for the minimal template, use that friction as a signal: write the full format. The discomfort of expanding the spec is cheaper than debugging a misaligned output.

---

Practical Examples

Example 1: Minimal spec for a small utility (engineer)

An engineer on the scheduling platform needs a function that formats a duration in minutes into a human-readable string: "30 min", "1 hr", "1 hr 30 min". This is a single function with no dependencies and low rework cost. Minimal format is correct.

---
spec_type: technical
status: active
last_updated: 2026-05-20
---

# Spec: Format Duration Utility

## Context
The booking confirmation UI displays appointment lengths.
Durations are stored as integers in minutes.
A utility function is needed to convert these to display strings.

## Objective
Write a pure TypeScript function `formatDuration(minutes: number): string`
that converts a duration in minutes to a human-readable string.

## Constraints
- Output format: "30 min", "1 hr", "1 hr 30 min" (no seconds, no decimal hours)
- Input is always a positive integer; no validation needed
- No external dependencies

## Output Format
A single exported function in `src/utils/formatDuration.ts`,
with a co-located test file covering the core cases.

## Acceptance Criteria
- [ ] Returns "30 min" for input 30
- [ ] Returns "1 hr" for input 60
- [ ] Returns "1 hr 30 min" for input 90
- [ ] Returns "2 hr" for input 120

This spec takes three minutes to write. The agent produces a correct implementation on the first pass with no clarifying questions because every constraint is explicit.

---

Example 2: Scaling up to full format (product manager + engineering lead)

The team now needs to specify the group booking feature: a multi-step capability involving a product decision, a system behaviour definition, an implementation design, and a test plan. One misunderstood layer affects the others. The team writes all four spec types for the feature.

The product manager writes the product spec first, defining the user need (event organisers need a single booking page for multiple attendees) and the scope (attendees book individually until a cap is reached; no waitlist in v1; no cross-host group sessions). The engineering lead then writes the functional spec: the user flow from opening the group session page to receiving a confirmation, the system behaviour (spot count decrements on booking, not on page load; slot locks for 60 seconds during checkout), and the business rules (a client who has already booked cannot book again for the same session).

A senior engineer writes the technical spec: the GroupSession data model, the concurrency approach (row-level lock on the group session record to prevent the attendee count from exceeding the cap under concurrent load), and the API endpoints. The QA lead writes the test spec last, deriving test cases from the functional spec: the concurrent booking scenario, the 409 response case, and the attendee count invariant.

Each spec is written in the correct order. The product spec shapes what the functional spec needs to cover. The functional spec shapes what the technical spec needs to enforce. The technical spec shapes what the test spec needs to verify. Each layer takes 10 to 20 minutes to write and prevents the cost of reworking a misunderstood assumption at a later stage.

---

Example 3: Choosing the format (technical director)

A technical director reviews four incoming tasks and decides which format each needs:

The director writes minimal specs for the two low-risk tasks in the same time it would have taken to explain them in a Slack message, then spends focused time on the two full specs where the cost of ambiguity is real.

---

Implementation Workflow

This exercise takes 25 to 30 minutes. You will write a real spec for a real task using the minimal template, run an agent session with it, evaluate the output, and update your spec library.

1. Set up your spec library. Create a /specs folder in your project (or a scratch folder if you are working outside a codebase). Inside it, copy the minimal spec template from the Tools section above into a file named _template.md. Create at least two domain subfolders that match a product you are currently working on. If you do not have a current project, use the scheduling platform and create /specs/booking and /specs/notifications.

2. Pick a real task. Choose one task from your current work that fits in a single agent session: a component, a function, a validation rule, or a set of test scenarios. If you are using the scheduling platform, choose one of these: the 24-hour reminder email functional spec, the host settings form validation rules, or the slot confirmation modal component technical spec.

3. Write the spec using the minimal template. Copy _template.md to the appropriate domain folder. Name the file after the task in kebab-case. Fill in all five sections: context, objective, constraints, output format, and acceptance criteria. Time yourself. If it takes more than ten minutes for a small task, your objective or constraints are too vague: rewrite them as single sentences.

4. Decide on format. Before running the agent, apply the format decision test: if the agent misunderstands one thing, how much rework does that create? If the answer is more than an hour, expand your spec to the full format. If not, proceed with minimal.

5. Run the agent session. Open your agent (Claude, Claude Code, or equivalent). Paste the full spec as your first message, prefixed with: "Act on the following spec. Ask clarifying questions if any acceptance criterion is ambiguous before writing code." Review any clarifying questions the agent asks. If it asks about something you already specified, your spec has a gap: note it.

6. Evaluate the output against acceptance criteria. Check each acceptance criterion in your spec. Mark each as passed or failed. For any failed criterion, identify whether the failure was caused by an ambiguous spec field or a genuine agent error. If the spec was ambiguous, rewrite that field.

7. Update the spec. Add one to three sentences to the constraints or output format section that reflect what you learned from this session. Change the status to active and update last_updated. Commit the spec file alongside any generated code.

8. Log the decision. In a comment at the bottom of your spec file or in a team channel, write one sentence: what format you used, and why. This builds the shared intuition your team needs to choose format confidently on the next task.