Guides
When to use a prompt, an agent, a workflow, a pipeline, a multi-agent system or an MCP tool, and how to write the spec for each. Every guide names the sources it was checked against.
20 guides so far. New ones are added as they are ready.
Which build type do I need
-
When a single AI prompt is enough, and when it isn't
How to tell whether your task needs one well written prompt or something that can call tools, react to results, repeat on a schedule and remember.
-
When to Use an AI Agent (and What the Spec Must Pin Down)
An agent is the right build when you cannot list the steps in advance, because the next action depends on what the last one returned.
-
When to Use a Workflow: The Flowchart Test for AI Builds
If you can draw the whole process as a flowchart with every branch labelled, you want a workflow, not an agent. Here is how to tell.
-
When to Use a Pipeline Spec Instead of a Workflow Spec
A pipeline moves a body of records through fixed transformations on a schedule, and its correctness question is completeness, not routing.
-
When a Multi Agent System Earns Its Cost, and When It Doesn't
Multi agent systems cost far more tokens than a single agent, so use one only for real specialisation, real parallelism, or a checker that catches misses.
-
When to Use an MCP Tool Instead of Building an Agent
An MCP tool does one job when asked. If your description contains a decision the model must make, or more than one job, you are describing an agent.
Own-the-vocabulary comparisons
-
AI Agent vs Workflow vs Pipeline: the real differences
Workflow, agent and pipeline are not interchangeable. The difference is what decides the next step: a branch you wrote, the model, or the schedule.
-
Context Engineering vs Prompt Engineering: what changed
Anthropic calls context engineering the natural progression of prompt engineering. Here is what that actually changes in your work.
-
Spec-Driven Development: why specs are replacing vibe coding
Karpathy named vibe coding in 2025. The tooling reaction since is uniform: write the intended behaviour down before the model writes code.
-
Claude Skills vs MCP Servers vs Subagents: the real difference
A Skill changes what the model knows how to do, an MCP server changes what it can reach, and a subagent changes whose context does the work.
Failure modes and guardrails
-
Why AI agents fail in production: the six failure modes
The six ways AI agents break in production, what each one looks like in a real incident, and the specific spec line that would have caught it.
-
Why AI agents drift: attention decay and context window limits
Why an agent that behaved for ten turns stops behaving at turn forty, and what the attention budget and context rot research actually measured.
-
Choosing agent complexity: why bigger is not safer
How to pick a complexity tier, an autonomy level and a memory type when the signals are ambiguous, and why rounding down beats rounding up.
-
Why every agent tool call needs a fallback, not just a happy path
A real tool fallback names the retry budget, what happens when it runs out, and which of four outcomes applies. Handle the error is not one.
MCP and the wider ecosystem
-
What is MCP (Model Context Protocol): a plain-English guide
A plain-English guide to the Model Context Protocol at revision 2026-07-28: what a server offers, what clients do, and what older guides get wrong.
Practical how-to
-
How to write a spec for an AI agent, before you prompt anything
A section by section walkthrough that turns one sentence about a support triage agent into a working agent spec, and what each part prevents.
-
Multi-agent shared state: when two agents write one field
Two agents write the same field and the last writer wins silently. The fix is a declared merge strategy per field, not more coordination.
-
Workflow vs Pipeline: Is There Even a Real Difference?
In common usage the terms are interchangeable, but a workflow and a pipeline fail in different ways, which is why they need different specs.
-
AI agent guardrails: what belongs in a real safety spec
Why a bare prohibition fails under a competing instruction, the four guardrail classes an agent spec needs, and when to require approval.
-
Why your AI coding agent needs a spec, not just a prompt
A prompt is consumed and gone. A spec persists, so intent can be reviewed, diffed and argued with before your coding agent writes a line of code.