How to talk to the agent

Prompting is a craft. A few simple rules, applied consistently, account for most of the difference between productive sessions and frustrating ones.

Frame the work, then get out of the way

Your first message sets the frame. Once Claude has the frame, you should be doing less typing, not more.

The two-message anti-pattern:

> "look at the email service"
> "actually I meant the marketing-app email service, not the chowly one"

Better:

> "in the marketing-app repo, look at the email service. Find the contact-create flow. I want to add SES validation there."

One message, complete frame.

Specific redirects beat vague ones

When you need to correct course, name the thing you want different.

Vague: "no, do it differently"

Specific:

• "use openrouter, not gemini directly — we have an existing openrouter client"
• "stub at the service level, not via webmock"
• "use the atlassian mcp, not the cli"

The specific version saves a round-trip and produces the right output the first time.

Constraints up front, not later

Constraints buried in turn 4 cost you turns 1–3. Surface them up front:

> /chowly:implement_jira TEAM-12084
> Important constraints: must use the existing openrouter client at
  app/services/openrouter/client.rb. Stub external calls at the
  service level, not webmock. Don't add a new gem.

Three sentences that save 20 minutes.

Approve specifically when the plan is good

"Approved" works. "Approved, but specs in spec/services/, not spec/lib/" is better. The plan moment is your highest-leverage turn — use it.

Trust short messages once flow is set

After the plan is approved and execution is happening, your messages should be short. "yes," "fix it," "Create a PR." Long messages mid-execution are usually a sign that the plan was underspecified.

If you're typing a paragraph in turn 6, ask whether turn 1 should have included that paragraph.

Brief sub-agents like a smart colleague who just walked into the room

A sub-agent has none of your conversation context. The prompt to it must contain:

• What you want done.
• The relevant context — file paths, ticket key, what's been ruled out.
• The shape of the answer you want back.

Bad: "find the bug"

Good: "find why TEAM-11843's promo codes are missing on DAM campaigns. Files to start in: app/services/campaigns/. The bug is reproduced by [steps]. We've ruled out the AI-image path. Return: file path of the bug, what the fix should be, and any related places that need similar fixes."

When stuck, narrow

If a session is going wrong, the answer is rarely "more context." It's almost always "narrower scope."

> stop. Forget everything else. Just answer: in
  app/services/campaigns/image_selector.rb, where does promo_code
  get assigned? Return file:line. No other commentary.

Smaller question, fast answer, momentum restored.