I've been told "User Stories are not requirements, it is just a reminder of what customer wants, you cannot put requirements within a story". But let's take for an example that a customer wants a different processing for different credit cards. There are strict requirements that must be implemented and known so that test cases can be written. Where should requirements go if not in the user story?

How can developers develop from a story if there are no lower requirements? How testers can write test cases (detailed ones) based on a user story? Where to requirements like DB constraints, fields validation etc. live outside of the user story?

  • 6
    User stories are just that - user level requirements. Lower level 'software requirements' (often what limitations are considered acceptable ) should always be harvested separately and documented separately with an appropriate reference.
    – Gusdor
    Commented Feb 9, 2015 at 13:10
  • 7
    The point of getting the user stories is that most users of your program will never know or care how it works. They don't care about database structure, separation of concerns, class structures, etc.; they care about stability, speed and ease of use. That's why you capture their stories, to find out what they're going to use the program for. How you then implement it is a whole separate level of requirements, the users generally won't be able or willing to inform that process.
    – jonrsharpe
    Commented Feb 9, 2015 at 13:15
  • 2
    gnat: Actually not. I asked because I am genuinely interested how this can be done correctly as I am sure, given to the widespread use of SCRUM, this must be an issue for many teams.
    – user144171
    Commented Feb 9, 2015 at 15:44
  • 4
    @maple_shaft the problem with "rantish" elements is these tend to attract rantish answers. I agree that there is a sensible core in there, wonder if it can be edited to just keep that core and wipe out invitation to ranty answers
    – gnat
    Commented Feb 9, 2015 at 15:53
  • 2
    There is a good question here, but it's written as a rant. I made an attempt at an edit.
    – DA01
    Commented Feb 10, 2015 at 0:01

9 Answers 9


This answer will focus on how to work with User Stories and lower level requirements. I won't be discussing the virtues, or lack thereof, of Scrum or Agile. I won't be talking about gurus either.

This answer assumes you're on board with Scrum but haven't yet found a way to make it work for you.

As others have mentioned, User Stories are meant to cover how the Users would like the software to be. Because the Users don't care about low level implementation stuff like database tables, constraints, architectural patterns, etc, you won't find such details in a User Story.

However, that doesn't mean these details should not be recorded anywhere.

When developers implement User Stories they need to be aware of lower level details typical Users won't know. This information can come from SMEs, BAs, the Product Owner, your architect, or any other expert or technically minded person.

Does this mean low level details should be recorded in User Stories? No (and yes).

At some point between the time the story is created and implemented somebody will need to work out how to implement it. This usually takes the form of conversations with the people involved in the Story (User, architect, developer, etc). These conversations should result in unambiguous Acceptance Criteria which clearly delineate the scope of the User Story's implementation. These details will need to be recorded somewhere and where that is is really up to you. The key here is that these details are elicited after the User Story has been created. I think this is what your guru is trying to emphasise.

As a developer it is clear that you'll need a way to associate more specific requirements with your User Story. Just how you do that is entirely up to your team.

If people on your team want to keep these details out of the User Stories then you may need to respect that. There are benefits to keeping your high level User Stories free of implementation details. It keeps them lean and your backlog can be read as a history of what your Users and Product Owner wanted. Just make your needs as a developer known as well. You should be able to work out a compromise where simply linking to the User Story keeps everyone happy.

  • 3
    +1 Acceptance Criteria adds more detail
    – Fractional
    Commented Feb 9, 2015 at 14:39

Yup, its BS. And Scrum is not Agile.

I hate the rigidity of so-called agile practitioners who tel you that there is one way of doing agile and that you must follow all the rules laid out in the holy scriptures of whichever 'agile' methodology they use. Its all BS.

Agile is about being agile.

Agile is about getting stuff done with a minimum of overhead. This doesn't mean "no documentation" as you usually end up documenting more in an agile role, you just get on with the documenting without having to plan a process for doing the documentation. Similarly with coding, testing and requirements capture. The only things that matter in an agile process are those that help you get your job done, quickly and efficiently without any BS.

So in this case, if putting user requirements in the cards helps you write, test, document and demonstrate the code that is needed... put the requirements on the card and tell the gurus that the team is always right.

What does the rest of your dev team think? In a true agile methodology, if they all think requirements should be written up front without any 'user conversations' then that should be it, you do what the team thinks works best for them to do their work. If the team thinks that the user conversations are a good thing, then listen to them and understand why they think this and bring yourself into their way of working.

  • 4
    Would you please mind to phrase this in a less (i.e., non-) derogatory way? I agree with you on the topic, but people have different opinions and that's no justification for losing your manners in that way.
    – Frank
    Commented Feb 9, 2015 at 13:24
  • Actually, I cannot imagine requirements not written up front - even for the simplest things like numeric fields you need to know the lenght, datatype, validations. According to those gurus, these things are uneccessary to be in the story. But when you write the code, high level US is useless, you have to know the constraints, flows, etc. etc. I have never seen a project with pure two-sentence US that was efficient for implementation and testing.
    – user144171
    Commented Feb 9, 2015 at 13:45
  • 4
    The client agreed to an 8 bit integer, so it's not my fault.
    – JeffO
    Commented Feb 9, 2015 at 13:50
  • 2
    @gbjbaanb: Agile is just a new fancy word for "using common sense", i.e. finding the right balance between upfront analysis / design and quickly delivering a partial solution to gather feedback. I find the term agile quite irritating because there is very little new to these ideas, other than the name. The worse happens when a rather inflexible framework like SCRUM is imposed as agile. IMO truly being agile would mean dropping the words agile and SCRUM and adapting your process to your needs, as we had always been doing before the agile wave started.
    – Giorgio
    Commented Feb 9, 2015 at 14:57
  • 1
    @Alex he's asking very much in the context of SCRUM and agile processes.
    – gbjbaanb
    Commented Feb 9, 2015 at 15:51

Just don't call this a User Story and everyone will be happy.

I think the answer is, you can write this down wherever you want.

In general, specific implementations are not included in a user story for a few reasons:

  1. You know what the customer wants, but you don't know how it is going to be implemented.
  2. The customer is aware there are more specific requirements involved, but really doesn't care and/or understand them anyway.
  3. Everyone thinks they are fully aware of the specific implementations at this time, but nobody wants to write them down because in their experience, it is all going to change anyway and no one will want to rewrite it.

There are no rules that omit additional documents when necessary. Maybe the client needs access to it and maybe not. If you're hopes are to generate some sort of contract between you and the client on the specific implementation as if you can follow it and when it doesn't work blame the client for agreeing to it, you're mistaken. If the client understands the technical details of credit card processing, you should share these documents with them and possibly make it a part of the conversation.

  • 1
    But here is the problem, some clain US is all you need but I say that it is not possible when the story is about "what" and not about "how". If they want a login screen, what lenghts will the field have? What characters will be allowed? etc...users do not care, but devs and testers will and hence this must be written somewhere.
    – user144171
    Commented Feb 9, 2015 at 13:42
  • 4
    So write it down! There's nothing wrong with supplemental documentation if that's what it takes to get the job done. Just understand that in many cases, you can't treat this like some sort of client contract. The client will actually use your login screen and then tell you they need more characters regardless of what your documentation says. Now you get to decide if you want to change your code, the documentation or both.
    – JeffO
    Commented Feb 9, 2015 at 13:54
  • And if it is a massive undertaking to adjust the length of an input, your code isn't very agile anyway, so little or no documentation isn't going to make much difference.
    – JeffO
    Commented Feb 9, 2015 at 14:02
  • 3
    @user144171 Trying to write down ALL the requirements for a project, or a feature, up front, and in the most detailed way possible, down to the last bit, is just as bad as having no requirements at all. Same thing goes for design.
    – AK_
    Commented Feb 9, 2015 at 14:45
  • @AK_ I don't think he is stating that all of this needs to be done upfront, but certainly enough has to be done upfront prior to sprinting where a sizable backlog exists.
    – maple_shaft
    Commented Feb 9, 2015 at 15:51

I think if what your Scrum consultants are telling you is that Scrum doesn't require requirements then you have some very poor consultants. They are even wrong to tell you that a user story is not in fact a requirement at all, they just happen to be one kind of requirement.

What are the different types of software requirements?

Business Requirements

These are generally a high level business need, something that generally would amount to some kind of executive style statement about a system. It is purposely high level and broad and by itself cannot be implemented without vastly more detail.

User Requirements

These are the User Story requirements that you are familiar with. They can generally fit on a sticky note.

  • Actor - Typically a user or stakeholder.
  • Need - Some item or general functionality that is needed by the user
  • Reason - The reason or context behind why this need exists
  • Acceptance Criteria - This is the framework for user acceptance testing and during Sprint Demo how the Product Owner will be able to decide if a user story is Accepted or not.

Functional or System Requirements

This seems to be the missing piece in your puzzle. Driven from the user level requirements, a functional requirement defines system level actors and properties of a system, as well as behaviors and functions of a system. This could also be done in a story format and included in your backlog. These items should stand alone and can be implemented independently of any one user requirement.

  • Actor - A system or component of some kind.
  • Need - A need, or property, or statement of behavior of a system that should exist.
  • Reason - A context behind why this is needed in the system
  • Acceptance Criteria - Scenarios, behaviors, functions and flows that are necessary to communicate how System and Integration testing should be performed. When these types of tests are passed for the requirement then we know this functional requirement has been completed. These can exist in external documentation from your user stories but should be completed prior to these stories being assigned in a sprint.

The functional requirements define your solution which sounds like what you are describing as the gap in your process.

Notable requirement types that need mentioned but are inconsequential to your question: Non-Functional Requirements, Technical Requirements, etc...

  • I'm unsure about your distinction between user requirements and functional requirements. The user requirements, as in a US, should be functional requirements, and functional requirement are quite distinct from system requirements.
    – Alex
    Commented Feb 9, 2015 at 16:03
  • @Alex: User story/requirement => want to withdraw money from ATM, functional requirement=>total time to dispense bills can not exceed 30 seconds. The user requirement does not encompass the functional requirement.
    – jmoreno
    Commented Feb 9, 2015 at 18:59
  • @jmoreno That "user story" in your example is not a user story, it's the starting point in a user story. And the "functional requirement" about execution time is in a grey zone, the main functional requirement there is to dispense bills, the time constraint could have many origins.
    – Alex
    Commented Feb 9, 2015 at 19:39
  • 2
    @jmoreno Actually a performance metric like that is considered a Non-Functional Requirement a non-functional requirement is a requirement that specifies criteria that can be used to judge the operation of a system, rather than specific behaviors. The behaviors themselves are functions of a system. The user story contrasts both of these by defining the need of a user. The function of a user is instead what we know as a Use Case and not a functional requirement.
    – maple_shaft
    Commented Feb 9, 2015 at 20:49
  • @Alex See my comment above. I think you are both confused as to what a functional requirement is.
    – maple_shaft
    Commented Feb 9, 2015 at 20:51

I think the purpose of this approach is not to constrain user stories, but to prevent bad requirements.

In my experience, users are generally incapable of writing requirements. Developers are generally incapable of writing requirements. Heck, let's just admit it straight out: requirements are hard to write!

I think it would be valid for a user to write something in requirements lingo as part of a use story. However, doing so should not automatically make it a requirement. Having two conflicting use stories is a minor issue; having two conflicting requirements is a major contract-breaking issue. There's no sense in promoting one to the other before its time.

I think the draconian viewpoint comes from a recognition of human nature. If people start thinking of user stories as a place to put requirements, they will begin to do so. The real advantage of use stories over other means of gathering requirement like information is that they are worded in user's natural wordings and notation. This makes it more likely that the developers are thinking from the perspective of the customer. In a perfect world, cold requirements lingo could go there as well. In reality, such words tend to cause developers to latch onto the easy to understand requirements and miss the subtle wordings and nuances agile development wants to unearth using use stories.

  • 1
    The problem with this line of thinking is that it works well in a creative project where the user needs are clear but the hard specifications are limited. When we start talking about complex system interactions and especially regulatory constraints and business need for hard defined system parameters then user stories alone often fall short of capturing the important details. So they strike up the conversation but when I have 20 pages of hard unbending specifications and rules then that is too much to absorb in a "conversation". Functional requirements are necessary here as well.
    – maple_shaft
    Commented Feb 9, 2015 at 21:02
  • 2
    I do agree requirements are needed, I just think they should go elsewhere. I can't speak for the rest of the world, but I have found that it is extraordinarily easy to usurp the purpose of user stories and turn them into booklets full of requirements. If that happens, I have nowhere for the user stories to go. In a perfect world you could put both in user stories, but developers are human and culture is fickle. If a team gets in the habit of using user stories for requirements, it may be culturally impossible to go back to what I believe to be their primary objective.
    – Cort Ammon
    Commented Feb 10, 2015 at 5:05


User stories are for documenting what value should be added to the product, and why. Implementation details (e.g. how the value should be added, tested, measured, or validated) are constrained by the story, but are not contained within them. They are deliberately left as separate artifacts to maintain flexibility and agility within the framework.

The specifications and implementation details are most often captured in other artifacts such as Acceptance-Test Driven Development (ATDD), Test-Driven Development (TDD), and Behavior-Driven Development (BDD) scripts and scenarios. These particular artifacts aren't mandated by the Scrum framework, but they will certainly give you a good starting point if you don't already have other effective process controls in place.

User Stories Are Not Specifications

The original poster (OP) asked the following question:

[A] customer wants a different processing for different credit cards, there are strict requirements that must be implemented and known so that test cases can be written... WHERE SHOULD I PUT IT IF NOT IN THE STORY?

A user story is a feature that delivers value, provides some context to guide conversations about implementation, and a point of view tied to a value consumer who will benefit from the value delivered by the feature.

The whole point of a user story is that the implementation details are not prescriptive. The team is free to implement the feature in any way that delivers the identified value to the value consumer within the appropriate context.

A Worked Example

A Sample User Story

This is easier to explain if you start with a less ambiguous set of user stories. Since the OP didn't provide an actionable user story that follows the INVEST mnemonic, I'll invent one for the sake of an example. Consider the following story:

As a user who prefers to pay by Discover card,
I would like the option to make my purchases with the Discover card
so that I am not limited to Visa, Mastercard, or American Express.

This provides a concrete feature, provides some context that can guide the implementation decisions the team must make, and identifies the value consumer as a Discover-card owning customer. That's not a set of specifications, but it's what you need to have the right conversations with the customer and with the team about how best to implement the story during an iteration of development.

Analysis and Implementation

The actual implementation is up to the team. The team will have to do some analysis to determine:

  • The easiest way to implement a new feature.
  • Which of the various implementation options will be easiest to support going forward, without accruing technical debt.
  • How to apply the open-closed and YAGNI principles to ensure that your new feature is robust without being over-engineered.

One of the core principles of the Agile Manifesto is customer collaboration. A cross-functional, self-organizing team is expected to be able to collaborate with the customer to work out the implementation details within the guidelines provided by the user story.

If your user stories are not written well, or if the team doesn't have the skills or process maturity to do the just-enough analysis required by their agile framework, then this will obviously be much harder than it needs to be. Whole books have been written on the subject of how to create good user stories at the properly level of granularity; there is unfortunately no silver bullet, but it is a learnable skill for agile teams.

Test-Driven and Behavior-Driven Design

The best way to ensure that the analysis is sound, and that the implementation is both sane and supportable is through the use of TDD and BDD practices. For example, given the story above, the team should capture the planned implementation through artifacts such as:

  • Cucumber features with testable scenarios.

    This is most useful for driving the development of acceptance tests, and for documenting user expectations of application behavior. For example, the user story should have one or more related Cucumber features that describes how the user is able to check out with a Discover card, and what that process looks like to the user.

  • RSpec tests that validate the behavior (not the internal implementation details) of new code features.

    This is most useful for documenting and validating the intended behavior of the feature within the application. For example, the user story will drive the creation of unit and integration tests that ensure that using a Discover card invokes whatever card-specific behavior the application requires to authorize a sale through the payment gateway.

The specific tools don't matter. If you don't like Cucumber or RSpec, use whatever tools or methodologies work best for your team. However, the point is that the implementation details are based on the user story, but aren't prescribed by it. Instead, the implementation (or specifications, if you prefer) are details to be worked out during the development of the feature in a collaborative fashion.


A User Story is one specific kind of artefact with the goal of describing the interface that the user expects from the system and that is why low-level details simply does not belong there. If you put them there, you are changing the intent of the artefact and it no longer fits the definition of a US.

Use other forms of specification to capture lower level requirements and design decisions. Exactly what these other forms should be is something that have to be resolved in your organization and customized to your specific environment.

Your question sounds very similar to something like

I have this CarFactory and I need to have it make Bicycles as well, but our OOD "Guru" says I'm not allowed to do that. What is this BS!?!

Respect the separation of concerns and cohesion of your artefacts, both the ones in your code and the ones in your processes.


Make your own decisions

The answer to 'So how actually can developers ever develop a story if there are no lower requirements?' is very simple - the detailed requirements that are orthogonal to the needs of the end user (e.g. DB constraints, fields validation, etc) don't actually matter to the user. If the user needs can be met by very different fields validation, very different DB structures or perhaps even no traditional DB at all, then it would be counterproductive to have the users make up such information with a particular implementation in mind, which may be very different from how the system is implemented in the end.

You're professional developers, so make professional decisions to the best of your ability about implementation details. An user who wants a table can tell a carpenter what type of wood they'd like, but the carpenter is expected to decide how thick the table legs should be to handle reasonable loads. If you lack some information to make a meaningful decision, then that needs to be discussed with the user, but some 90% of content for a detailed requirements document actually does not need any information aside from the vague user stories common sense and industry best practices.

All those details aren't arbitrary - there are bad choices and better choices, and they should be documented since they affect other parts of the implementation, but in the end they are still implementation details that can and should be decided by the implementing team according to user needs and best practices.

A standard car analogy - if a customer wants the car painted red, then an appropriate clarification for the user story would be to ask which shade of red would be better, but not the chemical composition of the paint; nonetheless it would be expected that they wouldn't choose to paint the car with watercolors that would wash out in the rain, since it's best practice not to do so.


Lots of good answers here. Hopefully I can add some value with another one...

I think one hang up your team might be having is migrating from a non-Agile methodology.

That's usually some form waterfall methodology and, in practice, that usually does involve trying to document all technical requirements before a line of code is written.

But that doesn't always work. Often it doesn't work. The reason? Because the requirements rarely align with reality. Things change. Hence the move towards Agile.

With Agile, the User Story is all that the user cares about. They want to get form point A to point B. How to get there in terms of implementation is in your hands. If you're waiting for someone to tell you the technical requirements, then that's not really Agile. If you have questions, ask. If you need documentation, document, but you don't want the customer making all of these decisions for you. They may have opinions, but in an Agile environment those opinions should be (as your guru suggests) discusses in a conversation.

It may feel that this is a burden to your team, but consider it a luxury. Your team now has a lot of say in the solution--which wasn't necessarily the case in the waterfall model.

Not the answer you're looking for? Browse other questions tagged or ask your own question.