You've decided to build something custom. Maybe it's a web app, a client portal, or a platform for your business. You know what you need — or at least you think you do. Now you need to explain it to a developer.
This is where a lot of projects go sideways. Not because the developer is bad, and not because your idea is flawed. It's because the brief missed the mark. Too vague, too specific in the wrong areas, or focused on technology instead of outcomes.
Here's how to write a brief that actually gets you what you want.
Start With the Problem
The most important thing in your brief isn't what you want built. It's why you want it built. What problem are you solving? What's broken about how things work today?
"We need a booking system" tells a developer what to build. "Our customers currently call to schedule appointments, and we miss 30% of calls during business hours" tells them why it matters. The second version gives the developer context to make better decisions about how to solve it.
Start your brief with the problem. Explain what's happening today, why it's not working, and what you'd like to be different. The more specific you are about the problem, the better the solution will be.
For example: "Our team spends 2 hours every morning entering yesterday's appointments into our billing system because the tools don't sync" is infinitely more useful than "we need better software."
Describe Your Users
Who's going to use this thing? And not just the obvious answer — think about every type of person who'll interact with it.
If you're building a client portal, you have at least two user types: your team (admins) and your customers. What does each group need to do? What should admins see that customers shouldn't? Are there different levels of access within your team?
Describe your users like they're people, not roles. "Sarah runs our front desk. She needs to see today's appointments, check customers in, and process payments. She's not technical and gets frustrated when she has to click through multiple screens." That gives us more to work with than "admin user needs appointment management."
Need help with this?
We build custom solutions like this for clients every week.
Book a Strategy Call →What to Include
Your brief should cover the basics. Start with the business context — what your company does, how many users or customers you're dealing with, and what tools you currently use. Then describe the core workflows. Walk through the three or four things that need to happen most often. "A customer requests a quote through the form. Someone on our team reviews it and sends an estimate. The customer approves and we schedule the work."
Include your constraints. Budget range, timeline expectations, any technical requirements like integration with existing systems. If you use QuickBooks for accounting and need the new system to sync with it, say so now — not in week six.
If you have examples of products you like, share them. "The booking flow on this site is close to what we want" saves hours of back-and-forth. You're not asking the developer to copy it — you're giving them a reference point.
What to Leave Out
This is where most briefs go wrong. Leave out technology preferences unless you have a genuine technical constraint. "Build it in React" doesn't help unless you have a React team that needs to maintain it. Let the developer choose the tools — that's literally their expertise.
Leave out pixel-perfect mockups. Wireframes are great. Sketches on a napkin are fine. But a polished Figma file before the discovery process often does more harm than good. It locks you into a layout before you've validated the user flow, and it signals to the developer that the design decisions are already made.
Leave out comparisons to products built by 200-person engineering teams. "Make it like Uber" isn't helpful. Uber has spent billions on their platform. What specifically about Uber's experience do you like? The real-time tracking? The rating system? The simple booking flow? Be specific about the aspect, not the product.
The One Sentence That Saves Everything
At the end of your brief, write one sentence that answers this question: "If this project succeeds, what's different about your business in six months?"
"We're spending 50% less time on administrative work." "We're getting 3x more online bookings." "Our customers can self-serve instead of calling us." "We've consolidated five tools into one."
That sentence becomes the north star for every decision during the build. When we're debating whether to add a feature or simplify a flow, we go back to that sentence. Does this change move the needle on the outcome you care about?
A great brief isn't long. It doesn't need to be a formal document. It just needs to clearly explain the problem, the people, and the desired outcome. Everything else is a conversation.