Software development teams use working agreements to align their ways of working and improve collaboration. In this guide, we'll cover what working agreements are, why your team should document them, and what the best practices are. We’ll also share a few example templates to help you get started with building your team's working agreement.
What are working agreements?
Working agreements describe how a team wants to work together. In practice, they are guidelines, rules, or behaviors the team has agreed on. Depending on the context, the term "working agreement" can refer to either the entire document (i.e. a list of all the working agreements) or an individual rule or guideline (e.g. "Review pull requests in less than 1 day.")
Working agreements describe how your team wants to work together.
Sometimes the document is referred to as "team contract" or "team agreement" and the listed working agreements as "team standards," "rules of engagement," "ground rules," "team norms," "team rules," "team agreements," or "collaboration guidelines."
Why do you need working agreements?
In a team, the individual members' ways of working and expectations on how other people should behave don’t often match by default. For a team to work effectively and achieve their goal, the team members need to decide on the ways of working and behaviors they want to follow.
Working agreements help teams develop a shared sense of responsibility, make it easier to identify and discuss both positive and negative behavior, empower the leader to keep the team accountable, and enhance the team’s productivity.
What to include in working agreements?
Your list of working agreements should include all the guidelines, rules, or behaviors the team members are expected to follow. When you’re creating the list, it’s helpful to start it with: "as a team, we agree to..."
Examples of working agreements:
- Ask for help when we need it
- Be transparent and honest
- Actively give constructive feedback
- Join meetings on time
- Communicate our schedule and mark absences to the work calendar
- Only work on a maximum of four stories at a time (WIP limit)
- Link all pull requests to Jira issues
To improve readability, you might want to group your working agreements. For example, many working agreement documents have a separate section for "version control rules" (how to use e.g. GitHub).
A section on version control rules could include the following agreements:
- Never commit directly to the main branch
- Review all pull requests (at least 1 approval)
- Review pull requests in less than 1 day
- Only merge when all continuous integration (CI) checks pass
Sometimes a single working agreement can consist of multiple parts. For example, a team's "definition of done" could look like this:
- The change has sufficient automated tests
- Changes have been tested on the staging environment
- Code has been peer-reviewed
- All continuous integration (CI) checks pass
- Code is merged to the main branch and successfully deployed
- Relevant documentation is updated
- Task goal is met
As every team is different, there is no single working agreement list that will work for all teams. To get started with crafting your own, you can take a look at the working agreement example templates below to see what a complete working agreement document looks like.
Best practices
1. Get started with a simple version
Sometimes, teams get stuck and try to cover "everything" in the first iteration of their working agreement. To move past analysis paralysis, start with something simple. Write down the obvious things that everyone in the team agrees on.
Once you have a shared document, it’s easier to add new working agreements. Whenever you make a decision together with the team or realize that your team has agreed to behave a certain way, but it hasn’t been documented anywhere, simply add it to the document.
2. Create the working agreements together as a team
You should always create your list of working agreements together with the team. It can be tempting to just copy-paste an old working agreement document or an example template, slightly modify it, and call it a day. However, this often means that some of the working agreements don’t make sense to all the team members. This often results in some of the team members ignoring the document altogether as they feel like it doesn’t reflect reality.
You should always create your list of working agreements together with the team.
Working agreements only work well when they are important to the team and agreed on by each member of the team. By creating the working agreement together, you ensure everyone gets to comment on it and is committed to following the common agreements.
3. Document your working agreements in one place
You should have a single document that you can point to everyone who needs to understand how your team works.
It’s common for software companies to have company-level rules and processes that every team should follow. These may be documented in multiple different places and your team's working agreement may include additions or slight modifications to these rules. It’s important that you have a team-specific document where you bring everything together.
For example, If you have a company-level software development process, you should refer to it in your team's working agreement and include any team-specific additions or modifications next to the reference.
4. Keep your working agreements in sync with real life
A working agreement should be a living document that reflects how the team actually works. When you work as a team, you learn new things and often need to adjust the way you work together. Often, these changes happen organically within the team members, and it’s easy to forget to document these into the common list of working agreements.
A working agreement should be a living document that reflects how the team actually works.
One good way to keep your working agreement up to date is to regularly take a look at it in your team retrospectives. This is an opportunity for the team to discuss how you could improve the way you work together.
When you have these discussions, you should also remove working agreements that are no longer relevant. It’s easy for the list of working agreements to get bloated and become so complex that the team no longer finds it valuable.
5. Make it easy to propose changes to the working agreements
The easier you make it for people to propose changes to the working agreements, the more likely it is for the list to stay up to date. Ideally, you should have an entry at the beginning of the working agreement document that tells everyone how they can propose changes.
For example, if you host your document on a collaborative platform like Google Docs, Notion, or Confluence, you could include a note like this: "Everyone in the team can propose changes to our working agreements. You can propose changes to this document by adding a comment or suggestion and tagging <name of the team lead (/scrum master/agile coach)> in the message. You can also suggest new working agreements in the team retrospectives."
6. Go through the working agreements with new team members
Whenever a new person joins the team, it’s important that you go through the working agreements with them. They should be able to comment and ask questions to understand why certain working agreements are the way they are. Going through the list together is a great way to onboard people to the team and, at the same time, ensure they're committed to the team’s ways of working.
How to enforce working agreements
Working agreements that are not followed are useless and, at worst, harmful. Having a ton of agreements that are not actually followed may leave people feeling that the team has a lot of "bureaucracy" and useless "policies" just for a show but "no one actually follows them."
Working agreements that are not followed are useless and, at worst, harmful.
A great way to make sure team members follow the agreements is to remind them about the agreements during the course of their work. You can do this by effectively using your tools and continuous integration and by automating everything you reasonably can.
There are, of course, agreements that can’t be automatically enforced. (I wonder how you would automatically enforce the agreement to "be transparent and honest"?) In these cases, discussing working agreements in code reviews and regular retrospectives are your friend.
1. Automate all the agreements you can
The most efficient way to get people to consistently follow a working agreement is to automate it. It’s also often cheaper in the long run than having the whole team spend time and energy on adopting a new habit.
Automating working agreements also has the significant upside of reducing nitpicking in your team. No matter how well you do it, reminding other people of things that they should’ve known and done feels annoying. Automating agreements also helps you onboard new people and lowers the cognitive load for everyone in the team.
There are multiple things related to working agreements that you can enforce using your tools and continuous integration.
Automated code style. Working agreements often include references to code style that everyone should follow. Traditionally, people have enforced these by nitpicking in code reviews. This is often a waste of time.
Instead, format your code with a deterministic code formatter (like Prettier or Black) and enforce other aspects of your code style using a linter that works with your programming language (e.g. ESLint for JavaScript and TypeScript).
Automated code checks. In addition to code style, teams often have other code-related agreements. For example, many teams have a working agreement "test coverage should not decrease" to continually improve their test coverage while they create new code.
Whatever your code-related agreements are, you can likely use ready-made tools (like Codecov for code coverage) to enforce your agreements or use tools like Danger or Betterer to write your own checks.
Automated team workflows. If you have working agreements related to your development process like "do X before Y" or "send notification to customer support", you should see if your existing tools support these workflows. Many issue trackers have a wide range of notification settings and automation features.
Your version control system likely also supports workflow related policies. For example, GitHub has a built-in feature for enforcing a working agreement to "review all code before merging to the main branch."
If you're particularly interested in code reviews, my colleague Kimmo Brunfeldt has written a great guide with best practices for automating your code review processes.
Automated team habits. Automating team habits may be a new thing to most readers, as I'm not aware of any other product than Swarmia that does this. The idea with our working agreements feature is to allow your team to adopt working agreements for team habits like "close bugs in less than three days" or "link pull requests to issues."
These working agreements are automatically tracked and your team is notified in Slack whenever you're about to break your agreement and go back to your old, bad habits.
Automated checklists. If you have agreed to complete certain manual steps for each new task you can configure your tools to include a ready-made checklist for the person doing the task.
Automated checklists or templates for e.g., new issues or pull requests are supported by most software tools like issue and project trackers (Jira, Shortcut, etc.) and source code management tools (like GitHub and GitLab). Crossing out things from a checklist reminds team members about working agreements, reduces human error, and helps people to feel progress in their work.
2. Use code reviews and retrospectives
Some working agreements can’t be automatically enforced as they're often too subjective ("leave the codebase to a better state than where it was") or abstract ("be transparent and honest"). Code reviews and retrospectives are natural places for making sure these working agreements are followed.
When developing software, it’s common for people to feel "too busy" and cut corners. Sometimes this can be an acceptable trade-off but often it’s just a bad habit. Having a list of working agreements that everyone agrees to allows team members to refer to them in code reviews and hold each other to a higher standard.
Working agreements allow team members hold each other to a higher standard.
Abstract working agreements related to behavior and teamwork are often not binary but more nuanced. For example, when a team has agreed to "be transparent and honest," it is possible for the team to follow this in one thing (like communicating the status of their task) and miserably fail in another (e.g. sharing context on why a task has a high priority).
Retrospectives offer a great opportunity to discuss these nuances, when team members feel that the team has not succeeded in keeping their agreements. In the end, it’s up to the team to decide what’s good enough for them and what does following a specific working agreement look like in the end.
Working agreement example templates
To help you get started, you can check out these two example templates: one for agile project teams and the other one for product teams that are doing on-going product development.
Agile project team working agreement
This template is for a team that is developing software as a project. For example, an external agile team of consultants or an internal team composed of people from multiple teams that are working together as a temporary project team.
This template is designed to answer the question, "what should anyone working in or with the team know?" and therefore, it also includes the background for the project. This format works well for projects because their scope is limited.
When working on a project, you usually have stakeholders to whom you need to communicate about the project. You might also have one-off consultants doing specific tasks or new team members joining the project. In both cases, understanding the project and the team’s working agreements are important.
Product team working agreement
This template is for a team that is developing a software product on an on-going basis. Compared to the above agile project team working agreement, this is shorter and only includes team-specific working agreements.
Software products often have a lot of related context and documentation. It’s also common for companies that have their own software products to have company-wide policies and processes. There’s no reason to duplicate them to the team's working agreements documentation.
Conclusion
Working agreements are a great tool for agile software teams who want to improve collaboration and be more productive. When you agree on what you want to do together with the whole team and make sure everyone is able to keep the agreements, your team will work together with less friction and be happier.
