ailiteracynepal 🇳🇵
Text size

Chapter 04 · Section III · 12 min read

Writing effective agent prompts

A subagent has no memory of your session. Whatever it needs to know has to be in the briefing. Learning to write briefings that come back with the answer you actually needed is 80% of using agents well.

The single most common way a subagent disappoints is that the briefing gave it too little to work with. The main session had a rich picture. The subagent got a sentence. It did its best with the sentence, and the sentence was not enough. This section is about writing briefings that avoid that failure.

The rule: brief like a smart colleague

Imagine walking into a room, telling a smart colleague they will spend the next 20 minutes on a task, and leaving. What do they need from you before the door closes?

  • The goal. What is the outcome you want.
  • Why it matters. So they can make judgement calls if reality does not match the plan.
  • The relevant background. What you have already tried, what you have already ruled out, what is known-good.
  • The constraints. Frameworks, style rules, things not to touch.
  • The output shape. “A punch list of file paths.” “A one-paragraph verdict.” “A code-block diff.”

That is exactly the shape of a good subagent briefing.

Standalone context

Subagents do not see your chat history. Do not write “based on what we discussed above” — there is no above. Do not write “as I mentioned” — you have not mentioned it to the subagent. Every reference must be self-contained: file paths spelled out, symbol names spelled out, prior findings restated.

Ask for the shape of the reply

The reply format is not a nicety — it drives whether the answer is usable. Compare:

  • Loose: “Look into whether we have any race conditions in the payment code.”
  • Shaped: “Audit src/payments/*.ts for race conditions. For each candidate, return: file:line, one sentence describing the race, and a one-sentence severity assessment (blocking / worth-fixing / benign). If you find none, say so explicitly.”

The shaped version tells the subagent when it is done, prevents rambling, and produces something you can act on directly.

Say how deep to go

Subagents can spiral. If the task is “explore the repo,” they will keep exploring until you cut them off. Bound the depth:

  • “Under 500 words.” For a summary.
  • “Read the top-level of src/, do not descend into node_modules or dist.”
  • “Two options with tradeoffs; do not implement either yet.”

Bounded briefings return faster and cost less.

Tell them what to skip

A subagent will often ask “should I also check X?” internally and, for lack of guidance, do X. Head that off:

  • “Do not modify any files.”
  • “Do not run the tests — that’s my job after.”
  • “Do not follow the trail into the deprecated code in legacy/.”

Check your understanding

Quick check

—

Which subagent briefing is best?