DEV Community

Patrick
Patrick

Posted on

The Brief Method: How to Get 10x Better Results from Claude Code

#ai #programming #productivity #claudeai

Most developers who try Claude Code and get mediocre results have the same problem: they're not writing briefs, they're writing wishes.

"Make this function better" is a wish.

A brief looks different.

What a Brief Actually Is

A Claude Code brief is a structured task description with four parts:

  1. Context — What is this code? What does it do? Where does it live in the larger system?
  2. Task — Exactly what do you need done?
  3. Constraints — What should NOT change? What standards must be met?
  4. Success criteria — How will you know it worked?

Here's the difference in practice.

Wish:

"Refactor the payment processing module to be cleaner"

Brief:

"Context: This is our payment processing module (src/payments/processor.py). It handles Stripe webhooks and writes to our orders table. Written in 2021, ~500 transactions/day.

Task: Refactor for readability. Main issues: process_webhook is 180 lines, bare except clauses everywhere.

Constraints: Do NOT change function signatures — other modules depend on them. Do NOT change database write logic. Keep the same Stripe library version.

Success criteria: All functions < 50 lines. Specific exception types instead of bare excepts. Test suite still passes."

The first prompt will give you something. The second will give you something you can actually use.

Why Context Is the Most Important Part

Claude Code reads your codebase. That's its superpower. But it reads what's relevant — and "relevant" is determined by what you tell it to focus on.

Without context, Claude Code guesses at what matters. Sometimes it guesses right. Often it makes changes that are technically correct but practically wrong — because it didn't know that orders table is a read replica and you can't write to it.

Three sentences of context prevents three rounds of revision.

The Constraints Section Is Your Safety Net

Most AI coding disasters happen because constraints weren't specified.

"Rewrite this API endpoint to be faster" → Claude Code restructures your routing, breaking five other endpoints.

Not because it was wrong about making it faster. Because you didn't tell it the routing was off-limits.

Constraints to always consider:

  • Interface constraints: Function signatures, API contracts, schemas that can't change
  • Dependency constraints: Libraries, versions, compatibility requirements
  • Scope constraints: What NOT to touch even if it looks wrong
  • Style constraints: Team-specific patterns or conventions

Success Criteria Closes the Loop

This is the part developers skip most often. And it's the part that makes Claude Code self-evaluating.

When you include "the test suite still passes" as a success criterion, Claude Code will run your tests and iterate until they do. Without success criteria, you get "here's my best attempt" and you're doing the evaluation yourself.

Good success criteria are:

  • Measurable — "all tests pass" not "code is good"
  • Verifiable — Claude Code should be able to check this itself
  • Proportionate — 2-3 criteria for a small task, 5-6 for a complex one

A Brief Template You Can Copy 

Context:
[What this code is, what it does, where it sits, traffic/criticality]

Task:
[Specific, verb-first description of what to do]

Constraints:
- [Thing it cannot change]
- [Standard/style it must follow]

Success criteria:
- [Measurable outcome 1]
- [Test or check that verifies completion]
Enter fullscreen mode Exit fullscreen mode

When Teams Share This Format

The brief format isn't just useful for individuals — it's even more powerful at the team level.

When everyone writes briefs the same way:

  • PR reviews can trace what was delegated vs. authored
  • You can spot bad briefs in code review and learn from them
  • Junior developers improve faster because the template scaffolds their thinking
  • You build a reusable library of good briefs

The teams seeing the biggest Claude Code ROI aren't the ones with the most API access. They're the ones that made brief-writing a team norm.

Start Here

Write your next Claude Code task as a brief. All four parts. It will take 5 extra minutes.

See what comes back.

I'd bet you won't write a wish again.

If you're thinking about how to roll this out to your whole engineering team, that's exactly what the Ask Patrick co-work program covers. Free team assessment: askpatrick.co/assessment.html

Top comments (0)