Opening

Picture your first week on a new team. You inherited an assistant that answers customers on WhatsApp, looks up orders, and sometimes calls a person.

It works. But every prompt change is scary, the provider bill went up, and nobody can explain why the bot said something absurd yesterday.

You open the code. The first thing you see is a system prompt with forty paragraphs.

Then a loop that keeps calling the model until it decides it's done, with no counter.

And no tests. You can tell something is off. The hard part is saying what, deciding what comes first, and fixing it without breaking everything else.

You don't need another tutorial on how to call an API. You need words for what's wrong, and a safe path to fix it. That's what this catalog is for, and in this lesson you'll learn how to use it.

The idea

The catalog organizes the engineering of language model systems into five pillars. Each one answers a different question.

Fundamentals answer: what do I need to know before designing anything? Tokens, cost, how the model picks words.

Smells answer: what's wrong with my system? That giant prompt has a name. It's called prompt bloat.

Refactorings answer: how do I fix it without breaking it?

Patterns answer: what's the right shape for this kind of problem? And the fifth pillar, real-world scenarios, shows all of that inside a complete system.

How it works

The pillars are not separate boxes. They form a path, and you'll walk it again and again.

It starts with a smell. A smell is a sign that something will hurt later. The system works today, but it's getting expensive, fragile, or unsafe.

The smell points to a refactoring. A refactoring changes the structure without changing what users get. And every refactoring starts and ends with an eval, a test for what the model produces.

The refactoring leads to a design pattern, the proven way to solve that kind of problem.

And the pattern shows up in real-world scenarios. Each scenario starts with a naive first version. That first version has the smells from step one, and the cycle starts again.

A real case

Let's go back to the assistant you inherited and follow that path with its two most visible problems.

First, the loop with no counter. One single run cost dozens of times more than a normal one. That smell is called unbounded loop.

The fix is a refactoring called add loop budget: a limit on steps, tokens and time.

And where you land is a pattern called stop conditions, where the agent knows exactly when it has to stop.

Second, the forty paragraph prompt, where every bug that got fixed became one more paragraph. That's what we call prompt bloat.

The refactoring pulls one job out into its own smaller prompt. It's called extract subprompt.

And the target is prompt chaining: a few short steps, each one easy to test.

Now notice the order. You don't jump from the symptom straight to rewriting everything with the right pattern. The refactoring is the small, measured path between what exists today and the final shape. Measure first, change the structure, then measure again.

A challenge

Here's one for you. A teammate applied extract subprompt to the ticket classifier, and tells you it got much better. Based on what you just heard, what's missing before you accept that change?

What's missing is the eval, run before and after, with the numbers side by side. Without the before number, better is just an impression. And a drop in some other category would go completely unnoticed.

Switching to a bigger model wouldn't answer the question either. It mixes two changes and makes everything more expensive. The guarantee that nothing got worse comes from measuring.

A smell is not a bug

The word smell comes from classic code refactoring. And there's a difference worth holding on to. A bug breaks today. A smell works today and charges you later.

It charges on the bill.

In the time your team spends maintaining it.

And sometimes in a security incident.

That's why every smell in the catalog has a section called when to ignore. A big prompt in a prototype with ten users may be fine. The same prompt in a support channel with thousands of conversations a day is money leaving every month.

The catalog gives you the diagnosis. The decision of when to fix stays with you.

And the most common beginner mistake is the opposite one: reading the list of smells and trying to fix all of them at once. Start with what hurts most. Usually, that's what shows up on the bill, or in this week's incident.

Finding your way

Every page in a pillar has the same sections in the same order. Learn the format once and you'll find anything without hunting. And the numbers in the diagrams match the comments in the code. If step three in the diagram is classify, the code also says step three, classify. When you get lost in the code, go back to the diagram by number.

Along the way you'll find short questions. Every option has an explanation, including the wrong ones, because the most useful mistake is the one you understand.

And if you came from a search, reading out of order is fine. Every page ends with a read next, pointing to the most useful step from there. If you want an order, follow the trails. They form one course: foundations, evals, RAG and context, agents, security, and production.

Try it

Now pick a system you know and answer four questions. Write the answers down, even if the answer is I don't know.

One. How many tokens is the system prompt today? If the answer is several thousand, or no idea, read prompt bloat.

Two. If someone changes one line of the prompt, how do you know nothing got worse? If the answer is we try a few questions by hand, read untested prompt.

Three. If the model does something wrong in production, where do you look? If you can't tell, read no tracing.

Four. What was the most expensive run this month, and how much did it cost? If nobody tracks that, read no cost budget.

Most teams answer at least two of these badly. That's normal, and it's a good place to start. You just built your priority list, with names the rest of your team can look up.

Wrap-up

That's the real value of a shared vocabulary. Saying this agent has tool sprawl tells your team more than saying the agent gets confused sometimes. The name carries the diagnosis, the tested fix, and the shape you're aiming for.

In the next lesson, we start with the model itself: four properties every engineer needs to know, and that almost every pattern here tries to control. See you there.