Prompt engineering best practices

Treat prompts like code: give them structure, version them, evaluate them. Below are six practices that survived dozens of production paths on Starsg — the ones that consistently moved the needle, in the order they tend to matter.

1. Set the role and the goal

The first one or two lines should anchor the model's perspective: who it is, who it writes for, what success looks like. Term density, tone and the choice of what to include all fall out of that anchor — much cheaper than yanking the model back later with «not too verbose» or «not too academic». A solid opening answers three things: identity, audience, goal.

Role-setting template

You are a developer-relations engineer.
Audience: backend engineers comfortable with HTTP APIs but new to LLMs and token-based pricing.
Goal: in three minutes, help the reader decide whether Starsg is worth integrating, and tell them the next step.
Use a plain but professional tone. Avoid marketing fluff.

2. Write the task explicitly

«Write a product blurb» hands every decision to the model — every run is a guess. A reusable instruction has at least five elements: action (write/summarise/translate), object (what), audience (for whom), tone/style, and length or shape. Spell those out and your output stability jumps a tier immediately.

❌ Too vague

Write me a product blurb.

✅ All five elements

In ~200 words, for backend engineers, introduce three differentiators of Starsg (unified gateway, per-key billing, multi-model fallback). Tone: professional and restrained. Avoid words like «empower» or «next-gen». End with one concrete call to action.

3. Provide context and examples (Few-shot)

The more abstract the requirement, the more examples earn their keep. One to three «input → expected output» pairs are worth ten lines of explanation. Few-shot is especially decisive when format is fixed (classification, extraction, JSON), when style is hard to describe in words, or when the domain has its own conventions (legal, medical, internal systems). Make the examples cover the real distribution — not just the easy cases.

Few-shot extraction example

From the support-ticket text below, extract three fields: «type / scope / severity». Output JSON only.

Example 1:
Input: Users report login failures across the Guangzhou region; phone support is overloaded.
Output: {"type":"login","scope":"Guangzhou region","severity":"P1"}

Example 2:
Input: A test account shows the wrong balance; only internal QA is affected.
Output: {"type":"account","scope":"internal QA","severity":"P3"}

Now process:
Input: The Beijing API gateway returns 502; all paid users are affected.

4. Constrain the output format

Anything a downstream system consumes must be parseable. JSON? Provide a schema and field notes. List? Pin the count and the per-item shape. Length cap? Say so. Add a clause like «if the field is missing, set it to null — do not invent» and you will measurably cut hallucinations.

JSON output constraint

Convert the resume below into JSON, strictly matching this schema:
{
  "name": string,
  "yearsOfExperience": number,
  "skills": string[],     // at most 5, lowercase
  "summary": string        // <= 60 words
}
If the source does not mention a field, set it to null — do not invent. Output JSON only, with no surrounding text.

5. Decompose complex tasks (with chain-of-thought)

Asking a model to «analyse + plan + produce» in one shot usually loses detail or treats reasoning as the final answer. Two options: let it think step-by-step internally, or break the work into multiple turns yourself. For auditable workflows we prefer the latter — keep every intermediate so you can later pinpoint which step failed.

Step-by-step template

I will give you a product spec. Process it in three steps and separate each with a ## heading:

## 1. Key information
Bullet list: target user, core scenario, must-have features, things explicitly out of scope.

## 2. Risks and unclear points
List anything ambiguous or contradictory in the spec, one sentence each.

## 3. Next steps
Give the PM three concrete, executable next actions, ordered by priority.

Spec:
<<<

>>>

6. Iterate and evaluate

Good prompts are not written, they are iterated. Build a fixed eval set (20–50 cases covering normal + edge + adversarial). Run it on every prompt change and record hit rate, average length and token cost. Version your prompts like code — every change has a reason and a regression baseline, no «feels better this time».