An AI agent does not just answer, it acts: it reads files, runs tools and takes several steps in a row. That is exactly why the way you give it the task decides the result. In this guide we show how to write a prompt that the agent actually completes, and what role .md files play in it.

Chatbot vs. AI agent: why the prompt matters more

A regular AI chatbot answers your question with text. An AI agent goes further: it uses tools, reads and edits files, runs commands and works through the whole task across multiple steps on its own. You can read more about how agents work in the article on artificial intelligence, agents and MCP.

This leads to a simple consequence: when an agent acts, a vague prompt does not only produce a weak answer, it produces bad actions. A good brief is therefore half the success.

8 principles of a good prompt

1. A clear goal

Say exactly what the result should be. Not “help me with this file”, but “change the login function so it returns a 401 error instead of crashing when the password is wrong”. A concrete goal gives the agent a clear target.

2. Context

Supply the facts the agent needs: which files relate to the task, what environment it runs in, what the constraints and dependencies are. The less it has to guess, the more precisely it works.

3. Role and tone

Define the position the agent should reason from: “act as an experienced security specialist” or “write as a copywriter for a general audience”. The role shapes both the vocabulary and the depth of the solution.

4. Output format

Say what the answer should look like: a list, a table, ready-to-use code, an e-mail, a maximum length. Without this you get a format that may not fit your needs and you will have to ask again.

5. Examples (few-shot)

Show 1-2 sample inputs and the outputs you want for them. This single step markedly improves the result, because the agent sees exactly what you expect instead of having to assume it.

6. Break large tasks down

Split a big task into smaller steps. For a complex brief, ask the agent to first propose a step-by-step plan, let you approve it, and only then carry it out. This prevents it from running off in the wrong direction.

7. Define “done” and what to avoid

Write down when the task is complete (for example “the code must pass the tests”) and what NOT to do (do not change the database schema, do not use external libraries). The guardrails are often more important than the brief itself.

8. Iterate

Do not write everything at once. Look at the first output and refine it with feedback: “cut this in half”, “add error handling”. Gradual fine-tuning is faster and more accurate than one huge prompt.

What role .md (Markdown) files play

Markdown is a simple format for structured text. Using characters such as # (headings), bullet points and **bold text** you write a clear document that is readable for both a human and a machine and can be versioned in Git (a system for tracking changes in files).

With AI agents, .md files serve as lasting instructions and the project’s memory. Typically this is a rules file (often AGENTS.md, CLAUDE.md or README.md) that the agent reads at the start of every session and follows. This gives you consistent behaviour: the same style, respected conventions, a clear sense of what is and is not allowed, plus a stable project context.

Why it works:

  • You do not have to repeat instructions in every prompt. You write them into the .md file once and the agent always has them at hand.
  • Changes are visible in the history. When you edit a rule, Git shows who, when and why.
  • The rules are shared. The whole team and the agent work from the same document.

A practical tip to finish

Concreteness always beats vagueness. Giving the agent examples and clear guardrails is half the success. On top of that, write your project rules into a .md file so you do not have to keep repeating them. And keep in mind that AI is a good servant but a bad master, so always check the outputs.

Do you need to deploy an AI agent into your processes or set up a workflow around it? Get in touch, we will be glad to help.

This article is part of our Artificial intelligence overview.