How to Brief a Freelance Developer (So They Actually Build What You Want)
You’ve found a developer. Maybe on Upwork, maybe through a referral, maybe in a Discord server. They seem good. They’re available.
Now you need to tell them what to build.
This is where most founder-developer relationships die. Not because the developer is bad. Because the brief is.
A bad brief costs you $5,000-$15,000 in wasted iterations. A good brief costs you two hours of writing.
Here’s how to write the one that actually works.
Why Most Developer Briefs Fail
I’ve reviewed hundreds of founder-to-developer briefs. They fail for predictable reasons:
The “Just Build My Vision” Brief
“I want to build the Uber of dog walking. Here’s my 47-page pitch deck.”
Why it fails: Pitch decks are for investors. Developers need specs, not stories. Your vision is irrelevant to someone writing code — they need to know what happens when a user clicks a button.
The “Feature Wishlist” Brief
“User login, dashboard, payments, messaging, notifications, admin panel, analytics, AI recommendations, social features…”
Why it fails: This is a list of nouns, not a product. It tells the developer WHAT but not HOW, WHY, or IN WHAT ORDER. They’ll quote for all of it, take 6 months, and deliver something that does everything badly.
The “Pixel-Perfect Figma” Brief
Sends 200 Figma frames with no context
Why it fails: Design is not specification. Your Figma shows what it looks like, not what it does. What happens on error? What if the user has no data? What about mobile? What about edge cases?
The “Figure It Out” Brief
“You’re the expert, just make it good.”
Why it fails: You’re asking a developer to be a product manager, designer, and engineer. They’ll make decisions you wouldn’t have made, and you’ll blame them for it.
The Developer Brief Template
Here’s the template I use for every project. It works for $500 micro-projects and $50K builds.
Section 1: Context (1 paragraph)
What is this product? Who is it for? What problem does it solve?
Good example:
“Build Score is a free assessment tool for startup founders. They answer 12 questions about their idea, and get a score (0-100) with personalized recommendations for next steps. The goal is to capture emails and qualify leads for our paid strategy service.”
Bad example:
“We’re disrupting the startup advisory space with an AI-powered platform…”
Write it like you’re explaining to a smart friend at a bar. One paragraph. No jargon.
Section 2: User Stories (5-10 max)
Not features. User stories. The difference matters.
Format: As a [user type], I want to [action] so that [outcome].
Good examples:
- As a founder, I want to answer questions about my idea so that I get a score telling me how ready I am to build
- As a founder, I want to see personalized recommendations so that I know my specific next steps
- As an admin, I want to see all completed assessments so that I can identify qualified leads
Bad examples:
- User authentication
- Dashboard
- Analytics
The rule: If you have more than 10 user stories for v1, you’re building too much. Cut to 5-7.
Section 3: Core Flows (The Critical Part)
This is where 90% of briefs fail. You need to describe what happens, step by step.
Flow format:
FLOW: Complete Assessment
1. User lands on /build-score
2. Sees intro screen with "Start Your Assessment" button
3. Clicks → Question 1 appears (single question per screen)
4. Selects answer → auto-advances to Question 2
5. Progress bar updates (1/12, 2/12, etc.)
6. After Q12 → "Enter your email to see results" screen
7. Enters email → Results page with:
- Score (0-100) with color indicator
- 3 key strengths
- 3 areas to improve
- Personalized recommendation (mapped from score range)
- CTA: "Get a Strategy Sprint" button
8. Email saved to [database/service]Why this works: The developer can literally build this screen by screen. No guessing. No ambiguity.
Do this for every core flow. If your product has 3 main things a user does, write 3 flows.
Section 4: Tech Requirements
Be specific about what you know. Be explicit about what you don’t.
TECH REQUIREMENTS:
- Framework: Next.js (or "no preference, suggest what's best")
- Hosting: Vercel (or "wherever is cheapest for <1000 users/month")
- Database: Supabase (or "suggest, we need user accounts + assessment data")
- Auth: Email/password only for v1 (no social login yet)
- Payments: Not needed for v1 (free tool)
- Email: SendGrid (or "whatever integrates easiest")
- Mobile: Responsive web only (no native app)If you don’t care about tech stack, say so. “I don’t have a preference — suggest what’s best for this type of product and explain why” is a perfectly valid requirement.
Section 5: What’s NOT In Scope
This prevents scope creep better than any contract clause.
NOT IN V1:
- No social login (email/password only)
- No mobile app (responsive web only)
- No multi-language support
- No admin dashboard (we'll use direct DB queries)
- No automated emails (we'll send manually)
- No AI features (static recommendation mapping)The power of “no”: Every “no” saves your developer from asking about it and saves you from paying for it.
Section 6: Timeline & Milestones
Break it into checkpoints, not one big deadline.
MILESTONES:
Week 1: Setup + Question flow working (no scoring logic)
Week 2: Scoring engine + results page
Week 3: Email capture + admin view + polish
Week 4: Testing + bug fixes + deployment
DEMO CHECKPOINTS:
- End of Week 1: I can click through all 12 questions
- End of Week 2: I can complete assessment and see score
- End of Week 3: Full flow works, emails captured
- End of Week 4: Live on production URLWhy milestones matter: If Week 1’s demo doesn’t happen, you know immediately — not 4 weeks later when the whole thing is late.
Section 7: Reference & Design
DESIGN:
- Figma: [link] (if you have one)
- Reference sites: [site1.com], [site2.com] — "I want the clean feel of this"
- Brand colors: #1a1a1a, #ffffff, #3b82f6
- Font: Inter (or "you pick, keep it clean")
- Vibe: "Professional but approachable. Not corporate. Not startup-bro."
NO FIGMA? That's fine. Include:
- Screenshots of products you like, with notes on what specifically you like about them
- Screenshots of products you hate, with notes on what to avoidThe 9 Mistakes That Cost You Money
1. No “out of scope” section
Without it, the developer quotes for what they think you want, which is always bigger than what you actually need.
2. Using investor language
“TAM of $4.2B” and “first-mover advantage” mean nothing to a developer. They need button labels and database schemas.
3. Describing the destination, not the journey
“Users can manage their profile” is useless. What fields? Can they upload an avatar? Can they delete their account? What happens to their data?
4. Assuming the developer reads minds
If you didn’t write it, it doesn’t exist. “Obviously the user should be able to…” — no. Nothing is obvious.
5. Providing no reference points
“Make it look modern” means something different to everyone. Show, don’t tell. Screenshots > adjectives.
6. Skipping error states
What happens when the payment fails? When the email is already registered? When the file is too large? These are the things that take 40% of development time and 0% of most briefs.
7. Bundling v1 and v5
Your v1 should be embarrassingly small. If your brief has “Phase 2” and “Phase 3” features mixed with Phase 1, the developer will price for all of it.
8. No budget range
Developers need to know if you’re thinking $500 or $50,000. Not giving a range wastes everyone’s time. “My budget is $3K-$5K for v1” is respectful and efficient.
9. No success criteria
How will you know if the project succeeded? “Assessment works end to end, scores calculate correctly, emails are captured” is a testable success criteria. “Product feels good” is not.
The Quick Brief (For Small Projects)
Don’t need the full template? Here’s the minimum viable brief:
PROJECT: [Name]
WHAT: [1-2 sentences on what it does]
WHO: [Who uses it]
CORE FLOW: [Step by step, what happens]
TECH: [Any requirements or "you suggest"]
NOT IN SCOPE: [3-5 things this is NOT]
BUDGET: [$X - $Y]
TIMELINE: [Weeks/months]
REFERENCE: [1-2 links to similar products]This is enough for any project under $5K. Takes 30 minutes to write. Saves days of back-and-forth.
What Happens After the Brief
- Developer reviews and asks questions. Good sign — it means they read it.
- They send a proposal with timeline, cost, and any suggestions.
- You negotiate scope, not price. If it’s too expensive, remove features — don’t squeeze the rate.
- Agree on milestone checkpoints before any code is written.
- First milestone demo within 5-7 days. If it takes longer to see anything, your milestones are too big.
Red Flags in a Developer’s Response
🚩 They didn’t ask any questions (they didn’t read the brief) 🚩 “We’ll figure out the details as we go” (they have no plan) 🚩 They quoted without a timeline (scope will drift) 🚩 The quote is 10x or 0.1x your budget (misalignment) 🚩 “We usually do it differently” with no explanation (not listening)
Green Flags
✅ They push back on scope (“Do you really need X for v1?”) ✅ They suggest simpler alternatives (“Instead of custom auth, use Clerk”) ✅ They ask about edge cases you didn’t think of ✅ They provide a milestone breakdown ✅ They’ve built something similar and show it
FAQ
Do I need a brief for a $500 project? Yes. Use the Quick Brief format. Even 15 minutes of writing prevents 5 hours of miscommunication.
Should I write the brief before or after finding a developer? Before. It helps you understand your own product, makes your developer search more targeted, and shows developers you’re serious (serious founders get better developers).
What if I don’t know the tech stack? Say so. “I don’t have a preference, please suggest and explain your reasoning” is a valid requirement. Good developers appreciate the trust.
My developer says the brief is too detailed. Find a different developer. Detailed briefs save everyone time. A developer who finds specificity annoying will build something vague.
What about NDAs? For most MVPs, ideas aren’t valuable enough to steal. If you’re worried, a simple NDA is fine, but don’t let NDA negotiations delay your project by weeks.
Ready to Write Your Brief?
Take the Build Score assessment — it tells you exactly where your idea stands and what to focus on before briefing a developer.
Or if you want an expert to review your brief, define your tech stack, and map your build plan — that’s exactly what the Strategy Sprint does. 90 minutes. $197. You leave with a developer-ready spec.
Stop losing money to bad briefs. Start with a plan that actually works.