Spec-driven development is no longer just a process preference for enterprise teams with heavyweight requirement documents. As AI coding agents make implementation dramatically faster, a clear, maintained specification is becoming the difference between shipping a useful feature and producing a large, expensive misunderstanding.

A recent discussion in r/SaaS captures the shift well. The author, a software-agency leader with more than a decade of client work, described moving from risky fixed-scope projects toward a workflow where detailed specs are agreed on, stored in the repository, maintained alongside code, and made searchable for both people and AI agents. The original post is valuable not because its folder structure is revolutionary, but because it identifies the operational problem product teams now need to solve: AI can accelerate coding, but it cannot create shared intent on its own. (reddit.com)

Why specifications become more important when AI writes code

The usual argument against thorough documentation is that it slows teams down. That argument made more sense when the main bottleneck was translating an agreed idea into working code. When a developer needed days to build a first version, ambiguity could sometimes be discovered and corrected gradually through the implementation process.

Agentic coding changes the economics. A tool can now inspect a repository, generate a proposed implementation, add tests, refactor adjacent code, and prepare a pull request in a short span. The bottleneck shifts upward: What exactly should be built? Which existing behavior must remain untouched? What trade-offs are acceptable? Which business rule wins when two rules conflict?

That is the central case for spec-driven development. It does not mean turning every product decision into a 40-page requirements document. It means creating a structured, behavior-oriented source of truth that humans can review and AI coding agents can use as durable context. Martin Fowler’s recent overview of the category makes an important distinction here: “spec-driven” is an overloaded term, but its common thread is using a specification to guide an AI agent before code is written. (martinfowler.com)

The practical consequence is simple: faster generation increases the cost of vague instructions. If a poorly framed request once resulted in a half-day of incorrect work, it may now result in a convincing but incorrect multi-file change set, test suite, migration, and user-interface update. That output can look complete enough to escape casual review.

Speed amplifies both clarity and confusion

AI does not merely make good teams faster. It also allows teams to operationalize fuzzy thinking at a higher velocity. A prompt such as “add team billing” can conceal unresolved questions about plan ownership, invoice access, seat changes, proration, failed payments, permissions, currency, tax, cancellation, data retention, and support workflows.

A strong specification turns that vague request into explicit decisions. It records what is in scope, what is deliberately excluded, what must be true after the feature ships, and how the team will know it works. The AI then has a useful brief rather than a guess.

The spec is not a substitute for code

The opposite mistake is treating a spec as a magical higher-level replacement for engineering judgment. Code remains the executable truth of what the system currently does. As Martin Fowler has long argued, code is primary documentation only when it is clear enough to explain itself; that does not eliminate the need for other documentation that explains rationale, boundaries, and business intent. (martinfowler.com)

A useful division of responsibility looks like this:

  • Specifications explain intended behavior and decisions.
  • Tests demonstrate expected behavior in executable form.
  • Code implements the behavior.
  • Operational telemetry shows how the behavior performs in production.
  • Release notes and support material explain user-facing change.

The goal is not to duplicate every detail across all five places. The goal is to ensure the most important decisions have a home, and that the homes point to one another.

The r/SaaS workflow: put living specs in the repository

The r/SaaS author describes a lightweight but disciplined repo-native model. Their team keeps a ./specs directory, a table of contents that summarizes and links to the individual specifications, and an AGENTS.md instruction file that tells coding agents to maintain those documents after relevant changes. They also created a small search and AI question-answering interface over the Markdown files, and split documents once they passed a 500-line threshold. (reddit.com)

That pattern is more useful than a generic call to “document better” because it solves several common failures at once.

First, it puts documentation next to the work. A specification stored in a disconnected project-management system can be useful during planning but invisible during implementation. A Markdown file versioned with the repository is present in code review, branch history, pull requests, and local development environments.

Second, it gives agents a discoverable place to start. An agent cannot reliably infer a company’s commercial rules, product language, legacy constraints, or architectural decisions merely by reading application code. A short instruction file can direct it to the relevant durable context.

Third, it treats documentation drift as a delivery concern rather than an editorial chore. If a feature changes the contract but the spec does not change, the pull request is incomplete. That is a much better default than hoping someone updates a wiki later.

Why an index matters more than a giant knowledge file

Many teams react to AI tools by building a huge AGENTS.md, CLAUDE.md, or README packed with rules, architecture notes, commands, and historical context. It feels efficient at first because there is one file to update. It becomes inefficient when it turns into a long, contradictory document that neither people nor agents can navigate confidently.

OpenAI’s Codex guidance supports the idea of scoped, repository-aware instructions: discovered AGENTS.md files are supplied in root-to-leaf order, so instructions can be specific to the relevant portion of a project rather than monolithic for the whole codebase. (developers.openai.com) A separate index plus focused specifications fits that model well.

A table of contents is therefore not administrative overhead. It is the retrieval layer for your project’s institutional memory. A good index helps a contributor answer three questions in under a minute:

  1. What domains and capabilities does this system have?
  2. Which document is authoritative for the change I am about to make?
  3. What constraints or related decisions should I read before editing?

The original post’s 500-line split rule is also sensible as a heuristic. The exact limit matters less than the discipline behind it. Documents should be short enough to scan, targeted enough to retrieve, and structured enough that a human reviewer can recognize whether they still match the code.

What a useful AI-ready specification actually contains

A specification should not be a prose dump generated from a feature request. It should lower ambiguity for the people making decisions, the developers implementing them, the reviewers approving them, and the agent asked to work on them.

For most SaaS features, a practical spec can be written in Markdown and organized around behavior rather than around technical tasks. The document needs enough precision to constrain implementation without freezing every internal design choice too early.

A durable specification template

Use this structure as a starting point:

# Feature: Team invitations

## Status
Draft | Approved | Implemented | Superseded

## Problem
What user or business problem are we solving? Why now?

## Scope
What is included in this change?

## Non-goals
What is explicitly not included?

## Users and permissions
Who can perform each action? Who can view each result?

## Behavior
- Given ... when ... then ...
- Edge cases and failure states
- Validation and limits

## UX and copy
Key screens, messages, terms, and links.

## Data and integrations
Data created or changed, external systems, migration needs, privacy concerns.

## Acceptance criteria
Observable conditions required for approval.

## Technical constraints
Architecture boundaries, performance targets, security requirements, compatibility limits.

## Open questions and decisions
Owner, decision date, answer, and consequences.

## Related artifacts
Links to tests, migrations, API contracts, designs, issues, and superseded specs.

This template helps distinguish several things teams often blur together. The problem statement explains why the feature exists. Scope and non-goals protect the delivery boundary. Acceptance criteria define what success means. Technical constraints explain the implementation space without prematurely dictating every line of code.

The “open questions and decisions” section is particularly important. A question hidden in Slack or a chat transcript is not a decision. If the answer affects behavior, revenue, compliance, support, or architecture, write it down in the spec with an owner and date. That makes later revisions intelligible instead of mysterious.

Write behavior, not implementation theater

Consider a weak requirement: “Build invite links for teams.” It is too vague for reliable human estimation and far too vague for agentic execution.

A better specification could say that workspace owners may create a single-use or multi-use invitation link; links expire after a configurable period; a link does not grant access until the recipient authenticates; memberships inherit the inviter-selected role; revoked links must fail safely; and invitation events must be visible in an audit log. It can also state non-goals, such as not supporting domain-restricted auto-join in the first release.

That is specific enough for implementation and review, while leaving room for the engineering team to choose tables, services, and UI components. It also creates obvious test scenarios.

Fixed scope, time and materials, and the commercial value of clarity

The source post began with a familiar agency experience: fixed-price work can go badly when client expectations are not aligned or when effort is underestimated. The author’s response was to establish a defined scope first, then move into a time-and-materials engagement. (reddit.com)

This is not only a contract lesson. It is a product-management lesson.

Fixed scope does not mean the product will never change. It means the parties share a snapshot of what will be delivered, what assumptions make that delivery possible, and what counts as a change. When a request changes, the team can evaluate it honestly rather than quietly absorbing it into an estimate that no longer reflects reality.

Specs turn scope change into a visible conversation

Without a specification, scope creep is often emotionally framed: “It is just one small adjustment.” With a specification, the question becomes operational: Does this alter an approved behavior, add a user group, introduce a new integration, change a non-goal, or invalidate an acceptance criterion?

That reframing is valuable for founders as well as agencies. A founder may be both client and product owner, but the same mismatch exists between what is imagined, what is requested, and what the team believes it is building. Specs make the mismatch easier to surface before it becomes code.

Use a simple change protocol:

  1. Identify the impacted specification. Do not describe the change only in an issue or chat.
  2. State the new behavior and affected non-goals. Make the changed boundary explicit.
  3. Assess implementation, data, test, and rollout consequences.
  4. Approve the revised decision. This can be lightweight, but it must have an accountable owner.
  5. Update code, tests, docs, and release communication together.

The point is not bureaucracy. It is to prevent invisible product decisions from masquerading as small engineering tasks.

How AI changes the specification workflow

AI is extremely useful in specification work, but the best use is not asking it to manufacture certainty. The best use is making uncertainty visible, organizing information, and tracing consequences across a codebase.

The r/SaaS author says their team can quickly draft specs in the agentic era, then review them carefully before moving approved documents into the codebase. That sequence matters. Generation is cheap; accountable review is the quality gate. (reddit.com)

Martin Fowler’s work on structured prompt-driven development reaches a similar conclusion: agent tools can make individual developers faster, but ambiguous requirements are also implemented faster, which raises review and integration risk. (martinfowler.com)

High-value jobs for AI during discovery

Use an agent to help with work that benefits from broad retrieval and structured challenge:

  • Turn interview notes, support tickets, and issue discussions into a first draft of a problem statement.
  • Extract unresolved decisions, contradictory statements, and vague terms such as “fast,” “secure,” “admin,” or “simple.”
  • Map a proposed behavior to relevant routes, models, services, tests, feature flags, and documentation.
  • Generate edge-case tables and acceptance-test candidates.
  • Compare the proposed spec with the current code to identify likely incompatibilities.
  • Draft a concise change summary for stakeholders after a human approves the actual decision.

These tasks reduce blank-page work. They do not remove the need for a product owner, domain expert, security reviewer, or engineer to judge the result.

Low-value or dangerous uses

Avoid treating an AI-generated document as evidence that a decision has been made. Models can fill gaps with plausible assumptions, especially where terminology is inconsistent or the codebase reflects legacy behavior.

Also avoid prompting an agent with “implement the spec” when the spec has no explicit acceptance criteria, no ownership model, and no non-goals. That instruction effectively delegates product judgment to a probabilistic system. You may get working code, but you cannot claim you got aligned product behavior.

A healthier pattern is to ask the agent to return a plan in a fixed format before editing:

Read the relevant specs and code. Do not modify files yet.
Return:
1. The intended behavior in your own words.
2. Assumptions that are not explicitly specified.
3. Files and systems likely affected.
4. Risks to existing behavior.
5. A proposed test plan.
6. Questions that require a human decision.

This makes the agent’s interpretation inspectable. It also lets the team catch mismatched context before a large patch appears.

Repository structure: a practical model that scales

A specs folder alone does not create a system. The folder needs conventions for ownership, discoverability, change history, and review.

Here is a structure that works for a typical application repository:

/specs
  TABLE_OF_CONTENTS.md
  /product
    authentication.md
    billing.md
    team-management.md
  /platform
    api-contracts.md
    background-jobs.md
    observability.md
  /decisions
    adr-001-auth-provider.md
    adr-002-tenant-boundaries.md
  /runbooks
    incident-response.md
    data-repair.md
AGENTS.md
README.md

The exact taxonomy can vary. A smaller startup may begin with three files. A larger product may organize by bounded context, platform concern, or customer journey. What matters is that documents have stable names and a predictable location.

Keep AGENTS.md short and directional

Your root AGENTS.md should describe how an agent works in the repository, not attempt to explain every product rule. Good content includes:

  • Commands for setup, testing, linting, type checking, and local verification.
  • Architectural boundaries the agent must respect.
  • A directive to read relevant specs before planning or changing behavior.
  • A directive to update a spec when a behavior or decision changes.
  • Rules for database migrations, secrets, dependencies, and generated files.
  • A requirement to call out ambiguity instead of inventing business rules.

OpenAI explicitly recommends clear documentation, reliable tests, and configured environments for better Codex performance, while its current tooling supports repository instruction files such as AGENTS.md. (openai.com)

A short instruction file with strong links is more durable than a sprawling manifesto. If a rule only applies to the billing domain, locate it in the billing spec or a directory-specific instruction file. That reduces irrelevant context and makes updates safer.

Treat the table of contents as a product map

Do not limit TABLE_OF_CONTENTS.md to a bare list of filenames. Add a one- or two-sentence summary, owner, status, and last-reviewed date for each document. This makes the file useful to a new engineer, a founder returning to an old area, and an agent trying to locate context.

For example:

| Spec | Status | Owner | Summary |
|---|---|---|---|
| product/billing.md | Implemented | Product + Engineering | Plans, trials, seat changes, invoices, cancellation, and payment failure behavior. |
| product/team-management.md | Draft | Product | Roles, invitations, membership lifecycle, and audit events. |
| decisions/adr-002-tenant-boundaries.md | Accepted | Engineering | Rules that prevent cross-workspace data access. |

This is a small investment with a large retrieval payoff. It also makes stale documents conspicuous rather than silently abandoned.

Prevent documentation drift with delivery gates

The hardest part of spec-driven development is not authoring the initial document. It is keeping it true after six months of bug fixes, shortcuts, product experiments, and customer-specific exceptions.

The solution is not demanding that every comment change update documentation. It is defining which events require a spec review and building that expectation into pull requests.

Use a documentation impact check in every PR

Add a pull-request checklist such as:

  • Does this change user-visible behavior?
  • Does it alter an API contract, permission rule, billing rule, or data-retention rule?
  • Does it introduce or remove a product limitation?
  • Does it change an architectural decision recorded in an ADR?
  • If yes, which spec or decision record was updated?
  • If no update is needed, why not?

This does two things. It gives authors a moment to consider the system beyond the diff, and it gives reviewers permission to ask about missing context without sounding procedural.

Make tests and specs cross-reference each other

A spec should not become a parallel, untested fantasy. Link key acceptance criteria to test names, API contract tests, end-to-end scenarios, or monitoring checks. Tests should also point back to the behavior they are protecting when the reason is non-obvious.

For example, a test called cannot_transfer_workspace_ownership_to_pending_invitee is more valuable if the relevant team-management spec describes why this rule exists. The test tells you the behavior is guarded; the spec tells you why the rule matters and whether it should change.

This reinforces a mature view of documentation: code and tests can explain mechanics, but they cannot reliably preserve every product decision, rejected alternative, or commercial constraint. Architecture guidance likewise emphasizes that the important aspects of a system are the difficult-to-change decisions; those are precisely the ones worth documenting explicitly. (martinfowler.com)

Search, chat, and the right way to build a knowledge layer

The source author mentions building a small web interface with search and AI question answering over the repository specifications. (reddit.com) That can be a powerful convenience layer, especially when sales, support, design, and engineering need fast answers about system behavior.

But the key design principle is that the Markdown files remain the canonical artifacts. The search application and chat interface are views over the source of truth, not new places where policy quietly evolves.

A safe question-answering workflow

If you build an internal spec assistant, make it answer with citations to the exact document and heading it relied on. It should distinguish between an explicit answer, an inference, and missing documentation.

A trustworthy response style is:

  • Documented: “Workspace owners can revoke invitation links; see product/team-management.md, Invitation lifecycle.”
  • Inferred: “The code suggests this behavior applies to enterprise plans, but the billing spec does not state it.”
  • Unknown: “No current spec defines whether an invite can be resent after expiry. This needs a product decision.”

That approach prevents the assistant from turning undocumented behavior into apparent policy. It is especially important for regulated, financial, privacy-sensitive, or customer-contractual workflows.

Do not confuse retrieval with governance

A vector database, embeddings, or a chat interface can make documents easier to find. None of them guarantees that the documents are current, approved, or correct. Governance still comes from ownership, review status, version control, and delivery discipline.

The most effective teams solve this in order: first establish a clean source of truth; then make it searchable; then add AI retrieval and workflow automation. Reversing that order tends to produce a polished interface over a confusing knowledge base.

Community signal: the pattern is emerging, not settled

The supplied r/SaaS snapshot did not include substantive top-comment reactions, so there is no meaningful community consensus from that thread to report. The post should be read as an experienced practitioner’s workflow rather than proof that one folder layout is the industry standard. (reddit.com)

Still, the wider developer conversation points in the same direction. A recent OpenAI developer-community discussion describes a closely related pattern: keep AGENTS.md short, use it as a navigation entry point, and place durable repository knowledge in structured docs instead of trying to load every detail into the agent instruction file. (community.openai.com)

The broader lesson is not “everyone should adopt /specs tomorrow.” It is that agent-assisted development creates a persistent-context problem. Chat history is temporary, individual memory does not scale, and code alone often does not reveal why a behavior exists. Externalizing decision context into a living document is one response to that problem. (martinfowler.com)

When spec-driven development is the wrong tool

Not every task deserves a formal specification. Requiring one for trivial copy edits, a narrowly scoped bug with an obvious failing test, or a dependency patch can create drag with no corresponding gain.

Use judgment based on reversibility, blast radius, ambiguity, and cost of failure. The more difficult a decision is to reverse, the more valuable a spec becomes.

A lightweight issue or pull-request description is usually enough when the change is:

  • A straightforward bug fix with a clear expected result.
  • Internal refactoring with no intended behavioral change.
  • A localized visual adjustment governed by an established design system.
  • A dependency update with a known compatibility path.

A maintained specification is warranted when the change affects:

  • Pricing, subscriptions, entitlements, or account ownership.
  • Authentication, authorization, privacy, security, or auditability.
  • Public APIs, integrations, imports, exports, or data migrations.
  • Cross-team workflows or language that support and sales will need to explain.
  • Product behavior that is difficult to infer from code alone.

The point is proportionality. A two-page Markdown document with crisp acceptance criteria is often better than an elaborate process. Conversely, a one-line ticket is insufficient when it hides a major commercial or technical decision.

A 30-day adoption plan for SaaS teams

If your team currently relies on tickets, chat messages, and prompt history, do not attempt to document the entire product at once. Start by using the approach on the next feature with meaningful ambiguity or risk.

Week 1: create the operating system

Create /specs, write a table of contents, and add a concise AGENTS.md. Pick one high-value domain such as billing, access control, tenant boundaries, or onboarding. Write the first spec from current reality, not from an imagined ideal.

Week 2: use it on a live feature

Before implementation, have product and engineering review the spec together. Ask an AI agent to identify unanswered questions, affected modules, and test scenarios. Keep the answers in the document rather than only in the conversation.

Week 3: connect it to review

Add the documentation-impact checklist to pull requests. Require a link to the relevant spec for behavior-changing work. During review, check whether implementation and acceptance criteria still agree.

Week 4: improve retrieval and ownership

Add owners, statuses, and last-reviewed dates. Build simple local search before investing in an AI chat interface. At the end of the month, review which documents were actually used, which sections were ignored, and where contributors still had to ask the same questions repeatedly.

Success is not measured by the number of pages written. Measure whether estimates become clearer, reviews find fewer “what should happen?” gaps, onboarding gets easier, and agents require fewer corrective loops.

The strategic payoff: specifications as organizational memory

The real promise of spec-driven development is not that agents will write all your code. It is that teams can preserve decisions in a form that remains useful as people, tools, and codebases change.

For agencies, that memory protects the boundary between an agreed deliverable and a newly requested feature. For SaaS founders, it prevents critical product rules from living only in the founder’s head. For engineering teams, it gives AI agents the context needed to help without silently inventing business policy.

The r/SaaS workflow offers a pragmatic starting point: versioned Markdown specs, a navigable index, explicit agent instructions, searchable access, and a rule that documentation changes when system behavior changes. (reddit.com) You do not need a new methodology or a complicated platform to begin.

Start with the decisions that would be painful to rediscover six months from now. Put them in the repository. Review them before code is generated. Update them when the product changes. In an AI-assisted development environment, that is not paperwork—it is the control plane for speed.

FAQ

What is spec-driven development?

Spec-driven development is an approach where a structured description of intended software behavior guides implementation, review, testing, and ongoing maintenance. In AI-assisted workflows, the spec also provides durable context for coding agents.

Is spec-driven development the same as writing PRDs?

No. A PRD is usually a product-planning document, while spec-driven development connects product intent to technical constraints, acceptance criteria, decisions, and repository maintenance. A useful spec may be shorter than a traditional PRD but more actionable for implementation.

Should every engineering change have a specification?

No. Use specs proportionally. Small, reversible fixes usually need only a clear issue and test. Changes involving permissions, billing, public contracts, data, integrations, or major user behavior deserve a maintained spec.

How should AI agents use specifications?

Tell agents to read the relevant specs before proposing or implementing a change, identify gaps and assumptions, and update the spec when approved behavior changes. Keep human approval for business rules, trade-offs, and ambiguous requirements.

Where should software specifications live?

For product behavior that changes with the code, a version-controlled repository directory such as /specs is often the most practical home. Use an index file for discovery, keep documents focused, and link them to tests, decisions, and related artifacts.