← Agent workflows guides

How to keep agent prompts short with SpecDD

How-To Agent workflows Beginner 1041014HOWTO-1041014

HOWTO-1041014Agent workflowsBeginner

This guide shows you how to keep agent prompts short while preserving the context an agent needs to do correct work in a spec-driven development workflow.

Short prompts are not vague when the project has good specs. With SpecDD, the prompt names the work and the repository files provide intent, authority, boundaries, tasks, and checks.

Short answer

Write durable context into .sdd specs and bootstrap files. Then prompt the specific action:

Plan the Itinerary validation change.

or:

Implement the open validation task.

Keep each prompt to one instruction. Use separate prompts for explanation, planning, implementation, and review.

Why this works

Long prompts often try to carry too many jobs:

SpecDD moves most of that durable context into files. The agent can use bootstrap files for workflow rules, root specs for broad intent, local specs for behavior and authority, and tasks for current work. The prompt can stay focused.

Steps

1. Move repeated prompt context into specs

If you keep typing a rule, write it where it belongs.

Local behavior:

Must:
  Missing place names are rejected before an itinerary item is stored.

Local boundary:

Must not:
  Change destination search behavior.

Writable scope:

Can modify:
  ./itinerary.js
  ./itinerary.test.js

Shared project conventions belong in:

.specdd/bootstrap.project.md

Do not use a long prompt as a substitute for missing project context.

2. Name the work in human terms

Good prompt:

Implement the missing-place validation task.

This identifies the task. The spec supplies the rest.

Vague prompt:

Improve trip validation.

This invites scope expansion.

3. Use one instruction per prompt

Use separate prompts for separate phases:

Explain the Itinerary spec.

Plan the Itinerary validation change.

Implement the approved Itinerary validation plan.

Review this change against the Itinerary spec.

This gives you a review point between understanding, planning, implementation, and review.

4. Avoid bundling optional work

A short prompt should not hide extra scope.

Too broad:

Implement the validation task, refactor related code, update nearby tests, close all open tasks, and clean up the module.

Better:

Implement the missing-place validation task.

If related cleanup is truly needed, create a separate task or spec update.

5. Use tasks to make short prompts precise

Tasks let short prompts refer to a durable local work packet:

Tasks:
  [ ] Add missing-place validation.

Then:

Complete the open Itinerary validation task.

The task should be specific enough that the agent does not have to infer the work from a vague prompt.

6. Use Done when to keep short prompts safe

Completion criteria prevent short prompts from becoming under-specified:

Done when:
  Missing-place behavior is covered by a check.
  Existing itinerary ordering still passes.

The prompt can be short because “done” is defined in the spec.

7. Review the result against the contract

Short prompts need strong review. Check:

Prompt examples

For orientation:

Orient in this SpecDD project.

For explanation:

Explain the Itinerary spec.

For planning:

Plan the Itinerary validation change.

For implementation:

Implement the approved Itinerary validation plan.

For review:

Review this change against the Itinerary spec.

Common mistakes

How to verify the result

Your prompts are short in the right way when:

← Agent workflows guides