Why Most Claude Code Sessions Underperform
The most common reason a Claude Code session produces mediocre output is not the model - it is the brief. Or more precisely, the absence of one. Most builders open the app with a rough idea in their head and type the first message that captures it. That message is the brief, and it is usually missing half the information the agent needs to do the job well.
Claude Code fills in the gaps with generic assumptions. Stack not specified? It picks one. User base not described? It builds for a generic user. Success criteria not stated? It stops when it has written something that compiles. The output is technically correct and practically wrong because it was built to a vague target.
The Five Parts of a Claude Code Project Brief
A brief does not need to be long. It needs to be precise. Here are the five sections I write for every project, from a half-day freelance build to a multi-week client delivery.
- What we are building. One sentence. Not 'a dashboard' - 'a dashboard that shows daily revenue and churn for a SaaS product, pulling from a Stripe webhook.' The specificity is the point.
- Who it is for. The actual user, not a persona. If it is for a client, describe them: 'a 45-year-old operations manager who checks this once a day and has never used developer tools.' That sentence changes every UI decision.
- The tech stack. Exact versions where they matter. 'React 18, Supabase Postgres, Vercel hosting, no external auth library - we are rolling our own with JWTs.' Anything unspecified gets guessed.
- What done looks like. Two or three acceptance criteria written as tests you can actually run. 'A user can log in and see their data. A failed login shows an error. The dashboard loads in under two seconds on a slow 3G connection.' If you cannot write this, you do not know what you are building yet.
- What is out of scope. Explicitly. 'No mobile view this sprint. No admin panel. No email notifications.' This is the section most briefs skip, and it is the one that stops scope creep before it starts.
A Real Brief From a Recent Client Build
Here is a brief I wrote before a recent client project - a simple internal tool for a small agency. I am reproducing the structure, not the identifying details, because the format is what matters.
That brief is 120 words. It took 10 minutes to write. The build that followed ran clean because Claude Code had a real target. When a session started drifting - adding features, suggesting third-party integrations - I pointed back to the 'out of scope' section and it corrected immediately.
How to Use the Brief During the Build
The brief is not a one-time document. It is the reference you return to throughout the build. In practice I use it three ways.
- As the first message in every new session. I paste the brief (or a condensed version of it) at the top of each session so the agent always has the full picture, not just the recent conversation.
- As a scope check when output drifts. When the agent starts adding features that were not in the brief, I quote the out-of-scope section and ask it to remove them. This is faster than trying to negotiate with the agent about what you actually need.
- As a done check before I hand off. When I think the build is finished, I read each acceptance criterion and verify it is true. If a criterion is not met, the build is not done.
When the Brief Reveals You Are Not Ready to Build
Sometimes writing the brief exposes gaps you did not know you had. You sit down to write the acceptance criteria and realize you do not actually know what happens when a user's trial expires. Or you start writing the tech stack and realize you have not decided whether the database is server-side or client-side. These are the gaps that become expensive bugs mid-build.
When the brief stalls, that is the brief doing its job. The right move is to answer the open questions before you open Claude Code - call the client, sketch the flow, check the constraint. A build started on resolved questions runs two to three times faster than one started on assumptions.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
How long should a Claude Code project brief be?
For most projects, 100 to 200 words is the right range. Long enough to cover all five sections with one to three sentences each. Short enough that you can read it back in 60 seconds and verify it is accurate. If your brief is getting longer, split it into multiple scoped sessions rather than expanding the brief.
Do I need a brief for small one-hour builds?
Yes, but a shorter version. Even for a one-hour build, knowing what done looks like before you start prevents the session from expanding into a three-hour session. A three-sentence brief - what it does, what done looks like, what is out of scope - is enough for a small task.
Where does the brief live - in CLAUDE.md or the first message?
Both, depending on scope. For a single session, paste it as the first message. For a multi-session project, put the stable parts (stack, user description, architectural decisions) into CLAUDE.md so every session inherits them, and use the first message for the session-specific scope and acceptance criteria.
What is the difference between a project brief and a CLAUDE.md file?
The brief is written once before the project starts and captures your thinking. CLAUDE.md is a living document that travels with the repo and is updated as the project evolves. The brief answers 'what are we building and why' - CLAUDE.md answers 'how do we build in this project and what are the rules.'
Where can I learn more about running Claude Code builds professionally?
The Claude Code Club is the community where builders share real workflows, templates, and client delivery systems. Join for $9/month at claudecodeclub.ai.
Last reviewed by Duncan Rogoff on August 4, 2026
