|
| Codebase | |
### Use case
flxbl addresses the painful reality of enterprise Salesforce DevOps:
**1. Deployment Hell**\
Traditional Salesforce deployments are a nightmare. Hours-long deployments, manual cherry-picking between release branches, deployment failures at the last minute, and that one person who knows the "right" order to deploy things. Without enforced structure, deployments become a full-time job for someone on the team.
**2. Forced Modularity**\
Like fflib forces code structure, flxbl forces deployment structure. It won't work unless you properly modularize your org. No more giant, monolithic deployments where everything depends on everything else. You're forced to think in packages, boundaries, and clean dependencies from day one.
**3. Shift-Left Testing**\
Instead of finding deployment issues after merging (requiring painful rollbacks), flxbl validates everything during the PR phase. Every PR gets its own environment, automatically validated before merge. When deployment fails, you fix the PR - not roll back commits from main.
**4. Single Trunk Development**\
No more release branch hell. No more cherry-picking commits. No more "which branch has the latest version?" confusion. Single trunk with versioned packages means you can release fast and often. Deploy what's ready, when it's ready.
**5. Incremental Deployments**\
Deploy individual packages, not the entire org. A fix to the revenue module doesn't require redeploying your entire lead management system. This granularity reduces risk and deployment time from hours to minutes.
### Rationale
**Why flxbl over point-and-click tools:**
**The Enforced Process Advantage**\
Gearset, Copado, and similar tools are powerful but they're ultimately just tools. They'll happily deploy your mess faster. flxbl is opinionated - it enforces modularity or it simply won't work. This constraint is its strength.
**Modularity as a Requirement**\
You can't half-implement flxbl. Your code must be properly modularized into packages with clear dependencies. This forced structure pays dividends:
* Parallel development without conflicts
* Independent testing and deployment
* Clear ownership boundaries
* Genuine reusability
**Developer-First Approach**\
While point-and-click tools add UI layers, flxbl integrates into developer workflows:
* Git is the source of truth
* CI/CD pipelines as code
* Version control for everything
**The Journey to Modularity**
**For Existing Orgs:**\
Moving to modularity is a journey, not a sprint. We advocate incremental modularity:
1. Start with new features as packages
2. Extract stable, low-change components first
3. Gradually refactor high-value areas
4. Accept that some legacy code may never be packaged
Trying to modularize everything at once is a recipe for failure. Pick your battles.
**For New Implementations:**\
Start modular from day one. It's essential to:
* Keep packages small and focused
* Follow the modularity guidelines strictly
* Resist the temptation to create "misc" or "utils" packages
* Design clear interfaces between packages
**The Real Cost-Benefit:**
**Benefits:**
* Deployments go from hours to minutes
* No more deployment-day surprises
* Developers can work independently
* Rollbacks are package-specific, not org-wide
* True continuous delivery becomes possible
**Costs:**
* High initial learning curve for modularity
* Requires strong architectural discipline
* Package dependency management adds complexity
* Refactoring existing orgs is a significant investment
**Our Verdict:**\
For teams committed to continuous delivery and willing to invest in proper architecture, flxbl is transformative. For teams wanting a quick fix to deployment problems without changing how they build, look elsewhere.
### Alternatives
| Tool/Approach | When It Works | When It Doesn't | Our Take |
| ---------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Gearset** | Want UI-based deployments, comparison tools, rollback capabilities | Need enforced modularity, want git-native workflows | Great tool but doesn't enforce good architecture. Can deploy bad code faster |
| **Copado** | Enterprise with budget, want full DevOps suite, compliance requirements | Small teams, limited budget, developer-first culture | Comprehensive but expensive. Can become a crutch that hides architectural problems |
| **Salesforce CLI + Scripts** | Small team, simple requirements, high technical capability | Complex dependencies, multiple developers, need orchestration | Works until it doesn't. Scripts become unmaintainable as complexity grows |
| **SFDX + GitHub Actions** | Want free, simple CI/CD, comfortable with YAML | Need package management, complex orchestration, multi-org deployments | Good starting point but lacks advanced features. Consider migrating to flxbl as you grow |
| **Salto** | Want declarative change tracking, business user friendly | Need package-based architecture, complex dependencies | Focuses on different problem - configuration management vs architectural modularity |
| **Manual Change Sets** | Very simple requirements, infrequent deployments | Everything else | Please don't. It's 2024 |
### Implementation Guidance
**Critical Success Factors:**
1. **Understand Modularity First**\
Before touching flxbl, understand modular architecture. Read our modularity guidelines and anti-patterns documentation. flxbl is just a tool - modularity is the discipline.
2. **Start Small with New Features**\
Don't try to modularize your entire org at once. Start with:
* New features as independent packages
* Extracted utility functions
* Stable, low-change components Each success builds confidence and knowledge.
3. **Package Boundaries Are Sacred**\
Once you define a package boundary, defend it fiercely. No "temporary" cross-package dependencies. No "we'll fix it later" violations. The moment you compromise, you're back to monolithic chaos.
4. **Follow the Branching Model**\
Stick to the flxbl-recommended branching strategy (documented in their guides). Don't try to adapt it to your old branching model - you'll lose the benefits.
5. **Incremental Migration Strategy**\
For existing orgs:
* Phase 1: New features in packages
* Phase 2: Extract stable utilities
* Phase 3: Modularize high-value domains
* Phase 4: Tackle legacy code (if worth it)
Many orgs successfully run hybrid - some code packaged, some not. That's fine.
6. **Package Design Principles**
* **Small and Focused**: One package, one purpose
* **Clear Interfaces**: Public APIs, everything else private
* **Minimal Dependencies**: Fewer dependencies = easier deployment
* **Version Everything**: Semantic versioning from day one
7. **Common Pitfalls:**
* Creating "common" or "utils" packages that become dumping grounds
* Circular dependencies between packages
* Too many small packages (maintenance overhead)
* Too few large packages (loses modularity benefits)
* Ignoring the CI/CD pipeline until "later"
8. **Investment Required:**
* 2-3 months to properly modularize a medium-complexity org
* Ongoing architectural governance
* Team training on package-based development
* CI/CD pipeline setup and maintenance
**When Not to Use flxbl:**
* Simple orgs with infrequent changes
* Teams without architectural discipline
* Organizations unwilling to invest in modularity
* Quick prototypes or POCs
The key message: flxbl enables continuous delivery, but only if you commit to modular architecture. Half-measures will frustrate everyone and deliver no value.
# fflib - Apex Framework
### Links
| Description | Url |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| main | - fflib-apex-mocks
- fflib-apex-common
|
| extensions | |
| template generator | *(beta version)* |
### Use case
fflib addresses fundamental challenges that plague Salesforce development at scale:
**1. Inconsistent Implementation Patterns**\
Without a framework, every developer implements solutions differently. One developer puts business logic in triggers, another in helper classes, a third creates utility methods. This inconsistency makes code reviews painful, onboarding slow, and maintenance a nightmare. fflib enforces a consistent, opinionated structure similar to Spring Framework in Java - everyone knows where to find and place specific types of logic.
**2. Testing Bottlenecks**\
Traditional Salesforce testing requires extensive data factories and real database operations. Tests take forever to run, often timeout, and break when validation rules change. fflib's mocking capabilities let you test business logic in isolation without touching the database, reducing test execution time from minutes to seconds.
**3. God Classes and Spaghetti Code**\
We've all seen them - 3000-line trigger handlers where business logic, database queries, and field updates are tangled together. fflib forces separation through its layer architecture:
* **Selectors** handle all SOQL queries
* **Domains** encapsulate record-level business logic and validation
* **Services** orchestrate complex business processes
* **Unit of Work** manages DML operations and transaction control
This separation makes code genuinely testable, reusable, and maintainable.
**4. Lack of Dependency Injection**\
Salesforce's static nature makes it hard to swap implementations for testing or different contexts. fflib provides dependency injection patterns that let you inject mock implementations during testing or different implementations based on configuration.
### Rationale
**Why we chose fflib (the honest take):**
**The Good:**
1. **Enforced Consistency** - fflib is opinionated, and that's its strength. It forces developers to think and structure code in a specific way. Once you learn the pattern, you can jump into any fflib codebase and immediately understand the architecture.
2. **Professional Software Engineering Practices** - It brings enterprise patterns (Service Layer, Repository, Unit of Work) to Salesforce. If you've worked with Spring, .NET, or similar frameworks, fflib feels familiar and natural.
3. **Genuine Testability** - With fflib-apex-mocks, you can write fast, isolated unit tests. We're talking about 90%+ code coverage with tests that run in seconds, not minutes. This alone justifies the framework for teams doing continuous integration.
4. **Scalable Architecture** - As your org grows from 10 to 1000 classes, fflib's structure prevents the codebase from becoming unmaintainable. You always know where to add new features.
**The Trade-offs (let's be real):**
1. **Steep Learning Curve** - If you're a declarative developer or self-taught coder without formal software engineering background, fflib will be challenging. Concepts like dependency injection, mocking, and layer separation require significant investment to understand and apply effectively.
2. **Performance Overhead** - fflib adds CPU time and memory consumption through its abstraction layers and boilerplate. For simple operations, you're loading multiple framework classes. In CPU-critical contexts, this matters.
3. **All-or-Nothing Commitment** - Half-hearted fflib adoption is worse than no fflib. If you use the framework but ignore its patterns, you get all the overhead with none of the benefits - slower code that's still poorly structured.
4. **Team Buy-in Required** - Everyone needs to understand and follow the patterns. One developer doing their own thing can undermine the entire architecture.
**Our Verdict:**\
For teams building enterprise-scale Salesforce applications with multiple developers, the benefits far outweigh the costs. The initial learning investment pays dividends in maintainability, testability, and developer productivity. However, for small orgs with simple requirements or teams without software engineering experience, the overhead might not be justified.
### Alternatives
| Approach | When It Works | When It Doesn't | Our Take |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **No Framework (Vanilla Apex)** | Small orgs, simple requirements, single developer | Multiple developers, complex business logic, need for extensive testing | Works until it doesn't. Every org starts here, most regret not adopting structure sooner |
| **Trigger Handler Frameworks** (Trigger Framework by Kevin O'Hara) | Want minimal overhead, focus only on trigger management | Need service layer patterns, dependency injection, mocking | Good stepping stone but doesn't address broader architectural needs |
| **Custom Framework** | Unique requirements, full control needed, experienced architect available | Most teams, ongoing maintenance burden, lack of community support | Unless you have specific needs fflib doesn't meet, you're reinventing the wheel |
| **AT4DX** (Salesforce Labs) | Want Salesforce-official patterns, lighter weight than fflib | Need comprehensive mocking, extensive community resources | Newer, less mature, smaller community. Worth watching but not yet proven at scale |
| **Force-DI** | Only need dependency injection, want minimal framework | Need full architectural patterns, service layers, domain logic organization | Good for specific DI needs but doesn't provide complete architecture |
### Implementation Guidance
**Critical Success Factors:**
1. **Be Strict or Don't Bother**\
We enforce layer separation strictly. No shortcuts, no "just this once" exceptions. The moment you let business logic creep into Selectors or queries into Services, you've undermined the entire pattern. Either commit fully or use something simpler.
2. **Start with the Team's Strongest Developer**\
Have your most experienced software engineer implement the first few features using fflib. They'll establish patterns others can follow. Don't let everyone figure it out independently - you'll end up with different interpretations of the same patterns.
3. **Invest in Learning**\
Budget 2-4 weeks for developers new to enterprise patterns to become productive with fflib. For experienced Java/.NET developers, it's faster. For Salesforce-only developers, it's a significant paradigm shift. Consider:
1. Internal workshops on DI, mocking, and layer architecture
2. Pair programming during initial implementation
3. Code review checklists specific to fflib patterns
4. A reference implementation in your codebase
4. **Mock Everything, Test Fast**\
The framework's value emerges when you embrace mocking. If you're still writing tests that insert records, you're missing the point. Every test should run in milliseconds, not seconds. Learn fflib-apex-mocks deeply - it's as important as the framework itself.
5. **Layer Responsibilities (Our Rules):**
1. **Selectors**: SOQL only. No business logic. Not even "simple" field checks
2. **Domains**: Single-object business logic, validation, defaulting. No cross-object operations
3. **Services**: Multi-object orchestration, transaction control. No direct SOQL
4. **Unit of Work**: DML operations only. Register operations, don't execute them directly
6. **Performance Considerations** \
Accept that fflib adds overhead. In most cases, the maintainability gain justifies the performance cost. However:
1. Profile critical code paths
2. Consider bypassing the framework for high-volume batch operations
3. Use lazy initialization for framework components
4. Don't over-engineer simple operations
7. **Common Pitfalls to Avoid:**
1. Mixing fflib and non-fflib patterns in the same module
2. Creating anemic domains (domains with no behavior)
3. Skipping the Service layer for "simple" operations
4. Using Unit of Work inconsistently
5. Not mocking in tests "because it's easier to use real data"
8. **When to Break the Rules:** \
Almost never. The framework's value comes from consistency. The only exceptions we make:
1. Platform event triggers (often need immediate DML)
2. High-volume batch processing (performance critical)
3. Simple configuration/metadata operations (overhead not justified)
# Nebula Logger - Logging
## Links
**Codebase**\
## Use case
Nebula Logger addresses the critical need for comprehensive logging capabilities within the Salesforce platform that go beyond the standard debug logs. It serves as a robust solution for tracking, monitoring, and analyzing activities and errors across your Salesforce org. The framework allows development teams to:
* Capture detailed information about errors, transactions, and system processes
* Maintain a persistent record of system activities that won't be auto-purged
* Relate log entries to specific Salesforce records for improved troubleshooting
* Control logging verbosity at the org, profile, or user level
* Support logging across all automation types: Apex, Flow, and Lightning Components (LWC & Aura)
* Track related logs across asynchronous processes and transactions
* Automatically capture contextual information about the org, user, and record
* Monitor platform events in real-time through the "Log Entry Event Stream" tab
* Apply data masking rules to protect sensitive information like SSNs and credit card numbers
* Organize and categorize logs using scenarios and tagging systems
* Extend functionality through the plugin framework for integration with external systems
This framework fills significant gaps in Salesforce's native logging capabilities, enabling teams to proactively monitor system health, identify issues before they impact users, and provide detailed information for troubleshooting when problems occur.
{% hint style="info" %}
To see how to use Nebula Logger in practice, refer to the [Logging best practices](/technical/best-practices/logging) documentation.
{% endhint %}
## Rationale
Our team has chosen Nebula Logger over other logging frameworks for several reasons:
1. **Native Salesforce Integration**: Unlike external logging solutions, Nebula Logger stores data within the Salesforce platform, allowing us to leverage familiar Salesforce features (reports, dashboards, list views, etc.) to manage and analyze logs.
2. **Platform Event Architecture**: The framework utilizes Salesforce Platform Events, enabling us to both log information AND throw exceptions - a critical capability that was virtually impossible in Salesforce before Platform Events. The "Log Entry Event Stream" tab allows real-time monitoring of these events.
3. **Comprehensive Information Capture**: Nebula Logger automatically captures extensive contextual data about the execution environment, including org details, user information, platform limits, and record data.
4. **Flexible Configuration**: The framework provides granular control over logging levels (ERROR, WARN, INFO, DEBUG, FINE, FINER, FINEST) that can be configured at the org, profile, or user level, allowing us to increase logging detail for specific teams or during new feature rollouts.
5. **Support for All Development Approaches**: With built-in support for Apex, Flow, and Lightning Components (both LWC and Aura), the framework accommodates our full development stack, enabling consistent logging practices across all automation types.
6. **Enhanced Data Security**: Data masking rules allow us to automatically protect sensitive information (like SSNs and credit card numbers) from being stored in logs, addressing compliance requirements.
7. **Scenario-Based Log Management**: The scenario feature allows us to categorize transactions and apply specific logging levels and retention policies to different types of operations.
8. **Transaction Tracking**: The ability to track related logs across asynchronous processes gives us visibility into complex operations that span multiple transactions.
9. **Extensibility via Plugins**: The plugin framework allows us to extend functionality without modifying core code, enabling integration with external systems like Slack and custom dashboards.
10. **Automatic Log Management**: Built-in purging capabilities help us manage data storage by automatically removing old logs based on configurable retention periods.
11. **Unlocked Package Deployment**: Available as an unlocked package, we can see and modify the underlying code if needed, providing greater flexibility for customization and security auditing.
12. **Open Source with Active Community**: As one of the most starred Salesforce logging repositories on GitHub, Nebula Logger continues to evolve and improve, ensuring we benefit from ongoing enhancements and refinements.
## Alternatives
Several alternatives to Nebula Logger exist for handling logging in Salesforce:
1. **Salesforce Native Debug Logs**: The platform's built-in debug logs provide basic logging functionality but have significant limitations including 24-hour retention, 20MB size limits, potential truncation, and limited reporting capabilities.
2. **Custom-Built Logging Solutions**: Organizations can build their own logging frameworks, but this requires significant development time and ongoing maintenance without the benefit of community support and continuous improvement.
3. **External Logging Services**: Solutions like Loggly or Rollbar can be integrated with Salesforce, but require additional infrastructure, often have per-seat licensing costs, and require developing integration points between Salesforce and external systems.
4. **AppExchange Logging Solutions**: Various paid logging solutions exist on the AppExchange, but many have ongoing subscription costs and may not provide the same level of flexibility and customization.
Nebula Logger provides the best balance of being a free, open-source solution with rich features specifically designed for the Salesforce platform while maintaining the flexibility to integrate with external systems through its plugin architecture when needed.
# Technical Documentation
# Writing and Maintaining Technical Documentation
Effective technical documentation is a critical component of maintainable software systems. Well-written documentation reduces onboarding time, minimizes support burden, and serves as a single source of truth for architectural decisions and implementation patterns.
## Documentation Philosophy
### Write for Your Audience
Technical documentation serves multiple audiences with different needs:
* New developers: Need conceptual overviews, getting started guides, and common patterns
* Experienced team members: Need detailed API references, edge cases, and optimization techniques
* Operations teams: Need runbooks, troubleshooting guides, and monitoring procedures
* Architects: Need system diagrams, integration patterns, and design decisions
Tailor content depth and terminology to your target audience. Avoid assuming knowledge that new team members won't have, but don't over-explain concepts that experienced developers already understand.
### Documentation as Code
Treat documentation with the same rigor as code:
* **Version control**: Store documentation in the same repository as code.
* **Review process**: Require peer review for documentation changes.
* **Broken link checking**: Validate internal and external references.
* **Search optimization**: Structure content for discoverability.
### Living Documentation
Documentation decays without maintenance:
* **Update on code changes**: Documentation updates are part of definition of done.
* **Regular reviews**: Schedule periodic audits to ensure accuracy.
* **Deprecation markers**: Clearly flag outdated content with removal dates.
## Style Guide Foundations
Follow [Google's Technical Writing Style Guide](https://developers.google.com/style) as your baseline, with the following Salesforce-specific adaptations.
### Terminology Standards
Maintain consistent terminology:
#### Salesforce-specific terms:
* Use "org" or "organization", not "instance" or "environment".
* Use "record" not "row" or "entry".
* Use "field" not "column" or "attribute".
#### Code element formatting:
* Class names: `AccountTriggerHandler`
* Method names: `processRecords()`
* Field names: `Account.AnnualRevenue`
* sObject API names: `Account`, `Opportunity`, `CustomObject__c`
# Architecture & Feature Design Guidelines
## Index
* [Diagrams](#diagrams)
* [Design Decisions](#design-decisions)
* [Template: Design Decision](#template-design-decision)
* [Feature Design Documentation](#feature-design-documentation)
* [Template: Feature Name](#template-feature-name)
## Diagrams
* [ ] [System Architecture Diagram](https://architect.salesforce.com/diagrams/framework/docs-implementation)
* [ ] [ERD](https://architect.salesforce.com/diagrams/framework/data-model-notation)
* [ ] Data Flow Diagrams
* [ ] UML Diagram
## **Design Decisions**
Core design decisions are significant technical choices that influence the overall architecture of a platform or a set of features. These decisions often adhere to specific design principles, facilitating better integration and information sharing among different parts of the system.
### **Template: Design Decision**
#### **Problem Statement**
A concise description of the issue that necessitates a design solution. This statement should highlight the critical problem we aim to solve.
#### **Research Insights**
Summarize the research conducted to understand the problem better.
Include:
* The components evaluated during the problem analysis.
* Any relevant environmental or contextual factors, such as the customer's internal capabilities. For instance, if a customer's team consists only of administrators, why would we opt to configure all triggers in Apex rather than leveraging Salesforce Flows? This section aims to shed light on the rationale behind certain design considerations based on research findings.
#### **Solution Hypothesis**
Describe the expected outcomes and benefits of addressing the problem. This section should articulate:
* The anticipated changes following the problem's resolution.
* The advantages these changes would bring to users or the organization as a whole.
#### **Design Options**
Present a list of potential solutions that were considered. For each option, detail the following:
* **WHAT:** A brief description of the solution.
* **WHY:** The rationale for considering this option.
* **BENEFIT:** The potential advantages of implementing the solution.
* **DOWNSIDE:** Any trade-offs or negative aspects associated with the solution. This part encourages a balanced view of each option, recognizing that most design choices involve compromises.
#### **Conclusion**
Summarize the chosen solution and justify the decision. This section should provide clarity on:
* The decision made regarding the design dilemma.
* The primary reasons behind selecting this particular solution over others.
## Feature Design Documentation
Design documentation is essential for individual features, not just for stories. It's crucial to design larger features thoroughly, rather than designing each story separately, to avoid a chaotic and poorly designed amalgamation of elements.
While smaller adjustments or enhancements to these features might not always necessitate changes in the documentation, their potential impact should still be assessed. Such documentation should be organized at the epic level to ensure clarity and cohesion.
{% hint style="info" %}
When creating this feature-level documentation, it's useful to conduct a gut check: consider how often the documentation will need to be adjusted when new stories are introduced. If the answer is "often," then the documentation is too detailed at a low level.
{% endhint %}
### Template: Feature Name
#### **Functionality Design Goals**
Provide a succinct description of the functionality this feature aims to introduce. Outline the primary objectives and the need the feature addresses. This section sets the stage by explaining what the feature intends to achieve and its significance to users or the business.
| Jira Story | Link |
| ---------------------- | --------------------- |
| (List of Jira stories) | (corresponding links) |
#### **Design Solutions**
Offer a detailed account of how various metadata components will function cohesively to realize the feature. Describe the sequence and interaction of these components, utilizing bullet points or numbers for clarity. This narrative should paint a clear picture of the feature's operational flow and how each element contributes to the overall functionality.
#### **Limitations and Tradeoffs**
Dive into the critical design discussions that shaped the final design choice. Highlight specific limitations encountered during the design process and the tradeoffs made to navigate these challenges. For instance, elaborate on the decision to utilize APIs over a managed package, detailing the reasoning and benefits of this choice versus the alternatives considered.
#### **Components List**
Provide a comprehensive table or list of all metadata components involved in the feature's design. While exhaustive detail isn't necessary for each component, employ discretion to decide when additional explanation is warranted. Essential components might include objects, main entry apex classes, lightning web components, and more.
This list serves as a blueprint of the technical elements that constitute the feature.
| Component | Description |
| ------------------------ | ------------------------------------------------------------------------------- |
| Example\_SF Flow | Captures user input for new X registration. |
| Validation Rules | Ensures data integrity with selective bypass for X users. |
| Email Notification Flows | Manages email communications regarding opportunity submissions and assignments. |
| componentDetail | Custom lwc for detailed viewing of lead and opportunity records. |
*Table: Example component list*
# AI Assisted Documentation
{% hint style="info" %}
**TODO**: Add link to AI agent setup guide once available.
{% endhint %}
# Requirement definition
Requirements should be formatted in a consistent way and always contain 3 main elements:
* Requirement (User Story) definition itself (*As a* x, *I want to be able to* y, *so that* z)
* Acceptance Criteria (written in [Gherkin syntax](https://cucumber.io/docs/gherkin/reference/): given, when, then)
* High level solution design notes
{% hint style="info" %}
We do not distinguish between the definitions of requirements in theoretical models, nor do we strictly adhere to 'the book' when it comes to Scrum, Agile, or Waterfall methodologies.
{% endhint %}
## AI-Assisted Requirement Definition
When working with AI coding assistants, well-structured requirements become even more critical. The format described on this page serves as the foundation for [spec-driven development](/functional/requirement-definition/spec-driven-development), which uses Open Spec's artifact-guided workflow to produce complete, consistent specifications that AI assistants can reliably implement.
See also:
* [Spec-Driven Development](/functional/requirement-definition/spec-driven-development) - Using Open Spec for AI-assisted requirement generation
### **1. User Story (Requirement) Definition**
> **Template Format**:
>
> **As a** \[user/role/persona], **I want** \[capability/functionality], **so that** \[benefit/value].
#### **Explanation**
1. **Who**: Identify the primary user or role that will benefit from the feature. It could be a job function (e.g., “As a project manager”) or a type of end user (e.g., “As a customer”).
2. **What**: Clearly state the functionality or capability the user needs (e.g., “I want to export data to CSV”).
3. **Why**: Explain the value or benefit of having that capability (e.g., “so that I can analyze it in a spreadsheet”).
#### **Good Example**
> **As a** Customer Support Agent,\
> **I want** to filter tickets by their status,\
> **so that** I can quickly prioritize unresolved issues.
* **Who**: Customer Support Agent
* **What**: Ability to filter tickets by status
* **Why**: To prioritize unresolved issues and work more efficiently
#### **Bad Example**
> **As a** user,\
> **I want** the system to be better,\
> **so that** it’s easier to use.
* **Vagueness**: Does not specify the user persona clearly (simply says “user”).
* **Lack of clarity**: “System to be better” is not a concrete requirement.
* **Unclear benefit**: “So that it’s easier to use” is too generic and gives no measurable outcome.
***
### **2. Acceptance Criteria (Gherkin Syntax)**
> **Template Format**:
>
> **Scenario**: \[Meaningful title or label]\
> **Given** \[initial context/conditions],\
> **When** \[action/event],\
> **Then** \[expected outcome/result].
#### **Explanation**
1. **Scenario Title**: Give each scenario a descriptive name that quickly conveys its purpose.
2. **Given**: Pre-conditions or context required before the user takes an action.
3. **When**: The action the user takes or the event that triggers a behavior.
4. **Then**: The outcome or the result that must be achieved to consider this scenario successful.
You can have multiple **Given–When–Then** sequences within a single scenario if needed, or multiple scenarios under the same story to cover different permutations.
#### **Good Example**
> **Scenario**: Filter tickets by status\
> **Given** I am logged in as a Customer Support Agent\
> **And** I have at least one ticket with the status “Open” and one ticket with the status “Closed”\
> **When** I navigate to the ticket dashboard\
> **And** I apply a filter for “Open” tickets\
> **Then** I should only see tickets with status “Open” in the list\
> **And** I should not see any tickets with the status “Closed”
* **Clear context** (“I am logged in as a Customer Support Agent” and tickets exist).
* **Distinct action** (“apply a filter for ‘Open’ tickets”).
* **Valid expected outcome** (“only see tickets with status ‘Open’”).
#### **Bad Example**
> **Scenario**: Filter\
> **Given** the system is open,\
> **When** I filter,\
> **Then** I should see results.
* **Vague context**: “the system is open” is not precise—where is the user, what page or screen is active?
* **Incomplete**: “I filter” does not describe how or what filter is being applied.
* **No clear outcome**: “I should see results” is too generic.
***
### **3. High-Level Solution Design Notes**
> **Template Format**:
>
> * **Technical Considerations**: Summarize any major technical components, APIs, or integrations needed.
> * **Constraints or Limitations**: Mention performance constraints, platform constraints, or known limitations.
> * **UX/UI Considerations**: Briefly note any specific UI elements or design guidelines that must be followed.
> * **Dependencies**: List any upstream or downstream dependencies that might affect this user story (e.g., other microservices, external data sources, or features).
#### **Explanation**
1. **Technical considerations**: Identify if new components, services, or data structures are needed.
2. **Constraints or limitations**: E.g., maximum number of records, device constraints, security, etc.
3. **UX/UI considerations**: Include a rough sketch, wireframe reference, or important design elements if necessary.
4. **Dependencies**: Call out any reliant features or external tools.
#### **Good Example**
> * **Technical Considerations**:
> * Implement an API endpoint `/tickets/filter` to handle filtering logic on the backend.
> * Use indexed queries in the database to improve filter performance.
> * **Constraints**:
> * Must support up to 10,000 tickets in the list.
> * Filtering should respond within 2 seconds.
> * **UX/UI Considerations**:
> * The filter dropdown should display all possible status options (Open, In Progress, Closed).
> * The default state of the filter is set to “All Statuses.”
> * **Dependencies**:
> * The user login and authentication service must be implemented before testing this feature.
> * Any changes to ticket statuses in other services should trigger an update in our ticketing database.
* **Concise yet informative**: It highlights the back-end endpoint and performance requirements without going into overly detailed technical documentation.
* **Clear constraints**: Performance metrics and capacity.
* **User experience**: The dropdown status filter is specified.
* **Dependencies**: Auth service and database updates are mentioned.
#### **Bad Example**
> * **Technical Stuff**: We’ll do something with the database.
> * **Constraints**: Shouldn’t be too slow.
> * **Design**: Make it look nice.
> * **Dependencies**: Not sure yet.
* **Lacks details**: “Do something with the database” is not actionable or specific.
* **No performance expectations**: “Shouldn’t be too slow” is too vague.
* **No clarity**: “Make it look nice” does not reference any design guidelines.
* **No identified dependencies**: “Not sure yet” is not helpful.
***
## **Complete Template**
Below is a **copy-paste-ready template** you can use for your own user stories. Simply fill in the sections with details specific to your requirement.
***
```
## User Story
**As a** [user persona or role],
**I want** [capability or functionality],
**so that** [benefit or value].
## Acceptance Criteria
### Scenario 1: [Descriptive Title]
**Given** [initial context/conditions],
**And** [additional context if any],
**When** [action the user or system takes],
**And** [any additional event if required],
**Then** [expected outcome],
**And** [any additional outcome if required].
### Scenario 2: [Additional scenario title, if necessary]
[Repeat Gherkin steps as needed]
## High-Level Solution Design
- **Technical Considerations**:
- [Brief note on approach, services, APIs, data schemas, etc.]
- **Constraints or Limitations**:
- [Performance, device constraints, data volume, etc.]
- **UX/UI Considerations**:
- [Any relevant design guidelines, references to wireframes, or key UI elements]
- **Dependencies**:
- [Other features, services, or external components that impact this user story]
```
***
### **How to Use This Template Effectively**
1. **Keep the “why” clear**: The user story must focus on the user’s goal and the value it provides.
2. **Be specific in acceptance criteria**: Use **Given-When-Then** to detail all conditions, actions, and outcomes, ensuring no ambiguity.
3. **Keep solution notes high-level**: Details in this section should aid in understanding and planning without becoming full technical designs.
4. **Review often**: Regularly revisit and refine the story, criteria, and design notes to ensure they remain accurate and aligned with the project goals.
Following these guidelines will help ensure your requirements are well-defined, testable, and provide clear value to stakeholders.
# AI-Assisted Requirement Generation with Open Spec
{% hint style="info" %}
**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](https://github.com/Fission-AI/OpenSpec) for the most current technical details and implementation guidance.
{% endhint %}
## 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
{% hint style="warning" %}
**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.
{% endhint %}
## Why We Adopted Open Spec
We needed an approach that aligned with our existing [requirement definition standards](/functional/requirement-definition) while solving the consistency problem inherent in chat-based AI interactions. [Open Spec](https://github.com/Fission-AI/OpenSpec) 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](/functional/requirement-definition) require:
| Our Standard | Open Spec Artifact | Why This Matters |
| -------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------- |
| **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:
1. Developer provides a prompt
2. AI generates code
3. Developer manually reviews to check if code matches intent
With spec-driven development, verification becomes systematic:
1. Developer creates specification using Open Spec
2. AI generates code from specification
3. Tests are generated directly from Gherkin scenarios
4. 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
{% hint style="info" %}
**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.
{% endhint %}
## 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:
1. **Understand our requirement standards first**: Review our [requirement definition format](/functional/requirement-definition) to see how user stories, acceptance criteria, and design notes are structured
2. **Learn Open Spec's approach**: Visit the [Fission-AI/OpenSpec repository](https://github.com/Fission-AI/OpenSpec) to understand the OPSX workflow and artifact structure
3. **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
4. **Customize to your context**: Use OPSX's customization capabilities to adapt templates, questions, and workflows to match your team's standards and domain
5. **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](/functional/requirement-definition) - Our standard format for user stories and acceptance criteria
* [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) - Open Spec framework and OPSX workflow documentation
* [Gherkin Reference](https://cucumber.io/docs/gherkin/reference/) - Syntax for behavior-driven scenarios
* [Behavior-Driven Development](https://cucumber.io/docs/bdd/) - Principles behind the Gherkin approach
# Documentation
### Diagrams
* [ ] Business Process Diagram
### Rationale & overall documentation strategy
Functional documentation focuses on the narratives of completed stories. When acceptance criteria are clearly defined and articulated, the collective sum of these stories should illustrate a comprehensive behavioral overview.
Nonetheless, there exists a necessity for overarching business process documentation. This is accomplished not through written documentation but via flowcharts.
BPMN or alternative notations may be employed, provided they clearly delineate the various stages in a process, including their prerequisites or conditions that are assessed, and the subsequent effects across systems or actors.