How to Write Specifications for an Agile Project

As we saw in a previous article, the Agile approach is a project management method that favors project planning where goals are set over a short period.

Do you have a project? Do you want to write specifications following this methodology? Whether you are considering custom web development (in French) or an existing solution, this article is for you!

Table of contents:

• Definition of specifications
• Are they necessary?
• What is the format of specifications?
• Steps
• Specifications as a living document
• Including user stories in the specifications
• Deadlines

Definition of specifications

Specifications are a necessary document for the development of any new project. They are a brief that defines all the needs, expectations, and constraints for developing the project in question.

Writing them can prove tedious, they are rarely detailed, and they require a discussion if the project is carried out by a service provider or on a fixed-scope basis.

That is why the Agile method favors the backlog and user stories, or "US".

Backlog: "An ordered and emergent list of what is needed to improve the product"

A user story: A requirement stated from the point of view of a user goal.

User stories, also called epics, themes, or features, all follow the same format:

• As a <role>
• I must <requirement or feature>
• In order to <goal/value>

In a classic project (V-model), the specifications try to plan everything in advance. In an agile approach, they set out the broad outlines and leave room for adaptation. This fundamental difference changes how the document is written: the aim is to communicate a vision rather than to freeze an exhaustive list of specifications.

Are they necessary in an agile project?

No, writing specifications is not always necessary if you trust your service provider or if your development team is already in place. It is therefore advisable to build the backlog and start the implementation.

Otherwise (choosing a service provider or launching the project in-house), you must wait for the answer to your request for a technical solution with a detailed estimate to know whether the project is feasible. The specifications here will present your goal: the number of development days required.

In an agile approach, the specifications provide answers to questions before the project starts, and user stories take over afterward!

When specifications remain essential

Even in an agile approach, some situations make specifications unavoidable. When you issue a call for tenders to several service providers, you need a reference document to compare proposals on a common basis. Likewise, in a regulated context (healthcare, finance, public sector), formal specifications may be required for compliance. Finally, if your project involves several teams or departments, this document serves as a shared foundation to align everyone on the same vision. When you take over an existing project, a technical audit at Efficience IT (in French) lets you objectively assess the state of the code and feed the technical constraints of the specifications.

What is the format of specifications?

You can find templates online to help you write them, but they always remain insufficient and ill-suited, because every project is different from the next.

So to write yours, simply put together slides and sentences in bullet points containing your essential features and your thinking (there is no ideal number of pages!).

Favor clarity over volume

Good agile specifications often fit in a few pages. The point is not to detail everything, but to clearly convey three elements: the problem you are solving, the value expected for the end user, and the known limits of the project. For example, for a meeting room booking application, the specifications could simply state: "Employees must be able to book a room in under 30 seconds from their phone", rather than describing every screen and every button.

Concrete examples of content

For an e-commerce site redesign with a solution like Sylius (in French), agile specifications could contain:

• The vision: "Increase the conversion rate by 15% by simplifying the purchase funnel"
• The personas: an occasional 35-year-old buyer, a professional buyer who orders in bulk
• The main features: product catalog, cart, secure payment, order tracking
• What is out of scope: loyalty program (postponed to a later phase)

This level of detail is enough to guide a service provider without constraining them on implementation choices.

Steps

1. General presentation of the company (activity, clients, competitors...)

2. Context: Where did your idea come from? What problem does it solve? What will it change within your organization? What are your expectations and ambitions? This is also the stage to ask the fundamental question: custom development or off-the-shelf software? The advantages of off-the-shelf software for your company (in French) deserve to be evaluated before launching a development effort.

3. Features: do not go into too much detail or describe your specifications; the point is to list, in a general and understandable way, what is expected to be built (highly detailed features = high failure rate & lighter features = reduced complexity, time savings, and the ability to test hypotheses in the field)

4. Special considerations: if there are complex points in your project, explain them clearly and in detail so they are obvious to readers.

5. Constraints: it is essential to lay out all the constraints, whether technical (operating system, web hosting, security...), or related to scheduling (in the case of seasonal activity where the project must be ready before the start of a defined period). Among the technical constraints, the choice of architecture is a defining one: microservices or modular monolith (in French) is a decision to anticipate as early as the specifications.

This will allow proposals to be handled in a way that suits your project!

How to describe features well

The temptation is strong to write exhaustive specifications. Yet in an agile approach, a feature described too precisely leaves little room for the technical team to propose innovative solutions. Prefer an outcome-oriented description: "The user can filter products by color, category, and availability" rather than "A three-level dropdown menu with checkboxes lets users select the filter criteria". The first wording leaves room to find the best possible interface. The second locks the team into a choice that may not have been tested with users.

Specifications as a living document

In the Agile method, the specifications are not a frozen document that you write once and for all before putting it away in a drawer. They evolve with the project. At each sprint, user feedback and the team's learnings can lead you to revisit priorities, add features, or remove some.

Keeping the document up to date

We recommend versioning your specifications, exactly like source code. Choosing the right technical documentation tool (in French) makes this easier. Use a collaborative tool (Notion, Confluence, Google Docs) that keeps the change history. At the end of each sprint or at each key stage, take a few minutes to update the document: remove what is no longer relevant, and add the new directions that come from field feedback.

Specifications feed the backlog

The link between the specifications and the backlog is direct. Each major feature identified in the specifications translates into one or more user stories in the backlog. For example, the "order tracking" feature in the specifications could generate the following user stories:

• As a customer, I must be able to view the status of my order in real time, in order to know when it will be delivered.
• As a logistics manager, I must be able to update the status of an order, in order for the customer to be informed automatically.

Including user stories in the specifications

Some teams choose to include the first user stories directly in the specifications. This approach has the advantage of showing a service provider concretely how you envision the functional breakdown of the project.

From business need to user story

Let us take a concrete example. You are developing an appointment management application for a medical practice. The business need is: "Patients must be able to book appointments online." Translated into user stories, this gives:

• As a patient, I must be able to choose an available slot on a calendar, in order to book an appointment without calling the practice.
• As a medical secretary, I must be able to block slots for emergencies, in order to keep flexibility in the schedule.
• As a doctor, I must receive a notification when a new appointment is booked, in order to organize my day.

Including these user stories in the specifications lets the service provider understand not only what you want, but also for whom and why. This saves considerable time in the first discussions.

Acceptance criteria

Each user story can come with acceptance criteria that specify the validation conditions. For example, for the user story of the patient booking an appointment: "The patient receives a confirmation email within 5 minutes of booking" or "A booked slot no longer appears as available to other patients". These criteria serve as a contract between you and the development team, without dictating the technical solution.

Deadlines

"Give your service providers a realistic go-live date"

The Agile method therefore does not deny the functional specifications and their necessity, but rather changes their form by allowing them to be completed while the project is already under way.

One essential point to remember: in an agile approach, the schedule is often an adjustment variable. Rather than fixing an immutable functional scope, you define a calendar, then prioritize features based on their business value. This is the approach we took for Doctavis, an MVP delivered in record time (in French). If the allotted time runs out before all the features are developed, the lowest-priority ones are postponed. This approach considerably reduces the risk of missed deadlines and ensures that the most important features are delivered first.

At Efficience IT, all projects are run using the Agile approach.

Going further

• Core Team: structuring a project team (in French), organizing the team that will carry the specifications
• Doctavis and Efficience IT: a race against the clock to ship an MVP, a concrete case study on building an MVP with agile specifications
• Which tool should you choose for your technical documentation? Structuring the project documentation alongside the specifications
• How to produce documentation for your Symfony project with the Diataxis approach (in French), organizing a project's documentation deliverables
• Scrum Guide, the official guide to the Scrum methodology
• Agile Manifesto, the founding values and principles of the agile approach
• Mountain Goat Software: User Stories, reference resources on user stories