# Prompts and exploration

A vague prompt makes the agent explore, and everything it reads is re-read on every later reply. Learn cheaper ways to give context and when exploring is worth it.

> A vague prompt makes the agent search and read before it can act, and all of that output stays in the context. A specific prompt gives the agent a starting point, so less accumulates before the real work.

Source: https://ai-sw-factory.mellicci.dev/cost/prompts-and-exploration

**Diagram:** The same fix, asked two ways; the vague prompt pays for exploration that the specific prompt skips.

- Vague prompt:
  - Search the repo — many matches returned
  - →
  - Read 12 files — most not relevant
  - →
  - Run tests — full suite output
  - →
  - Finally edit
- Specific prompt:
  - Read 2 files — named in the prompt
  - →
  - Edit
  - →
  - Run the one test

An agent can only act on what it knows. If your prompt does not say where the problem is, the model decides to find out: it calls tools to search, read and run, and the harness returns their output. That output is exploration, and you pay for it even though none of it is the fix.

Prompt wording is therefore a cost lever, not just a quality lever. A prompt that names the place, the symptom and the expected behavior removes most of the searching.

## Why it matters

Exploration output does not disappear when the agent moves on. Each file read and search result becomes part of the context, and every later call re-reads it (see [Tokens, turns and context](https://ai-sw-factory.mellicci.dev/cost/tokens-turns-and-context)). Twelve files read to find one relevant line are re-read on every reply that follows.

So a vague prompt costs twice: once for the tokens that arrive, and again as a larger context on each later reply. [Context growth](https://ai-sw-factory.mellicci.dev/cost/context-growth) shows how that compounds over a session.

## How it works

The table compares where context can come from, and what each source costs.

| Source | When it loads | Cost profile |
|---|---|---|
| Instruction file | Every session, at the start | Always present, but stable, so it sits in the cached prefix ([Prompt caching](https://ai-sw-factory.mellicci.dev/cost/prompt-caching)) |
| Skill | Only its short description up front; the full text when the task matches | Small until needed; then its full text enters the context |
| Named files in your prompt | When the agent reads them | Only the files you chose |
| Exploration by the agent | Whenever the prompt leaves gaps | Unbounded: depends on what the search finds |

The cheapest context is the one that is already cached, or never loaded. See [Instruction files](https://ai-sw-factory.mellicci.dev/fundamentals/instruction-files) and [Skills](https://ai-sw-factory.mellicci.dev/fundamentals/skills) for what belongs where.

## Example

The `ticket-service` team's agent spend doubled last month. Reviewing sessions, they find many started with "fix the bug in tickets". The same bug was then asked a second way: "the 500 in `POST /tickets` when `priority` is missing; see `src/routes/tickets.ts` and `test/tickets.test.ts`".

Both runs fix the bug. The numbers are illustrative token counts.

| | "Fix the bug in tickets" | Specific prompt |
|---|---|---|
| Tool calls before the first edit | 14 | 3 |
| Tokens of tool output before the first edit | 38,000 | 4,500 |
| Context size when the fix lands | 52,000 | 18,500 |

The specific prompt skips the search and the twelve unrelated file reads. The agent also finishes with a context almost 34,000 tokens smaller, which every remaining reply in that session re-reads.

## What helps, what hurts

Helps:

- Name the files, the symptom and the expected behavior. This replaces searching with reading two files.
- Put standing facts (layout, test command, conventions) in an [instruction file](https://ai-sw-factory.mellicci.dev/fundamentals/instruction-files), where they are cached instead of rediscovered.
- Put occasional procedures in a [skill](https://ai-sw-factory.mellicci.dev/fundamentals/skills), so they load only when relevant.
- When you must explore, do it deliberately in a [subagent](https://ai-sw-factory.mellicci.dev/fundamentals/subagents): it reads widely in its own context and returns a summary, so the main context grows by the summary only.
- Start a fresh session for an unrelated task, so old exploration is not re-read ([Context growth](https://ai-sw-factory.mellicci.dev/cost/context-growth)).

Hurts:

- "Fix the bug", "make it faster", "clean this up": broad verbs with no place attached.
- Telling the agent nothing about the symptom, so it runs the full test suite to find out.
- Putting rarely needed material in an always-loaded instruction file, which adds tokens to every session.

## Trade-offs

- **Over-specifying can mislead.** If you point at the wrong file, the agent may patch there and miss the real cause. State the symptom as well as the location, and leave room for it to look elsewhere.
- **Sometimes exploration is the work.** For an unknown bug or unfamiliar code, a narrow prompt just hides the unknown. Explore on purpose, ideally in a subagent, and accept the extra calls and a summary that can leave things out.
- **Writing a precise prompt costs your time.** For a quick, small task, a short vague prompt may be the cheaper choice overall.
- **Instruction files are not free.** They keep tokens in every call; they are cheap because they are cached, not because they are small.

## Related

- [Tokens, turns and context](https://ai-sw-factory.mellicci.dev/cost/tokens-turns-and-context) - why every call re-reads everything.
- [Context growth](https://ai-sw-factory.mellicci.dev/cost/context-growth) - how exploration output accumulates.
- [Prompt caching](https://ai-sw-factory.mellicci.dev/cost/prompt-caching) - why stable instruction files are cheap to keep.
- [Subagents](https://ai-sw-factory.mellicci.dev/fundamentals/subagents) - exploring without filling the main context.
- [Skills](https://ai-sw-factory.mellicci.dev/fundamentals/skills) - context that loads only when needed.

## Key terms

- **Exploration** - searching and reading to find where the work is.
- **Tool output** - text returned by tools; it joins the context.
- **Starting point** - files, symptom and expected behavior named in the prompt.