How Many Ways Are There to Understand the Word “Spec”?
Do you know different people understand the word “spec” differently?
AI coding and spec-driven development have made the word ‘spec’ popular, yet we understand it in wildly different ways. It may refer to a product requirements document, a behavioral specification, an architectural design, or even an implementation plan. This ambiguity can create a false sense of alignment — and while humans can ask for clarification, coding agents may simply fill in what was left unsaid.
If you don’t have membership subscription, you can read it full at https://tien8436.substack.com/p/how-many-ways-are-there-to-understand?r=2186ie&utm_campaign=post-expanded-share&utm_medium=web
Understood as Product Intent — a Product Requirements Document
In many product teams, “spec” means something close to a PRD: the problem, the users, the scope, the outcome, and what success looks like. The primary job of a PRD is to capture product intent.
Example: Product Intent in a PRD
## Problem Statement
Task discussions often require another member's attention, but comment authors
currently need to contact that person through a separate channel.
This separates the request from its context, creates duplicate conversations
and makes it difficult for the recipient to return to the relevant comment.
## Solution
Allow a comment author to mention another member by typing @ and selecting an
eligible member.
When the comment is submitted, the mentioned member receives an in-app
notification that links directly to the task and originating comment. Email is
sent when the recipient's notification preferences allow it.
## User Stories
1. As a task participant, I want to search for a member by typing @ so that
I can address them without leaving the comment composer.
2. As a task participant, I want suggestions limited to people who can access
the task so that I do not accidentally reference private work to an
unauthorized person.
...However, product intent does not translate to product behavior. “Customers should be able to cancel an order” leaves a surprising amount of room for creativity. Can they cancel one item or the whole order? What happens to a voucher? What if payment has already been captured, or the warehouse begins packing while the customer is pressing the button? A product document may leave all of that open without being incomplete; it simply is not yet a behavioral specification. The confusion begins when both are called the spec.
As a Behavioral Contract — an Functional Requirements Document
For business analysts, QA and many product teams, a spec describes observable behavior: rules, acceptance criteria, inputs, outputs, exceptions, edge cases. This material used to live in a requirements specification or a set of use cases, and among current tools OpenSpec holds the firmest line on keeping it apart from everything else.
“A spec is a behavior contract, not an implementation plan.” — OpenSpec concepts
Under that definition, a spec may require cancelling an order initiates a refund, without deciding whether the refund happens synchronously, through a message queue, or by a small ceremonial committee inside the payment service. That belongs to the design. The distinction is worth recognizing, because behavior should survive changes in implementation: we can replace the broker without changing the rule that a cancelled order gets refunded.
Example: A Behavioral Contract in OpenSpec
## ADDED Requirements
### Requirement: Suggest eligible mention recipients
The system SHALL suggest only active members who are authorized to access the
task containing the comment.
#### Scenario: Search for an eligible member
- GIVEN Mina is active and can access the task
- WHEN Alice searches for Mina from the task comment composer
- THEN Mina SHALL appear as a mention optionExample: A Behavioral Contract in Spec Kit
# Feature Specification: Comment Mentions
## User Scenarios & Testing
### User Story 1 — Mention a teammate in a comment (Priority: P1)
As a workspace member, I can mention another member in a task comment
so that I can draw their attention to a specific discussion.
Why this priority:
Directly enables the primary collaboration use case.
Independent Test:
Create a comment containing "@Mina". Verify that Mina receives one
in-app notification linking to the comment.
Acceptance Scenarios:
1. Given Alice and Mina can access Task 42,
when Alice submits "Can you review this, @Mina?",
then Mina receives one notification linked to Task 42 and the comment.
2. Given Alice mentions herself,
when Alice submits the comment,
then no notification is created for Alice.
3. Given Bob cannot access Task 42,
when Alice searches for "@Bob",
then Bob is not included in the suggestions.Understood as Solution Design — Architecture
For some tech leads and architects, “spec” means the solution: components, data models, APIs, state transitions, failure handling, and deployment. Their toolset includes documents such as C4 system context diagrams, sequence diagrams, entity-relationship diagrams, RFCs, and more for modeling the solution.
An architecture or design spec decides the logical or physical components that need to be built to realize the behaviors in the specs above. These can range from where we should put the database — down to the physical infrastructure — to how we should model business logic abstractly in code.
Example: Solution Design in a C4 Diagram
Example: Solution Design in a Sequence Diagram
The Skip to Implementation Plan Trend
However, from what I have observed, many Spec-Driven Development tools capture architecture primarily as prose descriptions or instructions rather than traditional artifacts such as C4, sequence or ER diagrams. The spec in this school usually combines lightweight PRD, architectural descriptions and implementation plan, in one or multiple files.
Superpowers uses a *-design.md file containing elements of both a PRD and an architectural design, followed by a separate implementation plan with detailed instructions - sometimes down to the file or even line level. Spec Kit places much of the same material one step downstream, in a plan that follows the spec.
Example: Solution Design and an Implementation Plan in obra/superpowers
docs/superpowers/
├── specs/
│ └── 2026-08-03-comment-mentions-design.md
└── plans/
└── 2026-08-03-comment-mentions.md# Comment Mentions Design
## Goal
Allow users to mention workspace members in task comments using `@name`.
Mentioned users receive an in-app notification and, depending on their preferences,
an email notification.
## Scope
- Suggest eligible workspace members while typing.
- Do not notify users who mention themselves.
- On comment edits, notify only newly added mentions.
- Do not notify users who cannot access the task.
...
## Approach
...
## Data Model
...
## Create Comment Flow
1. Client submits comment text containing mention tokens.
2. API extracts unique user IDs.
3. API validates that each user can access the task.
4. Comment and mention records are saved in one transaction.
5. After commit, notification jobs are queued.
...
## Error Handling
Invalid or inaccessible user IDs are rejected with `400 INVALID_MENTION`.
...
## Testing
- Deduplicate repeated mentions.
- Exclude self-mentions.
- Verify email preference handling.
...# Comment Mentions Implementation Plan
## Task 1: Add mention parsing
Files:
- `server/comments/parseMentions.ts`
- `server/comments/parseMentions.test.ts`
1. Write a failing test for parsing `@[Jane Doe](user_123)`.
2. Implement extraction of unique user IDs.
3. Add tests for malformed and duplicate tokens.
4. Run:
npm test -- parseMentions
5. Commit:
git commit -am "feat: parse user mentions from comments"
## Task 2: Persist comment mentions
...
## Task 3: Validate mentioned users
Files:
- `server/comments/mentionService.ts`
- `server/comments/mentionService.test.ts`
...“Spec” Hides Which Meaning We Intend
I’m fine with any of these meanings. I don’t want to formally define it. I think each will be useful in a different situation. To me, the danger is not that there is no single, rigid definition. The danger is that the word creates a false sense of alignment, leaving open interpretation for involved parties. Until recently, humans managed pretty well without caring much about these distinctions. Unlike humans, however, a coding agent cannot reliably resolve every decision left implicit. Given “Customers should be able to cancel an order”, a human can ping you and ask “Can they cancel one item or the whole order?”. Left alone with the same request, a coding agent may invent a bad decision at worst, or make a different good decision on every invocation at best.
So next time someone says the spec is ready, I will ask:
Which one- product intent, behavioral contract, solution design, or implementation plan?
Not to enforce precision, not even for me, but for the coding agents I run.