What I’ve learned from building prompt files

When I first started working with AI, I treated prompts as disposable strings in code. Something like:

response = llm("Summarize this text")

That works, but it’s the programming equivalent of writing a function with no parameters, no return type, and no tests. It’ll run, but you won’t want to depend on it.

What I’ve learned is that prompts deserve structure. A prompt file is basically a config file for how your AI should behave. It sets role, instructions, formatting, and sometimes examples. Once you treat prompts like code, they get predictable.

How relevant is the role?

Traditionally, you’d start every prompt with a “role”:

You are a senior Python developer.

It used to be important for guiding tone and style, but with newer models, roles matter less than they used to. If you want a certain “voice” (professor, lawyer, backend engineer), keep it. If all you need is structured JSON, you can skip it.

Think of the role as optional styling, not a hard requirement.

Be specific in task instruction

Bad:

Summarize this.

Better:

Summarize this text in exactly three bullet points. Each bullet under 15 words.

The model will always fill gaps if you leave them. Your job is not to leave gaps.

Instruction length - short vs. long

A common beginner mistake is either being too short or way too verbose.

• Too short: The AI makes assumptions you didn’t want.
• Too long: The AI drowns in instructions and ignores half of them.

The sweet spot is usually:

• clear step-by-step instructions
• each step on its own line
• no filler text like “please” or “kindly”

Example:

Instructions:

1. Extract all company names from the text.
2. Return them as a JSON array.
3. If no companies are found, return an empty array.

Readable for both humans and the model.

Don't hardcode input variables

Prompts should have placeholders.

Summarize the following into three bullet points:
{text}

Your system replaces {text} at runtime. This keeps prompts reusable.

Always define output format

Models love to “get creative” unless you box them in. Define the structure like a return type in code.

Return JSON with this schema:
{
"title": string,
"summary": string,
"keywords": [string, string, string]
}

Now you can parse the response without headaches.

Examples

Examples work like inline test cases. You’re not just telling the model what you want, but you’re showing it.

Classify text as 'spam' or 'not spam'.

Example:
"Win a free iPhone now!" -> spam
"Meeting at 3pm" -> not spam

Now classify:
{text}

The AI copies the pattern.

Structuring complex prompt logic

If your prompt starts to feel like spaghetti code, break it down.

Two approaches work best:

1. Step-by-step inside one prompt

Do the following in order:

1. Identify all product names in the text.
2. Count how many times each appears.
3. Return JSON with fields "product" and "count".

2. Chain smaller prompts

• Prompt A extracts raw data.
• Prompt B formats or filters it.
• Prompt C summarizes it.

This is the same as splitting a huge function into smaller ones. Easier to debug, easier to test.

Parameters outside the prompt

When you call the model, parameters shape the response:

• Temperature = randomness.
  • 0 = consistent, deterministic.
  • 1 = creative.
• Max tokens = output length limit.
• Top_p = sampling diversity.

You tune these just like you’d tune function arguments.

Validation

Never trust the output blindly. Validate it like untrusted user input.

try:
data = json.loads(output)
except:
output = llm(f"Fix this to valid JSON: {output}")

Versioning

Prompts drift. What works today may not tomorrow. Version them like APIs:

PROMPTS = {
"summarize_v1": "...",
"summarize_v2": "...with examples..."
}

I think prompt engineering is less about clever hacks and more about applying basic software design to natural language. The role part feels optional to me now. It's useful if you want to control tone, but not something I rely on for correctness.

I’ve found that instructions work best when they’re short and step-based, not long paragraphs. Defining the output format is non-negotiable, otherwise you spend all your time cleaning up. When the task is complex, I break it down just like I would in code: smaller steps or separate prompts chained together. And I always version and validate, because prompts drift the same way APIs do.

To me, prompts are not magic. They are just another interface. If you treat them like code, they behave like code.

Checklist:

• Role is optional, mainly useful for tone.
• Instructions should be step-based and kept concise.
• Output format must be defined.
• Complex logic should be structured like code: broken into steps or chained prompts.
• Everything should be validated and versioned.