The Art of Agile Development: Incremental Requirements

The second edition is now available! The Art of Agile Development has been completely revised and updated with all new material. Visit the Second Edition page for more information, or buy it on Amazon.

Full Text

The following text is excerpted from The Art of Agile Development by James Shore and Shane Warden, published by O'Reilly. Copyright © 2008 the authors. All rights reserved.

Incremental Requirements


We define requirements in parallel with other work.

A team using an up-front requirements phase keeps their requirements in a requirements document. An XP team doesn't have a requirements phase and story cards aren't miniature requirements documents, so where do requirements come from?

The Living Requirements Document

Sit Together

In XP, the on-site customers sit with the team. They're expected to have all of the information about requirements at their fingertips. When somebody needs to know something about the requirements for the project, she asks one of the on-site customers rather than looking up the information in a document.

Face-to-face communication is much more effective than written communication, as [Cockburn] discusses, and it allows XP to save time by eliminate a long requirements analysis phase. However, requirements work is still necessary. The on-site customers need to understand the requirements for the software before they can explain it.

Real Customer Involvement

The key to successful requirements analysis in XP is expert customers. Involve real customers, an experienced product manager, and experts in your problem domain (see The XP Team in Chapter 3 and Real Customer Involvement in Chapter 6). Many of the requirements for your software will be intuitively obvious to the right customers.

If you have trouble with requirements, your team may not include the right customers.

Some requirements will require even expert customers to consider a variety of options or do some research before making a decision. Customers, you can and should include other team members in your discussions if it helps clarify your options. For example, you may wish to include a programmer in your discussion of user interface options so you can strike a balance between an impressive UI and low implementation cost.

Write down any requirements you might forget. These notes are primarily for your use as customers so you can easily answer questions in the future and to remind you of the decisions you made. They don't need to be detailed or formal requirements documents; keep them simple and short. When creating screen mock-ups, for example, I often prefer to create a sketch on a whiteboard and take a digital photo. I can create and photograph a whiteboard sketch in a fraction of the time it me to make a mock-up in an electronic tool.

Some teams store their requirements notes in a Wiki or database, but I prefer to use normal office tools and check the files into version control. This allows you to use all of the tools at your disposal, such as word processors, spreadsheets, and presentation software. It also keeps requirements documents synchronized with the rest of the project and allows you to travel back in time to previous versions.

Work Incrementally

Work on requirements incrementally, in parallel with the rest of the team's work. This makes your work easier and ensures that the rest of the team won't have to wait to get started. Your work will typically parallel your release planning horizons, discussed in Release Planning in Chapter 8.

Vision, Features, and Stories

Release Planning

Start by clarifying your project vision, then identify features and stories as described in Release Planning in Chapter 8. These initial ideas will guide the rest of your requirements work.

Rough Expectations

Figure out what a story means to you and how you'll know it's finished slightly before you ask programmers to estimate it. As they estimate, programmers will ask questions about your expectations; try to anticipate those questions and have answers ready. (Over time, you'll learn what sorts of questions your programmers will ask.) A rough sketch of the visible aspects of the story might help.

Mock-Ups, Customer Tests, and Completion Criteria

Customer Tests
"Done Done"

Figure out the details for each story just before programmers start implementing it. Create rough mock-ups that show what you expect the work to look like when it's done. Prepare customer tests that provide examples of tricky domain concepts and describe what "done done" means for each story. You'll typically wait for the corresponding iteration begins to do most of this work.

Sometimes the best way to create a UI mock-up is to work in collaboration with the programmers. The iteration planning meeting might be the best time for this work.

Customer Review

Only working applications show customers what they're really going to get.

While stories are under development, before they're "done done," review each story to make sure it works as you expected. You don't need to exhaustively test the application—you can rely on the programmers to test their work—but you should check those areas where programmers might think differently than you do. These areas include terminology, screen layout, and interactions between screen elements.

Prior to seeing the application in action, every conversation is theoretical. You can discuss options and costs, but until you have an implementation, everyone can only imagine how the choices will feel. Only working applications show you what you're really going to get.

Some of your findings will reveal errors due to miscommunication or misunderstanding. Others, while meeting your requirements, won't work as well in practice as you had hoped. In either case, the solution is the same: talk with the programmers about making changes. You can even pair with programmers as they work on the fixes.


Many changes will be minor and the programmers will be able to fix them as part of their iteration slack. If there are major changes, however, the programmers may not have time to fix them in the current iteration. (This can happen even when the change seems minor from the customer's perspective.) Create story cards for these changes. Before scheduling such a story into your release plan, consider whether the value of the change is worth its cost.

Over time, programmers will learn about your expectations for the application. Expect the number of issues you discover to decline each iteration.

Exploratory Testing

1See Exploratory Testing later in this chapter.


Our customers don't know what the team should build. What should we do?


Do you have a clear, compelling vision? If so, your customers should know where to start. If you don't, you may not have the right customers on your team. In this case, you can use traditional requirements gathering techniques (see "Further Reading" at the end of this section) to determine the software's requirements, but you're better off involving real experts (see The XP Team in Chapter 3 and Real Customer Involvement in Chapter 6).

What if the customer review finds too many problems for us to deal with?

This is most likely to happen at the beginning of the project, before programmers have learned what the customers like. If this happens to you, spend more time with programmers so that your perspective is captured sooner and more accurately. In some cases, customers should pair with programmers as they work on error-prone areas.

As a programmer, I'm offended by some of the things customers find in their reviews. They're too nitpicky.

Things that can seem nitpicky to programmers—such as the color of the screen background, or a few pixels of alignment in the UI—represent polish and professionalism to customers. This goes both ways: some things that seem important to programmers, such as quality code and refactoring, often seem like unnecessary perfectionism to customers.

Rather than getting upset about these differences of perspective, try to learn what your customers care about and why. As you learn, you will anticipate your customers' needs better, which will reduce the need to make changes.


When customers work out requirements incrementally, programmers are able to work on established stories while customers figure out the details for future stories. Customers have ready answers to requirements questions, allowing estimation and iteration planning to proceed quickly and smoothly. By the time a story is "done done," it reflects the customers' expectations, and customers experience no unpleasant surprises.


Sit Together

In order to incrementally define requirements, the team must include on-site customers who are dedicated to working out requirements details throughout the entire project. Without this dedicated resource, your team will struggle with insufficient and unclear requirements.

No Bugs

When performing customer reviews, think of them as tools for conveying the customers' perspective rather than as bug-hunting sessions. The programmers should be able to produce code that's nearly bug-free (see No Bugs in Chapter 7); the purpose of the review is to bring customers' expectations and programmers' work into alignment.


The traditional approach to requirements definition is to perform requirements analysis sessions and document the results. This requires an up-front requirements gathering phase, which takes extra time and introduces communication errors.

You can use an up-front analysis phase with XP, but good on-site customers should make that unnecessary.

Further Reading

Software Requirements [Wiegers 1999] is a good resource for classic approaches to requirements gathering.

If you liked this entry, check out my best writing and presentations, and consider subscribing to updates by email or RSS.