AI-Assisted Requirement Generation with Open Spec
Rapidly Evolving Ecosystem: AI-assisted development tools and frameworks are evolving rapidly. This documentation reflects our current approach as of early 2026. The Open Spec framework itself, AI coding assistants, and best practices in this space are all subject to change. Always refer to the official Open Spec repository for the most current technical details and implementation guidance.
Why Spec-Driven Development Matters
Traditional AI-assisted coding relies on chat-based prompts. A developer types "Build a lead scoring system" into an AI assistant and receives generated code based on whatever the AI infers from that brief instruction. This approach has a fundamental flaw: the quality and completeness of AI output depends entirely on the quality and completeness of the prompt.
This creates several critical problems:
Different developers get wildly different results for the same feature request
Requirements exist only in ephemeral chat history, not as permanent artifacts
There's no systematic way to verify that generated code meets all requirements
Edge cases, error handling, and integration concerns are frequently omitted
Teams can't build institutional knowledge when specifications aren't captured
The Core Issue: When requirements exist only in chat history, AI assistants produce unpredictable results. Without a structured specification layer, there's no way to ensure human-AI alignment before code creation begins.
Why We Adopted Open Spec
We needed an approach that aligned with our existing requirement definition standards while solving the consistency problem inherent in chat-based AI interactions. Open Spec provides this alignment through three key principles:
1. Artifacts Over Conversations
Open Spec generates permanent, reusable artifacts instead of relying on chat history:
Proposals document the "why" behind changes
Specifications capture requirements in our standard Gherkin format
Design documents record technical decisions
Task lists break work into trackable steps
This aligns perfectly with our requirement definition standard, which requires user stories, acceptance criteria (in Gherkin), and high-level solution design notes. Open Spec automates the creation of these artifacts through guided discovery rather than expecting developers to remember all the components.
2. Guided Discovery Over Freeform Prompts
Rather than asking "What do you want to build?", Open Spec guides you through structured questions that ensure completeness:
Who benefits from this and why?
What are the success criteria?
What are the edge cases and error scenarios?
What data flows through the system?
What are the constraints and dependencies?
This systematic approach ensures that specifications are consistent regardless of who creates them—addressing the variability problem in traditional prompting.
3. Customizable to Our Standards
Open Spec's OPSX framework is designed for customization. This means we can:
Adapt artifact templates to match our exact requirement format
Add domain-specific questions relevant to Salesforce development
Integrate with our existing toolchain and workflows
Evolve the framework as our practices mature
This flexibility is critical. We're not adopting a rigid methodology; we're adopting a customizable foundation that grows with our needs.
Alignment with Our Requirement Definition Standards
Open Spec produces exactly the artifacts our requirement definition standards require:
User Story (As a... I want... So that...)
Proposal documents
Captures the "who" and "why" before jumping to implementation
Acceptance Criteria (Gherkin: Given-When-Then)
Specification scenarios
Provides unambiguous, testable requirements that AI can implement precisely
High-Level Solution Design
Design documents
Records technical decisions, constraints, and dependencies for future reference
This alignment is not coincidental—it reflects a shared understanding that good requirements are behavior-driven, testable, and traceable.
The critical difference is that Open Spec guides you to create complete specifications rather than expecting you to remember all three components. Many developers write user stories but forget edge case scenarios. Open Spec's structured discovery ensures nothing is missed.
Why This Matters for AI-Assisted Development
The Consistency Problem
When ten developers ask an AI to "build authentication," you get ten different interpretations:
One might focus on username/password only
Another might include OAuth and SSO
A third might add MFA and password complexity rules
Most will forget error handling, rate limiting, or account lockout
With Open Spec, all ten developers go through the same guided discovery process. The specifications they create will have consistent structure and completeness, even if the specific requirements differ based on their context.
The Verification Problem
Traditional chat-based AI development creates a verification gap:
Developer provides a prompt
AI generates code
Developer manually reviews to check if code matches intent
With spec-driven development, verification becomes systematic:
Developer creates specification using Open Spec
AI generates code from specification
Tests are generated directly from Gherkin scenarios
Each acceptance criterion maps to specific functionality
The specification becomes the contract between human intent and AI implementation. This is particularly critical in regulated industries or mission-critical systems where traceability is not optional.
The Institutional Knowledge Problem
Chat conversations disappear. Specifications persist.
When a team member leaves or a feature needs enhancement six months later, spec-driven development provides:
Why decisions were made (captured in proposals)
What the system must do (captured in specifications)
How it was approached (captured in design documents)
This institutional knowledge is invaluable for maintenance, onboarding, and future enhancements.
When to Apply Spec-Driven Development
Not every task requires full specification. Apply judgment based on complexity and risk:
High Value for Specification
New features with business logic: Where requirements ambiguity leads to expensive rework
Multi-system integrations: Where clear contracts prevent integration failures
Regulated functionality: Where traceability and audit trails are required
Team handoffs: Where future maintainers need to understand intent
AI-generated code: Where consistent, complete specifications drive predictable output
Lower Value for Specification
Obvious bug fixes: The bug report defines the requirement
Trivial changes: Typo corrections, minor UI adjustments
Exploratory prototypes: Where learning is the goal, not production code
Emergency hotfixes: Where time constraints demand immediate action
Pragmatic Application: The goal is reliable, maintainable software—not documentation for its own sake. Apply the level of specification that serves that goal. A bug fix doesn't need a proposal document, but a new integration pattern does.
Why Open Spec Instead of Other Approaches
Several frameworks address requirement specification, each with different strengths:
Traditional BDD tools (Cucumber, SpecFlow, Behat) focus on test automation from Gherkin scenarios. They excel at testing but don't provide the guided discovery or artifact generation that Open Spec offers. They assume you already know what to specify.
Formal specification methods (RFC, ADR) capture decisions and technical details but are often too heavyweight for feature development. They're valuable for architectural decisions but create friction for day-to-day development.
Story mapping and user story workshops help organize requirements visually but don't produce the structured, machine-readable artifacts that AI coding assistants need.
Open Spec is purpose-built for AI-assisted development. It combines:
Guided discovery that ensures completeness
Gherkin-based scenarios that provide unambiguous acceptance criteria
Artifact generation that creates permanent, reusable specifications
Customizability through OPSX to match your team's standards
For our context—Salesforce development with AI coding assistants in an environment where requirements must be traceable and testable—Open Spec provides the right balance of structure and flexibility.
Adopting Spec-Driven Development
If you're convinced of the value and want to adopt this approach:
Understand our requirement standards first: Review our requirement definition format to see how user stories, acceptance criteria, and design notes are structured
Learn Open Spec's approach: Visit the Fission-AI/OpenSpec repository to understand the OPSX workflow and artifact structure
Start small: Apply spec-driven development to a single new feature before rolling it out team-wide. Experience the guided discovery process and evaluate whether it improves your AI-assisted development
Customize to your context: Use OPSX's customization capabilities to adapt templates, questions, and workflows to match your team's standards and domain
Build the habit: Spec-driven development feels like overhead initially but becomes natural once you experience the reduction in rework and clarification cycles
The goal is not to add process for its own sake—it's to reduce the cost of misunderstanding in AI-assisted development.
Resources
Requirement Definition Standards - Our standard format for user stories and acceptance criteria
Fission-AI/OpenSpec - Open Spec framework and OPSX workflow documentation
Gherkin Reference - Syntax for behavior-driven scenarios
Behavior-Driven Development - Principles behind the Gherkin approach
Last updated
Was this helpful?