---
title: "Write effective instructions"
description: "The anatomy of a good thread prompt: goal, constraints, and how the agent should verify its work."
canonical_url: "https://hoplite.sh/docs/prompting"
markdown_url: "https://hoplite.sh/docs/prompting.md"
---

# Write effective instructions
URL: /docs/prompting
LLM index: /llms.txt
Description: The anatomy of a good thread prompt: goal, constraints, and how the agent should verify its work.
Related: /docs/prompt-templates, /docs/delegate, /docs/agent/instructions, /docs/threads

# Write effective instructions

A good thread prompt has three parts: a **goal** the agent can act on, **constraints** that bound the change, and **verification criteria** it can check itself against. The agent works in a real sandbox — it can run your tests, start a [preview](/docs/sandboxes/previews), and check UI changes in a browser — so the biggest single upgrade to any prompt is telling it how to prove the work is done.

| Part | What it answers | Example |
| --- | --- | --- |
| Goal | What should be true when you're done? | "Email addresses are validated client-side with a clear error." |
| Constraints | What must the change respect? | "Match the existing form patterns in `src/components/forms`. Don't touch the API." |
| Verification | How will you know it works? | "Add a test for the invalid case and run the suite." |

## Weak to strong: three rewrites

### A bug report

```text title="weak"
Login is broken, fix it.
```

```text title="strong"
Fix: logging in with a correct password sometimes returns "invalid
credentials". Repro: log in twice within a few seconds — the second
attempt fails. Expected: both succeed.
Start by writing a failing test that captures this, then fix it.
Run the auth test suite and confirm everything passes.
```

The weak version makes the agent guess what "broken" means. The strong version gives a symptom, a repro, an expectation, and a proof — the failing test — so the fix is verified before you read a line of the diff.

### A feature request

```text title="weak"
Add dark mode.
```

```text title="strong"
Add a dark theme toggle to the settings page.
Follow the existing theme handling in src/styles — extend it, don't
replace it. Persist the choice the same way other settings persist.
Start a preview and verify both themes in the browser; the settings
page and the dashboard are the ones I care about.
```

The strong version scopes the surface (settings page), anchors on existing patterns, and names where to look during browser verification. For a rendered frontend change, the agent captures before-and-after screenshots — telling it which screens matter makes that evidence useful.

### A vague quality goal

```text title="weak"
Clean up the payments code.
```

```text title="strong"
Refactor src/payments/charge.ts: the retry logic is duplicated in
three places — extract it into one implementation.
Behavior must not change. Run the payments test suite before you
start and after; if coverage there is thin, add tests first.
Keep the diff to src/payments.
```

"Clean up" invites unbounded change. The strong version names one target, one transformation, an invariant (behavior unchanged), and a diff boundary — which is what makes the PR reviewable.

## Put standing context where it belongs

Don't repeat your conventions in every prompt. Project **instructions** (under **Settings → Project → Agent**) are prepended to every run — architecture notes, style rules, things the agent should always or never do. See [Instructions](/docs/agent/instructions).

For named, repeatable workflows — a release checklist, a migration procedure — use [skills](/docs/agent/skills): versioned instruction bundles in the repo that the agent loads on demand with its `load_skill` tool. That leaves the per-thread prompt doing only its real job: describing this task.

## Steer mid-run

Your first message doesn't have to be perfect, because you can correct course while the agent works:

- **Queued messages** — messages sent mid-run stack in a Queued panel and apply in order when the current run completes. Remembered a constraint? Send it now; you can remove it from the queue before it runs.
- **`/stop`** — halts the current run immediately. Your next message takes over from there.
- **`/retry`** — re-runs from the last checkpoint after a failure or a wrong turn.

Approvals are a steering point too: when a file edit or shell command pauses for your sign-off, denying it and explaining why is often faster than letting a wrong direction play out. See [Threads](/docs/threads) for the full picture.

## Sitemap

See the full [sitemap](/docs/sitemap.md) for all pages.
Well-known sitemap: [/docs/.well-known/sitemap.md](/docs/.well-known/sitemap.md).