This document provides a framework for writing comprehensive specifications for software features and AI agents.
A good specification does more than describe functionality. It explains why a capability exists, what it is responsible for, how it behaves, how it will operate in production, and how it will evolve over time.
A specification should allow a new engineer, product manager, designer, operator, or AI agent to understand the system without relying on tribal knowledge or external context.
Every section in this guide contributes to answering one of five questions:
- Why are we building this?
- What does it do?
- How does it behave?
- How will it operate in production?
- How will it evolve?
The guide is organized around those questions.
Before discussing implementation details, establish why the capability should exist. These sections explain the problem being solved, the value being created, and the outcomes that define success.
Describe why the capability exists.
- What problem are we solving?
- Why is this worth building?
- What outcomes are expected?
- How will success be defined?
- Problem statement
- Business rationale
- User value proposition
- Strategic objectives
- Success criteria
A reader should understand why the feature should be built.
Define the limits of the capability.
- What is included?
- What is excluded?
- What is intentionally deferred?
Features included in the current release.
Capabilities explicitly excluded.
Capabilities expected in future releases.
Constraints and assumptions regarding surrounding systems.
A reader should understand what the feature is and is not responsible for.
Identify everyone who interacts with or is affected by the capability.
- Who benefits?
- Who operates the system?
- Who owns the outcomes?
For each stakeholder:
- Role
- Goals
- Responsibilities
- Expectations
Typical stakeholders:
- End users
- Administrators
- Moderators
- Product teams
- Engineering teams
- External systems
A reader should understand who cares about the capability and why.
Provide a concise executive summary.
- What is this capability?
- How does it work at a high level?
- What are its primary responsibilities?
- Feature name
- One-sentence description
- Core workflow
- Major responsibilities
- High-level architecture summary
A reader should understand the capability in under two minutes.
Describe everything available to the system.
- What information can the system access?
- What information is required?
- What information is optional?
- User inputs
- External inputs
- System state
- Environmental context
- Configuration
- Runtime constraints
A reader should understand what information drives behavior.
Define what the system produces.
- What does success generate?
- What do users receive?
- What do downstream systems receive?
- User-facing outputs
- Notifications
- Data updates
- Reports
- Artifacts
- API responses
A reader should understand the results produced by the capability.
Now that the motivation is clear, define the responsibilities and boundaries of the capability itself.
Define what the system can do.
- What functionality is provided?
- What obligations does the system have?
- Functional capabilities
- Responsibilities
- Service guarantees
- Required behaviors
Focus on what the capability does, not how it is implemented.
A reader should understand the functional contract of the feature.
Define what the system must not do.
- What is intentionally unsupported?
- What actions are prohibited?
- Non-goals
- Unsupported behavior
- Policy restrictions
- Security limitations
- Regulatory constraints
A reader should understand where the capability's authority ends.
Describe where the capability executes.
- Where does the system run?
- What environmental constraints exist?
- Platforms
- Deployment targets
- Infrastructure
- Runtime environments
- Availability zones
- Network assumptions
A reader should understand the execution environment.
Document dependencies.
- What systems are required?
- How does the capability interact with them?
For each integration:
- Name
- Purpose
- Owner
- Authentication model
- Reliability expectations
- Failure considerations
A reader should understand all external dependencies.
Describe where information originates.
- What information sources are used?
- How trustworthy are they?
For each source:
- Owner
- Access method
- Update frequency
- Trust level
- Access controls
A reader should understand the provenance of system knowledge.
These sections explain how the capability operates during normal execution and exceptional situations.
Describe how choices are made.
- How are alternatives evaluated?
- How are priorities determined?
- When is escalation required?
- Rules
- Prioritization logic
- Confidence thresholds
- Escalation criteria
- Decision hierarchy
A reader should understand how the system reaches conclusions.
Describe end-to-end execution.
- What happens during normal operation?
- What alternate paths exist?
- Primary workflow
- Alternate workflows
- Edge cases
- State transitions
- Sequence diagrams
- Process diagrams
A reader should understand operational behavior.
Describe where humans participate.
- When is human involvement required?
- What actions can humans override?
- Reviews
- Approvals
- Escalations
- Overrides
- Manual corrections
A reader should understand the human role in the workflow.
Define safeguards.
- How are users protected?
- What compliance obligations exist?
- Security controls
- Privacy requirements
- Compliance obligations
- Audit requirements
- Abuse prevention
- Data handling requirements
A reader should understand how risk is controlled.
Define behavior during failures.
- What can fail?
- How does recovery occur?
- Failure scenarios
- Retries
- Fallbacks
- Escalation behavior
- User messaging
A reader should understand resilience and recovery.
Describe persistence requirements.
- What information is retained?
- For how long?
- Under what conditions?
- Session state
- Long-term memory
- Caching
- Persistence
- Retention policies
- Cleanup rules
A reader should understand how state evolves over time.
Define measurable operational targets.
- Latency targets
- Throughput targets
- Availability objectives
- Scalability requirements
A reader should understand performance expectations.
Define how operational health is measured.
- Metrics
- Logs
- Traces
- Dashboards
- Alerts
- Incident thresholds
A reader should understand how issues are detected.
Define success measurement.
- Adoption metrics
- Quality metrics
- Reliability metrics
- Business metrics
- User metrics
A reader should understand how success is evaluated.
Describe how correctness is verified.
- Unit testing
- Integration testing
- Security testing
- Load testing
- User acceptance testing
- AI evaluations
- Benchmarking
A reader should understand how quality is established.
Describe how the capability reaches production.
- Release strategy
- Rollout plan
- Rollback plan
- Operational ownership
- Incident procedures
A reader should understand how the capability is operated.
Define ownership and decision-making authority.
- Owners
- Approval process
- Review process
- Versioning strategy
- Change control procedures
A reader should understand who governs the capability.
Document uncertainty.
For each risk:
- Description
- Likelihood
- Impact
- Mitigation
Also include:
- Assumptions
- Constraints
- Dependencies
A reader should understand threats to success.
Capture unresolved issues and future opportunities.
- Open questions
- Pending decisions
- Research items
- Future roadmap ideas
A reader should understand what remains uncertain and what may come next.
Reference material supports implementation but should not interrupt the narrative flow of the specification.
Provide supporting implementation detail.
- API contracts
- Schemas
- Data models
- Example requests
- Example responses
- Prompt templates
- Diagrams
- Glossaries
- Reference links
A reader should find all supporting implementation material needed to build or integrate with the capability.
A completed specification should enable a new engineer, product manager, designer, operator, or AI agent to answer five questions:
- Why are we building this?
- What exactly should it do?
- How should it behave in every situation?
- How will we operate and measure it?
- How will we maintain and evolve it?
If the specification does not answer all five questions, it is incomplete.