DEV Community: AI Coding Patterns

Shieldstral: Why a 3B Guard Model Ties a 20B One

AI Coding Patterns — Thu, 06 Aug 2026 19:37:39 +0000

Some teams are paying for inference on a 20B model that reasons out loud for several hundred tokens just to decide whether a comment breaks their content policy. On August 4th Mistral released Shieldstral, a 3B classifier that answers the same question with a single token ^[1]. What's worth digging into is where that difference comes from, because it isn't the architecture.

The Taxonomy Is Baked Into the Weights

The problem with classic guard models is that the list of harm categories gets fixed during training. A guard model is a small model dedicated to one thing: looking at a piece of text or an image and saying whether it violates a policy. It's the concrete implementation of what I call a guardrail in other posts, applied to content. LlamaGuard and ShieldGemma work this way, and both carry their taxonomy inside the weights.

That breaks down the moment your product isn't the average product. Text describing how to exploit a known vulnerability is normal content in a pentesting tool and material to block in a teen companion app: the same document, two legitimate verdicts. With the taxonomy baked into the weights, adjusting that nuance means relabeling a dataset and retraining.

And retraining over a policy change is an absurd cost for something that, looked at closely, is just text.

How Does Shieldstral Turn Moderation Into a Yes-or-No Question?

Shieldstral frames moderation as a binary-answer task: it receives a written policy and a question, and answers "yes" or "no". The prompt has three fields ^[1].

<Instruct>
You are a moderator for a cybersecurity community. Be strict about
operational instructions targeting specific systems, and permissive
with theory and educational discussion.
</Instruct>

<Query>
Does this message give actionable instructions for attacking someone
else's system?
</Query>

<Document>
[the user's message, the model's response, or an image]
</Document>

<Instruct> sets the context and the bar for enforcement, <Query> is the question being answered, and <Document> is what's being judged: text, an image, or both at once. With that format, four problems you'd normally solve with four separate models collapse into one: classifying the user's prompt, moderating the model's response, detecting whether the model refused to answer, and detecting toxicity ^[1]. Change the <Query> and you change the problem.

What matters about this design is where your policy ends up living: in the prompt. Adjusting the line between what's acceptable and what isn't becomes editing a paragraph and re-evaluating, not opening a training notebook.

The Score Comes From Two Logits, Not Generated Text

At inference time Shieldstral doesn't generate text. It runs a forward pass, reads the logits for the "yes" and "no" tokens, and normalizes with softmax over just those two ^[3]. A logit is the raw score the model assigns to each candidate token before it's converted into a probability; in the most probable answer isn't the correct one I explain what that distribution means.

# Safety score without generating a single output token
# pseudocode; the real snippet with transformers is on the HF model card
logits = model(prompt).logits[-1]          # next-token distribution
z_yes, z_no = logits[tok_yes], logits[tok_no]
score = exp(z_yes) / (exp(z_yes) + exp(z_no))   # softmax over two tokens
unsafe = score > 0.5                       # default threshold

The result is a continuous number between 0 and 1, with a default threshold of 0.5 ^[3], instead of a fixed label. Coming out of a softmax, it behaves like a probability: the score is calibrated, and the threshold becomes your decision. You can raise it where a false positive annoys the user, lower it where a false negative costs you an incident, and route only the middle band to human review. With a plain binary label you don't have that lever.

The obvious comparison is GPT-OSS-Safeguard-20B, which also accepts your policy in the prompt, but produces a full reasoning chain before the verdict. Same average text F1 (84.9%), a whole different order of cost per call ^[2].

	Shieldstral-1.0-3B	GPT-OSS-Safeguard-20B	OmniGuard-7B
Parameters	3B	20B	7B
Average text F1	84.9%	84.9%	not reported in the paper
Multimodal F1	83.8% (state of the art)	text only	77.6%
How it emits the verdict	"yes"/"no" logits in a single forward pass, continuous score	generates a reasoning trace, then the label	label
Where the policy lives	in the prompt	in the prompt	training taxonomy
License	Apache 2.0	Apache 2.0	check its model card

A 3B model matching a 20B model on average text benchmarks isn't explained by architecture or by more inference-time compute. It's explained by the dataset.

Contrastive Pairs: The Same Document, Opposite Verdicts

The most interesting part of the technical report is how they generated the data so the model learns which specific policy is being violated, instead of a crude safe/unsafe distinction. They trained on roughly 54.1M examples, of which 4.4M are synthetic contrastive pairs ^[2].

A contrastive pair is the same document evaluated twice against two sibling-category questions: for one the correct answer is "yes" and for the other it's "no". A text about drug dosage can violate "unsupervised medical advice" without violating "promotion of illegal substances". If the model only sees examples labeled toxic or non-toxic, it learns a general sense of toxicity and misses the distinction. If it sees the same paragraph with opposite verdicts depending on the question, it has no choice but to read the <Query>.

They validated against an evaluation taxonomy deliberately different from the training one, which is the only honest way to measure whether the prompt's policy is actually being used. Without the synthetic data, 61.1% F1. With it, 84.4% ^[2].

Twenty-three points that didn't come from more parameters.

The Final Checkpoint Is a Merge of Three Models

Shieldstral isn't the direct output of a single training run: it's a weight merge of three models. Model merging means interpolating the weights of several checkpoints to get a new one without any further training, and here they used SLERP (spherical interpolation between weights, not a linear average) with 0.6 from the checkpoint trained on synthetic data, 0.3 from the one trained on public data, and 0.1 from the starting instruct model ^[2].

The blend outperforms any of its ingredients: on adaptation to new taxonomies it goes from 84.4% to 88.7% F1. Those four points come from an algebra operation on the weights.

There's an extra data point in the paper that will save you money if you end up adapting it to your domain: LoRA (training a few small matrices added to the model instead of all its weights) performs nearly as well as full fine-tuning on this task, 87.1% versus 87.8% on Aegis v2, one of the safety benchmarks used in the evaluation ^[2]. Seven-tenths of a point of difference for a fraction of the cost.

When It's Worth It, and When It Isn't

Shieldstral makes sense when you have your own policy and volume. The cost per call is a forward pass on a 3B model that fits on a 16 GB GPU ^[1], so the economics change compared to billing reasoning tokens for every comment that comes in. If you're also moderating images: 83.8% multimodal F1 versus OmniGuard-7B's 77.6% ^[2].

Where it falls apart is in low-resource languages, and the paper itself publishes this. In Indonesian, prompt classification drops to 55.5% F1 while response classification in that same language scores 94.1% ^[2]. Same model, same language, and nearly forty points of difference depending on what you ask it to do.

That's the reading that matters for your decision: the 84.9% average is an average. Before you put this in front of real users, look up your language and your specific task in the appendix tables.

Common Mistakes

Choosing the Guard Model by Size

It's the natural instinct, and it doesn't work here. The "more parameters, better result" curve applies to open-ended tasks; on a bounded task like deciding whether a document answers "yes" to a question, what moves the needle is the data. The contrastive-pair ablation is worth more than multiplying the model by seven.

Trusting the Average F1

If the appendix's per-language breakdown shows 55.5% in your primary language and you decided based on the front-page 84.9%, you've shipped a moderator that fails almost half the time in your market. Read the breakdown before the headline number.

Retraining a Classifier When the Policy Fits in the Prompt

This is the expensive mistake. A team with its own classifier in production handles every policy change by opening up the training pipeline, because that's what it knows how to do. With a model that reads the policy from the prompt, that change is editing the <Instruct> block, running it against your eval set, and comparing results. From weeks to an afternoon. The condition is having that eval set: without it, editing the prompt means changing behavior blind.

Paying for a Reasoning Trace on Every Message

A judge with explicit reasoning is a great tool for ambiguous cases, quality reviews, or auditing questionable decisions. Using it for 100% of a high-volume platform's traffic means paying for an explanation nobody reads. Reserve reasoning for the middle band of scores.

Checklist Before Putting a Guard Model in Production

[ ] You have your own eval set, built from your product's content and labeled with your policy
[ ] You've read the model's per-language and per-task breakdown, not just the average
[ ] The policy is written in the prompt and versioned in the repo, not scattered across the team's heads
[ ] The threshold is set per product and per surface, not inherited from the default without thinking
[ ] There's a middle score band that routes to human review or a reasoning model
[ ] You're measuring false positives in production, not just the benchmark F1

Sources

Shieldstral — Mistral AI — official announcement from August 4, 2026: the three-field format, the four problems covered, running on a single 16 GB GPU, and the claim of matching models up to seven times its size.
Shieldstral — arXiv:2607.25857 — technical paper on the multimodal safety classifier: text and multimodal F1, dataset size and composition, the contrastive-pairs ablation, the SLERP merge weights, LoRA versus full fine-tuning, and the per-language breakdown.
mistralai/Shieldstral-1.0-3B — Hugging Face — model card: Ministral-3B base, Pixtral vision encoder, how the score is computed from the "yes"/"no" logits, the default 0.5 threshold, and the list of supported languages.

Frequently Asked Questions

What is a guard model and how is it different from a regular LLM?

A guard model is a model trained to classify content against a safety policy, not to converse or write: it takes in a document and returns a verdict on whether it violates a rule. In Shieldstral the output is a probability between 0 and 1 derived from two logits, without generating a single sentence, which is far cheaper than asking a general-purpose model the same question.

Does Shieldstral replace moderation APIs like OpenAI's or Azure's?

It depends on whether your policy fits theirs. Managed APIs moderate against categories defined by the provider and don't require you to run any infrastructure; Shieldstral requires you to serve the model yourself, but in exchange you write the policy in the prompt and your content never leaves your network.

If your criteria are standard and your volume is low, the API comes out cheaper in engineering time.

What does it mean for the score to be calibrated?

That you can treat the number as a confidence level and cut wherever suits you: above 0.8 you auto-block, between 0.4 and 0.8 you send to human review. The default threshold is 0.5 ^[3].

Can I fine-tune Shieldstral with my own policy?

You can, but try editing the prompt first: the model is specifically trained so the policy can live there. If you still need to adapt it after that, the paper measures LoRA against full fine-tuning on this task and the gap is seven-tenths of a point of F1 ^[2], so start with LoRA.

Does it work in Spanish?

Yes. Spanish is among the supported languages listed on the model card ^[3], alongside English, French, German, Italian, Portuguese, Dutch, Chinese, Japanese, Korean, Arabic, and Russian. Even so, the paper's per-language breakdown shows large gaps between languages and tasks, so evaluate it against your own Spanish-language content before trusting the global average.

This article was originally published on AI Coding Patterns — visual, interactive courses to learn programming with AI. Explore the courses.

Prompt Chaining: How to Break Down Complex Tasks Into Simple Steps

AI Coding Patterns — Tue, 21 Jul 2026 14:12:02 +0000

The first time I tried to do something useful with an LLM in code, I asked it to do everything at once: "analyze this review, extract the main emotions, classify it, and return the result in JSON". The model tried, but somewhere in the process it lost the thread, mixed up steps, and the final JSON was useless. The solution wasn't a better model. It was breaking the problem down.

Before we start: to follow this post you need to know what an LLM is (a language model like ChatGPT or Claude that generates text from instructions) and have written some TypeScript or JavaScript. That's all you need.

The problem: asking it to do everything at once

Imagine going to the supermarket and, right as you walk through the door, someone shouts a list of 10 different things at you without giving you time to write them down. You'll probably manage to get the bread and milk right, but you'll end up forgetting half of it or buying the wrong product. The same thing happens to AI models.

Every time you send an instruction to a model, that's called a prompt: it's the text you send, the question or task you want it to solve. When a prompt mixes four different tasks, the model has to keep them all "in mind" at the same time. It usually starts well, but at some point it makes an error. And that error carries through to the end.

The solution is simple: one step, one call.

How chaining works

Prompt chaining divides a complex task into a chain of calls to the LLM. Each call solves only one part of the problem, and the response from that step becomes the input to the next.

A concrete example. You want to process the resumes that arrive at your company:

Call 1: "Extract only the work experience from this document."
Call 2: "Calculate the total years of experience based on that excerpt."
Call 3: "Classify the profile as Junior, Mid, or Senior based on those years."
Call 4: "Draft a follow-up email for the candidate based on that classification."

Each call has a single responsibility. The model in step 4 doesn't need to read the entire three-page resume: it only receives the clean label ('Senior') from step 3 and works with that.

This pattern has existed in classic software for decades. It's called Pipe & Filter: data passes through a series of independent transformations, and each filter does one thing well. LLMs are simply another type of filter.

When does it make sense to use it?

It makes sense when the task has clear sequential sub-steps. Writing an SEO article is the textbook example: first you generate the outline, then you develop each section, then you review the tone. Each step depends on the previous one but does something different.

It also makes sense when you need to verify intermediate results. If step 1 extracts entities from text and the result comes back empty, there's no point spending money on steps 2 and 3. You can stop there.

When not to use it is equally important. If the task is straightforward ("summarize this in three points", "translate this sentence"), a single well-written prompt solves it. Adding steps only adds latency and cost. Before designing a pipeline, ask yourself: can I solve this with a single well-structured call? If the answer is yes, do it that way. The post on prompt engineering for developers covers the basic patterns for building those effective prompts.

The gate: how to prevent errors from multiplying

Between steps, you have to validate. That's a gate: a block of code that checks if the result from the previous step is valid before continuing.

Without gates, this happens: step 1 generates text with the wrong format (what's called a hallucination when the model invents or distorts the expected response). Step 2 receives that as input and produces something worse. Step 3 receives what step 2 made. By the time you reach the final output, the original error has multiplied and it's impossible to know where it started.

The simplest gate is a function that returns true or false. If it returns false, you apply an early exit: you exit the pipeline before reaching the end, return a clear error message, and don't spend more calls or money.

Guardrails in AI agents are the broader concept (the general boundaries on what the system can do), but in a sequential pipeline the gate is its most concrete and practical version.

A pipeline in TypeScript, step by step

Here's a working example. Two steps with a gate between them, no framework, just the official Anthropic SDK:

import Anthropic from "@anthropic-ai/sdk";

// Create the client (uses the ANTHROPIC_API_KEY environment variable)
const client = new Anthropic();

// Reusable helper: send a prompt to the LLM and return the text
async function llamarLLM(prompt: string): Promise<string> {
  try {
    const respuesta = await client.messages.create({
      model: "claude-haiku-4-5-20251001", // fast model, ideal for simple steps
      max_tokens: 300,                     // maximum tokens it can generate
      messages: [{ role: "user", content: prompt }],
    });
    // Check the block type: the API can return text, images, or other types
    const bloque = respuesta.content[0];
    if (!bloque || bloque.type !== "text") {
      throw new Error("El modelo no devolvió un bloque de texto");
    }
    return bloque.text;
  } catch (error) {
    throw new Error(`Error calling the LLM: ${error instanceof Error ? error.message : String(error)}`);
  }
}

// Gate: checks that the summary has reasonable length
// This gate is deliberately simple. In production, typical gates include:
// regex to verify expected format (/^(positive|negative|neutral)$/.test(output)),
// JSON.parse() for structured outputs (try { JSON.parse(output) } catch { early exit }),
// or a second LLM call when validation requires semantic judgment.
function esResumenValido(resumen: string): boolean {
  return resumen.trim().length > 10 && resumen.length < 300;
}

async function analizarResena(resena: string) {
  // In production: validate and limit user input before interpolating it
  // Step 1: summarize the review
  const resumen = await llamarLLM(
    `Resume esta reseña de cliente en una sola frase:\n\n${resena}`
  );

  console.log("[paso 1] resumen:", resumen);

  // Gate: if the summary is invalid, early exit
  if (!esResumenValido(resumen)) {
    return { error: "No se pudo generar un resumen válido. Revisa el input." };
  }

  // Step 2: classify using ONLY the summary, not the complete review
  const clasificacion = await llamarLLM(
    `Clasifica este texto como "positivo", "negativo" o "neutral":\n\n${resumen}`
  );

  return { resumen, clasificacion };
}

Notice in step 2: we pass resumen, not resena. The classification model doesn't need to read the complete original text. Passing less is cheaper and faster.

This is where the context window comes in (the amount of text you can send to a model in a single call, with a maximum limit). In long pipelines, if you don't filter what you pass in each step, the cost explodes without improving results. The post on context window and best practices goes into detail on how to manage it.

Mistakes everyone will make

Too many steps for too little

A six-step pipeline for something that's solved in two. Each extra step adds latency and a new point of failure. Always start with the minimum number of steps and add only if the result justifies it.

Passing all context to each call

The most expensive mistake. Tokens are the units that models use to measure text (sort of like word fragments). LLM APIs charge per token: both for what you send and what you receive. If in step 3 you include the complete history from steps 1 and 2, that cost multiplies by the number of steps. Pass only the clean data that step needs. The inverse tradeoff also exists: cutting too much can weaken the result of the next step. Not the entire history, but what's necessary for that step to have enough signal.

Calls without error handling

The mistake I saw repeated most often, especially at the beginning: a pipeline without gates where step 1 fails silently and subsequent steps receive incorrect data. The system fails in cascade, you don't know at which point the error occurred, and the user receives a generic message with no context. Gates aren't an optimization: they're what makes the system usable.

Unvalidated user input

If the pipeline processes text that comes from the user (a review, a form, any free field), that text gets interpolated directly into the prompt. A user can inject instructions within the content and alter the model's behavior. In production, validate and limit input before using it in a prompt: maximum length, allowed characters, whatever makes sense for your case.

Using prompt chaining for atomic tasks

"Translate this word to English" doesn't need a pipeline. If you find yourself adding steps to a task that's fundamentally simple, step back and ask yourself if the real problem is in the prompt, not the architecture. Complexity has a cost: more code, more points of failure, more latency.

Implementation checklist

[ ] Each step of the pipeline has a single clear responsibility
[ ] There's a validation gate between each pair of steps
[ ] The gate implements early exit with an error message that helps debug
[ ] Each step receives only the context it needs, not the complete history
[ ] The number of steps is the minimum necessary for the task
[ ] Results from each step are logged to facilitate debugging

Frequently Asked Questions

What's the difference between prompt chaining and an AI agent?

An agent decides for itself what steps to take, in what order, and when to stop. Prompt chaining is a fixed sequence that you define in advance. If you know exactly what steps you need, use prompt chaining: it's much more predictable and easier to debug when something fails.

Do I need a framework like LangChain to build a pipeline?

No. The example in this post doesn't use any framework. For pipelines of two or four steps, adding a framework adds unnecessary dependencies and layers of abstraction. A couple of functions in TypeScript do exactly the same thing with much less complexity.

What if the model in step 1 generates an incorrect format?

That's what the gate is for. Check the format before continuing and if the output doesn't pass validation, the pipeline stops and returns a clear error. Without a gate, that incorrect format propagates and afterward it's almost impossible to trace the origin of the failure.

If your step 1 returns JSON, the most direct gate is try { JSON.parse(output) } catch { return { error: "Invalid format" } }. If you expect an enumerated value ("positive" / "negative" / "neutral"), a regex is enough: /^(positive|negative|neutral)$/i.test(output). Catching the failure here, before step 2, is the difference between a clear error and 40 minutes of debugging.

Does the model in step 2 remember what step 1 did?

No, unless you explicitly pass that information to it. Each call to the LLM starts from zero. There's no memory between calls. If you need step 2 to know something from step 1, you have to pass it yourself in the prompt. It's one of the things that confuses people most at first, and it's also why the design of what information passes between steps matters so much.

How many steps is too many?

In practice, more than four or five steps for a single task usually indicates you're over-dividing the problem. Ask yourself if you can merge some steps without losing control over the intermediate results. If the answer is yes, merge them.

This article was originally published on AI Coding Patterns — visual, interactive courses to learn programming with AI. Explore the courses.

Guardrails for AI Agents: How to Implement Them (With Code)

AI Coding Patterns — Tue, 21 Jul 2026 14:10:33 +0000

Imagine asking an AI assistant: "delete the project's temporary files." The assistant thinks it knows which ones they are, but it's wrong... and deletes an important file (.env.local) with configuration data you need. The data is lost.

Why did it happen? Because the assistant did exactly what it understood from your order, without thinking about whether it was safe to do so.

Guardrails are safety boundaries that prevent this from happening. They're like fencing off a dangerous zone: the assistant keeps working, but can't enter areas where it might cause harm.

Want to understand what a guardrail is and why you need one first, with analogies and no code? Start with the conceptual guide. Here we go straight to implementing them.

Before you start

What is an AI agent? It's a program that uses artificial intelligence (like ChatGPT) to:

Receive your instruction
Decide what to do
Execute actions (delete a file, send an email, etc.)

The code examples are in TypeScript, but you can follow along even if you're not a heavy programmer—I'll explain them in simple terms.

What is a guardrail

Think of a fenced-in playground. The fence doesn't decide where kids go or how they play. It just prevents them from running off toward the road.

An AI guardrail is basically a boundary you define in advance. The assistant stays intelligent and makes decisions, but there are certain actions it cannot do, no matter what you ask.

Examples:

"You can't delete configuration files"
"You can't access the customer database"
"You can't transfer money from the account"

There are three places where you can put guardrails:

1. Before (input): You review what the user asks before passing it to the assistant.

Example: If someone writes "delete everything," the system blocks it before the assistant tries.

2. During (execution): Limits on the actions the assistant can execute.

Example: The assistant can read files, but when it tries to delete one, the system checks: "Is this file in the allowed folder? Isn't it a protected file?"

3. After (output): You review what the assistant returns before using it.

Example: If the assistant generates a command to run, you verify the command is safe before executing it.

Why agents without guardrails fail

The problem isn't that AI is bad. The problem is that it does exactly what it understands from your orders, without questioning whether it's safe.

Example: You tell it "make the application faster" and the assistant deletes the database because it thinks it's slow. Technically it obeyed your order. But the result is disastrous.

Three common problems:

1. Irreversible actions without confirmation
The assistant executes dangerous orders immediately (delete a file, change settings) without asking for confirmation. It's like a worker who executes every order without checking if it's safe.

2. Sharing information that shouldn't be shared
The assistant has access to sensitive information (passwords, customer data) and shares it in its response, even though it shouldn't. It's not malice—it just uses all the information it has to answer.

3. Infinite loops
The assistant detects an error, tries to fix it, that generates another error, tries again... and enters an infinite cycle that doesn't stop on its own.

The root reason: Without guardrails, the assistant doesn't know what's allowed and what isn't in your specific situation.

How to implement them in practice

There are four levels of protection, from simplest to strongest. Start with the first ones—you don't need all of them from the beginning.

Level 1: The rulebook 📋

What is it? It's the initial instruction you give the agent. Like a manual that says "this yes, that no." It goes at the beginning of the system prompt and sets expectations from the start.

Real-world example: It's like telling a worker: "you can read the documents, but never touch the safe." It's the golden rule that guides all their decisions.

const systemPrompt = `
You are a code assistant.

✅ I CAN:
- Read files
- Suggest improvements
- Explain errors

❌ I CAN NEVER:
- Delete files
- View .env files
- Touch the database
`;

The agent uses these instructions to interpret each request it receives. If someone says "delete everything," the agent should reject it because it knows it can't delete files.

Pro: Fast to implement. With this you block almost all common accidents. It's the agent's psychological filter.

Con: A persistent user might try to get you to ignore these rules. The agent is trained to be obedient, and with the right words it might try to follow orders that contradict the manual. That's why the other levels exist.

Level 2: The safety filter 🛡️

What is it? Before the agent receives the user's message, your code checks: "Does this seem safe?" This filter runs between the user and the agent, analyzing dangerous text patterns.

Real-world example: It's like having a guard at the door checking if someone tries to enter with a weapon. If someone says a dangerous keyword, they never enter the building.

function isSecure(message: string): boolean {
  const dangers = [
    /delete.*database/i,
    /drop.*production/i,
    /DELETE FROM/i
  ];

  for (const danger of dangers) {
    if (danger.test(message)) {
      return false; // blocked here, agent never sees it
    }
  }
  return true;
}

The advantage is that the agent never processes dangerous messages. If the message is blocked here, the AI model never tries to process it or justify why it should do it anyway.

Customization options:

You can also implement a lightweight classification model to evaluate messages before they reach the main agent. Small, fast models can be used to:

Intent classification: Determine if the request is asking for an allowed action
Safety scoring: Assign a risk level (low, medium, high) to each message
Content filtering: Detect sensitive topics or patterns more accurately than regex patterns

import Anthropic from "@anthropic-ai/sdk";

async function classifyMessage(message: string): Promise<{
  safe: boolean;
  riskLevel: "low" | "medium" | "high";
  reason: string;
}> {
  const client = new Anthropic();

  const response = await client.messages.create({
    model: "claude-3-5-haiku-20241022", // Fast, small model
    max_tokens: 100,
    system: `You are a security classifier. Analyze if a message is safe for an AI agent to process.
    Respond with JSON: {"safe": boolean, "riskLevel": "low|medium|high", "reason": "brief explanation"}`,
    messages: [
      {
        role: "user",
        content: message
      }
    ]
  });

  const content = response.content[0];
  if (content.type === "text") {
    return JSON.parse(content.text);
  }

  return { safe: true, riskLevel: "low", reason: "Could not classify" };
}

// Use it before sending to the main agent
const classification = await classifyMessage(userMessage);
if (classification.safe && classification.riskLevel !== "high") {
  // Send to main agent
  await mainAgent.process(userMessage);
} else {
  console.log(`❌ Blocked: ${classification.reason}`);
}

This approach is more accurate than pattern matching but slightly slower. Choose:

Pattern-based filtering (regex) for speed and simplicity
Model-based classification (lightweight AI model) for accuracy and nuance

Pro: The agent never sees malicious messages. It can't try to interpret them weirdly because the input never reaches it. Model-based classification catches sophisticated attempts to bypass simple pattern rules.

Con: It's a list of patterns (if pattern-based). There's always someone who finds a new way to write the same thing without triggering any pattern (for example, "remove production data" instead of "delete production"). Model-based classification adds latency and cost, though using a small, fast model minimizes both.

Level 3: Limits on each tool 🔒

What is it? Every action the agent can take has its own guardrail in the code. The agent asks for something, and before executing it, we verify if it's allowed. It's function-level protection.

Real-world example: It's like having a waiter who can serve water, but the bottle system only allows water, not alcohol. Even if the waiter asks for something from the bar, the machine only gives water.

async function deleteFile(path: string) {
  // Is it in the allowed folder?
  if (!path.includes('/tmp/')) {
    return '❌ I can only delete in /tmp/';
  }

  // Is it a special file we don't touch?
  if (path.endsWith('.env') || path.endsWith('.config')) {
    return '❌ This file is protected';
  }

  // If it passed both checks, ok
  delete(path);
  return '✅ File deleted';
}

This level is the most robust because the limits are in the code, not in the agent's interpretation. Even if the agent tries to bypass the rules, the code itself prevents it.

Pro: The agent can try whatever it wants; the code won't allow it. It's very hard to circumvent because it doesn't depend on words or patterns, but on pure logic.

Con: You need to write this code for each important action. It's more work, but it's the one that works best in practice.

Level 4: Output review 👀

What is it? Before using the response or commands the agent generates, your code reviews them. If the agent generates a dangerous SQL command, you block it before executing it. It's the final filter.

Real-world example: It's like an editor reviewing a document before publishing it: "this paragraph doesn't get published." Or a security director validating each action before it happens.

function isSQLSafe(sql: string): boolean {
  if (sql.includes('DROP') || sql.includes('TRUNCATE')) {
    return false; // blocked before executing
  }
  return true;
}

// Before executing:
if (isSQLSafe(agentSQL)) {
  execute(agentSQL);
} else {
  display('❌ This command is not safe');
}

This level is especially useful when the agent generates code or commands that will be executed. Even if the agent passed all previous filters, this is the last one checking that what's about to happen is really safe.

Pro: You're the final filter. Even if everything else fails, this catches it. It's especially important if the agent generates SQL commands, executable code, or actions that affect real systems.

Con: If you're generating a lot of content to review, the user waits longer. Also, it requires extra effort to analyze each output before executing it.

Quick summary:

Level	Think of it as	Speed	Security
1️⃣ Manual	A sign that says "don't touch"	Very fast	Basic
2️⃣ Filter	A guard at the door	Fast	Medium
3️⃣ Tools	A technician who checks each tool	Medium	High
4️⃣ Output	A final editor	Medium	Very high

How many do you need? Start with the first two. If the agent does dangerous things (delete, send emails), add the 3rd. If the result is used to execute code, add the 4th.

Common mistakes

Trusting only the system prompt

The system prompt is the starting point, not the complete system. If the agent has tools that can delete data, instructions saying "don't delete anything" aren't enough. Code-level limits don't depend on model interpretation and are harder to bypass.

Guardrails that block too much

An agent that rejects almost every request because filters are too aggressive is useless. The goal isn't to make the agent useless: it's to make it predictable. Start with few guardrails and add only those that address problems you've actually seen.

Not logging rejections

When a guardrail blocks something, keep a log. That record tells you what the agent (or user) tried to do, how often it happens, and whether your guardrail is well-calibrated or being too restrictive. Without logs, you're flying blind. When logging rejections though, avoid saving the complete user message if it might contain sensitive data. Save only the pattern that blocked it and the timestamp.

Guardrails only on the client

If your agent calls an API or executes code on the server, guardrails need to be on the server too. A client-only guardrail can be bypassed by directly calling the endpoint.

Implementation checklist

For infinite correction loops, attempt limit is the simplest thing that works:

// Attempt limit to prevent infinite correction loops
const MAX_RETRIES = 3;
let attempts = 0;

while (attempts < MAX_RETRIES) {
  const result = await agent.execute(instruction);
  if (result.successful) return result;
  attempts++;
}

throw new Error(`Agent didn't complete the task in ${MAX_RETRIES} attempts`);

[ ] The system prompt explicitly lists what the agent can and cannot do
[ ] There's input validation before sending requests to the model
[ ] Each tool with destructive effects (delete, modify, send) has its own guardrail in its implementation
[ ] Guardrail rejections are logged
[ ] Critical validations are on the server, not just the client
[ ] There's an attempt limit to prevent infinite correction loops

Frequently asked questions

Do guardrails slow down the agent?

The ones in the system prompt and input validation have almost no performance impact: they're local checks that execute in microseconds. What can add latency is using a second model to classify intentions or validate outputs. To start, stick with pure code validations.

What if a user tries to bypass guardrails with an elaborate instruction?

It's possible. Text pattern-based guardrails have blind spots. For systems where this is critical, the most robust approach is combining tool-level guardrails (hardest to bypass) with human review before executing irreversible actions. Without that second level, there will always be edge cases.

Do I need guardrails if the agent only answers questions and doesn't execute actions?

The risk is lower, yes. But output validation is still useful to prevent the agent from including in its responses data it shouldn't share: fragments of configuration files it has in context, for example.

How many guardrails are enough?

One irreversible action, one guardrail. An agent that only reads and responds needs few. An agent that writes to a database, sends emails, or modifies files needs guardrails on each of those actions. Start with actions that can't be undone.

This article was originally published on AI Coding Patterns — visual, interactive courses to learn programming with AI. Explore the courses.

GoF Patterns in AI Agents: The Complete Map

AI Coding Patterns — Fri, 10 Jul 2026 14:12:06 +0000

GoF patterns have existed for thirty years: Factory, Observer, Command, Singleton. They are proven ways to organize code.

In AI agents, these patterns reappear with new names and a clearer purpose.

Before you continue: this article is technical, but you don't need to be an expert. It's helpful to know some basic concepts, but we'll explain it step by step with easy-to-understand examples.

GoF Patterns in Thirty Seconds

In 1994, a very famous book came out with 23 solutions to problems every programmer faces. They're not lines of code, but proven ways to organize your program so it's easier to change and understand.

Imagine they're like construction blueprints: instead of inventing how to build each house, you use a blueprint that already worked.

Patterns are divided into groups by what they solve:

Creational: how to create things (like telling a machine to fabricate an object)
Structural: how to connect things together (like assembling pieces)
Behavioral: who does what and in what order (how actions are coordinated)
Enterprise: how to organize very large systems

In AI agent systems (machines that think and act on their own), almost all these patterns reappear with new names. The following table shows how old patterns serve modern agents. Don't worry if you don't understand the full table now—we'll explain the most important ones step by step.

The Complete Map

Classic Pattern	Family	Agentic Equivalent
Factory	Creational	Creates the right subagent based on task type
Builder	Creational	Incrementally builds agent context
Prototype	Creational	Reusable and cloneable prompt templates
Singleton	Creational	Centralized tool registry
Adapter	Structural	MCP: adapts any API to the format the model expects
Decorator	Structural	Guardrails: wrap the agent without touching its logic
Proxy	Structural	Model router: redirects by cost or capacity
Composite	Structural	Agent-of-agents: one agent coordinating other agents
Command	Behavioral	Tool call: encapsulated action the model can invoke
Observer	Behavioral	Hooks: react to agent events
Strategy	Behavioral	Model selection based on task
Mediator	Behavioral	Orchestrator: coordinates agents without direct communication
Chain of Responsibility	Behavioral	Pipeline of chained agents
Template Method	Behavioral	System prompt: defines expected response structure
Repository	PoEAA	RAG: abstracts external knowledge retrieval
DTO	PoEAA	Structured outputs: schema-defined objects between agents
Service Layer	PoEAA	Layer of orchestrator agents with clear responsibility
Saga	EIP	Long-running agentic transactions with compensation
Pub-Sub	EIP	Agents reacting to async events
Scatter-Gather	EIP	Multi-agent debate and best-answer synthesis
Circuit Breaker	Resilience	Maximum iteration limit in the tool loop
Bulkhead	Resilience	Budget and context isolation per agent
Fallback	Resilience	Chain of alternative models if primary fails

The table gives you the map. The following sections explain the patterns that appear most in early real-world agentic systems.

Creational Patterns: How an Agent is Born

Factory is like a worker who picks the right specialist for each task.

If you need code written, call the programming expert. If you need to search the web, call the search expert. If you need to analyze a document, call the analysis expert. Factory automatically picks the right specialist without you having to tell it manually which one to use.

// Factory: returns the correct agent based on task type
function createAgent(taskType: string): Agent {
  switch (taskType) {
    case "document-analysis":
      return new DocumentAnalysisAgent({
        model: "claude-opus-4-6",
        tools: [readFile, extractText, summarizeContent],
        systemPrompt: "You are an expert in analyzing complex documents..."
      });

    case "code-generation":
      return new CodeGenerationAgent({
        model: "claude-opus-4-6",
        tools: [writeFile, runTests, linter],
        systemPrompt: "You are a senior software engineer..."
      });

    case "web-research":
      return new ResearchAgent({
        model: "claude-haiku-4-5-20251001",
        tools: [webSearch, fetchArticle],
        systemPrompt: "You are a researcher gathering up-to-date information..."
      });

    default:
      throw new Error(`Unsupported agent type: ${taskType}`);
  }
}

// Usage: the system automatically picks the best agent for the task
const agent = createAgent("document-analysis");
await agent.run(newTask);

Builder is useful when you need to prepare an agent step by step, like putting together a puzzle.

First you give it basic instructions ("you're an analysis expert"). Then you add the history of previous conversations. Then the documents it needs. Instead of giving it everything at once, you do it in steps, and each step is a piece that fits into place.

Prototype is when you have a model or template you reuse.

For example: you have a "prompt" (instruction) that works well for analyzing code. Instead of writing new instructions for each project, you copy this template and adapt it slightly for each case. It's like having a form you fill with different data, but the structure is always the same.

Singleton solves a specific problem: the tool registry. A single point from which the system knows all available tools. Each tool registers once; agents invoke it by name. Without this centralized registry, you end up with tools defined in multiple places with mismatched schemas. Small, but it fixes an error that appears early.

Structural Patterns: How Everything Connects

Imagine your AI agent is like a person in an office. These four patterns are the "infrastructures" that make everything work together:

Adapter: it's like a translator between languages

Suppose your agent needs to use different external tools: Google, a database, a private API from your company. The problem is each one "speaks" in a different format. Adapter is a translator that converts each format to one your agent understands. That way, your agent doesn't need to learn 10 different languages. The translator handles the conversion automatically.

Decorator: it's like a bodyguard who reviews your actions (without getting into your head)

Your agent wants to execute an action: delete files, change a setting, send money. Before it does, you wrap it with a control layer that checks: "Are you sure you want to do this?" or "Does this action follow safety rules?" The agent doesn't know there's a bodyguard reviewing. It keeps thinking normally. The Decorator just acts as an external filter.

Proxy: it's like an intelligent receptionist who routes requests

When someone enters the office, the receptionist decides: "This simple question goes to a Junior. This complex question goes to the Senior." Proxy is like that: it receives the request, evaluates how complicated it is, and routes to the right model (Haiku for simple tasks, Opus for complex tasks). Your code stays the same; the receptionist makes the decision.

Composite: it's like a project director who coordinates specialists

Imagine your main agent is a director who doesn't do all the work alone. It's smarter: it has specialists under its command (an analysis agent, another for search, another for writing). From the outside, it looks like one person is working on the project. Inside, it's a coordinated team. The director (main agent) decides who does what, but the effort is collective.

Behavioral Patterns: How the Agent Acts

Imagine your AI agent is like an assistant that needs to do things. These patterns explain how that assistant works, what actions it can take, and how all those actions are coordinated.

Command is like giving a to-do list written on a note

Your agent has a list of things it can do: search the web, write a document, analyze an image, etc. Each task is written clearly on a note with:

What it's called (for example: "search the web")
What it does (for example: "find up-to-date information")
What information it needs (for example: "text to search")

When the agent needs to do something, you give it a note with that specific task. The agent reads the note, understands what it needs to do, and executes it. You control which tasks are available in the list.

Observer is like having alarms that go off at specific moments

Imagine you have alarms that go off when certain things happen:

An alarm that goes off when the agent finishes a search
An alarm that goes off when the agent starts writing
An alarm that goes off when it finishes completely

When each alarm goes off, you execute an action (for example: save the result, send a notification, update a database). The agent doesn't know there are alarms. It just does its work, and the alarms respond to what it does.

Strategy is like having different paths to the same destination

You have several ways to solve a problem:

Ask model A (fast but less accurate)
Ask model B (slow but more exact)
Ask model C (very precise but very expensive)

Depending on the situation, you pick a path: if the task is urgent and not important, use the fast model. If you need precision, use the exact model. The agent's logic stays the same; you only change which model it uses based on what you need at that moment.

Mediator is like having an orchestra conductor

Imagine you have several specialists:

One searches for information
Another analyzes documents
Another writes reports

Without a conductor, each specialist would need to know how to communicate with the others, who needs what information, etc. It's chaos.

With a conductor (Mediator), everyone talks only to the conductor:

The searcher says: "I found this information"
The conductor receives it and sends it to the analyst
The analyst says: "I've analyzed this"
The conductor sends it to the writer
The writer delivers the final report

The conductor is the only one who knows how all the parts work. The specialists only need to know the conductor.

Enterprise Patterns: PoEAA and EIP

They're ways to organize large, complex systems. We'll explain with simple examples:

Repository: it's like a "gateway to data"

Your agent needs to search for information. Instead of the agent knowing where the data is (Is it in a database? In files? On the internet?), there's a single gateway: ask for the information and someone finds it wherever it is. RAG (pattern for agents to access external knowledge) works like this: your agent just asks, without caring where the answer comes from.

DTO (sending structured information): it's like an envelope with clearly defined fields

When two agents need to communicate, they don't send loose text. They send an "envelope" with clear structure: this is a name, this is a number, this is a date. Less confusion, fewer errors.

Scatter-Gather: ask several at once and gather the answers

You have a difficult problem. Instead of asking one model (who might be wrong), you ask three models in parallel. They all solve the same problem from their perspectives. Then you gather the answers and reach the best conclusion. It's like asking advice from several friends instead of one.

Saga: it's a plan with "Plan B" if something goes wrong

Your agent needs to do five steps in sequence (step 1, step 2, step 3, step 4, step 5). If step 4 fails, what happens to steps 1, 2, and 3? Saga is a plan that says: if it fails here, undo this; if it fails there, undo that. That way the system keeps working without getting stuck halfway.

Resilience: When the Agent Fails or Gets Stuck

Imagine your agent is like a person working on a task. Sometimes it gets stuck: it keeps trying the same thing over and over without making progress, wasting time and money without results.

Circuit Breaker: it's like an emergency button

The agent tries to do something up to 10 times (or whatever number you set). If after those 10 attempts it can't succeed, the system stops. Without this limit, the stuck agent would keep trying forever, wasting your money on tokens without ever finishing the task.

// Emergency button: stop if it tries more than 10 times
if (attemptsAttempted > 10) {
  stopNow();
}

Bulkhead: it's like giving each agent its own budget

If you have several agents working at once, each gets its budget limit (tokens). If one goes overboard and uses up its limit, the others keep working with their budget. One doesn't ruin everyone.

Fallback chains: it's like having a Plan B

If the agent tries the Claude model (the most powerful but expensive) and fails, it automatically tries the Sonnet model (cheaper). If that also fails, it tries Haiku (the fastest). The system always has an alternative option.

What Has No Classic Equivalent

These are genuinely new agentic patterns. They're not in GoF, not in Fowler, not in Hohpe.

Context engineering: actively managing what information enters the context window (the memory space the model has during a conversation) at each moment. It's not caching or lazy loading. It's an explicit decision about what the model knows and doesn't know, made step by step.

Eval harness: infrastructure to measure whether the agent works well. Classic testing doesn't apply because model outputs are probabilistic, not deterministic. An eval harness defines test cases, runs the agent multiple times, and aggregates metrics to detect degradation.

LLM-as-Judge: use one model to evaluate the quality of another model's response. There's no classic equivalent because in traditional software tests are binary. Here the "judge" reasons about quality, coherence, or semantic correctness.

Sandbox execution: run code generated by the agent in an isolated environment before it touches production. The agent writes. The sandbox verifies. Only if it passes does it deploy. Without this pattern, every agent run is a gamble.

Cost/latency-aware routing: route requests to different models not just by capability, but with explicit constraints on cost and latency. Strategy solves the "how to choose". This pattern adds "how much can you spend and how long can you wait" as first-class citizens in the decision.

The difference between these five and GoF patterns is they require reasoning about uncertainty. GoF assumes code does what you tell it to. Agentic patterns assume the model can surprise you.

Common Mistakes When Mapping These Patterns

Confusing Decorator with Proxy

They're structurally similar, but the intent is different. Decorator adds behavior to the agent's output (verify, filter, enrich). Proxy controls access to the agent or model (redirect, limit, authenticate). If you're checking output, it's Decorator. If you're redirecting requests, it's Proxy. Mixing them leads to guardrails that do too much, or routers that also validate, and neither can change without breaking the other.

Applying Factory When You Only Have One Agent Type

Factory makes sense when you have two or more variants with different logic. If you only have one agent with one configuration, Factory is pure over-engineering. Start with a direct function. Add Factory when the second agent type actually appears.

Ignoring Circuit Breaker Until the Problem Happens

I've seen this in early agentic projects I worked on in production: the tool loop gets stuck in a loop, the agent keeps calling the same tool expecting a different result, and token spending multiplies without anyone noticing until the bill arrives. The iteration limit isn't an optimization. It's the first line of defense.

Using Saga Without Defining Compensations First

Saga without compensations is just a sequence of steps that doesn't know how to recover if something fails. Before implementing Saga, write on paper what the system does if step 3 of 5 fails. If you can't answer that question, you're not ready for Saga yet.

Implementation Checklist

[ ] Subagents are created with Factory based on task type, not scattered conditional logic
[ ] Each tool call is modeled as a Command object with explicit schema and clear description
[ ] Guardrails are implemented as Decorator, external to agent logic
[ ] The orchestrator centralizes communication between agents (Mediator), agents don't call each other
[ ] The tool loop has a Circuit Breaker with iteration limit defined before production deployment
[ ] RAG abstracts access to external knowledge (Repository), the agent doesn't know the data source
[ ] Outputs between agents use structured outputs with typed schema (DTO)
[ ] The system has at least a basic eval harness before deployment
[ ] Tools that execute user code run in an isolated sandbox before touching production

Frequently Asked Questions

Do I need to know GoF patterns to start with agents?

No. You can build functional agents without having read the 1994 book. But if you already know them, this map gives you an advantage: instead of learning agentic concepts from scratch, you recognize familiar structures with new roles. You already know how to use Factory. That it now creates subagents instead of business objects is a small step.

What pattern should I learn first if I'm starting from zero?

Command=tool call. It's the most fundamental of all. If you don't understand that each tool you give the model is a Command object with name, description, and schema, the rest of the patterns have no solid foundation. Everything else builds on that concept.

What's the difference between Decorator and Proxy in an agentic system?

Decorator adds behavior: the guardrails that verify or filter agent output. Proxy controls access: the router that decides which model to send the request to. The code structure is almost identical, but the intent is different. In practice: if you're modifying or checking output, it's Decorator. If you're redirecting requests, it's Proxy.

Does the Singleton pattern serve any purpose in agents?

Yes, for the tool registry: a centralized registry of all available tools, accessible from anywhere in the system. Each tool registers once. Agents invoke it by name. Without this registry, you end up with tools defined in multiple places with inconsistent schemas.

Are resilience patterns (Circuit Breaker, Bulkhead) for advanced systems?

Circuit Breaker is not. It's the first you should implement, before even any orchestration pattern. An agent without an iteration limit is one that can cost you money unpredictably. Bulkhead is more relevant when you have multiple agents running in parallel and need one's failure not to affect the others.

This article was originally published on AI Coding Patterns — visual, interactive courses to learn programming with AI. Explore the courses.

Loop engineering: the loop is the product, not the code

AI Coding Patterns — Fri, 10 Jul 2026 14:12:03 +0000

For years my job was writing the code. Now I describe a goal, and an agent writes it, runs the tests, reads the error, and tries again. The real work has moved up one level: I no longer write the code — I design the loop in which the agent writes it. I call this loop engineering. And the idea that organizes everything else is uncomfortably simple: the loop is the product, not the code.

If you've already built an agent with Claude Code or your own orchestrator, this will ring a bell. It works, but you iterate by gut feel. You tweak a prompt, run it, see if the result looks better, repeat. The quality leap almost never comes from a smarter prompt. It comes from designing a better loop.

What is "the loop," exactly?

The loop is the cycle an agent repeats until it finishes a task: it receives context, decides on an action, observes the result, compares it against what you wanted, and decides whether to try again or stop. It's the classic perception-decision-action of agents, with one addition that almost everyone skips: the explicit comparison against an objective.

Five pieces make up each iteration.

Context is everything the model can see at that moment: the objective, the code state, the error from the previous iteration, the available tools. What's not in the context doesn't exist for the agent, so managing it well is half the battle. If you've never thought of context as a scarce resource, start with context window best practices.

The action is the tool the model chooses and executes: writing a file, running a test, querying the database. That's tool calling.

The observation is the result the system feeds back into the context after executing the action. An important detail: the model reads the observation, it doesn't invent it. It's produced by the real world (the test runner, the compiler, the API), which is why the observation is the only part of the loop that the agent cannot fabricate.

Feedback is the signal that says whether this iteration is going better or worse than the previous one. Observing is not the same as knowing whether you're making progress. A failing test is an observation; that the failure count is one fewer than the previous iteration is feedback.

The stopping condition decides when the loop halts: objective achieved, budget exhausted, or lack of progress.

If you want the full breakdown, you'll find it in what exactly is an agentic loop and in the AI agent cycle explained step by step. What I'm interested in here is what happens when you scale that simple cycle: does this loop live inside a single task, or does it govern the entire system?

Inner loop and outer loop: two loops, two jobs

In an agentic system, two loops are operating at the same time, and confusing them is the primary source of poor design. The inner loop is the short cycle within a task. The agent generates a piece of code, runs the test, sees it fail, and corrects itself — all within the same reasoning session. It's the try-and-fix that Claude Code runs on every turn without you doing anything.

The outer loop is the long cycle. It's the system that launches that inner loop over and over: it gives it work, reviews the result, decides what comes next, and starts again — without you typing each prompt. This is where improvement between runs lives, the part that turns an agent that solves a task into an agent that solves tasks increasingly well.

The distinction isn't academic — it changes where you optimize. Improving the inner loop means faster, more readable feedback within the session: tests that run in seconds, errors the model can understand. Improving the outer loop is about orchestration, budget, and memory between runs. And there's a rule you learn the hard way: when the inner loop gets stuck, the outer loop must rethink the entire strategy, not repeat the same step hoping for a different result. Feedback loops in AI agents deserve their own article, because they're the mechanism that connects the two.

Both loops share one requirement. Without a good feedback signal, neither converges. It doesn't matter how elegant your orchestration is.

What makes a loop converge

A loop converges when each iteration brings it closer to the objective, and that only happens if it has a feedback signal that distinguishes between better and worse. There are two ways to get that signal, and choosing well between them is a significant part of the design.

The first is deterministic feedback: tests, linters, type-checkers, gates. Pass or fail. It's cheap, unambiguous, and non-negotiable. A red test is a red test, and the agent can't argue with it. When the problem can be reduced to a checkable rule, this is always the best signal. Claude Code hooks for deterministic quality are exactly this: walls the loop cannot jump over. And if the agent is writing code, the testing strategy when AI codes fast is what gives the loop a reliable signal.

The second is model judgment: one LLM evaluates what another produces. It covers what no test captures — things like "is this response clear?" or "does this text sound natural?" It's more expensive and noisier, but it covers the territory that deterministic verification can't reach. The pattern is in a model as judge.

Dimension	Deterministic feedback	Model judgment
What it measures	Anything reducible to a rule: compiles, passes the test, matches the type	Qualitative aspects: clarity, tone, whether the solution makes sense
Cost per iteration	Low	High: it's another model call
Reliability	High and repeatable	Variable; needs calibration to avoid scoring everything the same
When to use it	Whenever the problem allows it	Only for what can't be reduced to a rule

The practical rule is to prefer deterministic feedback whenever you can and reserve model judgment for what genuinely cannot be turned into a rule. A loop with ambiguous feedback doesn't converge — it spins because the signal doesn't tell it which direction to go. Designing that signal is such a big topic that I dedicate an entire article to it: how to evaluate AI agents in production.

A reliable signal tells you which direction to go. It doesn't tell you when to stop. And that's a different problem.

Why a loop doesn't terminate

A loop without an explicit stopping condition doesn't terminate: it keeps repeating the same state or burns through its budget until someone kills it. Unchecked autonomy isn't autonomy — it's a runaway.

Every loop needs a budget (a maximum number of iterations or tokens) and a definition of "done" that the loop itself can verify. But the most insidious failure is different: the lack of no-progress detection. If two consecutive iterations produce the same diff or the same error, the agent isn't advancing — it's stuck. Retrying the same thing expecting a different result isn't iterating. When that happens, the right move is to reframe or escalate, not take another identical turn. The extreme case, an AI agent stuck in an infinite loop, is almost always exactly this, without a brake.

// El bucle para por objetivo cumplido, presupuesto agotado o falta de progreso
async function runLoop(agente: Agent, objetivo: Objetivo, budget: Budget) {
  let estado = estadoInicial(objetivo);
  for (let vuelta = 0; vuelta < budget.maxVueltas; vuelta++) {
    const accion = await agente.decidir(estado);
    const observacion = await ejecutar(accion);
    const señal = await verificar(observacion, objetivo); // tests, lint o juez
    if (señal.cumplido) return observacion;
    if (sinProgreso(estado, observacion)) break; // mismo diff/error: atascado
    estado = actualizar(estado, observacion, señal.feedback);
  }
  return escalarAHumano(estado); // el bucle no decide solo cuándo rendirse
}

The guardrails that prevent a loop from going off the rails have their own name and their own design: guardrails for AI agents. Setting a limit is the easy part. The hard part is that each iteration has a cost, and deciding how many iterations are worth it is part of the design.

The cost of each iteration

Each loop iteration costs tokens, latency, money, and the risk of breaking something that was already working — so designing the loop also means deciding how many iterations are worth it. A loop that iterates twenty times to fix a typo is worse than one that stops at three and hands it back to you. More iterations don't mean a better result. Past a certain point, a loop with no new signal just burns budget.

The tradeoff shows up in every decision. Richer feedback per iteration — like running the full test suite — costs more per iteration but tends to converge in fewer iterations. Cheap feedback, like running only the linter, is fast but may need many more. And there's a cost that grows on its own: context accumulates with each iteration, more history means more tokens per call, and past a certain size the model starts losing track of what you originally asked for.

The iteration budget is a business decision disguised as a technical parameter. And like any costly decision, it shouldn't be made by the agent alone.

Where the human belongs in the loop

The human shouldn't be on every iteration of the loop, but at the costly, irreversible decision points. Reviewing every iteration turns the agent into a slow and expensive autocomplete: you lose the advantage of automation and keep doing the tedious work by hand.

Your place is where mistakes are expensive to undo: approving a hypothesis before spending to implement it, or authorizing a merge to main that the agent can't revert without consequences. The best example I know of this done right is the how I make my agents improve themselves methodology, where the only human intervention point is approving each hypothesis before it's implemented. Everything else runs on its own.

That pattern — human at the hypothesis, machine at the iteration — has a name when you take it to the extreme.

A loop that improves itself

The outer loop taken to the extreme is a loop that doesn't just solve the task — it improves the way it solves it. Instead of iterating over the code, you iterate over the system that writes the code.

The complete case study is the experiment-driven optimization methodology: measure against a frozen baseline, propose a hypothesis, implement it, validate whether the number improves, and document the experiment even when you discard it. Each run doesn't just produce a result — it produces information about how to produce better results. That's the ceiling of loop engineering: the system optimizes itself, and you only approve hypotheses.

Common mistakes

Iterating because "it looks better"

Without a signal that compares against the previous iteration, "looks better" is an opinion, and opinions don't converge. A number or a test that says why this iteration beats the previous one is the only way to know whether you're actually iterating.

The runaway loop

A loop without a budget or no-progress detection is a runaway waiting to happen. Set an iteration limit before you add anything else.

The human reviewing every iteration

If you approve every step, you haven't automated anything — you've just added latency to your own work. Save your attention for decisions that are expensive to undo and let the loop run on everything else.

Confusing more iterations with higher quality

Past a certain point, each additional iteration without a new signal only adds cost and the risk that the agent breaks something that was already working. A loop that converges in a few iterations and stops is better than one that takes twenty and keeps going.

Feedback that doesn't discriminate

The most subtle of all. A judge that scores everything a 7, or a test suite that always passes, gives the illusion of a signal without actually being one. Before trusting your feedback mechanism, verify that it genuinely separates good output from bad. If it can't tell the difference, the loop is blind even when it appears to see — and no number of iterations will fix that.

Checklist for designing your loop

[ ] Each iteration has a feedback signal that says whether it's going better or worse than the previous one
[ ] The signal is deterministic (tests, lint, type-check) whenever the problem allows it, and model judgment is reserved for what can't be reduced to a rule
[ ] The loop has an explicit stopping condition, with at least two exits beyond "objective achieved": budget exhausted and no-progress detected
[ ] There is an iteration budget (maximum iterations or tokens) defined before launching
[ ] The human only intervenes on costly or irreversible decisions, not on every iteration
[ ] When the loop gets stuck, it escalates or reframes instead of repeating the same step

Frequently Asked Questions

Is loop engineering the same as prompt engineering?

No: prompt engineering fine-tunes a single model call; loop engineering designs the complete cycle surrounding it, including what context goes in, how the output is verified, and when it stops.

What's the difference between inner loop and outer loop?

The inner loop is the short cycle of testing and correcting within a single task — like when an agent writes code, runs the test, and corrects itself in the same session. The outer loop is the long cycle that launches that task many times, reviews the result, and decides what comes next — and it's where the system improves between runs.

How many iterations are too many?

It depends on the cost of each iteration and the value of getting it right, but the alarm bell isn't the number — it's the lack of progress. If two consecutive iterations produce the same result or the same error, you've over-iterated even if you're only on iteration three. Set a maximum budget as a safety net and no-progress detection for the normal case.

Does loop engineering apply to any agent?

It applies to any agent whose task has a quality metric you can calculate, even if that metric requires a model as a judge. The problem appears with tasks that have no definable metric: "write an email that convinces this client" has no test and no clear success criterion — and without a way to say whether one draft beats another, the loop has nothing to hold on to. That's usually the first piece of work before automating anything: turning "make it good" into something you can measure.

This article was originally published on AI Coding Patterns — visual, interactive courses to learn programming with AI. Explore the courses.

How to Create a Claude Project: Step-by-Step Guide (2026)

AI Coding Patterns — Sun, 05 Jul 2026 19:17:03 +0000

Every time you open a new chat with Claude, it starts from scratch. It doesn't know you're a developer. It doesn't know what company you work for or what tone you prefer. You have to explain the context each time, and when you do it in every conversation, you end up writing the same introductory paragraph over and over.

Claude Projects solve that problem.

All you need to follow this post is an account on claude.ai—free or paid. No coding knowledge required.

What is a Project in Claude?

Before the technical definition, here's an analogy: imagine you have a fixed desk in an office. On that desk you have your notes pinned up, the documents for the project you're working on, and your tools organized. When you come back the next day, everything is still where you left it.

A normal chat with Claude is like a shared desk that someone cleans every time you leave. A Project is your fixed desk.

A Project has three parts:

Custom instructions: a text you write once that Claude reads at the start of each conversation in the project. It tells Claude who you are, what context you work in, what format you prefer, and any restrictions that matter.

Knowledge files: documents you upload to the project (PDFs, Markdown, code, plain text) that Claude can consult automatically when relevant. No need to paste them into the chat.

Conversation history: conversations you have in the project are saved and you can refer back to them anytime. But what Claude automatically loads at the start of each new conversation are the instructions and files; content from previous chats doesn't load.

Projects are available to all Claude users, including the free plan. With the free account you can create up to five projects and use the Sonnet model. Paid plans (Pro, Max, Team, Enterprise) add access to the more powerful Opus model and advanced support for large volumes of documents in the knowledge section.

How to Find Projects in Claude.ai

On claude.ai, Projects appear in the left sidebar below your recent conversations. You'll see a "+ New Project" button.

When you click it, it asks for a project name. Give it a descriptive one: "Work — Your Company Name" or "Learning React" work much better than "My Project".

Once inside the project, the interface has two main areas:

Project header: at the top of the screen you'll see the name you gave it. Just below is an "Edit project" button. That button opens a side panel with two fields: one for the name and one for custom instructions. The instructions field is a free text box with no visible length limit.
"Project Knowledge" tab: it's at the top of the central area, next to the conversations tab. From there you can drag files or use the upload button. Each uploaded file appears listed with its name, and you can delete or replace it anytime.

New conversations you create in the project automatically inherit the instructions and have access to the files. You don't need to do anything else.

Custom Instructions: What Actually Works

Most people using custom instructions write things like "always respond in English" or "be concise". That's fine. But it's just the surface layer.

The real value is giving Claude the context it would need to help you well from the first message, without you having to explain it every time.

Four useful questions for writing your instructions:

What should Claude know about me or my company to respond well?
What response format saves me time?
What constraints or preferences matter here?
What should Claude not do in this context?

Below you'll find three complete examples you can copy and adapt.

For someone learning to code

I'm a student in the final module of a web development bootcamp.
I work with React, TypeScript, and Node.js. My level is beginner.

When you explain code to me:
- Use comments in the code itself to explain each important part
- If there's a simpler way to do what I'm asking, tell me even if I didn't ask for it
- Avoid advanced concepts (decorators, complex generics) until I mention them first

When you review my code:
- Prioritize errors that would cause production bugs over style issues
- Explain why something is wrong, not just how to fix it

Always in English.

For someone doing content marketing

I work as a content marketer for a SaaS company that makes project management tools for small businesses.
Our customers are operations directors and CEOs of companies with 10-50 people.
Our company tone is professional but approachable, never corporate.

For written content:
- Short paragraphs, maximum three sentences
- No marketing jargon: nothing like "synergies", "added value", or "end-to-end solutions"
- Headlines that speak to the reader's problem, not our features

When you review my writing, tell me first if the main message is clear
before getting into writing details.

Language: American English.

For someone launching their own startup

I'm the founder of a startup in validation phase in the logistics sector.
I'm building the MVP alone, with no technical team yet.

Important context:
- Very limited budget, I prioritize free or cheap solutions
- I'm not technical, so explain the technical implications of decisions in simple terms
- My priority now is validating the product quickly, not building something scalable

When you suggest tools, always note whether they have a free plan.
When we talk about technology, explain trade-offs in terms of cost
and development speed, not architecture.

Use Cases by Profile

So you can recognize yourself in one, here's a quick reference by professional profile:

Profile	What Goes in Instructions	What Files to Upload
Developer	Tech stack, level, code format preferences	API documentation, project specifications you're building, team style guide
Marketer	Company, brand tone, target audience	Campaign briefs, brand voice guides, approved templates
Consultant	Specialization, working methodology, current client	Meeting notes, previous proposals, industry context
Entrepreneur	Startup stage, budget constraints, priorities	Summary business plan, user feedback, list of assumptions to validate
Student	Area of study, level, how you prefer concepts explained	Your own notes, exercise descriptions, course materials

The Same Question, Two Very Different Answers

To show you the contrast in practice, here's the same message in two contexts.

The message: "Can you review this email before I send it to clients?"

In a generic chat, no project:

Sure, paste the email and I'll review it. Do you want me to focus on tone, grammar, or structure?

Claude knows nothing about the context. It asks for clarification before starting. Reasonable, but slow. And next time it will ask the same thing.

In a project configured with the marketer profile's instructions from above, with the client brief uploaded as a file:

I've reviewed the email. The main message doesn't appear until the third paragraph—the reader should understand what you're offering in the first sentence.

The subject line "October Updates" won't generate much open rate. Something like "How [Company X] Cut Their Check-in Meetings in Half" connects better with the problem you describe in the body.

The tone is good, approachable without losing professionalism. One adjustment: the closing "we hope we can help" sounds passive. "Email us if you want to try it this week" is more direct and has a clear call to action.

The difference isn't that Claude is smarter in one case than the other. It's that it has the context it needs to give you specific feedback without you having to write it every time.

Knowledge Files: What to Upload

Files are useful when you have documents Claude would need to consult in many different conversations. Some concrete examples:

Your app's design document or a project's specifications
A client brief: their company, their products, their audience
Your own decision notes and things you've already ruled out
Documentation for an obscure library or tool that Claude usually gets wrong

What doesn't work as well: scanned PDFs (they're images, not text), documents with very complex tables, or files that change constantly. For information that changes, it's better to write it directly in the project instructions or update the file when it changes.

Before uploading a document, consider whether it contains sensitive client data or confidential company information that shouldn't leave your internal systems. Claude.ai is an external service, and what you upload there leaves your systems.

Claude doesn't read all files in every response. It reads the ones that are relevant to what you're asking at that moment. If you upload a client brief but ask something about code, it won't read the brief unless it's related.

The context window explains why: Claude can only process a certain amount of information at a time. Files are designed to be retrieved when needed, not all loaded together.

How to Organize Your Projects

A common mistake is creating one giant project for everything. The problem is that contexts mix and instructions become vague trying to cover everything.

An organization that works well: one project per coherent, stable context. Work at your current company, learning something specific, a particular client. The sign you need a new project is when you find yourself writing the same introductory context at the start of a chat over and over.

With the free plan you get up to five projects. For most use cases, that's more than enough if you define them well.

Common Mistakes

Instructions that try to cover everything

Three-page instructions that anticipate every possible situation. The result is Claude gets lost in the details and ends up ignoring parts. Better twenty well-chosen lines than two hundred that contradict each other.

Poorly prepared files

The filename matters: brief-client-acme-2024.md is easier to reference than document_final_v3.pdf. And format matters most: plain text and Markdown are read with much more accuracy than scanned PDFs or documents with complex tables.

A project that's too generic

A project called "General" with instructions like "be helpful and respond well" adds nothing over normal chat. A Project has value when the context it contains is specific and stable.

Files that never get updated

You upload a client brief in January and in April it's still there with data from the previous launch. Claude doesn't know that document is outdated: it responds with what it has. The same criteria you apply to instructions apply to files: when reality changes, the file needs to change.

Writing instructions once and forgetting them

Instructions aren't forever. A concrete example: I started a consulting project with instructions that mentioned a specific client as a tone reference. Three months later that client no longer existed and the instructions still pointed to them. Claude kept adjusting the tone to a context that no longer existed, and it took several weird conversations before I noticed the problem.

If you change roles, if you start with a new client, if you learn that Claude does something you don't want in that context, update the instructions. They're a living document.

Your First Project in Less Than 10 Minutes

Open claude.ai and click "+ New Project" in the left sidebar.
Give it a name that describes the context: "Work — [Your Company]" or "Learning [Technology]".
Enter the newly created project. At the top you'll see the project name and just below it the "Edit project" button: click it to open the custom instructions field.
Write your instructions using one of the examples above as a starting point. Don't try to make them perfect now.
If you have a relevant document (a brief, specifications, your notes), upload it from the "Project Knowledge" tab.
Create your first conversation inside the project and ask a real question you'd normally ask.

Instructions and files are already saved. The next conversation starts with that context loaded from the beginning.

Configuration Checklist

[ ] The project has a name that describes the context, not a generic one
[ ] Instructions include who you are and what context you work in
[ ] Instructions specify the response format you prefer
[ ] Instructions indicate what Claude shouldn't do in that context
[ ] If you uploaded files, they're in text format (not scanned PDFs)
[ ] You've done at least one test conversation to verify Claude uses the context

Frequently Asked Questions

How many projects can I have?

With the free plan, up to five. With paid plans you can create unlimited projects. For how to organize the ones you have, the organization section above has the logic that works.

What file types does Claude accept in projects?

Plain text (.txt), Markdown (.md), PDF, Word (.docx), spreadsheets (.csv), and code files (JavaScript, Python, TypeScript, among others). PDFs work well when they're digitized text. Scanned PDFs, which are really images, aren't read with the same accuracy. The free plan has a total file size limit per project; if you work with very large document corpora, that expanded capacity is only on paid plans.

Does a project's context affect my normal chats outside it?

No. A project's instructions, files, and history are only active inside that project. A new conversation you open outside any project starts from scratch with no access to any project's context.

How do I know if Claude is using the instructions I gave it properly?

Ask a question where the instructions should change the response. If in your instructions you asked "always give me a two-sentence summary first" and Claude doesn't do it, something needs adjusting, either in the instructions' wording or in length (too long and it might ignore parts). You can also ask directly: "What instructions do you have for this project?" and it will tell you what it has read.

With files the behavior is different. Claude only retrieves them when it considers them relevant to the specific question. If you upload a document and it seems like it's not using it, check two things: that the name is descriptive (client-acme-brief.md works better than v3_final.pdf) and that the format is text, not an image. Then ask the question by explicitly mentioning the document: "Based on the client brief I uploaded, what tone would be appropriate for this email?" That detail tells it exactly where to look.

If you've made it this far, you have everything you need to set up your first project today. Choose the context where you use Claude the most, write ten lines of instructions using the examples above as a starting point, and test it. You'll see the contrast with generic chat in the first response.

This article was originally published on AI Coding Patterns — visual, interactive courses to learn programming with AI. Explore the courses.