Chapterبەش 3 · Lectureوانە 3.1

Prompt Engineering: Asking a Model Wellئەندازیاریی هەوێن: چۆن بە باشی داوا لە مۆدێل بکەیت

How to write prompts that get useful answers: what a prompt is (CêIT's word هەوێن), the parts of a good prompt, clear instructions, system prompts and roles, few-shot examples, step-by-step thinking, JSON replies checked in Python, prompt templates, prompt chaining, testing prompts with a small set of test cases, and writing prompts in Kurdish.

چۆن بنووسیت کە وەڵامی بەسوود بهێنێت: چییە، بەشەکانی باش، ڕێنمایی ڕوون، و ڕۆڵەکان، ، بیرکردنەوەی هەنگاو بە هەنگاو، وەڵامی و پشکنینی لە ، ، ، تاقیکردنەوەی بە کۆمەڵێک و نووسینی بە کوردی.

21 min read21 خولەک خوێندنەوە · 18 stepsهەنگاو

What you will learnچی فێر دەبیت

Explain what a prompt is and why detail matters, using the “What is HTML?” example.
Write a prompt with a role, a task, context, a marked input, limits and an output format, saying what to do and why.
Use a system prompt, few-shot examples and step-by-step thinking.
Ask for JSON, check the reply in Python and build prompts from a template.
Test prompt versions on a small set of test cases, and write good prompts in Kurdish.

ڕوون بکەیتەوە چییە و بۆچی وردەکاری گرنگە، بە نموونەی « چییە؟».
بنووسیت بە ڕۆڵ، ئەرک، پاشخان، دیاریکراو، سنوور و شێوەی بنووسیت و بڵێیت چی بکات و بۆچی.
، نموونەکانی و بیرکردنەوەی هەنگاو بە هەنگاو بەکار بهێنیت.
داوای بکەیت، وەڵامەکە لە بپشکنیت و لە دروست بکەیت.
وەشانەکانی لەسەر کۆمەڵێکی بچووک تاقی بکەیتەوە و باش بە کوردی بنووسیت.

“What is HTML?”: why detail matters«HTML چییە؟»: بۆچی وردەکاری گرنگە

A model learned the world only from what people wrote (what a model knows). It cannot see you either, so it cannot guess who you are or what you need. The more useful detail you give, the closer the answer comes to what you want.

تەنیا لەو دەقانەوە جیهانی ناسیوە کە خەڵک نووسیویانە (مۆدێل چی دەزانێت). تۆش نابینێت، بۆیە ناتوانێت مەزەندە بکات تۆ کێیت و چیت پێویستە. هەتا وردەکاریی بەسوودتر بدەیت، وەڵامەکە زیاتر لەوە نزیک دەبێتەوە کە دەتەوێت.

Compare two prompts. “What is HTML?” gets a general answer. The detailed prompt says who it is for, what you need and in what form.

دوو بەراورد بکە. « چییە؟» وەڵامێکی گشتی وەردەگرێت. ورد دەڵێت بۆ کێیە، چیت پێویستە و بە چ شێوەیەک.

A detailed prompt says who it is for, what you need and in what form. ورد دەڵێت بۆ کێیە، چیت پێویستە و بە چ شێوەیەک.CêIT

At the tailor'sلای بەرگدروو

Ask a tailor in the bazaar only for “a shirt”, and he must guess the size, cloth and colour. Give him your measurements, the cloth, the colour and the day you need it, and you get the shirt you wanted.

ئەگەر بە بەرگدروویەکی بازاڕ تەنیا بڵێیت «کراسێکم بۆ بدروو»، دەبێت قەبارە، قوماش و ڕەنگ مەزەندە بکات. پێوانەکانت، قوماشەکە، ڕەنگەکە و ئەو ڕۆژەی پێویستتە پێی بدە، ئەو کراسەت دەست دەکەوێت کە دەتویست.

Where the analogy stops workingسنووری ئەم نموونەیە

A tailor asks when something is missing; a model usually just guesses, unless you tell it to ask.

بەرگدروو کاتێک شتێک کەم بێت دەپرسێت؛ زۆرجار تەنیا مەزەندە دەکات، مەگەر پێی بڵێیت بپرسێت.

What a prompt isهەوێن چییە

A prompt is everything the model reads before it answers: the app's hidden rules (the system prompt), the earlier messages of the chat, any files or pictures, and your new message. The app sends all of it again on every turn, because the model keeps nothing between requests (no memory between requests).

هەموو ئەو شتانەیە کە پێش وەڵامدانەوە دەیخوێنێتەوە: یاسا شاراوەکانی ()، پەیامەکانی پێشووی گفتوگۆکە، هەر فایل یان وێنەیەک و پەیامە نوێیەکەت. لە هەموو نۆرەیەکدا هەمووی دووپاتە دەنێرێتەوە، چونکە لە نێوان هیچ ناهێڵێتەوە (بێ بیرەوەری لە نێوان داواکارییەکاندا).

CêIT calls a prompt هەوێن. In everyday Kurdish, هەوێن is a starter: one spoonful turns a pot of milk into yogurt. A short prompt shapes a long answer in the same way.

CêIT بە prompt دەڵێت . لە زمانی ڕۆژانەدا هەوێن کەوچکێکە کە مەنجەڵێک شیر دەکات بە ماست. کورتیش بەو جۆرە وەڵامێکی درێژ دادەڕێژێت.

Prompt engineering is writing, testing and improving prompts until the answers are reliably good. It is closer to an experiment than to magic: change one thing, look at the results, keep what works.

واتە نووسین، تاقیکردنەوە و باشترکردنی تا وەڵامەکان بە بەردەوامی باش دەبن. لە تاقیکردنەوەی زانستییەوە نزیکترە تا لە جادوو: یەک شت بگۆڕە، سەیری ئەنجامەکان بکە و ئەوەی کار دەکات بیهێڵەوە.

The prompt is everything the model reads, not only your last message. هەموو ئەو شتانەیە کە دەیخوێنێتەوە، نەک تەنیا دوایین پەیامەکەت.CêIT

The parts of a good promptبەشەکانی هەوێنێکی باش

Most good prompts have six parts. A short question may need only two or three, but when an answer disappoints you, check this list:

زۆربەی باشەکان شەش بەشیان هەیە. پرسیارێکی کورت لەوانەیە تەنیا دوو یان سێیانی پێویست بێت، بەڵام کاتێک وەڵامێک دڵت ناخۆش دەکات، ئەم لیستە بپشکنە:

Role and reader: who the model should be, and who will read the answer.
Task: one clear verb, such as write, sort, explain, translate or check.
Context: why you need it and where it will be used.
Input: the text to work on, inside clear tags such as <book> … </book>, so it is not mixed up with your instructions.
Limits: language, length, level, and what it may use (“only the facts inside <book>”).
Output format: plain text, a list, a table or JSON.

ڕۆڵ و خوێنەر: چ کەسێک بێت و کێ وەڵامەکە دەخوێنێتەوە.
ئەرک: یەک کاری ڕوون، وەک بنووسە، پۆلێن بکە، ڕوون بکەرەوە، وەربگێڕە یان بپشکنە.
پاشخان: بۆچی پێویستتە و لە کوێ بەکار دێت.
: ئەو دەقەی کاری لەسەر دەکرێت، لە ناو نیشانەی ڕووندا وەک <book> … </book>، بۆ ئەوەی لەگەڵ ڕێنماییەکانتدا تێکەڵ نەبێت.
سنوور: زمان، درێژی، ئاست و ئەوەی بۆی هەیە بەکاری بهێنێت («تەنیا ڕاستییەکانی ناو <book>»).
شێوەی : دەقی سادە، لیست، خشتە یان .

Six parts of a good prompt, in one shelf-card prompt.شەش بەشی باش، لە کارتی ڕەفەدا.CêIT

Be clear and directڕوون و ڕاستەوخۆ بە

Anthropic's prompting guide suggests a simple test: show your prompt to a colleague who knows nothing about the task. If they would be confused, the model will be too. Three habits help:

ڕێبەری نووسینی Anthropic تاقیکردنەوەیەکی سادە پێشنیار دەکات: پیشانی هاوکارێک بدە کە هیچ لەبارەی کارەکە نازانێت. ئەگەر ئەو تێنەگات، تێناگات. سێ ڕاهاتن یارمەتی دەدەن:

Be specific. Give the facts, numbers and limits that are in your head.
Say what to do, not only what not to do. “Use words a 14-year-old knows” works better than “Don't use difficult words”.
Say why. A reason (“it is printed on a small card”) lets the model make good choices you did not list.

ورد بە. ئەو ڕاستی، ژمارە و سنوورانە بدە کە لە مێشکتدان.
بڵێ چی بکات، نەک تەنیا چی نەکات. «وشەی وا بەکار بهێنە کە منداڵێکی ⁦14⁩ ساڵ بیزانێت» لە «وشەی قورس بەکار مەهێنە» باشتر کار دەکات.
بڵێ بۆچی. هۆکارێک («لەسەر کارتێکی بچووک چاپ دەکرێت») ڕێگە بە دەدات بڕیاری باش بدات لەو شتانەی کە نەتنووسیون.

When the order matters, write the steps as a numbered list. The same habits get you better riffs, new versions of an idea: see Riff: Building on an Idea.

کاتێک ڕیزبەندی گرنگە، هەنگاوەکان وەک بنووسە. هەمان ڕاهاتنەکان یارمەتیت دەدەن riffsـی باشتر وەربگریت، واتە شێوەی نوێی بیرۆکەیەک: بڕوانە Riff: بنیاتنان لەسەر بیرۆکەیەک.

Three habits that turn an unclear prompt into a clear one.سێ ڕاهاتن کە ناڕوون دەکەن بە ڕوون.CêIT

System prompts and rolesهەوێنی سیستەم و ڕۆڵەکان

A chat has three kinds of messages. The system prompt holds the app's rules for the whole conversation and is written by the developer; OpenAI calls it the developer message or instructions. User messages are what people type. Assistant messages are the model's replies. Models are trained to give the developer's rules priority over a user's request.

گفتوگۆیەک سێ جۆر پەیامی هەیە. یاساکانی بۆ هەموو گفتوگۆکە هەڵدەگرێت و دەینووسێت؛ OpenAI پێی دەڵێت پەیامی developer یان instructions. پەیامەکانی user ئەوەن کە خەڵک دەینووسن. پەیامەکانی assistant وەڵامەکانی . ڕاهێنراون کە یاساکانی لە داوای پێش بخەن.

A role in the system prompt (“You are the helper of a bookshop in Sulaymaniyah”) sets the tone, the focus and the words: this is role prompting. A role adds no knowledge: telling a model it is a doctor does not make its medical facts more correct.

ڕۆڵێک لە («تۆ یارمەتیدەری کتێبفرۆشییەکیت لە سلێمانی») شێوازی دەربڕین، سەرنج و وشەکان دیاری دەکات: ئەمە ـە. ڕۆڵ هیچ زانیارییەک زیاد ناکات: ئەگەر بە بڵێیت دکتۆرە، ڕاستییە پزیشکییەکانی ڕاستتر نابن.

The system prompt is like the rules on the shop wall. وەک یاساکانی سەر دیواری دوکانە.CêIT

System prompts and rolesهەوێنی سیستەم و ڕۆڵەکان

A system prompt in codeهەوێنی سیستەم لە کۆددا

In an app, the system prompt is a separate field of the request. This is how it looks with Anthropic's Python SDK. The answer's text comes back in message.content, as in the first request.

لە ، خانەیەکی جیاوازە لە . ئەمە شێوەکەیەتی لەگەڵ Pythonـی Anthropic. دەقی وەڵامەکە لە message.contentـدا دەگەڕێتەوە، وەک لە یەکەم داواکاری.

Example only (not run): a system prompt with the Claude APIتەنیا نموونە (کار پێ نەکراوە): هەوێنی سیستەم لەگەڵ Claude APIPYTHONType in a terminalلە تێرمیناڵدا بینووسە

import anthropic

client = anthropic.Anthropic()          # reads the key from ANTHROPIC_API_KEY

message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=300,
    system=("You are the helper of Shilan's bookshop in Sulaymaniyah. "
            "Answer in Central Kurdish (Sorani). Use only the book list you are given. "
            "If a book is not in the list, say that you do not know."),
    messages=[
        {"role": "user", "content": "Do you have Mem u Zin?"},
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

Explain the codeڕوونکردنەوەی کۆدەکە

Lineدێڕی 8-10

The system field: the shop's rules, kept apart from the customer's message.

خانەی system: یاساکانی دوکان، جیا لە پەیامی کڕیارەکە.

Lineدێڕی 11-13

The messages list: the conversation, here one user message.

لیستی messages: گفتوگۆکە، لێرەدا یەک پەیامی user.

Lineدێڕی 10

Allowing “I do not know” stops the model from inventing books (next screens).

ڕێگەدان بە «نازانم» ڕێگە لە دەگرێت کتێب دروست بکات (شاشەکانی داهاتوو).

Noteتێبینی

Example only. It needs the anthropic package and an API key, which stays on the server and never in the app (API keys). Checked against Anthropic's “Get started” and “Prompting best practices” pages on 10 November 2026 (model name as of November 2026); not run here, so no output is shown. OpenAI's Responses API has the same idea in its instructions parameter.

تەنیا نموونەیە. anthropic و پێویستە، کە لەسەر دەمێنێتەوە و هەرگیز لە نییە (کلیلەکانی API). لە ⁦10⁩ی تشرینی دووەمی ⁦2026⁩ لەگەڵ لاپەڕەکانی «Get started» و «Prompting best practices»ـی Anthropic بەراورد کراوە (ناوی وەک تشرینی دووەمی ⁦2026⁩)؛ لێرەدا کاری پێ نەکراوە، بۆیە هیچ پیشان نادرێت. Responses APIـی OpenAI هەمان بیرۆکەی لە instructionsـدا هەیە.

Show examples: few-shot promptingنموونە پیشان بدە: هەوێنی چەندنموونەیی

A prompt with instructions only is zero-shot. Add a few solved examples and it becomes few-shot: the model copies the pattern, including the labels, the length and the tone. Shilan's helper sorts customer messages into order, question or complaint; with three examples, every answer is one clean word.

کە تەنیا ڕێنمایی تێدا بێت ـە. چەند نموونەیەکی چارەسەرکراوی بۆ زیاد بکە، دەبێتە : شێوازەکە لاسایی دەکاتەوە، لەوانە ناوەکان، درێژی و شێوازی دەربڕین. یارمەتیدەرەکەی شیلان پەیامی کڕیاران دەکات بە order (داواکردن)، question (پرسیار) یان complaint (سکاڵا)؛ بە سێ نموونە هەموو وەڵامێک یەک وشەی پاکە.

Good examples are relevant (like the real messages), diverse (different cases, so the model does not copy an accident such as “every example is short”) and marked, for example inside <examples> tags. Anthropic suggests 3 to 5. The model's weights do not change: the examples work only inside this prompt, as the GPT-3 paper showed (Brown and colleagues, 2020).

نموونەی باش گونجاون (وەک پەیامە ڕاستەقینەکان)، جۆراوجۆرن (حاڵەتی جیاواز، بۆ ئەوەی ڕێکەوتێک لاسایی نەکاتەوە، وەک «هەموو نموونەکان کورتن») و دیاریکراون، بۆ نموونە لە ناو نیشانەکانی <examples>ـدا. ⁦Anthropic 3⁩ تا 5 نموونە پێشنیار دەکات. ناگۆڕێن: نموونەکان تەنیا لە ناو ئەم کار دەکەن، وەک توێژینەوەی ⁦GPT-3⁩ پیشانی دا (Brown و هاوکارانی، ⁦2020⁩).

Examples show the model the exact format you want.نموونەکان ڕێک ئەو شێوەیە بە پیشان دەدەن کە دەتەوێت.CêIT

Ask for the steps: chain of thoughtداوای هەنگاوەکان بکە: زنجیرەی بیرکردنەوە

For maths, logic or planning, ask the model to work step by step before it answers. The written steps are called a chain of thought. Each step becomes text that the next tokens are predicted from, so the model can build on it, like a student who shows the working. Wei and colleagues (2022) found that a few worked examples with steps made large models much better at maths word problems.

بۆ بیرکاری، لۆجیک یان پلاندانان، داوا لە بکە هەنگاو بە هەنگاو کار بکات پێش ئەوەی وەڵام بداتەوە. هەنگاوە نووسراوەکان پێیان دەگوترێت . هەر هەنگاوێک دەبێتە دەقێک کە داهاتووەکان لەسەری پێشبینی دەکرێن، بۆیە دەتوانێت لەسەری بنیات بنێت، وەک خوێندکارێک کە کارەکەی پیشان دەدات. Wei و هاوکارانی ⁦(2022)⁩ دۆزییانەوە کە چەند نموونەیەکی چارەسەرکراو بە هەنگاوەوە لە پرسیاری بیرکاریی وشەییدا زۆر باشتر دەکات.

Today's reasoning models do this by themselves before answering (reasoning models); for them, a clear goal matters more than the words “think step by step”. Either way, thinking costs tokens (how pricing works), and a step can still be wrong, so check it.

ئەمڕۆ خۆیان ئەمە دەکەن پێش وەڵامدانەوە (مۆدێلە بیرکەرەوەکان)؛ بۆ ئەوان ئامانجێکی ڕوون لە وشەکانی «هەنگاو بە هەنگاو بیر بکەرەوە» گرنگترە. بە هەر حاڵ، بیرکردنەوە دەخوات (نرخدانان چۆن کار دەکات) و هەنگاوێکیش دەتوانێت هەڵە بێت، بۆیە بیپشکنە.

Written steps give the model text to build on, and give you something to check.هەنگاوە نووسراوەکان دەقێک دەدەنە کە لەسەری بنیات بنێت و شتێکیش دەدەنە تۆ کە بیپشکنیت.CêIT

Ask for a fixed format: JSONداوای شێوەیەکی جێگیر بکە: JSON

When a program, not a person, reads the answer, ask for JSON with exact keys and allowed values, and show one example (JSON). Then the app can read the fields category, book and copies and act on them.

کاتێک ، نەک مرۆڤێک، وەڵامەکە دەخوێنێتەوە، داوای بکە بە ڕێک و ڕێگەپێدراو و نموونەیەکیش پیشان بدە (JSON). ئینجا دەتوانێت خانەکانی category، book و copies بخوێنێتەوە و کاریان لەسەر بکات.

Asking is not a guarantee: a model may add “Here is the JSON:” or forget a key. Many APIs now offer structured output: you send a JSON schema and the API forces the reply to match it (Anthropic and OpenAI both call it structured outputs). Even then, check the values: valid JSON can still name a book the shop does not have.

داواکردن دڵنیایی نادات: لەوانەیە «Here is the JSON:» زیاد بکات یان لەبیر بکات. ئێستا زۆر پێشکەش دەکەن: دەنێریت و ناچاری وەڵامەکە دەکات لەگەڵیدا بگونجێت (Anthropic و OpenAI هەردووکیان پێی دەڵێن structured outputs). تەنانەت ئەوکاتیش بپشکنە: دروستیش دەتوانێت ناوی کتێبێک بهێنێت کە دوکانەکە نییەتی.

Ask for JSON with exact keys; a schema enforced by the API is even safer.داوای بکە بە ڕێک؛ کە بیسەپێنێت سەلامەتترە.CêIT

Ask for a fixed format: JSONداوای شێوەیەکی جێگیر بکە: JSON

Check the reply in Pythonوەڵامەکە لە Pythonـدا بپشکنە

json.loads() turns JSON text into a Python dictionary (JSON in Python). A clean reply is easy:

json.loads() دەقی دەکات بە Python (JSON لە Pythonـدا). وەڵامێکی پاک ئاسانە:

Reading a JSON replyخوێندنەوەی وەڵامێکی JSONcheck_reply.pyPYTHONType in a terminalلە تێرمیناڵدا بینووسە

import json

# A reply the model sent back (copied from the app's log)
reply = '{"category": "order", "book": "Mem u Zin", "copies": 2}'

data = json.loads(reply)          # text -> Python dictionary
print(data["category"], "|", data["book"], "|", data["copies"] + 1)

But a chatty reply that starts with “Here is the JSON:” is not JSON, and json.loads() raises an exception:

بەڵام وەڵامێکی قسەکەر کە بە «Here is the JSON:» دەست پێ دەکات نییە و json.loads() دروست دەکات:

Common mistake: a reply with extra wordsهەڵەی باو: وەڵامێک بە وشەی زیادەوەchatty_reply.pyPYTHONType in a terminalلە تێرمیناڵدا بینووسە

import json

reply = 'Here is the JSON: {"category": "order", "book": "Mem u Zin", "copies": 2}'
data = json.loads(reply)
print(data["category"])

The fix: ask for JSON only (or use structured output), and read replies with a careful function that returns None when there is no valid JSON, so the program can ask again instead of crashing.

چارەسەر: تەنیا داوای بکە (یان بەکار بهێنە) و وەڵامەکان بە وریا بخوێنەرەوە کە کاتێک دروست نییە None دەگەڕێنێتەوە، بۆ ئەوەی لە جیاتی تێکچوون دووپاتە بپرسێت.

The fix: find the JSON, catch the errorچارەسەر: JSONـەکە بدۆزەوە، هەڵەکە بگرەsafe_reply.pyPYTHONType in a terminalلە تێرمیناڵدا بینووسە

import json

def read_json_reply(reply):
    """Return the dictionary inside a reply, or None if there is none."""
    start = reply.find("{")
    end = reply.rfind("}")
    if start == -1 or end == -1:
        return None
    try:
        return json.loads(reply[start:end + 1])
    except json.JSONDecodeError:
        return None

replies = [
    '{"category": "order", "book": "Mem u Zin", "copies": 2}',
    'Here is the JSON: {"category": "question", "book": "The Little Prince"}',
    "Sorry, I am not sure what you mean.",
]
for reply in replies:
    data = read_json_reply(reply)
    if data is None:
        print("no JSON -> ask the model again")
    else:
        print("OK:", data["category"], "-", data["book"])

Explain the codeڕوونکردنەوەی کۆدەکە

Lineدێڕی 5-6

find() gives the first {, rfind() the last }; both give -1 when the character is missing.

find() یەکەم { دەدات و rfind() دوایین }؛ هەردووکیان کاتێک پیتەکە نییە ⁦-1⁩ دەدەن.

Lineدێڕی 9-12

try / except json.JSONDecodeError: broken JSON returns None instead of crashing (exceptions).

try / except json.JSONDecodeError: شکاو لە جیاتی تێکچوون None دەگەڕێنێتەوە (هەڵاوێردەکان).

Check every reply before the program uses it.هەموو وەڵامێک بپشکنە پێش ئەوەی بەکاری بهێنێت.CêIT

Prompt templates in Pythonقاڵبەکانی هەوێن لە Pythonـدا

Shilan needs a shelf card for 300 books. Typing 300 prompts by hand is slow, and each would come out a little different. A prompt template keeps the rules once and leaves slots for the data. In Python, a function that returns an f-string is a simple template (f-strings):

شیلان بۆ ⁦300⁩ کتێب کارتی ڕەفەی پێویستە. نووسینی ⁦300⁩ بە دەست هێواشە و هەر یەکەیان کەمێک جیاواز دەردەچێت. یاساکان یەکجار هەڵدەگرێت و شوێن بۆ بەجێ دەهێڵێت. لە ، سادەترین کە بگەڕێنێتەوە (f-string):

One template, three booksیەک قاڵبی هەوێن، سێ کتێبprompt_template.pyPYTHONType in a terminalلە تێرمیناڵدا بینووسە

# One prompt template, many books
def make_prompt(title, author, about):
    return f"""You write shelf cards for Shilan's bookshop in Sulaymaniyah.
Readers are teenagers. Write in Central Kurdish (Sorani, Arabic script).

<book>
Title: {title}
Author: {author}
About: {about}
</book>

Write two sentences, at most 35 words. Use only the facts inside <book>."""

books = [
    ("Mem u Zin", "Ahmad Khani", "a classic Kurdish love story told in verse"),
    ("The Little Prince", "Antoine de Saint-Exupery", "a pilot meets a boy from a tiny planet"),
    ("A Brief History of Time", "Stephen Hawking", "black holes, the Big Bang and time"),
]

for number, (title, author, about) in enumerate(books, start=1):
    prompt = make_prompt(title, author, about)
    if number == 1:
        print(prompt)
        print("-" * 40)
    print(f"prompt {number}: {title}, {len(prompt)} characters")

Explain the codeڕوونکردنەوەی کۆدەکە

Lineدێڕی 2-12

The rules are written once; {title}, {author} and {about} are the slots.

یاساکان یەکجار نووسراون؛ {title}، {author} و {about} شوێنەکانن.

Lineدێڕی 20-25

The same function makes every prompt; we print the first one in full and the length of each.

هەمان هەموو دروست دەکات؛ یەکەمیان بە تەواوی و درێژیی هەر یەکەیان چاپ دەکەین.

A template also makes testing fair: when you improve the rules, every book gets the improvement, and you compare like with like.

تاقیکردنەوەش دادپەروەر دەکات: کاتێک یاساکان باشتر دەکەیت، هەموو کتێبێک باشترکردنەکە وەردەگرێت و شتی هاوشێوە بەراورد دەکەیت.

One template, many prompts.یەک ، چەندین .CêIT

Common mistake: JSON braces inside an f-stringهەڵەی باو: کەوانەی JSON لە ناو f-stringـدا

In an f-string, { and } mean “put a value here”. A JSON example inside the template confuses Python:

لە ، { و } واتە «بەهایەک لێرە دابنێ». نموونەیەکی لە ناو Python تێک دەدات:

Wrong: single braces around the JSONهەڵە: کەوانەی تاک بە دەوری JSONـەکەbrace_mistake.pyPYTHONType in a terminalلە تێرمیناڵدا بینووسە

book = "Mem u Zin"
prompt = f'Reply about {book} only with JSON like {"category": "question"}'
print(prompt)

The fix: double the braces that are text. Each doubled pair prints one brace.

چارەسەر: ئەو کەوانانەی کە دەقن دووانە بکە. هەر جووتێکی دووانە یەک کەوانە چاپ دەکات.

Right: doubled braces for the JSON textڕاست: کەوانەی دووانە بۆ دەقی JSONـەکەbrace_fix.pyPYTHONType in a terminalلە تێرمیناڵدا بینووسە

book = "Mem u Zin"
prompt = f'Reply about {book} only with JSON like {{"category": "question"}}'
print(prompt)

Break big jobs into a chainکاری گەورە بکە بە زنجیرە

One huge prompt for a big job is hard to check. Prompt chaining splits the job into small prompts, and the output of one becomes the input of the next: outline → draft → check → translate. You, or your program, can look at every step, and a failed check sends the work back.

زۆر گەورە بۆ کارێکی گەورە پشکنینی قورسە. کارەکە دەکات بە چەند بچووک و هەر یەکێکیان دەبێتە دواتر: پلان ← ڕەشنووس ← پشکنین ← وەرگێڕان. تۆ، یان ، دەتوانیت سەیری هەموو هەنگاوێک بکەیت و پشکنینێکی شکستخواردوو کارەکە دەگەڕێنێتەوە.

Anthropic's guide calls the most common chain self-correction: write a draft, review it against your rules, then improve it. A chain makes more calls, so use it when each step's quality matters. Agents take the idea further (workflows before agents).

ڕێبەرەکەی Anthropic بە باوترین زنجیرە دەڵێت ڕاستکردنەوەی خۆیی: ڕەشنووسێک بنووسە، لەگەڵ یاساکانتدا بیپشکنە، پاشان باشتری بکە. زنجیرە بانگکردنی زیاتر دەکات، بۆیە کاتێک بەکاری بهێنە کە کوالیتیی هەر هەنگاوێک گرنگە. ئەم بیرۆکەیە زیاتر دەبەن (سەرەتا ڕەوتی کار، پاشان ئەیجێنت).

An animation of four boxes for the job “a one-page guide for a new helper in Shilan's bookshop”. Step 1, Outline: five topics (opening hours, finding a book, prices, returns, being kind). Step 2, Draft. Step 3, Check: at most 200 words, all 5 topics, prices from the list; one price is wrong, so a dashed arrow goes back to the draft with “fix and try again”. Step 3 again: all checks pass. Step 4, Translate into Central Kurdish. Last frame: all four boxes ticked; small steps are easier to check, fix and improve than one huge prompt. — A chain of small prompts: each step can be checked.زنجیرەیەک بچووک: هەموو هەنگاوێک دەپشکنرێت.CêIT

Test your prompt like a programهەوێنەکەت وەک بەرنامەیەک تاقی بکەرەوە

A prompt that worked once may fail tomorrow on a different message. So test it as you test code, and as you test models (testing the claims): first decide what a good reply is; collect 10 to 20 real test cases (easy, hard and strange ones); run every version of the prompt on all of them and count the passes. Change one thing at a time.

کە جارێک کاری کرد، لەوانەیە سبەی لەسەر پەیامێکی جیاواز شکست بهێنێت. بۆیە وەک کۆد و وەک تاقی بکەرەوە (تاقیکردنەوەی بانگەشەکان): سەرەتا دیاری بکە وەڵامی باش چییە؛ ⁦10⁩ تا ⁦20⁩ ڕاستەقینە کۆ بکەرەوە (ئاسان، قورس و سەیر)؛ هەموو وەشانێکی لەسەر هەموویان تاقی بکەرەوە و دەرچووەکان بژمێرە. هەر جارێک یەک شت بگۆڕە.

Two rules from the providers' guides help a lot. Allow “I don't know” (“If the book is not in the list, say so”), so the model does not invent an answer (hallucination). And ask it to answer only from the text you gave, as RAG prompts do (RAG).

دوو یاسا لە ڕێبەرەکانی دابینکەرانەوە زۆر یارمەتی دەدەن. ڕێگە بە «نازانم» بدە («ئەگەر کتێبەکە لە لیستەکەدا نییە، بڵێ»)، بۆ ئەوەی وەڵامێک دروست نەکات (هەڵبەستنی زانیاری). هەروەها داوای لێ بکە تەنیا لەو دەقەوە وەڵام بداتەوە کە داوتە، وەک (RAG).

Test every version on the same test cases, and keep the best.هەموو وەشانێک لەسەر هەمان تاقی بکەرەوە و باشترینیان بهێڵەوە.CêIT

Test your prompt like a programهەوێنەکەت وەک بەرنامەیەک تاقی بکەرەوە

A mini evaluation in Pythonهەڵسەنگاندنی مۆدێل لە Pythonـدا: نموونەیەکی بچووک

This program checks four replies against three rules: valid JSON with both keys, a category from the allowed list, and at most 40 words. The replies are typed in for the example; in a real test they come from the model, one for each test message.

ئەم چوار وەڵام لەگەڵ سێ یاسادا دەپشکنێت: دروست بە هەردوو ، جۆرێک لە و زۆرترین ⁦40⁩ وشە. وەڵامەکان بۆ نموونەکە بە دەست نووسراون؛ لە تاقیکردنەوەی ڕاستەقینەدا لە دێن، یەکێک بۆ هەر پەیامێکی تاقیکردنەوە.

Pass or fail for each test caseدەرچوو یان دەرنەچوو بۆ هەر حاڵەتێکی تاقیکردنەوەmini_eval.pyPYTHONType in a terminalلە تێرمیناڵدا بینووسە

import json

ALLOWED = {"order", "question", "complaint"}

def check(reply):
    """Check one reply against our rules. Return a list of problems."""
    try:
        data = json.loads(reply)
    except json.JSONDecodeError:
        return ["not JSON"]
    problems = []
    for key in ("category", "answer"):
        if key not in data:
            problems.append(f"no {key!r}")
    if data.get("category") not in ALLOWED:
        problems.append("unknown category")
    if len(data.get("answer", "").split()) > 40:
        problems.append("answer over 40 words")
    return problems

long_answer = ("Thank you so much for your kind order. We are very happy to help you today. "
               "We will check the shelves, count the copies, wrap them carefully, write your "
               "name on the parcel and call you as soon as everything is ready for you to "
               "collect from the shop.")

# Test messages and the replies one prompt version gave (typed here for the example)
replies = {
    "Do you have Mem u Zin?": '{"category": "question", "answer": "Yes, two copies."}',
    "Send me 3 copies":       json.dumps({"category": "order", "answer": long_answer}),
    "The book was torn":      'Sorry to hear that! {"category": "complaint"}',
    "Open on Friday?":        '{"category": "info", "answer": "No, we close on Fridays."}',
}

passed = 0
for message, reply in replies.items():
    problems = check(reply)
    if problems:
        print(f"{message:24} FAIL: {', '.join(problems)}")
    else:
        print(f"{message:24} PASS")
        passed += 1
print(f"passed {passed} of {len(replies)}")

Explain the codeڕوونکردنەوەی کۆدەکە

Lineدێڕی 5-19

check() returns a list of problems; an empty list means the reply passed.

check() لیستێکی کێشەکان دەگەڕێنێتەوە؛ لیستی بەتاڵ واتە وەڵامەکە دەرچوو.

Lineدێڕی 34-42

Every test message is checked the same way, and the passes are counted.

هەموو پەیامێکی تاقیکردنەوە بە هەمان شێوە دەپشکنرێت و دەرچووەکان دەژمێردرێن.

Each failure points to a fix in the prompt: a word limit, a “JSON only” rule, and the list of allowed categories. Run the same test after every change.

هەر شکستێک ئاماژە بە چارەسەرێک لە دەکات: سنووری وشە، یاسای «تەنیا » و جۆرەکان. دوای هەموو گۆڕانکارییەک هەمان تاقیکردنەوە دووپاتە بکەرەوە.

Writing prompts in Kurdishنووسینی هەوێن بە کوردی

Models learned far less Kurdish than English, so Kurdish answers are often weaker: mixed dialects, Arabic or Persian words, odd spelling (generative AI and Kurdish). A Kurdish prompt helps when it:

کوردییان زۆر کەمتر لە ئینگلیزی فێر بووە، بۆیە وەڵامی کوردی زۆرجار لاوازترە: زاراوەی تێکەڵ، وشەی عەرەبی یان فارسی، ڕێنووسی سەیر (ژیریی دەستکردی بەرهەمهێنەر و کوردی). کوردی یارمەتی دەدات کاتێک:

names the dialect and the script: Central Kurdish (Sorani) in Arabic script, not just “Kurdish”;
gives the technical words you want, for example CêIT's terms, so the model does not invent new ones;
keeps code, commands and function names in English;
states the reader's level and asks for short sentences.

زاراوە و ئەلفوبێکە دیاری دەکات: کوردیی ناوەندی (سۆرانی) بە ئەلفوبێی عەرەبی، نەک تەنیا «کوردی»؛
ئەو وشە تەکنیکییانە دەدات کە دەتەوێت، بۆ نموونە زاراوەکانی CêIT، بۆ ئەوەی وشەی نوێ دروست نەکات؛
کۆد، و ناوی بە ئینگلیزی دەهێڵێتەوە؛
ئاستی خوێنەر دەڵێت و داوای ڕستەی کورت دەکات.

Check the result with a teacher or a dictionary before you share it. Kurdish text also needs more tokens than English, so the same answer costs more (estimating tokens).

پێش ئەوەی بڵاوی بکەیتەوە، ئەنجامەکە لای مامۆستایەک یان لە فەرهەنگێکدا بپشکنە. دەقی کوردی هەروەها زیاتر لە ئینگلیزی دەخوازێت، بۆیە هەمان وەڵام گرانترە (مەزەندەکردنی تۆکنەکان).

Four habits for better Kurdish answers.چوار ڕاهاتن بۆ وەڵامی کوردیی باشتر.CêIT

Common mistakesهەڵە باوەکان

Watch out for theseئاگاداری ئەمانە بە

A vague prompt: “Tell me about networks.” Say who it is for, what you need and in what form.
Three jobs in one sentence: “Translate this, check the prices and write an e-mail.” Split them, or number the steps.
Only “don'ts”: a list of things to avoid. Say what you want instead.
Trusting the answer unchecked: a confident answer can be invented. Check facts, numbers and code.
Pasting secrets or other people's data: never put passwords, API keys, ID numbers or customers' personal data into a prompt you do not control (privacy).
Looking for magic words: capital letters, threats or “you are the world's best expert” do not replace clear instructions and examples.
Letting AI do your homework: use it as a tutor (“explain”, “quiz me”, “check my answer”), follow your college's rules and say how you used it (studying honestly, AI-written posts).

ناڕوون: «باسی بۆ بکە.» بڵێ بۆ کێیە، چیت پێویستە و بە چ شێوەیەک.
سێ کار لە یەک ڕستەدا: «ئەمە وەربگێڕە، نرخەکان بپشکنە و ئیمەیڵێک بنووسە.» جیایان بکەرەوە، یان هەنگاوەکان ژمارە بکە.
تەنیا «مەکە»: لیستێکی ئەو شتانەی دەبێت خۆی لێ بپارێزێت. لە جیاتی ئەوە بڵێ چیت دەوێت.
متمانە بە وەڵام بێ پشکنین: وەڵامێکی دڵنیا دەکرێت دروستکراو بێت. ڕاستی، ژمارە و کۆد بپشکنە.
لکاندنی نهێنی یان خەڵکی تر: هەرگیز ، ، ژمارەی ناسنامە یان کڕیاران مەخەرە ناو کە تۆ کۆنترۆڵی ناکەیت (تایبەتێتی).
گەڕان بە دوای وشەی جادوویی: پیتی گەورە، هەڕەشە یان «تۆ باشترین شارەزای جیهانیت» جێگەی ڕێنمایی و نموونەی ڕوون ناگرنەوە.
هێشتنەوەی ئەرکی ماڵەوە بۆ : وەک مامۆستای تایبەت بەکاری بهێنە («ڕوونی بکەرەوە»، «تاقیم بکەرەوە»، «وەڵامەکەم بپشکنە»)، یاساکانی کۆلێژەکەت پەیڕەو بکە و بڵێ چۆن بەکارت هێنا (خوێندنی دەستپاک، پۆستی نووسراو بە ژیریی دەستکرد).

Exercisesڕاهێنانەکان

ExerciseڕاهێنانRewrite three weak promptsسێ هەوێنی لاواز دووپاتە بنووسەوە

Rewrite each prompt using the six parts: (a) “Summarise this.” (b) “Translate to Kurdish.” (c) “Don't make it too long and don't use hard words.”

هەر بە شەش بەشەکە دووپاتە بنووسەوە: ⁦(a)⁩ «پوختەی بکە.» ⁦(b)⁩ «وەری بگێڕە بۆ کوردی.» ⁦(c)⁩ «زۆر درێژی مەکە و وشەی قورس بەکار مەهێنە.»

Hintئاماژە

Who reads it? What exactly? How long, in what language and form? Where is the input?

کێ دەیخوێنێتەوە؟ ڕێک چی؟ چەند درێژ، بە چ زمانێک و بە چ شێوەیەک؟ لە کوێیە؟

Show answerوەڵامەکە پیشان بدە

(a) “You help first-year IT students. Summarise the article inside <article> in 5 bullet points of at most 15 words each, in English, keeping every definition. <article> … </article>”
(b) “Translate the shop notice inside <notice> into Central Kurdish (Sorani), Arabic script, for customers of a bookshop. Keep the opening hours and prices exactly as written.”
(c) “Write at most 120 words, in short sentences that a 14-year-old understands. Explain each technical word once, the first time you use it.”

⁦(a)⁩ «تۆ یارمەتیی خوێندکارانی قۆناغی یەکەمی IT دەدەیت. پوختەی ئەو وتارەی ناو <article> بکە بە 5 خاڵ، هەر خاڵێک زۆرترین ⁦15⁩ وشە، بە ئینگلیزی و هەموو پێناسەیەک بهێڵەوە. <article> … </article>»
⁦(b)⁩ «ئاگادارییەکەی دوکان کە لە ناو <notice>ـدایە وەربگێڕە بۆ کوردیی ناوەندی (سۆرانی)، بە ئەلفوبێی عەرەبی، بۆ کڕیارانی کتێبفرۆشییەک. کاتی کار و نرخەکان ڕێک وەک خۆیان بهێڵەوە.»
⁦(c)⁩ «زۆرترین ⁦120⁩ وشە بنووسە، بە ڕستەی کورت کە منداڵێکی ⁦14⁩ ساڵ تێی بگات. هەر وشەیەکی تەکنیکی یەکجار ڕوون بکەرەوە، یەکەم جار کە بەکاری دەهێنیت.»

ExerciseڕاهێنانWrite a few-shot promptهەوێنی چەندنموونەیی بنووسە

Karwan's app gets reviews. Write a few-shot prompt that sorts each review into bug, feature or praise and answers with one word only.

کاروان هەڵسەنگاندن وەردەگرێت. چەندنموونەیی بنووسە کە هەر هەڵسەنگاندنێک بکات بە bug (هەڵە)، feature (داوای تایبەتمەندی) یان praise (ستایش) و تەنیا بە یەک وشە وەڵام بداتەوە.

Show answerوەڵامەکە پیشان بدە

One possible answerوەڵامێکی گونجاوTEXT

Sort the app review into exactly one word: bug, feature or praise.

<examples>
The app closes when I open my profile. -> bug
Please add a dark mode. -> feature
Very fast and easy to use, thank you! -> praise
The Kurdish letters look broken on the search page. -> bug
</examples>

Review: {review}
Answer with one word only.

It has one example of each label and two bugs that look different, so the model does not learn “every bug mentions crashing”. {review} is the slot a template fills.

بۆ هەر ناوێک نموونەیەکی هەیە و دوو bugـی جیاواز، بۆ ئەوەی فێری «هەموو هەڵەیەک باسی داخستن دەکات» نەبێت. {review} ئەو شوێنەیە کە پڕی دەکاتەوە.

ExerciseڕاهێنانSpot the missing partsبەشە کەمەکان بدۆزەوە

Dilan, a teacher, writes: “You are a maths teacher. Explain fractions.” Which parts of a good prompt are missing?

دیلان، کە مامۆستایە، دەنووسێت: «تۆ مامۆستای بیرکاریت. کەرتەکان ڕوون بکەرەوە.» کام بەشەکانی باش کەمن؟

Show answerوەڵامەکە پیشان بدە

Role and task are there. Missing: the reader (which class, what age), the context (a lesson, homework, a test?), limits (language, length, level) and the output format (for example three steps with one worked example and two practice questions).

ڕۆڵ و ئەرک هەن. کەمن: خوێنەر (کام پۆل، چ تەمەنێک)، پاشخان (وانە، ئەرکی ماڵەوە، تاقیکردنەوە؟)، سنوور (زمان، درێژی، ئاست) و شێوەی (بۆ نموونە سێ هەنگاو بە یەک نموونەی چارەسەرکراو و دوو پرسیاری ڕاهێنان).

ExerciseڕاهێنانAdd a rule to the evaluationیاسایەک بۆ کرداری check() زیاد بکە

Change check() in mini_eval.py so a reply whose answer is empty or only spaces fails with “empty answer”. Test it with an empty answer and a good one.

check() لە mini_eval.pyـدا بگۆڕە بۆ ئەوەی وەڵامێک کە answerـەکەی بەتاڵە یان تەنیا بۆشاییە بە «empty answer» دەرنەچێت. بە وەڵامێکی بەتاڵ و یەکێکی باش تاقی بکەرەوە.

Hintئاماژە

Use .strip() and an if that appends to problems.

.strip() و ifـێک بەکار بهێنە کە بۆ problems زیاد بکات.

Show answerوەڵامەکە پیشان بدە

One possible answerوەڵامێکی گونجاوeval_empty.pyPYTHONType in a terminalلە تێرمیناڵدا بینووسە

import json

ALLOWED = {"order", "question", "complaint"}

def check(reply):
    try:
        data = json.loads(reply)
    except json.JSONDecodeError:
        return ["not JSON"]
    problems = []
    for key in ("category", "answer"):
        if key not in data:
            problems.append(f"no {key!r}")
    if data.get("category") not in ALLOWED:
        problems.append("unknown category")
    answer = data.get("answer", "")
    if len(answer.split()) > 40:
        problems.append("answer over 40 words")
    if "answer" in data and not answer.strip():     # the new rule
        problems.append("empty answer")
    return problems

print(check('{"category": "question", "answer": "   "}'))
print(check('{"category": "question", "answer": "Yes, two copies."}'))

Explain the codeڕوونکردنەوەی کۆدەکە

Lineدێڕی 19-20

strip() removes spaces, so “ ” becomes empty and fails; the check runs only when the key exists.

strip() بۆشاییەکان لادەبات، بۆیە « » بەتاڵ دەبێت و دەرناچێت؛ پشکنینەکە تەنیا کاتێک کار دەکات کە هەبێت.

ExerciseڕاهێنانA tutor prompt for Aramهەوێنێکی مامۆستای تایبەت بۆ ئارام

Write a prompt Aram can use before his database exam that helps him learn, without doing the work for him.

بنووسە کە ئارام پێش تاقیکردنەوەی وانەی بەکاری بهێنێت و یارمەتیی بدات فێر ببێت، بێ ئەوەی کارەکەی بۆ بکات.

Show answerوەڵامەکە پیشان بدە

For example: “I am a first-year IT student preparing for a database exam. Ask me one question about SQL joins at a time. Wait for my answer, then tell me what was right, what was wrong and why, before the next question. Do not give the answer before I try.”

بۆ نموونە: «من خوێندکاری قۆناغی یەکەمی ITم و خۆم بۆ تاقیکردنەوەی ئامادە دەکەم. هەر جارە یەک پرسیارم لەبارەی JOINـەکانی SQL لێ بکە. چاوەڕێی وەڵامەکەم بکە، پاشان پێم بڵێ چی ڕاست بوو، چی هەڵە بوو و بۆچی، پێش پرسیاری داهاتوو. پێش ئەوەی هەوڵ بدەم وەڵامەکە مەدە.»

Summaryپوختە

A prompt («هەوێن») is everything the model reads: system prompt, chat history, files and your message. Detail helps because the model cannot guess what you need.
A good prompt has a role and reader, a task, context, a clearly marked input, limits and an output format. Say what to do, and why.
The system prompt holds the app's rules; a role sets tone, not knowledge; rules are not locks, so the program checks too.
Few-shot examples fix the format; chain of thought helps with maths and logic; ask for JSON and check it with json.loads().
Templates reuse the rules; chains split big jobs into checkable steps; test cases show which version is best.
In Kurdish, name the dialect and script, give the terms, keep code in English, and check the answer.

هەموو ئەو شتانەیە کە دەیخوێنێتەوە: ، مێژووی گفتوگۆ، فایل و پەیامەکەت. وردەکاری یارمەتی دەدات، چونکە ناتوانێت مەزەندە بکات چیت پێویستە.
باش ڕۆڵ و خوێنەر، ئەرک، پاشخان، بە ڕوونی دیاریکراو، سنوور و شێوەی هەیە. بڵێ چی بکات و بۆچی.
یاساکانی هەڵدەگرێت؛ ڕۆڵ شێوازی دەربڕین دیاری دەکات، نەک زانیاری؛ یاسا قوفڵ نییە، بۆیە دەپشکنێت.
نموونەکانی شێوەکە جێگیر دەکەن؛ لە بیرکاری و لۆجیکدا یارمەتی دەدات؛ داوای بکە و بە json.loads() بیپشکنە.
یاساکان دووپاتە بەکار دەهێننەوە؛ زنجیرەکان کاری گەورە دەکەن بە هەنگاوی پشکنراو؛ پیشان دەدەن کام وەشان باشترە.
بە کوردی، زاراوە و ئەلفوبێ دیاری بکە، زاراوەکان بدە، کۆد بە ئینگلیزی بهێڵەوە و وەڵامەکە بپشکنە.

Next: the same prompts cost money and time. See how to count and save tokens in Token optimization.

داهاتوو: هەمان پارە و کات دەخۆن. ببینە چۆن بژمێریت و پاشەکەوتیان بکەیت لە باشترینکردنی تۆکن.

Lesson complete!وانەکە تەواو بوو!

Well done. Review the key terms, then go on to the next lesson.دەستخۆش. سەیرێکی زاراوە سەرەکییەکان بکەرەوە، پاشان بڕۆ بۆ وانەی داهاتوو.

Key termsزاراوە سەرەکییەکان

Next lessonوانەی داهاتوو

Token Optimization: Saving Cost, Time and Contextباشترینکردنی تۆکن: پاشەکەوتی پارە، کات و شوێن

Related lecturesوانە پەیوەندیدارەکان

References and further readingسەرچاوەکان و خوێندنەوەی زیاتر

This lecture is a first edition. The Kurdish text and terminology are waiting for review by Kurdish IT teachers.ئەم وانەیە چاپی یەکەمە. دەقە کوردییەکە و زاراوەکانی چاوەڕێی پێداچوونەوەی مامۆستایانی کوردی بواری IT ن.