Sketches endpoints or function signatures with naming, errors, and the future-proofing that prevents v2 pain.
claudechatgptadvanced
The prompt
Help me design a clean API before I lock it in.
What it does & who calls it: {{internal service? public? a library?}}
The main operations: {{list what callers need to do}}
Constraints: {{stack, auth, versioning needs}}
Design: 1) THE ENDPOINTS/SIGNATURES — named consistently, predictable, following the conventions of my ecosystem. 2) INPUTS & OUTPUTS — shapes, required vs optional, sensible defaults. 3) ERRORS — how failures are reported so callers can handle them. 4) THE FUTURE-PROOFING — what's likely to change, and how to design so v2 doesn't break v1 callers. 5) THE SMELL CHECK — anything here that'll be painful to live with. Prioritize caller experience over implementation convenience.
612 copies
Why this works
APIs are contracts you can't easily change once people depend on them; designing for the caller and naming where change is likely prevents the painful breaking-v2 you'd otherwise ship in six months.
Shared by Sam Kowalski — Full-stack dev. Debugs out loud so you don't have to.
You are a senior engineer doing a patient code review.
Here's my error:
{{paste the full error message}}
Here's the relevant code:
{{paste the smallest chunk that reproduces it}}
Respond in exactly this order:
1. ROOT CAUSE — one sentence, no hedging.
2. THE MINIMAL FIX — smallest possible diff, shown as before/after.
3. THE MISCONCEPTION — what I likely misunderstood for this bug to exist, explained like I'm smart but new to this corner of the language.
4. THE SMELL TEST — one thing to check elsewhere in my codebase where I've probably made the same mistake.
Do not refactor unrelated code. Do not add features.
You are the most thorough reviewer on my team — kind, but nothing gets past you.
Here's my diff:
{{paste your diff or changed files}}
Context: {{what this change is supposed to do}}
Review it:
1. CORRECTNESS — bugs, edge cases, race conditions. Rank by severity; say "solid" if it's solid.
2. NAMING & CLARITY — the 3 spots a stranger would misread first.
3. THE QUESTION — what will a reviewer inevitably ask about this diff? Draft my answer.
4. TESTS — the one test that's missing and would catch a real regression.
Skip style nitpicks a linter would catch.
I'm stuck in git. Help me fix it without losing work.
What happened / what I want: {{describe — wrong branch, bad commit, need to undo, merge conflict, detached head...}}
Output of git status (and git log if relevant):
{{paste}}
Give me: 1) WHAT STATE I'm actually in, plainly. 2) THE SAFE FIX — exact commands in order, with what each does and why. Prefer non-destructive options; clearly flag anything that discards work before I run it. 3) HOW TO VERIFY it worked. 4) THE HABIT that prevents this next time. Assume I'll paste your commands literally — don't hand-wave.