Prompting guidelines
A prompt is a spec. The parts a staff engineer must get right are the finish line and the constraints. The agent can usually find the rest in the codebase.
Core principles:
- Direct: state the outcome, not how to think about it
- Specific: name the file, function, or line
- Constrained: set limits ("under 50 lines", "no new deps")
- Finished: say what "done" looks like, so the result can be checked
Wordy vs precise:
| Wordy (avoid) | Precise (better) |
|---|---|
| "I need you to fix the bug that's causing issues" | "Fix null check in UserService.getProfile()" |
| "Can you please make the API faster somehow?" | "Add Redis cache to /api/products. Target <200ms" |
| "Build out the entire checkout flow for me" | "Create cart summary component: items, qty, subtotal" |
| "I was wondering if you could add authentication" | "Add JWT auth to Express API. Use existing users table" |
| "Write some tests if you have time" | "Tests for payment module. Mock external APIs. Cover refunds" |
Short prompts that work:
"Fix the N+1 query in OrderRepository.findAll()"
"Add rate limiting to /api/upload. 10 req/min"
"Refactor UserService - extract validation to separate function"
"Follow patterns in src/services/"
"Review for SQL injection"Add context only when the codebase can't supply it:
"Add password reset. We use SendGrid for email, tokens in Redis, 1hr expiry"Use short sentences with only the facts.
Long-running tasks (Opus 5.5)
Short prompts win for small edits. For big jobs, give the whole task in one message with a clear finish line and let it run. Source: Getting the most out of Opus 5.5.
Say what "done" looks like:
"Every endpoint uses the new client, the old client is deleted, and the test suite passes.
Stop and ask me only if a test fails for a reason you can't explain."Drop "think hard": the model thinks before answering by default. Delete "think carefully" and "think step by step" from prompts and CLAUDE.md. For a quick reply, say "Answer directly."
Steer, don't restart: type follow-ups while it works. Restarting throws away progress.
Tell it which stops you want (CLAUDE.md):
Keep going when steps don't need input. Stop only when you can't continue or before
destructive actions: deleting data, force-pushing, or changing outside the repository.Split big work and track it in a file:
"Audit every service for [issue]. Give each service to its own subagent. Check evidence
before accepting. Finish with one table: service, affected yes/no, evidence"
"Keep a checklist in TASKS.md. Tick items when done, add anything new you find"Read what it needs from you first:
"End every run with three headings: Blocked on me, Changed, Found"
"Mark anything you couldn't confirm, and say where you looked"Design work: name the styles you don't want:
"Don't use cream backgrounds, italic accent words, numbered labels, monospace text, or pill-shaped buttons"Making it a team practice:
- Turn prompts that work into shared commands or skills. A good prompt that only one person uses is wasted
- Keep common templates for review, security, and migrations, so output is comparable across teams
- Review prompts in pairing sessions the way you review code. A vague prompt usually means a vague design