Thinking like an architect

Picture two teams building the same thing: an assistant that answers billing questions. Same model, same week, same goal. The first team’s demo is dazzling and dies in month two, buried under weird edge cases nobody can trace. The second team’s demo is plain, and two years later it is still quietly answering billing questions every day.

The difference was never the prompt. Both teams wrote good prompts. The difference was a set of decisions the second team made before writing anything: what the model gets to decide, what the code decides for it, and what waits for a human. Those decisions have a name. They are called architecture.

This lesson is about that layer: the judgment above the code. There is no code in this lesson at all, on purpose. If you can follow an argument about who should decide what, you can follow everything here. The code starts in lesson 2.

Where you are on the ladder

If you finished the Building with Claude track, you have already made single calls, defined tools, and run an agent loop. If you read the AI Agent Teams track, you have watched a real team of agents argue, decide, and check each other. You are in exactly the right place: this track is about the decisions in between, the ones that turn parts you understand into a system you would trust.

And if you arrived here without those tracks, you can still read this lesson. It asks for no code. It asks only that you care about a question every professional already knows: who should be allowed to decide what?

Every agentic system is four parts

Strip away the vendor names and the diagrams, and every agentic system you will ever build or buy is the same four parts.

A model. The thing that reads, reasons, and writes. It is capable and it is fallible, in the same breath.
Tools. The hands. Functions the model can call to look something up, change something, or ask another system for help.
A loop. The heartbeat. The model acts, sees the result, and decides what to do next, over and over, until the work is done.
A context window. The desk. Everything the model currently knows about the job sits on it, and the desk has edges.

That is the whole parts list. You met each part in the earlier tracks. What is left, and what this track teaches, is arrangement: how the parts are wired, and above all, where the decisions live. Architecture is deciding where judgment lives. Hold onto that sentence. Every lesson in this track is a variation on it.

The first decision: does this need an agent at all?

Here is the most senior thing you can learn to say in this field: “this does not need an agent.”

Anthropic’s engineering team, writing from a year of building alongside dozens of teams, draws a line worth memorizing. In their words, workflows are “systems where LLMs and tools are orchestrated through predefined code paths,” while agents are “systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks.” A workflow follows a route you drew in advance. An agent chooses its own route as it goes.

The same essay states the principle that should sit above every design you make: “Success in the LLM space isn’t about building the most sophisticated system. It’s about building the right system for your needs.”

That ordering matters. An agent that chooses its own route is more flexible, and it is also harder to predict, harder to test, and more expensive per run. A fixed route is rigid, and it is also repeatable, debuggable, and cheap. So the architect’s first question is never “how do I build the agent.” It is “is the path through this work predictable?” If you can draw the steps on a whiteboard and they hold for almost every case, draw them in code and let the model do focused work inside each step. Reach for a true agent when the path genuinely cannot be known in advance, when the number of steps depends on what the work uncovers.

The Building with Claude track walked through six named shapes this thinking produces, from prompt chaining to the autonomous agent. This track will not re-teach them. What it adds is the judgment for choosing among them when a real system, with real stakes, is on the table.

Three trade-offs you will make over and over

Watch any experienced builder design an agentic system and you will see the same three questions return, in every project, at every scale. This track is organized around them.

One: what does the model decide, and what does the code guarantee?

Suppose a rule matters: nothing gets published to the company’s public account without a human sign-off. You can tell the model this in its instructions, clearly and firmly. It will comply almost every time. “Almost” is the entire problem. An instruction is a request; code is a guarantee. When a rule must hold every single time, it belongs in the structure around the model, a check the flow cannot skip, not in the prompt. When a behavior benefits from judgment and tolerates variation, that is exactly what the model is for. Learning to sort rules into those two piles, must-hold versus should-usually, is the single most practical skill in this track.

Two: one agent, or a team?

The AI Agent Teams track showed you why a team of narrow specialists can beat one overloaded generalist: focus, deliberate opposition, replaceability. But a team is not free. Every seam between agents is a place where context gets lost, work gets duplicated, and failures hide. One capable agent with good tools is simpler to run, cheaper to debug, and very often enough. The architect’s discipline is to start with one, and split only when the work itself splits: when the pieces are genuinely different jobs, or too big for one desk.

Three: what sits on the desk, and what gets fetched?

The context window is finite, and everything on it competes for the model’s attention. Pile the whole company wiki onto the desk and the model gets worse, not better, at finding what matters. The architect decides what the model carries at all times, what it fetches when needed, and what gets written down outside the window so it survives. You have felt this trade-off already if you have ever watched a long chat slowly lose the plot. In this track you will learn to design for it deliberately.

Three questions. Decide-versus-enforce, one-versus-many, carry-versus-fetch. Different projects weigh them differently, and that is the point: they are trade-offs, not rules. The judgment is knowing what you are trading away.

The road through this track

Each lesson ahead takes one slice of the architect’s job and makes it concrete.

Lesson 2 turns configuration into a team asset: how Claude Code is set up so that standards live with the project, not in one person’s head. Lesson 3 is structured output: schemas that make a model’s answers honest about what it does not know. Lesson 4 is tool design: descriptions, boundaries, and errors that let an agent use your tools the way you meant. Lesson 5 is orchestration: teams of agents that survive contact with real failures. Lesson 6 is reliability: escalation, review, and the places a human hand belongs. Lesson 7 puts agents in the pipeline, working without anyone at the keyboard. And lesson 8 is the capstone: you design and build a small system, and defend the trade-offs you chose.

By the end, the goal is not that you memorized patterns. It is that when someone says “let’s just add an agent,” you know the next five questions to ask.

Why this matters when you use AI

You will evaluate these systems even if you never build one. Agentic products are arriving in every profession, and the sales pitch never mentions the trade-offs. Knowing the three questions lets you probe a vendor’s design the way an inspector probes a house: where does judgment live, what is guaranteed versus requested, what happens when a step fails?
The judgment transfers even as the tools churn. Model names, SDKs, and interfaces will change under your feet. Decide-versus-enforce, one-versus-many, carry-versus-fetch will not. They are older than AI; they are how organizations have always been designed. That is why this lesson opened with them instead of with code.
“It worked in the demo” stops surprising you. Once you see that a demo exercises the model and a product exercises the architecture, the pattern of dazzling demos and quiet failures stops being mysterious. You start asking demo-proof questions early, which is precisely when they are cheap to answer.

Common pitfalls

Reaching for an agent because agents are impressive. The costliest habit in the field right now. If the path through the work is predictable, a drawn route with the model working inside each step is faster, cheaper, and easier to trust. Sophistication is not the goal; fit is.

Putting guarantees in the prompt. “The model almost always follows the instruction” is a fine property for tone and judgment, and a terrible property for a compliance rule. If breaking the rule once is unacceptable, the rule cannot live only in words the model might weigh against something else.

Confusing more context with more knowledge. Giving the model everything you have feels generous and works against you. Attention is a budget. The skill is curation, not volume.

Treating the team as the advanced option. More agents is not the mark of a serious system. Some of the most reliable production systems are one well-configured agent with five good tools. The mark of a serious system is that every seam in it exists for a reason someone can state.

What you should remember

Every agentic system is four parts: a model, tools, a loop, and a context window. Architecture is how they are arranged, and above all, where judgment lives.
Workflows follow a predefined path; agents choose their own. Prefer the simplest arrangement that fits, and escalate to an agent only when the path cannot be known in advance.
The three recurring trade-offs: what the model decides versus what code guarantees; one agent versus a team; what stays in context versus what gets fetched.
Instructions are requests. Code is a guarantee. Rules that must always hold live in structure, not prompts.
A demo exercises the model. A product exercises the architecture.

What’s next

Lesson 2 opens the toolbox where an architect’s decisions become durable: Claude Code’s configuration layer, where a team’s standards, rules, and workflows live with the project instead of in anyone’s memory. That is where this track starts reading real configuration, line by line.

If you remember one thing

A prompt is what you ask of a model.
Architecture is what you decide around it.
This track teaches the deciding.