How to Write a Project Brief Your AI Assistant Can Actually Follow

Most of the frustration people have with AI coding assistants comes from one place: the AI is guessing. You ask for "a habit tracker app", it fills in a hundred blanks you never mentioned, and you get something that's technically an app but not your app.

The fix isn't a cleverer prompt. It's a short document you write once, before any code, that answers the questions the AI would otherwise guess at. I call it a project brief, and it's the most useful thing I write for any project.

What a project brief is (and isn't)

A project brief is one page — not a 30-page spec — that describes what you're building, who it's for and what "done" looks like. Think of it as what you'd tell a new teammate on their first morning.

It's not a list of every feature you might ever want. It's not a technical design document either. If you're not a developer, that's fine: the brief is about what and why. The AI is good at filling in how, as long as it knows what it's aiming for.

The six parts of a good project brief

1. The idea, in two sentences

If you can't explain it in two sentences, the AI can't build it in one go either. "A web app where I log what I spend each day and see a weekly total by category" is clear. "A finance app" is a hundred different apps.

2. Who it's for

One person, described plainly. "Me, on my phone, at the end of the day" leads to very different design choices than "a small team sharing a budget". The AI will make better calls about layout, logins and wording when it knows who's on the other end.

3. Must-haves

List the three to five things the first version can't live without. Be ruthless. Every item here is something you'll have to build, test and fix.

4. Not now

This is the section most people skip, and it's the one that saves the most time. AI assistants love to be helpful, which means they'll happily add user accounts, dark mode and an admin dashboard you never asked for. Writing "not now: no user accounts, no payments, no mobile app" keeps the first version small enough to finish.

5. Tech and rules

If you already know your stack, say so. If you don't, it's fine to write "suggest a simple, popular stack and explain why". Then add any rules you care about: "use TypeScript", "keep components small", "never put API keys in the code", "explain any new library before installing it".

6. Done means

Describe what "working" looks like in terms you can check yourself: "I can add an expense on my phone, refresh the page, and it's still there. The weekly total matches what I'd add up by hand." This turns "is it finished?" from a feeling into a checklist, for you and for the AI.

A project brief template you can copy

Here's the template I start from. Fill it in, cut anything that doesn't apply and keep it to about a page.

# Project brief: <name>

## The idea
<Two sentences: what it is and what it does.>

## Who it's for
<One person, their situation, and the problem this solves for them.>

## Must-haves (first version)
- <Feature 1>
- <Feature 2>
- <Feature 3>

## Not now
- <Things to leave out on purpose, even if they seem obvious>

## Tech and rules
- Stack: <your stack, or "suggest a simple, popular stack and explain why">
- <Rules: conventions, things to always or never do>

## Done means
- <A check you can do yourself, like "I can sign up, log out, log back in and my data is still there">
- <Another check>

How to use your brief with an AI assistant

A brief sitting in a folder doesn't do much. Here's how I'd put it to work:

1. Draft it with the AI. Paste in your rough notes and ask: "Turn this into a project brief using these six sections. Ask me questions about anything that's unclear before you write it." The questions are the valuable part.
2. Save it in your project. Most coding tools can read standing instructions from a file in your project. Claude Code reads CLAUDE.md, Cursor reads rules from a .cursor/rules folder, GitHub Copilot reads .github/copilot-instructions.md, and a growing number of tools also read an AGENTS.md file. Put your brief there, or link to it from there, so every session starts with it.
3. Point back to it. When you ask for a feature, say "check this against the brief first". When the AI suggests something from your "not now" list, you'll both notice.
4. Update it as you go. Briefs change. When you decide something new, like "we're adding logins after all", update the brief so the AI isn't working from an old plan.

If you want more on writing the prompts that go alongside a brief, the prompting guide covers patterns like asking for a plan first and keeping changes small.

Common mistakes

• Writing a novel. If your brief is five pages, the important parts get lost. One page is plenty.
• Describing the how instead of the what. "Use a useEffect hook to fetch data" is the AI's job. "The list should show my latest entries first" is yours.
• Skipping "done means". Without it, you'll accept the first thing that looks finished, and find the problems later.
• Never updating it. An out-of-date brief is worse than none, because the AI will follow it.

Start with your next idea

Pick the idea you've been sitting on and spend 20 minutes on a brief before you open your coding tool. It feels slower. It isn't. You'll spend far less time undoing work you never asked for.

If this is your first project, the first AI-assisted web app guide walks through what comes after the brief, from scaffolding to deploying.

— Spencer