I've run Claude Code on 47 production tasks. Here's what I've learned about the prompts that work.
The Problem With Most Agent Prompts
Most agent prompts are too long, too vague, and try to handle too many edge cases. They read like a specification document, not instructions to an intelligent agent.
Here's what actually works:
The Pattern: Constraint + Scope + Exit Criteria
You are a code reviewer with access to the repository.
Scope: Only modify files in /src/utils/
Exit: Every change passes `npm test` and `npm run lint`
Constraints:
- Never delete files
- Never modify /src/main/ without asking
- If tests don't pass after 3 attempts, report what failed and why
Starting point: Review the last commit for performance issues.
Three sections. That's it. Here's why this works:
Why This Pattern Works
1. Scope prevents scope creep
"Only modify files in /src/utils/" stops Claude from deciding to rewrite the entire codebase because it found a "better architecture."
2. Exit criteria prevent infinite loops
"If tests don't pass after 3 attempts, report what failed" stops Claude from spinning forever trying to fix a broken test.
3. Constraints prevent catastrophes
"Never delete files" and "never modify /src/main/ without asking" are explicit guardrails that override whatever else Claude thinks it should do.
The Prompt I Actually Use
You are a [role] working on [project].
You have access to: [capabilities]
You cannot: [explicit prohibitions]
You succeed when: [success criteria]
You fail when: [failure conditions]
Starting task: [specific task]
If you encounter [known edge case], do [specific handling].
Copy this. Modify the bracketed sections for your use case.
What Doesn't Work
❌ "Be helpful and thorough" — too vague
❌ "Don't break anything" — Claude doesn't know what "breaking" means until it happens
❌ 500-word descriptions of the entire system — Claude forgets by the third paragraph
❌ "Use your best judgment" — Claude's best judgment and yours differ more often than you'd expect
The Real Secret
The best agent prompts aren't about controlling Claude. They're about giving it just enough context to make the same decisions you would make — and explicit guardrails for the decisions you would never make.
Building Claude agents? I've open-sourced the monitoring stack I use alongside Claude Code: DriftWatch
Top comments (0)