2026-05-12

Tutorial: Good Prompting

The single highest-leverage thing you can do when working with AI agents is
to write a good prompt. This tutorial covers what goes into one, a simple
framework to remember the parts, and — most importantly — how a project's
agent documentation can give you most of those parts for free.

What Makes a Good Prompt?

Vague prompts produce vague results. A well-structured prompt gives the AI
clear instructions about what to do, how to do it, who it's for, and how to
verify success.

The industry-standard framework for this is CO-STAR, developed by data
scientist Sheila Teo (winner of Singapore's GPT-4 Prompt Engineering
competition). It has six components:

Letter Component What It Defines
C Context Background, situation, constraints
O Objective The specific task or goal
S Style Structural approach (technical, conversational, academic)
T Tone Emotional quality (formal, urgent, encouraging)
A Audience Who will read or use the output
R Response Exact format, structure, length of the output

A variant called CO-STAR+ adds a seventh component:

| + | E | Examples | Few-shot samples showing what you want |

Grounding

Grounding anchors LLM outputs to verifiable, external data — documents,
codebases, examples, or specific context — rather than relying solely on
training data. It prevents hallucinations, improves accuracy, and ensures
responses are relevant and actionable.

In CO-STAR+, the E (Examples) component is the primary grounding technique:
few-shot samples show the model the exact format, style, and reasoning you
want. But C (Context) and O (Objective) also ground the response by
narrowing scope to a specific situation and goal.

In the PROMPT framework, grounding lives in M (Material) — providing
trusted source material (documents, API specs, constraints) — and T (Test)
— concrete verification criteria to validate the output against reality. A
well-grounded prompt combines context, examples, and testable expectations so
the model acts as a precise, data-driven assistant rather than a creative
storyteller.

Another Framework for Use With Agent Documentation: P.R.O.M.P.T.

CO-STAR is thorough, but in my own projects, I keep agent documentation co-resident with
the repositories (I'll create an article and open a repository for bootstrapping this one day).

This framework is simply P.R.O.M.P.T.

Letter Stands For Question to Ask Yourself
P Persona Who is the AI acting as? (senior engineer, tutor, editor)
R Request What exactly do you want done? (the objective)
O Outline How should the output look? (format, structure, length)
M Material What context does the AI need? (background, constraints, references)
P Preference What's the style, tone, and audience level?
T Test How will you (or the AI) verify success? (examples, checks, tests)

P.R.O.M.P.T. covers the same ground as CO-STAR+ but uses a single word
you're already thinking about when you sit down to write one.

How A Project's Docs Can Fill In Most of P.R.O.M.P.T.

Here's the key insight: good prompting is mostly about transferring context
from your head to the AI. In projects with agent documentation, that context already lives in
structured documentation. Your prompt can be much shorter because the
scaffolding is already baked in.

My projects use the Diátaxis framework — four
documentation modes (tutorial, how-to, explanation, reference), plus
supplementary directories for agents, personas, and metadata. Each one maps
directly to a P.R.O.M.P.T. component:

PROMPT Filled by these docs What it gives the AI
Persona CLAUDE.md, docs/11-agents/, docs/13-personas/ Role, conventions, coding style, user archetypes
Material docs/01-explanation/, docs/04-reference/, docs/12-metadata/ Architecture, API specs, project metadata
Preference (Audience) docs/13-personas/ Who the output is for — developer, PM, operator, evaluator

That means your prompt shrinks from six items to three:

Remaining Why you still need to provide it
Request The AI can't read your mind — tell it what to do
Outline Every task has a different desired output format
Test This is the single highest-leverage thing you can provide
The PROMPT Framework — Lightened by Documentation Your project’s Diátaxis documentation covers the heavy context. You only write the task-specific details. Covered by docs You provide in your prompt P Persona Covered by docs R Request You write this O Outline You write this M Material Covered by docs P Preference Covered by docs T Test You write this Persona + Material + Preference are covered by your project docs → your prompt is just Request + Outline + Test

Let's see this in action.

Before and After

Before (no docs, vague prompt):

"Add a timer endpoint to the API."

After (leveraging docs, using P.R.O.M.P.T.):

Request: Add a POST /api/timers/start endpoint.

Outline: DRF viewset + serializer + test. Follow existing patterns.

Test: pytest — write a test that starts a timer and asserts the response.
Run pytest -k test_start_timer to verify.

(The AI already knows from CLAUDE.md + docs: Django, DRF serializers,
fat models/thin views, services.py pattern, auth required, pytest
fixtures. Your prompt doesn't need to repeat any of that.)

Even shorter — after you've built trust:

Once you and the AI have a shared understanding of the conventions, you can
drop the Outline too:

"Add a POST /api/timers/start endpoint. Write a test and verify it passes."

The AI pulls Persona from CLAUDE.md, Material from the codebase and docs,
and Preference from the project's existing patterns. You only supply the
Request and a Test to verify.

Putting It All Together

When writing a prompt for this project:

  1. Check what the docs already cover. Read CLAUDE.md, skim the relevant
    docs/ (or in my case, agent-docs/) section — you'll often find you can skip half the prompt.
  2. State the Request clearly. This is the one thing the AI cannot guess.
  3. Specify the Outline if the output format isn't obvious from context.
  4. Always include a Test. A command to run, an assertion to check, a
    screenshot to compare. This is the single highest-leverage practice
    across all AI coding tools.

When writing a prompt for any project:

Run through P.R.O.M.P.T.:

  1. Persona — role for the AI
  2. Request — what to do
  3. Outline — output format
  4. Material — context and constraints
  5. Preference — style, tone, audience
  6. Test — verification criteria

Skip any component the project's docs already provide. Over time, you'll
develop intuition for what each project needs.

References

Next Steps

Written by Paul B. Monday (pmonday@parallelhours.io) — published at parallelhours.io. Created with OpenCode Zen (Big Pickle model).
© 2026 Paul B. Monday