A spec tells an AI agent what to build. A guardrail tells it what not to do. Most teams write neither well, which is why AI-assisted development produces so much rework.
Fill in the templates below for your specific feature, then paste the completed spec into your agent.
Spec vs. guardrail: which one do you need
Spec
Guardrail
What it is
A complete description of what to build, why, and how success is measured
A constraint that limits agent behavior within a defined scope
Use when
Starting something new, touching multiple components, or integrating a system
Scoping a task already in motion, preventing drift, or setting hard limits
Contains
Problem statement, acceptance criteria, constraints, edge cases, definition of done
What the agent must not do, what counts as out of scope, fallback behavior
Length
300 to 2,000 words
5 to 15 rules
Who writes it
PM, tech lead, or founding engineer
The person delegating the task
Write a spec when you're starting something. Write guardrails when you're scoping something already in motion.
Spec template by stage
Match the depth of your spec to where you actually are. If you're not sure which stage you're in, ask: has the team agreed on why we're building this? If not, you're in early exploration regardless of how much detail you have.
Stage 1: Early exploration — Focus: Why are we building this?
FEATURE: [Name]
STAGE: Early exploration
PROBLEM STATEMENT
[Required. What is broken, missing, or inefficient? Who experiences it? What does it cost them?]
HYPOTHESIS
[Optional. What do you think the solution looks like? Keep this directional, not prescriptive.]
KNOWN CONSTRAINTS
[List only hard blockers you already know about. Leave the rest for later stages.]
OPEN QUESTIONS
[Document edge cases as questions, not answers. These get resolved in mid-design.]
DEPENDENCIES
[Name the systems and teams involved. No detail required yet.]
FEATURE: [Name]
STAGE: Early exploration
PROBLEM STATEMENT
[Required. What is broken, missing, or inefficient? Who experiences it? What does it cost them?]
HYPOTHESIS
[Optional. What do you think the solution looks like? Keep this directional, not prescriptive.]
KNOWN CONSTRAINTS
[List only hard blockers you already know about. Leave the rest for later stages.]
OPEN QUESTIONS
[Document edge cases as questions, not answers. These get resolved in mid-design.]
DEPENDENCIES
[Name the systems and teams involved. No detail required yet.]
FEATURE: [Name]
STAGE: Early exploration
PROBLEM STATEMENT
[Required. What is broken, missing, or inefficient? Who experiences it? What does it cost them?]
HYPOTHESIS
[Optional. What do you think the solution looks like? Keep this directional, not prescriptive.]
KNOWN CONSTRAINTS
[List only hard blockers you already know about. Leave the rest for later stages.]
OPEN QUESTIONS
[Document edge cases as questions, not answers. These get resolved in mid-design.]
DEPENDENCIES
[Name the systems and teams involved. No detail required yet.]
Stage 2: Mid-design — Focus: What are we building?
FEATURE: [Name]
STAGE: Mid-design
PROBLEM STATEMENT
[Required. Refined from early exploration. Should be tighter now.]
SOLUTION DESCRIPTION
[Required. Specific enough that two engineers would build the same thing.]
ACCEPTANCE CRITERIA (high-level)
[What does a successful outcome look like? Full Given/When/Then format not required yet.]
CONSTRAINTS
[Technical and business. Include both.]
EDGE CASES
[Partially resolved. Flag which are answered and which are still open.]
DEPENDENCIES
[Mapped. List every system this touches and who owns it.]
DEFINITION OF DONE (draft)
[What must be true before this is considered complete?]
FEATURE: [Name]
STAGE: Mid-design
PROBLEM STATEMENT
[Required. Refined from early exploration. Should be tighter now.]
SOLUTION DESCRIPTION
[Required. Specific enough that two engineers would build the same thing.]
ACCEPTANCE CRITERIA (high-level)
[What does a successful outcome look like? Full Given/When/Then format not required yet.]
CONSTRAINTS
[Technical and business. Include both.]
EDGE CASES
[Partially resolved. Flag which are answered and which are still open.]
DEPENDENCIES
[Mapped. List every system this touches and who owns it.]
DEFINITION OF DONE (draft)
[What must be true before this is considered complete?]
FEATURE: [Name]
STAGE: Mid-design
PROBLEM STATEMENT
[Required. Refined from early exploration. Should be tighter now.]
SOLUTION DESCRIPTION
[Required. Specific enough that two engineers would build the same thing.]
ACCEPTANCE CRITERIA (high-level)
[What does a successful outcome look like? Full Given/When/Then format not required yet.]
CONSTRAINTS
[Technical and business. Include both.]
EDGE CASES
[Partially resolved. Flag which are answered and which are still open.]
DEPENDENCIES
[Mapped. List every system this touches and who owns it.]
DEFINITION OF DONE (draft)
[What must be true before this is considered complete?]
Stage 3: Pre-build — Focus: How exactly does it work?
This is the version you paste into an agent. Everything above should be resolved before you reach this stage.
FEATURE: [Name]
STAGE: Pre-build
PROBLEM STATEMENT
[Required. Locked. Any changes at this stage require explicit sign-off.]
SOLUTION DESCRIPTION
[Required. Specific and implementation-ready.]
ACCEPTANCE CRITERIA
[One criterion per behavior. Use Given / When / Then for each.]
Given [the starting state or context]
When [the action or trigger]
Then [the expected outcome, specific and verifiable]
Given [the starting state or context]
When [the action or trigger]
Then [the expected outcome, specific and verifiable]
CONSTRAINTS
[All constraints explicit. Nothing implied.]
EDGE CASES
[Every edge case has a defined behavior. If out of scope, write "out of scope — do not handle."]
1. [Edge case] — [Defined behavior]
2. [Edge case] — [Defined behavior]
3. [Edge case] — [Defined behavior]
DEPENDENCIES
[Fully specified. Named systems, API contracts, version requirements.]
FEATURE: [Name]
STAGE: Pre-build
PROBLEM STATEMENT
[Required. Locked. Any changes at this stage require explicit sign-off.]
SOLUTION DESCRIPTION
[Required. Specific and implementation-ready.]
ACCEPTANCE CRITERIA
[One criterion per behavior. Use Given / When / Then for each.]
Given [the starting state or context]
When [the action or trigger]
Then [the expected outcome, specific and verifiable]
Given [the starting state or context]
When [the action or trigger]
Then [the expected outcome, specific and verifiable]
CONSTRAINTS
[All constraints explicit. Nothing implied.]
EDGE CASES
[Every edge case has a defined behavior. If out of scope, write "out of scope — do not handle."]
1. [Edge case] — [Defined behavior]
2. [Edge case] — [Defined behavior]
3. [Edge case] — [Defined behavior]
DEPENDENCIES
[Fully specified. Named systems, API contracts, version requirements.]
FEATURE: [Name]
STAGE: Pre-build
PROBLEM STATEMENT
[Required. Locked. Any changes at this stage require explicit sign-off.]
SOLUTION DESCRIPTION
[Required. Specific and implementation-ready.]
ACCEPTANCE CRITERIA
[One criterion per behavior. Use Given / When / Then for each.]
Given [the starting state or context]
When [the action or trigger]
Then [the expected outcome, specific and verifiable]
Given [the starting state or context]
When [the action or trigger]
Then [the expected outcome, specific and verifiable]
CONSTRAINTS
[All constraints explicit. Nothing implied.]
EDGE CASES
[Every edge case has a defined behavior. If out of scope, write "out of scope — do not handle."]
1. [Edge case] — [Defined behavior]
2. [Edge case] — [Defined behavior]
3. [Edge case] — [Defined behavior]
DEPENDENCIES
[Fully specified. Named systems, API contracts, version requirements.]
If the agent's summary contains surprises, the spec wasn't tight enough. Revise the spec, not the agent.
Guardrail template
FEATURE: [Name]
TYPE: Guardrail
SCOPE
Allowed: [What the agent is allowed to touch. Be specific: files, modules, systems.]
Off-limits: [What is explicitly off-limits, even if it seems relevant.]
PROHIBITED
[Things the agent must never do. No exceptions. No "unless necessary."]
FALLBACK
[What to do when an edge case falls outside defined scope.
Options: stop and log the blocker, ask before proceeding, default to a named state.]
DEPENDENCY CONSTRAINTS
May interact with: [list systems and file paths]
Must not touch: [list systems and file paths]
OUTPUT FORMAT
[What the completed output must look like.
Include: file names, comment conventions, PR description format, etc.]
ESCALATION TRIGGER
[The condition under which the agent must stop and surface a decision before continuing.]
FEATURE: [Name]
TYPE: Guardrail
SCOPE
Allowed: [What the agent is allowed to touch. Be specific: files, modules, systems.]
Off-limits: [What is explicitly off-limits, even if it seems relevant.]
PROHIBITED
[Things the agent must never do. No exceptions. No "unless necessary."]
FALLBACK
[What to do when an edge case falls outside defined scope.
Options: stop and log the blocker, ask before proceeding, default to a named state.]
DEPENDENCY CONSTRAINTS
May interact with: [list systems and file paths]
Must not touch: [list systems and file paths]
OUTPUT FORMAT
[What the completed output must look like.
Include: file names, comment conventions, PR description format, etc.]
ESCALATION TRIGGER
[The condition under which the agent must stop and surface a decision before continuing.]
FEATURE: [Name]
TYPE: Guardrail
SCOPE
Allowed: [What the agent is allowed to touch. Be specific: files, modules, systems.]
Off-limits: [What is explicitly off-limits, even if it seems relevant.]
PROHIBITED
[Things the agent must never do. No exceptions. No "unless necessary."]
FALLBACK
[What to do when an edge case falls outside defined scope.
Options: stop and log the blocker, ask before proceeding, default to a named state.]
DEPENDENCY CONSTRAINTS
May interact with: [list systems and file paths]
Must not touch: [list systems and file paths]
OUTPUT FORMAT
[What the completed output must look like.
Include: file names, comment conventions, PR description format, etc.]
ESCALATION TRIGGER
[The condition under which the agent must stop and surface a decision before continuing.]
Example: refactoring task
FEATURE: Auth middleware refactor
TYPE: Guardrail
SCOPE
Allowed: Refactor authentication middleware only.
Off-limits: Route handlers, database schemas, session storage logic.
PROHIBITED
Do not remove existing error handling.
Do not change public-facing API response shapes.
FALLBACK
If a dependency outside this scope needs to change for the refactor to work,
stop and log the blocker. Do not proceed.
DEPENDENCY CONSTRAINTS
May read from: /src/auth/*, /src/middleware/*
Must not modify: /src/routes/*, /src/db/*
FEATURE: Auth middleware refactor
TYPE: Guardrail
SCOPE
Allowed: Refactor authentication middleware only.
Off-limits: Route handlers, database schemas, session storage logic.
PROHIBITED
Do not remove existing error handling.
Do not change public-facing API response shapes.
FALLBACK
If a dependency outside this scope needs to change for the refactor to work,
stop and log the blocker. Do not proceed.
DEPENDENCY CONSTRAINTS
May read from: /src/auth/*, /src/middleware/*
Must not modify: /src/routes/*, /src/db/*
FEATURE: Auth middleware refactor
TYPE: Guardrail
SCOPE
Allowed: Refactor authentication middleware only.
Off-limits: Route handlers, database schemas, session storage logic.
PROHIBITED
Do not remove existing error handling.
Do not change public-facing API response shapes.
FALLBACK
If a dependency outside this scope needs to change for the refactor to work,
stop and log the blocker. Do not proceed.
DEPENDENCY CONSTRAINTS
May read from: /src/auth/*, /src/middleware/*
Must not modify: /src/routes/*, /src/db/*
Frequently asked questions
What's the difference between a spec and a PRD?
A PRD describes what a product should do and why, written for cross-functional alignment before engineering starts. A spec is more granular, describing how a specific feature should be implemented. For AI-assisted development, specs need acceptance criteria and constraints specific enough that an agent can complete the task without making judgment calls on your behalf.
Do you need a spec for every task?
No. Bug fixes, minor UI changes, and clearly scoped one-liners don't need a full spec. The trigger is complexity, not size. If a task touches more than one system, involves a decision a second engineer might make differently, or will be executed by an agent without review at every step, write a spec.
What's the difference between a guardrail and an acceptance criterion?
Acceptance criteria define what a successful output looks like. Guardrails define what the agent must not do to produce it. Acceptance criteria set the target, guardrails set the walls.
What if requirements change mid-build?
Stop the agent, update the spec, and restart from the last stable checkpoint. Do not course-correct a running agent with verbal instructions. The spec is the source of truth. If it's wrong, fix the spec first.
Use this in Devplan
Devplan generates specs and guardrails from structured prompts, keeps them synced with your Linear or Jira tickets, and maintains them as living documents through the build.