I have written a lot of bad agent prompts. Most of them failed for the same three reasons: the agent did not know who it was, it did not have the right information in front of it, or it was allowed to guess when it should have checked. This guide covers the four things that fixed that for us at Latticework and at AgenticX: writing a real agent personality, context engineering, ReAct-style reasoning, and running agents in parallel worktrees.

None of this is theory. These are the patterns we use every week to build the data pipelines, dashboards, and reporting agents we ship for retail brands.

What makes an agent prompt different from a chat prompt?

A chat prompt asks for an answer. An agent prompt sets up a worker that will take dozens of actions on its own before you look at the result. That changes what the prompt has to do.

A chat prompt can be a sentence. An agent prompt has to cover four things: who the agent is, what it can see, what tools it can use, and what “done” looks like. If any of those are missing, the agent fills the gap with a guess, and it will guess confidently.

The single best test for an agent prompt is this: hand it to a smart new hire on their first day with no other context. If they would have to ask you a question before starting, the agent will either ask the same question or make something up.

How do you write an AI agent personality that holds up?

The word “personality” throws people off. Think of it as a job description with a voice.

A good agent personality has four parts:

  1. Role and scope. One sentence on what this agent does and one sentence on what it does not do. “You are a retail analytics assistant for a DTC apparel brand. You answer questions about sales, customers, and marketing spend from the data warehouse. You do not give legal, tax, or HR advice.”
  2. Voice. How it talks. Short sentences or long. Numbers first or narrative first. Whether it hedges. For our client-facing reporting agents we use: “Lead with the number. One sentence of context. Never say ‘it seems’ when you have the data.”
  3. Rules of refusal. What it says when asked for something outside scope, and what it does when the data is missing. This is where most agents go wrong, because the default behavior of every model is to be helpful, and “helpful” without data means invented.
  4. Examples. Two or three short examples of a question and the ideal answer. Examples do more work than any amount of adjectives. “Be concise and professional” is worth almost nothing. One example of a concise, professional answer is worth a paragraph of instructions.

Here is a real system prompt we use, trimmed down:

You are the weekly reporting agent for a $40M DTC skincare brand.
You have read-only SQL access to the Snowflake warehouse.

Voice: lead with the number, then one sentence of why. No adjectives
about performance ("strong", "disappointing"). The reader decides that.

If a metric is not in the warehouse, say "not available in the
warehouse" and stop. Do not estimate.

Example
Q: How did new customer CAC trend last week?
A: New customer CAC was $62, up from $54 the prior week. Meta spend
rose 18% while new orders rose 3%.

Notice what is not in there. No “you are a world-class expert.” No “think step by step.” Those phrases made a difference two years ago. They do not now.

What is context engineering and why does it matter more than the prompt?

Context engineering is deciding what goes into the model’s context window and what stays out. It is the part of prompting that most people skip, and it is the part that decides whether an agent works in production.

The context window is the agent’s desk. Everything on the desk gets read. Everything off the desk does not exist. Most failed agents have one of two problems: a bare desk, so the agent guesses, or a desk buried in every document you could find, so the agent loses the one thing it needed.

Rules we follow:

  • Put the schema in, not the data. For a data agent, the table names, column names, and a one-line description of each table belong in the prompt. The rows do not. The agent should query for rows.
  • Put definitions in. If your company defines “new customer” as first order in the last 365 days, that definition goes in the context. Otherwise the agent will use its own, and it will be different from yours.
  • Retrieve, do not stuff. If the agent might need one of 200 documents, give it a search tool and let it pull the two it needs. Pasting all 200 in makes the agent slower and worse.
  • Keep the working set visible. For long tasks, keep a short running summary of what has been done and what is left, and put it back into the context each turn. Agents that lose track of their own progress repeat work or stop early.
  • Cut the noise. Every paragraph of boilerplate in the prompt is a paragraph the agent has to weigh against your actual instruction. If a line has never changed the agent’s behavior, delete it.

A practical measure: if your prompt plus context is more than a few thousand tokens before the agent has done any work, you are probably stuffing instead of retrieving.

How does ReAct prompting work, and when should you use it?

ReAct stands for Reason and Act. The agent writes down a short thought about what it should do next, takes one action (runs a query, reads a file, calls an API), looks at the result, and repeats. The pattern is:

Thought: I need last week's new customer count before I can compute CAC.
Action: run_sql("SELECT COUNT(*) FROM orders WHERE is_first_order AND ...")
Observation: 1,412
Thought: Now I need Meta and Google spend for the same window.
Action: ...

The reason this works is that it forces the agent to check before it asserts. Without the loop, an agent asked for CAC will produce a plausible number. With the loop, it produces the number that is in the warehouse.

When to use it: any task where the agent has tools and the answer depends on what those tools return. Data questions, code changes, anything that touches a live system.

When not to use it: single-shot writing or classification tasks with no tools. A ReAct loop on a task with nothing to observe just adds cost and latency.

Two things that make ReAct loops reliable in practice. First, cap the number of steps. An agent with no limit will occasionally loop on a failing query forever. Fifteen to twenty steps is enough for most data tasks. Second, make the final answer a separate, explicit action. The agent should have to say “this is my answer,” so a half-finished thought never gets returned as a result.

What is the worktree pattern for running agents in parallel?

This is the newest thing in our workflow and the one that changed our throughput the most.

A worktree is a separate, isolated copy of a codebase (or a dataset, or a project folder) that an agent can work in without touching anyone else’s copy. Git has this built in as git worktree. The idea is simple: instead of one agent working through a list of ten tasks in sequence, you start ten agents, give each one its own worktree, and let them work at the same time.

Why it matters for prompting: the prompt for a parallel agent has to be more self-contained than the prompt for a sequential one. It cannot rely on what the previous agent did, because there is no previous agent. Each prompt has to carry its own context, its own definition of done, and its own instruction for how to hand back the result.

The template we use for each parallel agent:

You are working in an isolated copy of the project at {path}.
No other agent can see your changes and you cannot see theirs.

Task: {one specific task}

Done means: {a testable condition, e.g. "the test file passes"
or "the query returns one row per customer"}

When done, return: a 3-line summary of what you changed and why.
Do not describe what you considered and rejected.

Then a separate step, usually a human or a single reviewing agent, reads the ten summaries and merges the work. The reviewer’s prompt is different again: it is looking for conflicts and gaps between the pieces, not doing the work itself.

The worktree pattern is what let us rebuild six pillar pages for our own site in an afternoon: one agent per page, each in its own copy, one review pass at the end.

How do you let a new agent pick up where the last one left off?

Worktrees solve the parallel problem. They do not solve the memory problem. Every agent session starts from zero. Close the window and everything it learned about your project is gone. The fix we use is to make the project folder itself carry the memory, in three plain Markdown files that live in the repo and get committed to GitHub with everything else.

CLAUDE.md (or AGENTS.md, the name depends on the tool) is the orientation file. It is the first thing an agent reads. Ours is about a page long and covers: what the project is, the folder map, the standing decisions we do not want re-litigated, and the order to read the other files in. It is written for a reader with no context at all. If a new agent has to ask a question that a teammate would already know the answer to, the answer goes in this file.

A history file is the long record of what was built and why. Ours is called website-builder.md and it has a dated entry for every change: what the ask was, what changed, what was tried and rejected, what to watch out for. It is long on purpose. An agent picking up a task six weeks later can read the last few entries and know exactly what state things are in and why they are that way.

A todo file is the short list of what is still open, who is blocked on what, and what has been decided but not built. This is the single place we check to see what is left. It is kept out of the history file so it never gets buried.

The workflow looks like this:

  1. Start a new agent session. Its first instruction is “read CLAUDE.md, then the last entries of the history file, then the todo file.”
  2. Give it the task.
  3. When the task is done, the agent’s last job is to append an entry to the history file, update the todo file, and update CLAUDE.md if a standing decision changed.
  4. Commit everything, including the generated output, to GitHub.
  5. Close the session. The next agent, in the next worktree, on the next day, starts from step 1 and loses nothing.

This is context engineering applied to the project instead of the prompt. The prompt stays short because the context lives in the repo. It also means a human can open the same three files and get the same picture, which matters when the person reviewing the work is not the person who started it.

Two rules that keep it working. The files are only useful if the agent is required to update them, so that instruction goes in the agent prompt, not in a note you hope it reads. And the history file should record what did not work and why, because the most expensive thing an agent can do is confidently repeat a mistake a previous agent already made.

Does writing a good agent prompt actually make a difference?

Yes, and it is measurable. The same task, a weekly performance summary for a retail client, run two ways:

A one-paragraph prompt (“You are a helpful analytics assistant. Summarize last week’s performance for the brand.”) produced a fluent summary in which two of the five numbers could not be traced to the warehouse. The agent had estimated them.

The full prompt above, with role, voice, refusal rules, schema in context, and a ReAct loop capped at 20 steps, produced a shorter summary in which every number matched a query the agent had actually run, and one line that read “return rate not available in the warehouse.”

The second version is the one you can send to a CFO.

A checklist before you ship an agent prompt

  • Role and scope stated in two sentences.
  • At least two examples of an ideal answer.
  • What the agent says when the data is missing.
  • Schema and definitions in context; raw data out.
  • A tool for retrieval if there are more than a handful of reference documents.
  • ReAct loop with a step cap, if the agent has tools.
  • A definition of done that can be checked.
  • If parallel: each prompt self-contained, plus a separate review step.
  • An orientation file, a history file, and a todo file in the repo, with the agent required to update them before it finishes.

FAQ

What is the best prompt to write an AI agent personality?

Write a job description, not a character. State the role in one sentence, the scope in one sentence, the voice in two or three concrete rules, and what the agent says when asked for something out of scope. Then add two examples of an ideal answer. Examples change behavior more than any adjective.

How do I write a prompt for an AI agent that acts as a knowledge base?

Give the agent a search or retrieval tool over the documents instead of pasting the documents into the prompt. Put the list of sources and a one-line description of each into context so the agent knows what exists. Instruct it to cite which source each answer came from and to say “not in the knowledge base” rather than answer from general knowledge.

How much difference does it make to write an agent prompt instead of a chat prompt?

For any task with tools or live data, a large one. In our own testing the same weekly reporting task went from two of five numbers being estimated to zero, once the prompt included role, refusal rules, schema in context, and a ReAct loop. For single-shot writing tasks with no tools, the difference is smaller.

What is context engineering in AI agents?

Deciding what goes into the model’s context window and what stays out. The practical rules: put schemas and definitions in, keep raw data out, retrieve documents on demand instead of stuffing them in, and keep a short running summary of progress in context on long tasks.

What is ReAct prompting?

A loop where the agent writes a short thought, takes one action with a tool, reads the result, and repeats until it has enough to answer. It forces the agent to check facts instead of asserting them. Cap the number of steps and make the final answer an explicit action.

How do I get an AI agent to remember previous sessions?

Keep the memory in the repo, not the chat. An orientation file (CLAUDE.md), a dated history file, and a todo file, all committed to GitHub. Every new session starts by reading them and ends by updating them. The next agent picks up where the last one stopped.

How do you run multiple AI agents in parallel?

Give each agent its own isolated copy of the project (a git worktree, or a copied folder) and a self-contained prompt with its own task and definition of done. Run them at the same time, then use a separate review step to merge the results and catch conflicts.

About Tim Shea & Latticework Insights

Tim Shea is the Founder & CEO of Latticework Insights and the founder of AgenticX, a Los Angeles community of creatives, developers, and executives building with agentic AI. Latticework Insights is a data science agency that provides Data Leadership to help Retail Brands become Elite Retail Brands, building the data warehouses, dashboards, and AI agents that give brands one trusted view of their business.

If you are building agents for your data and they keep guessing, get in touch. This is the work we do every week.