What I Learned Building Multi-Agent Systems from Scratch

Most teams that adopt LLMs hit the same wall: they write one enormous system prompt containing every rule the task requires, the model loses the thread, and the output is mediocre. Paulo Arruda, a staff engineer at Shopify, spent a year discovering that the fix is architectural rather than linguistic. His thesis is that agents should be lean, narrow-focused experts rather than generalists, and that those experts should be composed under a single unified orchestration strategy running in one process. He is explicit about the failure mode he wants to avoid: what he names the agent microservices architecture, in which each team builds on its own framework and the agents end up talking to each other over the network via A2A or MCP, dragging back every distributed-systems problem microservices already have. The interesting engineering problems, on his account, show up not in the prompts but in orchestration, duplication across teams, and how you feed data into a context window. The talk is deliberately a story rather than a framework tour: a chronological account of experiments, including the ones that failed, with the generalisable lessons pulled out at the end.

These notes report what the speaker presented. Where I add background that was not in the talk, it is labelled as such.

What You Will Learn

• Why Anthropic's report that agentic search beat codebase indexing for Claude Code — together with Arruda's own abandoned dependency-graph experiment — changed the economics of pre-computed code indexes for him.
• How chaining one Claude Code instance to another through MCP produced capabilities neither instance had alone, and why that works.
• The concrete measured wins Shopify got from decomposing "one giant prompt" into many narrow agents, and the human-verification caveat attached to all of them.
• Why Arruda deliberately avoided an agent-to-agent network architecture and built a single-process orchestrator instead.
• The organisational failure modes — the "AI SWAT team" antipattern, duplicated internal tooling, and framework fragmentation — that show up once agent adoption spreads past the early adopters.
• Why MCP servers bloat context windows, and the experimental filesystem-adapter and memory-defragmentation techniques Arruda is prototyping in response.

Where Shopify Started

The backdrop is a company that got access to LLMs early and still had an adoption problem. Shopify signed a contract with OpenAI when GPT-3.5 shipped and built internal chat tools on top. By 2024 the tooling was broad: contracts with all the major model providers, LibreChat as an open-source chat interface where you could define agents and set system prompts, VS Code with Copilot, and Cursor, which was roughly a year old at that point. Despite that, Arruda reports a significant portion of engineers still were not using AI day to day. His explanation is mundane and worth taking seriously: people are busy and never got around to trying it, or they tried GPT-3.5 once, had a bad experience, and wrote the whole category off. Skepticism, not lack of licences, was the binding constraint.

What made the experimentation possible was culture rather than budget. Arruda credits Shopify's CEO, Tobi Lütke, for a genuine hacker culture in which curiosity is encouraged and rewarded and tooling is made available to play with — Lütke's own phrasing is that he wants Shopify to be "a crafter's paradise". The company runs hackdays, three-day blocks where engineers form teams and build whatever they want. Both of the pivotal experiments in this talk came out of hackdays, which is a structural point rather than a cultural platitude: the discovery that follows required a multi-day block of unstructured time and permission to fail.

Experiment 1: Indexing a Monolith, and Why It Failed

Arruda's starting problem, around October 2024, was not agents at all. It was the second-order consequence of AI adoption. If engineers use AI to generate code, you get pull requests with 1,500 changed lines. At first reviewers make a heroic effort. Over time, if the AI is right often enough, things start slipping through the cracks. His reasoning was that the durable defence against AI-generated slop is a stronger test suite, so the leverage point was automatic test generation.

The obstacle is that Shopify is a giant Rails monolith. To write a meaningful test for untested code, you have to understand what the code actually does, and Ruby and Rails carry a great deal of implied behaviour — conventions and metaprogramming that are not visible as explicit calls in the source. Arruda's hypothesis, which he describes as one of a million things he could have tried, was to build a dependency graph over the codebase. Concretely:

• Generate a GPT summary of every single source file and store each summary as a node in a graph.
• Derive edges from real code relationships: where a constant is declared versus where it is used, where a method is defined versus where it is called.
• Generate summaries of the relationships as well, not just the files, in order to surface the semantic connections that plain vector search over code was missing.

The comparison point was Cursor, which at the time indexed the codebase and searched over those indexes. Arruda's assessment is that it worked reasonably but still missed a lot of the semantic relationships between things. His graph approach did work — and was useless anyway. It was extremely expensive to build, and Shopify sees "hundreds and hundreds of PRs a day" opened against the monolith, so keeping the index hot would have been impractical. The failure mode here is a general one worth internalising: a derived artefact over a fast-moving codebase is only as good as your ability to keep it fresh, and summarisation with an LLM makes every refresh cost real money.

(Supplementary context, not from the talk: this is the standard staleness problem for any pre-computed index. It is the same reason search engines invest heavily in incremental crawl and invalidation rather than periodic full rebuilds.)

The Spark: Agentic Search Changes the Economics

At the end of February 2025, Anthropic released Claude Code as a research preview, and Arruda says it changed everything. The specific claim that mattered was Anthropic's public statement that they had tried indexing the codebase and found that agentic search performs better. Rather than pre-computing an index, the agent uses the same tools a human would — Grep, Read, Glob — and navigates the source at query time.

Arruda could verify this directly by using it. His assessment is that agentic search was about as good as Cursor's indexing while carrying none of the overhead, which meant it worked in any codebase immediately, with no build step, no index to maintain, and no per-repository setup cost. That is the trade-off in a sentence: agentic search pays a per-query cost in tokens and latency in exchange for zero staleness and zero onboarding cost, while indexing pays a large up-front and continuous maintenance cost for faster lookups. In a monolith taking hundreds of pull requests a day, the second bill never stops arriving.

The other inflection was organisational. In early April 2025, Lütke sent a company-wide email — which subsequently leaked to social media — pushing everyone at Shopify to get onto the AI train, including a line about needing to demonstrate that AI could not do a job before hiring for it. Arruda is careful here: he says the widely circulated articles distorted the intent, and that it did not mean the company stopped hiring people. His point is about the effect on experimentation. With roughly 6,000 employees, the email fuelled tinkering across the entire company, to the point where non-R&D staff now vibe-code prototypes routinely.

Experiment 2: The Failure That Produced the Discovery

In May 2025, at another hackday during Shopify's annual summit, Arruda returned to code understanding with a new hypothesis. Agentic search over files works well — what if you gave Claude Code tools to navigate the abstract syntax tree instead? An AST is the structured, parsed representation of source code, so navigating it is precise in a way that text search is not: you can ask for the definition of a method rather than for lines containing its name.

The plan was to build a Ruby gem exposing an MCP server that wrapped Prism, Ruby's parser, and presented an adapter layer making AST navigation look like the Read, Grep, and Glob tools Claude Code already knew how to use. The design insight is worth noting on its own: rather than teaching the model new tools, you keep the tool interface the model is trained on and change what sits behind it. That idea returns at the end of the talk in a much more ambitious form.

He wanted to vibe-code it, because he had three days and also wanted to actually socialise at the summit. The first attempt went badly. Claude did not know much about Prism, and Prism's documentation lacked examples, so the model could not produce working code. Arruda's fallback was to read the Prism codebase himself and then instruct Claude Code from that understanding — which, as he puts it, "felt very last year". Then he did something better: he cloned the Prism repository, started a separate Claude Code session inside it, asked that session how to do things with Prism, and copy-pasted the answers into the session building his library. That worked, and was laborious.

The obvious next step was to automate the copy-paste. He ran a Claude Code instance in non-interactive mode, exposed it through MCP, and connected it as a tool to the main instance working in his library repository. It one-shotted the task. The thing he wanted was not complicated, and a single Claude Code could not do it; two Claude Codes could.

The AST experiment itself was a failure. It was slow and no better than plain file search, so the hypothesis died. But the orchestration pattern that had been built as scaffolding was the actual result. Arruda's own account of why it mattered is simply that neither he nor a single Claude Code knew how to use Prism, but two Claude Codes did — and that a Claude Code sitting in a cloned library repository "knows how to use" that library, which makes the main instance much smarter.

(Supplementary context, not from the talk — this mechanism is my reading, not the speaker's: each instance is grounded in a different repository, so each can perform agentic search over a body of code the other cannot see, and the parent's context window is never filled with the raw source of the dependency. The parent asks a question; the child does the expensive searching in its own context and returns a short answer. Arruda does not spell this out, but it is consistent with his stated rationale for putting specialists in separate directories.)

Claude Swarm: Turning the Pattern Into a Tool

Arruda wrapped the pattern in a Ruby gem called Claude Swarm so other people at hackdays could try it quickly; it was also released publicly as a Ruby gem and picked up a following outside Shopify — InfoQ's speaker bio credits it with over 1,400 GitHub stars. The model it exposes is simple:

• Agents are declared in a YAML file, so setting up a swarm does not require writing orchestration code.
• Instances are arranged in a tree, like an org chart, with as many levels as you want. A parent delegates to children; children can have their own children.
• Each instance is pointed at a working directory. Instances can share a directory or occupy different ones.
• A vibe: true flag runs Claude Code with dangerously-skipped permissions.

The directory placement is the load-bearing design decision. Arruda's rationale is that Shopify's codebase is massive and one Claude Code instance can never understand the whole thing, but if you build little specialists that each live in one part of the codebase, the arrangement works better. The same trick applies outward: clone the libraries you depend on, put an instance in each, and the main agent effectively gains an expert on every dependency.

On vibe: true, Arruda is enthusiastic — "just let it go wild", and he says it is all he uses now. The security implications of that are discussed in the combined trade-offs section below.

Architecture And Data Flow

The Claude Swarm topology is a tree of processes, each with its own context window and working directory, communicating over MCP.

flowchart TB
    USER["Engineer"] --> MAIN
    subgraph SWARM["Claude Swarm - YAML-defined tree"]
        MAIN["Main Claude Code instance
working dir: your library repo"]
        C1["Child instance
working dir: Prism repo"]
        C2["Child instance
working dir: monolith subsystem A"]
        C3["Child instance
working dir: monolith subsystem B"]
        G1["Grandchild instance
deeper specialist"]
        MAIN -->|"MCP tool call: ask a question"| C1
        MAIN -->|"MCP tool call"| C2
        MAIN -->|"MCP tool call"| C3
        C2 -->|"MCP tool call"| G1
    end
    C1 -->|"agentic search: Grep / Read / Glob"| P["Prism source"]
    C2 --> M["Monolith source"]
    C3 --> M
    C1 -->|"answer back to parent"| MAIN

(The following reading of the diagram is my analysis, not something the speaker states: the expensive searching happens in the child's context window, and what crosses back to the parent is an answer rather than the raw source. On that reading, this is what keeps the parent's context small enough to stay coherent.)

The later SwarmSDK rearchitecture collapses this from many operating-system processes talking over a protocol into many agents running inside one process.

flowchart LR
    subgraph PROC["Single Ruby process"]
        ORCH["SwarmSDK orchestrator
fiber scheduler"]
        A1["Agent 1"]
        A2["Agent 2"]
        A3["Agent 3"]
        WF["Workflow definition
stages, deterministic steps"]
        HOOKS["Event hooks"]
        PLUG["Plugin system
e.g. memory plugin"]
        OBS["Observability
and cost tracking"]
        ORCH --> A1
        ORCH --> A2
        ORCH --> A3
        WF --> ORCH
        ORCH --> HOOKS
        ORCH --> PLUG
        ORCH --> OBS
    end
    A1 -->|"I/O-bound HTTP"| LLM["LLM providers
multi-provider"]
    A2 --> LLM
    A3 --> LLM
    A2 -->|"tool calls"| MCPT["MCP tools / internal systems"]

Because every event happens in one process, tracing, cost accounting, and hooks are local operations rather than distributed-systems problems.

What Happened When People Actually Used It

Adoption started on the engineering side. Arruda still uses Claude Swarm for everyday development. On the augmented engineering team, the original test-generation-at-scale project became a swarm: one Claude Code instance generated tests, then Gemini 2.5 Pro and o3-pro each critiqued them. The only justification Arruda gives is outcome-based — "that way, I get some better results". He does not explain the mechanism, so treat any story about complementary failure modes across model families as inference rather than as his claim. Others used it to answer questions about large codebases.

Arruda is candid that his implementation was hacky. Logs were hard to work with — he had to steal them out of a directory Claude Code created inside the home folder — and it "just wasn't good". In early June 2025 he reached out — the transcript says only "I reached out to them", and while the surrounding context about Claude Code makes Anthropic the natural reading, he never names the recipient — and suggested they build the pattern into their own tool, since they could do a better job. On 24 July 2025 (the transcript says "July 24", which reads as a date but is not stated unambiguously), Anthropic shipped sub-agents. Arruda reads that as validation that the model was right rather than as a competitive loss, which is the healthier interpretation for anyone building internal tooling in a fast market.

By early July, several teams were running significant initiatives on Claude Swarm. Separately, the test-generation use case is what forced multi-provider support, since Gemini and o3 had to verify Claude's work. In August, the non-R&D side of the company found it, and use cases multiplied.

The pattern behind every success story

Arruda kept seeing the same before-and-after. Teams start with one LLM in LibreChat driving a massive prompt containing every rule. The result is poor, and the mechanism is specific: too many unrelated tokens and too many instructions in one context window, so the model gets lost. The fix, in every case, was to split that prompt into multiple narrow-focused agents.

Further reported uses: product design, tracking language translations, building work breakdown structures, multi-dimensional research across many internal systems, and vendor evaluation. The vendor case is a nice illustration of what agent fan-out is genuinely good at — vendors make claims and back them with a large pile of PDFs and slide decks, so you point a set of agents at those documents to check whether the answers you were given are actually supported.

One caveat Arruda states plainly and which should travel with every number above: none of this is fully automated. Humans still verify everything. These are reported internal results from one company, not benchmarks — no baselines were held constant and no error rates were presented — and the elapsed-time savings describe producing a draft that a person then checks.

Where Claude Swarm Ran Out of Road

The limitations Arruda lists are as instructive as the successes:

• Too hard for non-developers. Writing a YAML file, opening a Claude Code instance, and typing commands is a non-starter for the finance or operations colleague who has the actual use case.
• Sometimes too hard for developers too. Several were not happy about "setting up YAML programming" as a prerequisite to composing agents.
• Multi-provider support was a hack. Accessing providers other than Anthropic meant injecting another library inside the framework, and the logging differed per provider — Arruda calls it a nightmare.
• People did not only want agent-to-agent delegation; they wanted workflows. This is the deepest of the four. Real tasks contain deterministic steps and distinct stages — a planning stage and an execution stage, for example. The tempting shortcut is to describe the workflow in the prompt and ask the model to follow it, and Arruda's assessment is blunt: at scale, it will fail to follow instructions. His answer in SwarmSDK is first-class workflow support alongside the tree formation.

The Organisational Problems Nobody Warns You About

By September 2025 Arruda's job had changed completely. Agent adoption had spread across the company, every team wanted his help, and he spent his days travelling and sitting in meetings. He names the pattern and rejects it: "That's the AI guy, just go talk to Paulo" is an antipattern. It does not scale, and it is also the wrong division of labour — his line is that he does not know how to build an agent for finance, but the finance team does. Every team has its own linchpins and AI enthusiasts who understand their own domain; the job is to empower them with tools, not to centralise agent-building in one person or one squad.

Alongside that, he observed two structural problems:

1. Duplication. Developers like building their own things, and across the company he found teams independently building the same systems — the same AI-in-CI pipelines, their own workflow systems, their own multi-agent systems.
2. Fragmentation. Teams that were not building their own were each picking a different framework — one team on LangChain, another on something else, out of the many available.

His response to duplication was deliberately low-tech: he reached out to everyone doing sponsored work on AI tooling — Shopify's internal term for projects that are funded and officially staffed, as opposed to side projects and hackday experiments — and got them onto a recurring call on the third Thursday of every month, still running, where they say what they are building so that others can reuse it rather than rebuild it. The framing he draws from this is a useful one for platform teams: encourage the experimentation, then use the learnings to build the right thing. The duplication is not waste if you harvest it; it becomes waste when nobody is looking across it.

Why He Rejected Agent-to-Agent Networking

The fragmentation problem is where the talk turns architectural. Arruda projects the trend forward: if things continue as they are, every team inside a company ends up with its own agents fronting its own products, workflows, and processes. The natural next thought is to compose those agents to answer higher-order questions that span teams.

If each team built on a different framework, the only way to compose them is over the network, using something like A2A or MCP as the wire protocol. Arruda calls the result the agent microservices architecture, and the point is that you inherit every problem microservices already have: network retries, observability challenges, distributed tracing. His reaction is to stop before getting there rather than to solve it afterwards.

The alternative is a unified orchestration strategy. If everyone in the company defines agents the same way, then in his words "we don't need MCP for them to talk to each other" — you import the definitions and run them in a single process. Note the scope: this removes the wire protocol between agents, not network I/O in general. Agents still make HTTP requests to model providers, and their tools are still typically MCP tools called over the network, so "no network" is never literal here. Arruda notes the design maps particularly well onto Ruby because of fibers: almost all LLM work is I/O-bound, consisting of a network request to a provider, a tool call which is often itself an MCP call over the network, and another request. Fiber scheduling lets a large number of those concurrent waits share one process cheaply.

(Supplementary context, not from the talk: fibers are lightweight cooperative coroutines. Because they yield on I/O rather than blocking an OS thread, they suit workloads that are almost entirely waiting on the network. The trade-off is that one process means one failure domain and one machine's worth of headroom, so this is a bet that orchestration coherence matters more than independent scaling — a reasonable bet when the actual compute lives in someone else's inference cluster.)

SwarmSDK

SwarmSDK is the result, and Arruda notes it is unrelated to OpenAI's Swarm despite the name — the lineage is his own Claude Swarm. It is a Ruby gem, and its feature set reads as a direct list of fixes for the Claude Swarm limitations:

The Three Lessons

Arruda's own summary is short:

1. The best solution started with his own pain. Claude Swarm exists because he was personally stuck on a real problem, not because he set out to build an agent framework.
2. Treat agents as lean, narrow-focused experts, not generalists. He is pointed about a specific habit: writing personas and bios for agents is, in his view, a waste of tokens for the small tasks that multi-agent orchestration is made of. The exception he allows is when you are using the persona to control the style of answer the model gives. Otherwise, the fewer tokens, the better.
3. Do not build an AI SWAT team; build the tools that empower everyone.

Looking Forward: Context Engineering and the MCP Problem

Arruda's forward-looking section is explicitly labelled as hypothesis rather than result. His framing: 2025 was the year of agents, and by the end of it many companies will have orchestration systems and a pile of agents, but it will still be unclear what to do with them. He expects 2026 to be the year agents become useful at scale, through context engineering. The question he keeps returning to is: how do we expose data to agents in a way that maximises precision and recall?

(Supplementary context, not from the talk: precision means the fraction of what you put in the context window that is actually relevant; recall means the fraction of the genuinely relevant material that made it in. Optimising one at the expense of the other is easy — dumping everything in maximises recall and destroys precision — which is why the pairing matters.)

That leads him to what he calls the elephant in the room: MCP causes context bloat. The way MCP is used today, you attach a set of servers to a client and each one loads its tools, along with their descriptions and their parameter descriptions, into the context window. Much of that is irrelevant to the task at hand. His example: if you attach a Gmail MCP server and all you are doing is reading an email, you are still paying for the tokens describing how to send one. His ideal is stated as a principle worth remembering — every single token in an agent's context window should be relevant and steering the result toward where you want it to go.

He acknowledges the current workarounds, naming Anthropic's work on skills and on tool-search tools, and gives his opinion on them directly: he feels that is just moving the problem to another layer.

The llm-fuse Hypothesis

Arruda is explicit that he does not know the answer, and offers the following as something to take back and think about rather than as a recommendation.

The observation it rests on is that frontier models are heavily trained on coding tasks, because if you solve coding you solve most problems, so there is enormous commercial pressure in that direction. Being good at coding requires two distinct competencies: writing code, which comes from having seen many examples, and discovering code, which is the agentic search capability discussed earlier. The second one is the interesting one, because it is a general-purpose information-retrieval skill that happens to have been trained on filesystems.

The hypothesis: build an adapter layer that presents arbitrary data sources through the tool interface models are already extremely good at. He calls it llm-fuse, by analogy with FUSE, which lets you expose things as a filesystem — but he is clear you do not actually need to mount anything. If you control the tools, you can translate them to whatever storage sits behind:

• Read, Grep, Glob — the familiar navigation primitives.
• Search — vector search plus keyword search with good ranking.
• Write, Edit, Delete — mutation.
• Defrag — discussed below.

He has a prototype working internally where the data lives in a Postgres database behind such an adapter: the agents believe they are reading files, and they are actually querying the database. His analogy is the scene in The Matrix where Trinity asks over the phone to learn how to fly a helicopter and the skill is uploaded on demand — the transcript renders the name as "Neil", which appears to be a transcription artefact. The point of the analogy is that knowledge gets injected into the agent at the moment it is needed, and the only work required per data source is writing its adapter.

Memory and Defragmentation

The Defrag tool exists because agents in this design also write memories. They learn from interacting with you, and you can dispatch one on a task — give it a web search tool and tell it to go learn everything about X, let it also consult internal systems, and have it store what it finds. Over time that memory becomes fragmented, which is where the deliberately retro name comes from. Defrag walks the whole memory store, merges similar memories, and keeps it tidy, explicitly optimising for read.

Each memory carries metadata: a title, tags, a source indicating whether it came from a user, a hit count, and links to other related memories. The retrieval flow is designed so that the model, not the retrieval system, makes the final relevance decision:

sequenceDiagram
    participant U as User
    participant O as Orchestrator
    participant M as Memory store
    participant L as LLM
    U->>O: prompt
    O->>M: keyword search plus combined techniques
    M-->>O: candidate memories with path, title, tags
    O->>L: prompt plus appended system reminder
"these may or may not be related"
    L-->>O: decide whether to read a memory
    opt LLM chooses to read
        O->>M: read memory by path
        M-->>L: memory content plus reminder of related memories
        L-->>O: optionally request related memories
    end
    L-->>U: answer

Before the request goes to the model, the orchestrator appends a system reminder to the bottom of the prompt saying that these memories may or may not be related to the query, along with each memory's file path and title. The model then decides whether to read any of them. When it does read one, it receives another reminder listing the memories marked as related to that one, and again decides whether to follow the link. Arruda reports very good early results from this technique while stressing that it is experimental.

(My reading, not the speaker's: cheap, low-token pointers go into every prompt, and expensive full content is only pulled in when the model judges it relevant. That is precision and recall being traded deliberately rather than by accident, and it echoes the Claude Swarm child instance — keep the expensive material out of the main context window until something decides it is needed.)

Trade-offs And Practical Takeaways

The talk is an experience report, so it is worth separating what it demonstrates from what an engineer should do with it. (The caveats below are my reading except where attributed to Arruda; the numbered actions are my distillation of his advice.)

Every number is a reported internal result. The theme-review, candidate- assessment, and 15-instance research figures in the table above are Arruda's account of Shopify's experience with checklist-shaped and research-shaped tasks. There are no benchmarks, no baselines held constant, and no error rates.

Fan-out costs tokens and money. Splitting one prompt into fifteen agents means fifteen context windows, each with its own system prompt and tool descriptions, plus the orchestrator's. The talk emphasises quality gains and time savings and does not discuss the cost multiplier. The same applies to cross-model critique: running Gemini 2.5 Pro and o3-pro over Claude's output multiplies the inference bill for that stage.

vibe: true is a real security decision. Dangerously-skipped permissions mean the agent can run arbitrary shell commands, delete files, and make network calls without confirmation. That is defensible inside a disposable container or a throwaway clone, and much less so on a workstation holding production credentials; combined with untrusted input in the context window it is also the standard setup for turning prompt injection into code execution. Arruda endorses the flag enthusiastically for his own work, and the talk does not cover sandboxing, credential scoping, or injection.

A single-process orchestrator trades isolation for coherence. Running every agent in one Ruby process is what makes unified observability, cost tracking, and event hooks easy. It also means one crash takes everything down, one machine bounds concurrency, and teams cannot deploy or scale agents independently — the thing microservices were invented to provide. The bet also rests on everyone in the company defining agents the same way, which is an organisational commitment as much as a technical one, and the fragmentation Arruda observed shows how strong the pull in the other direction is.

Both directions on workflows have a cost. His warning that models will not reliably follow workflow instructions embedded in a prompt argues for encoding deterministic steps. The counter-pressure he does not raise is that hard-coding a sequence gives up the adaptivity that made agents attractive; SwarmSDK supports both formations, so the engineer still decides where the boundary sits.

The negative and experimental results should stay labelled as such. The AST prototype was slower and no better than file search — one prototype, on Ruby, over three days, so a data point rather than proof that structured code navigation is a dead end. llm-fuse, Defrag, and the memory retrieval scheme are presented by Arruda as a hypothesis he is not sure will work, backed by an internal Postgres prototype and "very good early results". His criticism of skills and tool-search tools as "moving the problem to another layer" is his stated opinion, offered without a head-to-head comparison.

With that framing, the actionable parts:

1. Split the giant prompt before you tune it. If a task has a checklist, stages, or independent criteria, give each one its own agent with only the instructions it needs. Every success story at Shopify started there.
2. Give each agent a working directory, not just a role. Grounding is what makes nested Claude Code instances powerful — an agent living in a dependency's repository can answer questions no amount of prompt text would convey. Clone your key dependencies and put a specialist in each, and keep the expensive exploration in the child rather than the parent.
3. Prefer agentic search over building an index in fast-moving codebases. An index over a repository taking hundreds of PRs a day is a perpetual freshness liability. Reach for pre-computation only when query latency dominates.
4. Drop personas and bios from task-oriented agents. Unless you are shaping the tone of a user-facing answer, they are tokens that do not steer the result.
5. Encode deterministic control flow rather than describing it in a prompt. If a step must happen, or must happen after another, make it a workflow; models will not reliably follow prose sequencing at scale.
6. Consider a second and third model as critics, as Shopify's test-generation pipeline did, and budget for the extra inference.
7. Audit what each attached MCP server costs you in tokens. Attach only what an agent needs and prefer narrow servers. The Gmail read-versus-send example generalises to almost every integration.
8. Do not become the AI SWAT team, and create a forum before a standard. Build tooling for each team's own enthusiasts; a monthly call surfaced duplication no architecture document would have caught.
9. Choose in-process orchestration or agent-to-agent networking deliberately. Letting every team pick its own framework chooses the networked option by default, along with retries, tracing, and observability work.
10. Keep your failed experiments in view. The AST prototype failed and its scaffolding became the most valuable thing Arruda shipped that year.

Key Terms

• Agentic search — Having a model explore a codebase or corpus at query time using ordinary tools such as Grep, Read, and Glob, rather than searching a pre-computed index. Anthropic reported it outperforming indexing for Claude Code.
• AST (abstract syntax tree) — The parsed, structured representation of source code. Navigating it is precise about definitions and references in a way that text search is not.
• MCP (Model Context Protocol) — A protocol for exposing tools and data sources to LLM clients. In Claude Swarm it is also the transport by which a parent agent calls a child agent.
• Claude Swarm — Arruda's Ruby gem for defining a tree of Claude Code instances in YAML, each in its own working directory, connected over MCP.
• SwarmSDK — Its successor: a Ruby gem with multi-provider support, YAML or Ruby DSL definitions, workflows alongside tree formations, event hooks, built-in observability and cost tracking, and a plugin system, all in a single process.
• Context bloat — The accumulation of irrelevant tokens in a context window, in this talk caused primarily by attached MCP servers loading tool and parameter descriptions that the current task does not need.
• Context engineering — Deliberately controlling what enters a model's context window in order to maximise the relevance of every token.
• llm-fuse — Arruda's experimental adapter layer that presents any data source through the file-oriented tools models are heavily trained on, so an agent "reading files" may actually be querying Postgres.
• Defrag — An experimental tool that walks an agent's accumulated memories, merges similar ones, and reorganises the store to optimise for reading.
• Vibe coding — Building software primarily by prompting a model rather than writing the code yourself; vibe: true in Claude Swarm runs Claude Code with permission prompts skipped.
• AI SWAT team antipattern — Centralising agent-building expertise in one person or squad that every team must queue for, instead of equipping each team's own practitioners.

Arruda's closing framing is that 2025 was the year everyone built agents and 2026 is the year they have to become useful at scale, which he believes is a context engineering problem rather than an orchestration one. What makes the talk useful is that the orchestration lessons and the context lessons turn out to be the same lesson at two scales: keep each unit narrow, keep irrelevant material out of its context, and let the thing that needs the information decide when to pull it in.

Reference: Paulo Arruda, What I Learned Building Multi-Agent Systems from Scratch, QCon AI New York 2025, published by InfoQ. Presentation length 35:28; notes based on the full published transcript.