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.
30 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.
-
Prompt vs Agent: How to Tell Them Apart
A prompt is an instruction and an agent is a loop that runs one against changing observations, which is why a chat window with tools looks like an agent.
-
Context Engineering vs Prompt Engineering: Not a Rebrand
Context engineering is not a replacement for prompt engineering, or a rebrand. Anthropic's definition, the attention budget, and independent evidence.
-
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.
-
Chatbot vs AI Agent vs Workflow: which does your business need
Chatbots answer, workflows complete a defined process, agents pursue an outcome they plan themselves. How to tell which one your business needs.
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.
-
Prompt injection, explained: what actually stops it
Where the term prompt injection came from, why models cannot separate instructions from data, and why filtering and warning prompts fail.
-
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.
-
Common prompt engineering mistakes and how to fix them
The prompt mistakes that cost the most time, with a fix for each, plus the over-specifying trap and two techniques Anthropic's docs demoted or removed.
-
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? A Plain-English Guide to the 2026 Spec
MCP in plain English at spec revision 2026-07-28: the three primitives, stdio vs Streamable HTTP, and what older tutorials get wrong.
-
MCP vs traditional API integration: what actually changes
Why MCP does not replace your API: it changes who writes the integration glue, and leaves auth, rate limits and error semantics with you.
-
n8n vs Zapier vs Make vs a Custom AI Agent
No-code platforms cover most known trigger-and-steps work. Here is the line where a specified custom component actually earns its place.
-
How to write an MCP tool spec Claude can actually run safely
The eight sections that belong in an MCP tool spec, and why the tool description is a prompt the model reads at decision time, not documentation.
-
Local vs remote MCP servers: which should you build
How to choose between a stdio local server and a Streamable HTTP remote one, what the 2026-07-28 spec changed, and the migration trap.
-
When should you build a Claude Skill instead of an MCP server
A Skill is a file and a description; an MCP server is software you run, secure and keep alive. Here is the test for choosing between them.
Practical how-to
-
How to write a system prompt that actually works in practice
The four parts every working system prompt has, why the right altitude beats a step list, and a before and after on one concrete task.
-
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.
-
AI Workflow vs Pipeline: Is There a Real Difference?
In AI systems the two terms are used interchangeably, 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.