How to write a brief for a developer: requirements, constraints and acceptance criteria

Two developers given the same vague brief will produce two incomparable quotes, because each filled the gaps with their own assumptions. A brief exists to reduce assumptions: not to describe the solution, but to define the problem, the constraints and how everyone will know the work is done. I write this as someone who receives briefs every week, mostly from agencies.

Problem, not solution

The most frequent mistake is a brief describing the implementation: "we need a plugin that does X", "we want an app". It is better to start from a measurable goal and the context: who uses the system, what problem they have today, what should happen afterwards. The technical solution is the developer's job, and a brief that imposes one often imposes the wrong one.

The sections you need

Context and goal

Who the end client is (if an agency is writing), what they do, why the project starts now. A verifiable goal: "reduce phone calls about opening hours", not "improve communication".

Users and roles

Who will use the system and with what permissions: visitors, registered customers, editors, administrators. Every extra role is extra complexity, and it is good to know upfront.

Functional requirements, prioritised

A list of features split into essential, important and nice-to-have. This split makes it possible to estimate a minimum scope and to think in phases rather than all or nothing.

Non-functional requirements

These are almost always missing and they cause the arguments at the end of a project:

• performance targets (for example "good" Core Web Vitals on the main templates);
• accessibility level (WCAG 2.1 AA or 2.2 AA);
• languages and translation workflow;
• supported browsers and devices;
• security and privacy requirements, including the personal data processed.

Existing systems and integrations

What already exists: site, hosting, domain, management system, CRM, payment platform. For each integration: is there a documented API? Who provides access? Is there a test environment? An undocumented integration is the number one cause of overruns.

Content and materials

Who supplies copy, images and translations, and when. If the design exists, in what format and how complete: a Figma file with components and states is very different from three static screens (I cover this in From Figma to WordPress).

Timing, budget, decisions

Real deadlines and why (an event, a campaign), a budget range, and who approves. A single decision-maker shortens projects more than any technical choice.

Ownership and handover

Who owns the code, where the repository lives, who holds the accounts (hosting, domain, stores), what is delivered at the end: documentation, access, staging environment.

Acceptance criteria

How you establish that the work is complete. For each essential feature, a verifiable sentence: "a registered user sees only their own bookings", "the form submits the request and shows a confirmation even without JavaScript". They are the technical contract between the parties.

A template

• Context and measurable goal: …
• Users and roles: …
• Essential / important / nice-to-have features: …
• Non-functional requirements (performance, accessibility, languages, security): …
• Existing systems and integrations, with documentation: …
• Available content and design: …
• Deadline and reason: …
• Budget (range): …
• Decision-maker: …
• Ownership of code and accounts: …
• Acceptance criteria: …

How to read the replies

A good quote sends the brief back with questions, explicit assumptions and exclusions. I would be wary of anyone who replies within an hour with a flat figure on a complex project: they have not read it, or filled the gaps their own way. Comparing quotes only makes sense if the assumptions are the same.

The most common mistakes

• Describing the solution instead of the problem: "we need a plugin", "we need an app", without saying what for.
• No priorities: every feature looks essential, and the estimate becomes all or nothing.
• Missing non-functional requirements: speed, accessibility and languages discovered at the end.
• Integrations taken for granted: "it connects to the management system", without knowing whether it has an API.
• Content "on its way": copy and images arriving when the project is finished and changing the layout.
• Too many decision-makers: every review opens a new round of opinions.
• Budget left unsaid: the developer proposes a solution out of scale, one way or the other.
• Deadlines without a reason: an arbitrary date prevents thinking in phases.

If the project is still vague, the most honest choice is a separate, paid analysis phase that produces the brief and a reliable estimate. It costs little compared with the project and greatly reduces risk for both sides.

My take

The best brief I receive is the one that admits what it does not know. Working mostly with agencies, I prefer a short document with clear goals and constraints to a long specification that already describes the solution. Then I work in previews: every week an online version you can review (with Netlify every change generates one), so the brief is checked against the real product, not on paper.

And I always ask for ownership of code and accounts to be put in writing: not out of distrust, but because it is the question that, asked late, causes the most trouble.

For me, an honest brief is worth more than a perfect specification.

Why work with me

I have been programming since 1999, delivered more than 300 projects and work as an external developer with about 30 agencies, from Rome and remotely. I answer a brief with questions, explicit assumptions and a phased estimate, not a flat figure.

If you have a project to set up, get in touch: in a call of about 20 minutes we turn the idea into a brief that holds up. The service is in Custom software development.