How do you deal with design in Scrum? Do you still have well written design documents for each scrum iteration? Do you just do design notes featuring UML diagrams? Or do you just have well commented code?

Each iteration may involve changing design so I just wanted to know how people capture this so new developers have an easy job of understanding the domain and getting on board as rapidly as possible.

  • Design should be dealt with incrementally by the team, both in advance of a sprint as well as during. Most teams incorporate backlog refinement as an ongoing activity to review the upcoming backlog items. This is a perfect time for the team to architect and design enough of the solution to estimate the effort. Any artifacts created should be attached to the story. During the sprint, more fine grained architecture and design activities should occur. Attach these artifacts as well. When the story is completed there should be a rich amount of information about the solution provided.
    – treefiddy
    Sep 21 '19 at 15:20

just because it is scrum does not mean everything changes each sprint!

Scrum is about doing what is necessary (but no more). You still need to do the design and you still need to document. Its just the amount is not fixed nor how to do it.

Part of the planning each sprint is deciding what needs to be done. If something in the backlog needs to be designed because it impacts other things then you need to add a specific task for the design processes and do that before the implementation task.


I have a lot to say on this topic. I've seen many cases where companies/teams/people say they're using an Agile approach to software but in reality, they want to reap the rewards that Agile methods promise without adhering to the principles.

For rapid iteration to work, you should do test driven development (I stopped short of saying you have to do TDD reluctantly). In TDD, your tests express the design and intent of the code (when they say "the code is the documentation" what they should be saying is "the tests are the documentation"). By writing unit tests that express your understanding of the feature at hand you are explicitly stating what you believe the code needs to do. Then you write the code that does it. Then you refactor that code so that adheres to good architectural principals "Red-Green-Refactor".

Running your unit tests with every checkin (or even before every checkin) verifies that the new code you've written doesn't break expected functionality in some other area of the application. This provides a safety net that allows you to change the code with wreckless abandon. As your understanding of the requirements at hand increases, you can modify the test to reflect that new knowledge. The real design lies in the Unit tests. Everything else (including code that is not covered) is a lie.

Here's some recommended reading

These are good places to start looking to learn how to truly approach agile development.

  • 4
    @Murph: The idea is that the architecture is emergent, that you should find it through testing rather than defining it up-front. Jan 14 '11 at 12:11
  • 5
    @Martin I sort of see - but there are still horrible issues of scale there. I'm comfortable with that up to a certain level but beyond that... well I suppose you should probably have done that (or at least got an initial structure) before you get to the scrum level of development (wherein one might expect the team to refine and evolve the high level architecture as well as the low).
    – Murph
    Jan 14 '11 at 13:30
  • 2
    @Murph: Yes bootstrapping is a problem. You need to select programming language at least. Non-functional requirements like scalability and performance influences the architecture a lot and must be taking into account asap. But apart from that I like to start out as simple as absolutetly possible, then incrementally and iteratively add working features (yagni) slice by slice. Focus on refactoring to keep the code base clean and extract stuff until the design appears. Jan 14 '11 at 15:15
  • 1
    The reason Scrum is iterative is that the very nature of software means we never get it right the first time. In many cases the stakeholders don't know what they really want until they have something in front of them. What's better: spending hours creating a design for a feature (that will need to be refined or most likely thrown out as the rubber hits the pavement) and communicating that design to the implementer; or spending those hours implementing a first pass at the feature and refining it through tests and refactoring. Jan 14 '11 at 17:17
  • 3
    By the way, you'll never realize the true value of TDD until you have a test UNEXPECTEDLY turn red. That was my big "aha" moment with TDD. Looking at the test that just turned red, I realized that without the test, the bug would have been very difficult to track down after the code was in testers hands. If you need to see a high-level top-down architecture, there are many tools that can generate Sequence and Class diagrams from your code. Use those to get a snapshot report and dispose of them because they are not the law. Jan 14 '11 at 17:25

Scrum is a project-management methodology, not a software-development methodology. Scrum is typically used in conjunction with an Agile methodology. Therein lies your answer.

  • 4
    Scrum is an agile methodology and it is focused on the development team and stake holders and getting iterative deliveries of working code. Top down project management and Scrum are like oil and water. Jan 14 '11 at 7:13
  • 1
    @Mike agreed, but I've always felt that Scrum is a project manager's agile methodology while Extreme Programming is a developer's agile methodology. That said, I've seen Scrum applied to a lot of projects other than software. Interestingly Wikipedia provides this definition of Scrum: Scrum is an iterative, incremental methodology for project management often seen in agile software development, a type of software engineering: en.wikipedia.org/wiki/Scrum_(development).
    – ahsteele
    Jan 14 '11 at 7:41
  • 2
    Just realized that I accidentally downvoted your comment...didn't mean to. They won't let me remove that vote unless you do a minor edit. I've never seen Scrum described as a project management method before. Interesting. That being said, I think expecting scrum to work for software without applying TDD is why many attempts at "doing agile" fail. Jan 14 '11 at 8:13

There is not as much up front design as requirements frequently change. So designing down to the class level is usually a waste of time. However, it can be worthwhile sketching higher level architectural decisions.

The problem with doing heavy duty design documents is that they're obsolete almost as soon as they are created. So what's worked best is usually high level documentation that's unlikely to completely change in a short amount of time.

  • 1
    I would not say the requirements are constantly changing. Infact during a sprint the requirements are static and unchanged. After each sprint the priority of the requirements can be re-assessed. Buy your overall goal will not change. Jan 14 '11 at 6:04
  • @Martin good point. I guess I should rephrase they're changing from scrum to scrum.
    – Vadim
    Jan 14 '11 at 6:05

Scrum is an iterative and incremental model based on agile values. That means you don't have a separate design phase. The idea is that you should constantly be dealing with design, just as you constantly are dealing with analysis, implementation, testing and integration throughout the project.

You need a bit of planning for this to work. Enter the sprint planning meeting, where the team estimates tasks for the sprint ahead. Most people don't realize this is not only an estimation meeting, but a design effort as well. For example, a task might be "Add code for new car model". You cannot estimate this yet, you need to know a bit more. So the team discusses the design and comes up with a broad solution ("subclass Car?") and adds that as a reminder to the task. You rarely need more formality than that. You now have an idea how to solve the problem. You don't have all details yet and that is fine, you know enough of the design to be able to make a comfortable estimate. Without having to create any diagrams at all (at this point).

For actual physical documentation, I recommend creating a systems overview diagram up on a wall for all to see. The overview only needs to have the most important classes and modules included and should rarely have to be updated. Also, creating a few state diagrams for the most important classes in the system is very helpful. Sprinkle with a few select sequence diagrams of typical use cases to make it easy for people to quickly see how things are connected. I assume you can generate class hierarchy diagrams from your code, so that problem is easily solved.

Note that all diagrams are created after the actual implementation. This is keeping with the "working software over comprehensive documentation" and just-in-time design.

And yes, readable code is definitely documentation.


The overall architecture of the project and the high level design would be done outside of the scrum teams when the project owners are creating the stories.

There needs to be enough of an overall design written down in whatever form to help see the relationship among the stories and the customer's expectations.

Some of the design needed for each story would be done in planning and negotiation with the product owner during planning.

The bulk of the design effort for a story would be done in the sprint.

If the story isn't defined enough to estimate, then a time box could be set aside in the current sprint to do enough design work that an appropriate story could be created for a later sprint.


My understanding is that you do a higher level design with the up front requirements that you gather at the beginning of the project. You document this design well.

Then when you go to actually implement the requirement, you change the lower level design as you need to, but you avoid changing the higher level design.

Well, that's how it was explained to me five minutes ago anyway...


There is today a split inside the Eclipse community between traditional UML tools focused on MDD in which the model drives the code/development and Omondo which considers that iterations should drive the development process and certainly not only the model.

I agree with them because MDD is crap while UML is really an excellent way because standardize in order to communicate with other team members. alt text

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