How to Brief a Developer: The Document That Saves Every Project
Most web projects fail not because of bad code, but because of a bad brief. Here's the exact document template I ask every client to fill out before we start, and why each question matters.
How to Brief a Developer: The Document That Saves Every Project
Most web development projects that go wrong don't go wrong because of bad code.
They go wrong in the first conversation, or in the silence before it. A client has a clear picture in their head of what they want. A developer has assumptions about what that means. Neither person knows the other's assumptions exist. Work starts. Three weeks in, the client sees something that looks nothing like what they imagined, the developer is confused about why, and both parties feel frustrated and slightly deceived.
This is not a technology problem. It is a communication problem. And it is almost entirely preventable with one document written before any code is touched.
This is that document.
I share this with every client before we start. Some people use it as a template and send it back filled out. Others use it as a conversation guide. Either way, the projects that start with this document go better, consistently, than the ones that don't.
Use it. Share it. Fill it out before you talk to any developer, including me.
Why Most Briefs Fail (And Why That Failure Is Expensive)
The standard client brief is some variation of: "I need a website for my business. It should look modern and professional. Something like [competitor's site] but better."
That brief is not useless. But it answers none of the questions that actually determine how long a project takes, how much it costs, and whether the result matches expectations.
Here's what happens when those questions go unanswered:
The developer scopes for the simple version. They quote based on assumptions. You're imagining the complex version. When your complex version turns out to need three times the work, you either pay more than expected or you get less than you wanted.
"I'll know it when I see it" becomes the acceptance criteria. This is the single most dangerous phrase in a client engagement. It means the project has no defined end state. Work can always be added, changed, or redone. Timelines slip, budgets expand, and both parties end up exhausted.
Decisions get made by default. Every project requires dozens of decisions: hosting, content management, user flows, mobile behavior, performance requirements. If you haven't made those decisions explicitly, the developer makes them for you based on what's easiest or fastest. Sometimes those decisions are fine. Sometimes they lock you into a direction that's expensive to change later.
A good brief forces all of those decisions to happen early, when they're cheap to make, instead of late, when they're expensive to undo.
The Brief Template
Copy this. Fill it out. Send it to any developer you're evaluating, including as a starting point for our first call.
Section 1: The Project in Plain English
1. Describe your project in one sentence, as if explaining it to a friend.
Not a technical sentence. Not a marketing sentence. A plain, honest sentence about what you're building. "I need an online store where customers can browse and buy handmade ceramics." That's a brief. "I need a scalable, enterprise-grade e-commerce solution with omnichannel capabilities" is not a brief. It's a word salad that tells a developer nothing actionable.
2. What problem does this solve for your users or customers?
This is the most important question in the entire document. If you can answer it clearly, every design and build decision that follows has a reference point. "My customers currently have to DM me on Instagram to place orders. It takes too long and I lose sales." Perfect. Now a developer knows the job to be done.
3. Who are your users? Describe them specifically.
Age range, technical comfort level, what device they're likely using, what they're trying to accomplish. "Mostly women aged 30–55, not particularly technical, primarily on mobile, browsing while commuting or during lunch" is a brief that changes decisions about typography size, mobile layout, checkout flow complexity, and page load requirements. "General public" is a brief that helps no one.
Section 2: What Already Exists
4. Do you have a current website or product? If yes, what's the URL?
If yes: what specifically is wrong with it that this project is meant to fix? Be precise. "It loads slowly on mobile" is precise. "It doesn't feel right" is a starting point for a conversation, not a brief.
5. Do you have designs, wireframes, or a Figma file?
If yes: are these final designs or starting-point sketches? Is the designer available for questions during development, or is this file the final word?
If no: do you need design as part of this project, or are you providing a direction and expecting the developer to make design decisions? (Either is fine, just needs to be explicit, because design work and development work are priced differently.)
6. What platforms, tools, or services does this need to integrate with?
Be exhaustive here. Payment processors (Stripe, PayPal, local gateways). Email marketing (Mailchimp, Klaviyo, Resend). Analytics (Google Analytics, Mixpanel, Posthog). CRM (HubSpot, Salesforce). Inventory management. Booking systems. Social login. Every integration adds scope. Missing one in the brief and discovering it mid-project is one of the most common causes of budget overruns.
Section 3: Scope and Features
7. List every feature you need at launch. Then list every feature that would be nice to have but isn't essential.
This is the exercise most clients skip, and it's the one that saves the most money.
Format it like this:
Must have at launch:
- Product catalog with photos, descriptions, pricing
- Cart and checkout with Stripe payments
- Order confirmation email to customer
- Basic inventory tracking (out-of-stock state)
- Mobile-responsive layout
Nice to have later:
- Customer accounts with order history
- Discount codes and promotions
- Product reviews
- Wishlist
- Related products recommendations
The "must have" list determines the quote and the timeline. The "nice to have" list tells a good developer what to build in a way that makes adding those things later easy and cheap, instead of requiring a rewrite.
8. Are there any features you've seen on other websites that you specifically want?
URLs are worth a thousand words here. "I want a product page like [URL]" is more useful than three paragraphs of description. Collect five to ten examples of things you like. They don't have to be from the same site, and they don't have to be from your industry. Just specific moments where you thought "I want that."
9. Are there things you've seen that you specifically do not want?
Equally useful. "No popups. No autoplay video. No infinite scroll." Knowing what to avoid is as valuable as knowing what to build.
Section 4: Technical Requirements
You don't need to be technical to answer these. Answer them in plain language and a developer will translate.
10. How much content will this site or app have at launch? How much in a year?
"About 50 products" versus "potentially 5,000 products" are two completely different architectural problems. A site with 50 products and one with 5,000 products are not the same project with more items. They require fundamentally different approaches to search, filtering, and database design.
11. Who will manage the content after launch?
If the answer is "you, the developer", that's one thing. If the answer is "my team, they're not technical", that determines whether you need a content management system, which one, and how user-friendly it needs to be. If the answer is "no one, the content won't change", that's the simplest case and should be stated explicitly.
12. How many users do you expect in the first 3 months? In the first year?
"I'm a local business expecting a few hundred visitors a month" and "I'm launching a Product Hunt campaign and expecting 10,000 visitors in the first week" are radically different infrastructure requirements. Neither is wrong, but they should be stated, because they change how the backend is architected and where it's deployed.
13. Do you have any specific performance requirements?
If you've heard terms like "Core Web Vitals," "Lighthouse score," "page load under 2 seconds": state what you've heard and what matters to you. If you don't know, say that too. A good developer will tell you what's appropriate for your situation.
14. Are there legal, compliance, or accessibility requirements?
GDPR cookie consent for European users. WCAG accessibility compliance for public sector projects. HIPAA considerations for anything involving health data. PCI compliance for payment handling. These requirements add scope and should not be discovered after development begins.
Section 5: Timeline and Budget
These two questions make most clients uncomfortable. Answer them honestly.
15. When do you need this live?
If there's a hard deadline (a product launch, a trade show, a seasonal campaign), state it. If there isn't, say there isn't. Don't invent an artificial urgency. Artificial urgency leads to rushed scoping, which leads to a quote that's either too low (and you end up paying more) or padded with contingency (and you pay more anyway).
If the deadline is genuinely hard and tight, say so. A good developer will tell you whether it's achievable and what would need to be cut from scope to hit it. That is a much better conversation to have before work starts than after.
16. What is your budget range?
State a range. Not a single number. A range.
"I have $2,000–$3,500 for this project" is information a developer can work with. It tells them what's in scope, what's out of scope, and whether this project is viable at all. It is not a negotiating weakness. A developer who would charge you $2,500 if you said your budget was $3,000 is not a developer you want to work with anyway.
If you genuinely don't know what something should cost, say that too. A good developer will give you a ballpark before asking for your number, or will tell you what's achievable at different budget levels. What doesn't work is leaving the budget entirely unstated. That leads to a quote that's either wildly over what you expected or missing things you assumed were included.
Section 6: Working Style
17. How do you prefer to communicate during a project?
Async (email, Notion updates, recorded walkthroughs) or synchronous (weekly video calls, Slack availability). Neither is wrong. But a developer who defaults to async working with a client who expects same-day Slack responses is a mismatch that should be discovered before a contract is signed.
18. How involved do you want to be during development?
Some clients want to approve every design decision. Others hand over a brief and want to see the result. Most are somewhere in between. They want to review at key milestones but don't want to be consulted on every button color. Stating your preference upfront means fewer surprises on both sides.
19. Who has final sign-off on this project?
If there are multiple stakeholders (a business partner, a manager, an investor), name them now. Projects that get to the final review stage and then require approval from someone new, someone who has different opinions and wasn't part of any earlier conversations, are one of the most reliable ways to blow a timeline and a relationship simultaneously.
Section 7: Success Criteria
20. How will you know this project was a success? What does "done" look like?
This is the question most briefs never ask, which is why so many projects never feel finished.
"Done means the store is live, payments are working, I can add products myself, and it loads in under 2 seconds on my phone." That is a clear, testable definition of success. The project ends when those four things are true.
"Done means I'm happy with it" is not a definition of done. It's an invitation to an infinite loop of revisions.
Write down what done looks like. If you can't write it down, the project isn't ready to start yet.
How to Use This Template
Option 1: Fill it out and send it. Work through each question, write your best answers, and send the document to the developers you're evaluating before the first call. You'll get better, more accurate quotes. You'll also signal immediately that you're a serious client who thinks clearly, which tends to attract better developers and better terms.
Option 2: Use it as a call agenda. If writing isn't your preferred mode, use the section headings as a guide for your first conversation. A developer who won't walk through these questions with you before quoting is a developer who is guessing at scope. You'll pay for those guesses.
Option 3: Use it to evaluate developer quality. Send it to three developers. See who asks follow-up questions versus who jumps straight to a quote. The developer who asks "for question 10, what does your product catalog look like: are these physical products with variants, or digital downloads, or services?" is thinking about your project. The developer who sends back a quote in two hours without asking anything is quoting a generic project, not yours.
What Happens When You Send This to Me
I read every brief carefully before responding. I look for the gaps, the questions where the answer is vague or missing, because those gaps are where projects get into trouble. My first response back to you will usually be a few follow-up questions on those specific points.
Then I give you a clear written scope: what I'll build, what's explicitly out of scope, the timeline, and the price. No vague "starting from" numbers. No hourly rates with uncapped ceilings. A defined piece of work for a defined price.
If the scope is right, we start. If it isn't, if your brief reveals that your project is larger or more complex than your budget allows. I'll tell you that directly and we'll talk about what's achievable. That conversation is worth having before work starts, not four weeks in.
Fill Out the Brief and Send It to Me →
You can paste your answers directly into the contact form message, or attach a document. I'll respond within 24 hours with follow-up questions or a preliminary scope.
Shihabul Islam is a Full-Stack Software Engineer specializing in Next.js, React, and production web applications. He works with founders, small businesses, and product teams to build things that actually ship. Based in Bangladesh, working with clients globally.
Recent work: CareerKor (AI SaaS platform), Nazaqa.com (headless e-commerce storefront), Aethes Armour IoT Dashboard, RUET Robotic Society Platform.
Shihabul Islam
Full Stack Software Engineer