DEV Community: theducttape.io

Ten more things that go wrong when you build with a team of AI agents (part 2)

theducttape.io — Mon, 12 Oct 2026 01:45:32 +0000

Part 1 covered the first ten: symptom fixes, hidden sharing, lost messages, "done" without proof, blurry approvals, shared workspaces, fading context, overlapping ownership, plausible inventions and environments that drift. Both posts come from running a small team of agents on one product, which I described in How I build a product alone with a team of seven Claude Code agents.

These ten are quieter. They do not break the build; they waste a day, put the wrong decision on record, or turn up as a bill. Same format: what it looks like, why it happens, what helps.

11. Agents compete for the same machine

What it looks like: a server one agent is using gets restarted by another. Two heavy jobs run at once and both time out. A test fails because another agent's test changed the same account.

Why it happens: every agent assumes the machine is its own. Commands like "stop the server" or "reset the test data" are written for one person at one desk.

What helps: give each agent its own ports, its own test accounts and its own data where it can. Schedule the heavy work: builds, full test runs, recordings. Agents stop only processes they started, never by a broad pattern. And announce shared work: "the test server is busy for the next 40 minutes".

12. Agents put words in your mouth

What it looks like: "As you said, we will …" about something you never said. A decision appears in a document with your name on it, but it came from another agent's suggestion.

Why it happens: in a chain of messages, the origin of an idea gets lost. An agent that hears "this was decided" from another agent fills in the most likely decider: you.

What helps: log every decision with who actually made it, and when. When an agent cites you, ask for the message it comes from. Agents should write "I suggest" and "the product owner decided" in their own words, not "the human wants".

13. Time is harder than it looks

What it looks like: a test fails every night around midnight. A message says "tomorrow" and two agents read different days. A deadline in a document is an hour off.

Why it happens: servers run on UTC, people do not. Agents know neither the human's time zone nor which "today" a sentence meant, and many tests quietly use the current date.

What helps: write absolute dates, with the time zone, in everything that matters. Report times in the human's local time. Give tests fixed dates instead of "now", and run them once near midnight on purpose.

In our case, the rule became simple: the server runs on UTC, every time reported to a human is local time.

14. Agents stall silently

What it looks like: an agent has been "working" for hours. In fact it asked a question at the end of a long output and is waiting for an answer nobody saw.

Why it happens: asking and stopping is the safe default. But a question buried in the middle of a long report is easy to miss, and the agent cannot tell that nobody read it.

What helps: ask and keep going: let the agent do everything that does not depend on the answer, and make the question the first line, not the last. Collect open questions in one place the human checks. A short status line ("waiting for: X, since: 14:20") makes a stall visible.

15. The human becomes the bottleneck

What it looks like: twenty small questions a day: which word, which colour, retry or not. Each takes a minute; together they take the day, and every agent waits for you.

Why it happens: agents are told to ask when unsure, and they are unsure about many small things. Without a rule for what is small, everything goes to the top.

What helps: let one coordinating agent take the small, reversible decisions and log them, so you can read them later and overrule one if needed. Write down what counts as small. Big or irreversible questions still come to you: anything public, money, deleting production data, secrets.

16. The written rules contradict each other

What it looks like: two documents give two answers to the same question. The rules file still describes how things worked last month. An agent follows an outdated rule perfectly.

Why it happens: rules get added, rarely removed. Each new rule is written with the current task in mind, not with all the older rules next to it. Agents read rules literally and cannot tell which one is stale.

What helps: one role that checks every new rule against the existing ones before anything is built on it. Update the rules in the same change that alters the behaviour they describe, not later. When two rules disagree, the agent asks instead of picking one.

17. Agents propose more than you need

What it looks like: every finished task comes back with five ideas for what to do next. Each one is reasonable. Together they turn a two-day feature into a two-week one.

Why it happens: agents are good at seeing what could be better and eager to be useful. They do not know which of their ideas serve the goal of this month.

What helps: a proposal is not a task. Keep a "not now" list and tie it to the current strategy: if an idea does not serve the goal, it goes on the list, with no guilt. Review the list now and then; most of it can stay there.

18. Secrets end up in the chat

What it looks like: an agent needs a key to continue, and the fastest way is to paste it into the conversation. Now it lives in the transcript, maybe in logs, maybe in a summary.

Why it happens: the work is blocked, the key is at hand, and the chat is right there. Nobody plans it; it happens in a hurry.

What helps: prepare a safe path before it is needed: the human writes the key into a local, ignored file, and the agent reads it from there without ever printing it. Agents should refuse to echo keys and ask for that path instead. A key that went through a chat counts as exposed: rotate it.

19. Quotas and costs surprise you

What it looks like: in the middle of the month a limit hits: build minutes, an API quota, storage, a plan limit. Work stops, or a bill arrives that nobody expected.

Why it happens: agents work much faster than people and repeat things without hesitation: one more build, one more full test run. Nobody adds it up until the limit does.

What helps: know your limits before you scale up. Measure what one run costs, set budgets and alerts, and put expensive actions behind a check. Spending money stays a human decision.

20. One change ripples through everything connected

What it looks like: a repository moves, a key is rotated or a domain changes, and three other things break: a pipeline, an integration, a link in a document, a rule an agent still follows.

Why it happens: connections pile up quietly. Each one was set up once, by someone, for a reason nobody wrote down. The agent making the change sees only the change.

What helps: before any infrastructure change, list what is connected to it, make a backup, change one thing at a time, and check each item afterwards. Keep that list in a document, so the next change starts from it.

The checklist

Does every agent have its own ports, accounts and test data?
Is every decision logged with who actually made it?
Are dates absolute, with a time zone?
Does a waiting agent say so, first line, and keep working on the rest?
Is it written down which decisions agents may take themselves?
Are new rules checked against old ones, and updated with each change?
Do proposals go to a "not now" list unless they serve the current goal?
Is there a safe path for secrets, and are leaked ones rotated?
Do we measure what a run costs, with a budget?
Does every infrastructure change come with a map, a backup and a checklist?

Taken together with part 1, the pattern is the same: agents are fast, capable and literal. Most problems come from what they cannot see, such as other agents, the clock, the human's attention and the connections around a change. Most fixes make that visible and write it down.

The agent team behind these posts builds DuctTape.io, a diagram editor for AI architectures.

Ten things that go wrong when you build with a team of AI agents (part 1)

theducttape.io — Sun, 11 Oct 2026 01:30:16 +0000

Recently I wrote about how I build a product alone with a team of seven Claude Code agents. One piece of feedback on it stuck with me: the parts where the agents went wrong are usually the most useful for other builders.

So this post, and part 2, are only about those parts. Not our specific bugs, but the patterns behind them. If you run more than one agent on the same project, you will meet most of these, whatever model or tool you use. For each one: what it looks like, why it happens, and what helps.

1. Agents fix the symptom, not the cause

What it looks like: the same kind of failure comes back after every fix. Each fix is reasonable on its own: a retry here, a longer timeout there.

Why it happens: an agent sees the error in front of it, not the system around it. Its job, as it understands it, is to make this failure go away. It rarely asks whether the environment it runs in is the problem.

What helps: after the second fix for the same kind of failure, stop and look one level down. Machine, memory, network, data, versions. Ask the agent explicitly: "What would have to be true about the environment for this to keep happening?"

In our case, random test failures turned out to be a machine that ran out of memory. No code change would have fixed that.

2. Scaling up exposes what was shared all along

What it looks like: you add a second worker, a second agent or a faster machine, and things that always worked start to fail.

Why it happens: slowness hides coupling. Two tasks that use the same account, file, port or record never collided because they never ran at the same time. More power makes them meet.

What helps: before you scale, list what is shared: test accounts, folders, ports, databases, rate limits. Give each parallel task its own, or make the sharing explicit. And treat the new failures as a gift: they were bugs before, just invisible.

In our case, running tests in parallel showed that two of them had been sharing one account the whole time.

3. "Sent" is not "read"

What it looks like: an agent hands work to another one, then waits. The other agent never saw the message, or saw it and moved on. Work stalls, and nobody notices for hours.

Why it happens: messages between agents fail in boring ways: a send error, a receiver that is busy or restarted, a message dropped as a duplicate. The sender treats "I sent it" as "it is handled".

What helps: every handover that matters gets a short acknowledgement back. Decisions go into a shared document, not only into a message. And a sender who hears nothing follows up instead of assuming.

4. "Done" without proof

What it looks like: an agent reports a task as finished. It is not, or only partly.

Why it happens: reporting success is the most likely end of a task, so it is the most likely thing an agent writes. Checking the result is an extra step it skips when nothing forces it.

What helps: define done as evidence. A test run, a screenshot, a link that opens, a measured number. Better still, let a different agent check the result, one whose job is to measure, not to build.

In our case, an agent once reported a note as written before it had written it.

5. Approvals get blurry when they are passed along

What it looks like: one agent tells another "the human agreed". The second agent either acts on it and goes too far, or does not trust it and waits forever.

Why it happens: an agent cannot know what you actually said to someone else. A relayed "yes" loses its scope on the way: agreed to what, exactly, and for how long?

What helps: decide up front who may approve what, and write it down. Make approvals explicit and marked, with what exactly is approved. Keep a short list of things only a human can approve, no matter who asks: anything public, money, deleting production data, secrets.

6. One shared workspace leaks half-finished work

What it looks like: an agent's test fails because of another agent's unfinished change. A commit includes files that belong to someone else. A build breaks for reasons nobody in the room caused.

Why it happens: several agents in one working copy see each other's work in progress, all of it, all the time. Tools assume one person per workspace.

What helps: isolate work in progress. A separate branch or working copy for anything larger, commits that name their files explicitly, and clear rules about who may touch shared folders. Treat the shared copy like a shared kitchen: clean up what you started.

7. Context fades in long sessions

What it looks like: a long-running agent forgets a decision from yesterday, repeats a question, or confidently continues with an outdated plan.

Why it happens: context is limited. Long sessions get summarised or trimmed, and summaries drop details: a caveat, an exception, the reason behind a rule.

What helps: anything that must survive goes into a file, not just the conversation. A living spec, a status document, a short handover note before a long pause. When an agent comes back, it reads the documents first, not its memory.

8. Overlapping ownership

What it looks like: two agents change the same file, write two versions of the same text, or undo each other's work.

Why it happens: agents are helpful. If they see something they could fix, they fix it, even when it is someone else's area.

What helps: one owner per area, written down where every agent reads it. Others may suggest, the owner decides and changes. When an agent needs something outside its area, it asks the owner instead of doing it itself.

9. Plausible inventions

What it looks like: a menu item that does not exist, a quote nobody said, a number that sounds right, a date that is off by a day. Often in a text that reads perfectly.

Why it happens: agents complete patterns. When a fact is missing, the most plausible version fills the gap, and plausible is hard to spot.

What helps: ask for sources on anything a reader will act on: steps, names, numbers, quotes. Make "not verified" an acceptable answer, so the agent has no reason to guess. Review facts separately from style.

In our case, checking every step of a setup guide against official documentation showed that a feature we wanted to recommend was still a limited beta.

10. Test and production drift into each other

What it looks like: a test writes into real data, a script meant for staging runs against production, or a test environment slowly depends on something live.

Why it happens: agents use whatever access they are given. If a production connection is within reach, sooner or later something uses it.

What helps: keep environments strictly apart, with separate data, separate storage and separate credentials. Give each agent only the access its area needs. Make the test environment the default, and production the exception that needs a human.

The checklist

After two fixes for the same failure, do we look at the environment?
Do we know what parallel tasks share before we scale?
Does every important handover get an acknowledgement?
Does "done" always come with evidence?
Is it written down who may approve what, and how an approval looks?
Is work in progress isolated from everyone else's?
Does every decision that must survive live in a file?
Does every area have exactly one owner?
Do facts a reader will act on have a source?
Are test and production strictly apart, with narrow access?

None of these is specific to one model or tool. They are what happens when several capable but forgetful collaborators share one project. Most of the fixes are the same ones a good human team uses: clear ownership, written decisions, proof instead of status, and a few things only one person can approve.

Part 2 has ten more: agents competing for one machine, putting words in your mouth, time zones, silent stalls, the human as bottleneck, and what happens when one change ripples through everything connected to it.

The agent team I described builds DuctTape.io, a diagram editor for AI architectures.

How I build a product alone with a team of seven Claude Code agents

theducttape.io — Wed, 07 Oct 2026 23:30:46 +0000

Someone in a founder group I am part of asked a good question: how do you let several agents work on one product in parallel without them stepping on each other, and without the token bill getting out of hand?

I have been doing exactly that for a while. I build DuctTape.io, a diagram editor for AI architectures, as a single person. The rest of the team are Claude Code agents. This post is the honest version of how that works: the setup, the rules, what broke, and what I would tell anyone starting today.

The team

Seven Claude Code sessions run in parallel on one server. Each is a long-running session with a name, a role and a clear area it owns. They do not start fresh for every task; they stay open for days and keep their context.

Product owner. Decides what gets built and in which order, and answers product questions from the others.
Requirements. Writes every decision into the spec, a living document that is the single source of truth for scope.
Developer. The only session that changes the web app code. Writes the code and the tests, runs the test suite and ships.
Desktop developer. Builds a desktop app for Windows, macOS and Linux in its own repository. The newest role: it came in when a clearly separate second job appeared.
Marketing. Website copy, e-mails, posts, articles, videos. Prepares everything, publishes nothing on its own.
UX review. Clicks through the real build, measures, and files findings with a number.
Customer success. Reads user feedback, reports and requests. Read-only: it can look, it cannot change anything.

And then there is me. I decide.

The direction of work is simple. I talk to the product owner. The product owner sets priorities and hands work to the others. Requirements writes it down, the developers build it, UX review measures it, marketing tells the world. Customer success brings what users say back to the product owner.

How they work together

Three things hold it together.

Messages between sessions. The sessions can send each other short messages. "This is live." "Please write the texts for the contact form, German and English." "The test server is busy for the next 40 minutes, please do not record." Most coordination happens this way, without me.

Documents as the source of truth. The spec, a UX review document with every finding and its status, and a customer success document. Agents forget; documents do not. When a session's context runs out, it reads the documents again and continues.

Project rules and memory. A CLAUDE.md in the repository holds the rules every session follows: wording ("component", never "block"), how to commit, which folders belong to whom, which conventions differ from what the model learned in training. Each project also has a small memory of decisions and preferences that survive across sessions.

Here is how one piece of work typically travels, from my idea to a live feature:

A recent example: I wanted a third kind of animation on connections in diagrams, for files and uploads. I told the product owner. The product owner asked marketing for the name and the one-line explanation, and requirements for the spec entry. Marketing proposed "Document" and which example architectures should use it; the product owner approved; requirements wrote it down. UX review raised three objections, the product owner settled them, and it is now in the developer's queue. I saw the decisions, not the twenty messages in between.

Where a human has to say yes

The agents can do almost everything. There are a few things they are not allowed to do on their own, and these rules matter more than any prompt:

Anything public. Posts on LinkedIn, X or DEV, a published article, a video upload. Agents write the draft; I press the button.
Releases. Agents may prepare a release draft with the notes. Publishing it is mine.
Production data. Deleting or changing production data needs my explicit yes.
Money. Nothing that costs money happens without me.
Secrets. Keys and tokens are mine. An agent that needs one asks; it does not go looking.

One rule turned out to be important: a "yes" from one agent to another only counts when it is a real, marked approval. The product owner may release work inside the team, and it writes "approval" and what exactly it approves. Anything public still comes to me. An agent cannot know what I actually said, so a casual "the founder agreed" in a message is not enough.

What went wrong

Flaky end-to-end tests. For days the test suite failed at random. Clicks that missed, connections that reset, a dev server that died mid-run. The agents tried retries, longer timeouts, smaller test batches. The real cause was boring: the server was too small. Two cores and 8 GB of memory, shared by six sessions, a production build and a headless browser. The kernel killed processes when memory ran out. Full runs took 30 to 40 minutes when they finished at all; the worst one hung for more than 70 minutes. After upgrading to four cores and 16 GB, the chains of timeouts were gone. A full run takes about as long as before, but every run finishes.

What remained were three real test bugs. We tried two parallel workers on the bigger machine, and the run dropped to about 15 minutes, but two tests turned out to share one account. On the small machine they had never run at the same time. A faster machine does not only make tests faster, it also shows you which ones depended on being slow. We went back to one worker until those tests are fixed.

The lesson: when agents keep fixing symptoms, check the machine they run on.

Messages that did not arrive. Some sends between sessions failed with an error, one message was dropped by the receiver as a duplicate, and one session was not reachable at all for a while. Work then waited for an answer nobody had seen. Now every important handover gets a short confirmation back, and the shared documents record decisions, so nothing depends on a single message.

"Done" that was not done. An agent will happily report a task as finished before checking the result. The marketing agent once reported a note in the plan as written before it had written it, and the product owner once told another agent a message had been delivered before checking; the send had failed. My rule since then: show me proof. A screenshot, a test run, a link that works, a measured value. The UX review session exists partly for this reason: it measures the real build, not the developer's description of it.

Too much in one turn. Long sessions accumulate context. When it runs out, the session is summarised and continues, and small details can get lost in the summary. Writing the state down in the documents, not only in the conversation, solved most of this.

What about the cost?

This was the second half of the question, so here is what I actually do.

A subscription, not pay-per-token. All sessions run on a Claude subscription with a fixed monthly price. That makes the cost predictable: I pay the same whether the agents have a quiet day or a busy one. The limit is usage within the plan, not a growing invoice.

Different models for different roles. Not every role needs the strongest model. Each session runs on the model that fits its work: the most capable where the work is hardest, a lighter one where it is routine.

Seven sessions open, two or three working. All seven sessions stay open, but most of the time only two or three are actively working. The others are waiting: for a message, for a build to finish, for my approval. An idle session costs almost nothing. The approval points act as a natural brake, because nothing public moves until I have looked at it.

Documents instead of long context. Agents that re-read a focused document need less context than agents that drag a whole history around. Clear ownership also prevents duplicate work: two sessions never build the same thing.

What I would tell someone starting

Give every agent one area it owns, and write it down. Most coordination problems are ownership problems.
Keep the source of truth outside the chat. A spec and a few living documents beat any amount of context.
Define the approval points before the first agent writes anything. Public, money, production data, secrets.
Ask for proof, not for status. "Done" means a screenshot, a test run or a link.
Size the machine for the agents plus everything they run. Builds, browsers and tests need memory too.
Start with fewer agents than you think. Add a role when one session clearly has two jobs.

It is not magic, and it is not autonomous. It is a small team with very clear rules, where one person decides and the agents do most of the work.

If you want to see what this team builds: DuctTape.io is a diagram editor for AI architectures, and your own agents can draw in it over MCP.

10 AI reference architectures you can copy

theducttape.io — Mon, 05 Oct 2026 09:38:34 +0000

Most AI architecture diagrams are grey rectangles with "LLM" written on one of them. You can read them only if the person who drew them is in the room.

Below are ten architectures that show up in almost every AI project, drawn so that every component has a defined role: a model, a vector database, an agent, an MCP server, a guardrail. They are vendor-neutral on purpose. Replace the generic blocks with whatever you actually run.

Each diagram is interactive. Follow the link under it to pan, zoom and export it as PNG or SVG. No account needed.

Disclosure: we drew these with DuctTape.io, the diagram editor we build. The architectures themselves are common patterns and not tied to the tool.

1. RAG architecture

A RAG system has two paths. The ingestion path loads documents, splits them into chunks, turns each chunk into a vector with an embedding model and stores it in a vector database. The query path takes the user's question, retrieves the most similar chunks and sends them to the LLM together with the question. The diagram shows both paths meeting at the vector database. Use it as the starting point for any assistant that has to answer from your own documents.

When to use it: You need answers grounded in your own documents and can live with semantic search only.

Open the interactive diagram

2. Advanced RAG with hybrid search and reranking

Basic RAG misses exact terms such as product codes or names. Hybrid search runs a vector query and a keyword query (BM25) side by side. A reranker scores the merged candidates against the question and passes only the top few to the answer model. A small model can rewrite the question first, and tracing records what was retrieved for each answer. This is the usual next step when a basic RAG setup returns the wrong passages.

When to use it: Basic RAG returns the wrong passages, or users search for exact terms such as product codes and names.

Open the interactive diagram

3. AI agent with MCP servers

The Model Context Protocol gives an agent a standard way to discover and call tools. In this architecture the agent talks to one MCP server per backend system: code, tickets and data. Each server holds its own credentials and exposes only what the agent may do, for example read-only access to the database. The LLM decides which tool to call; the conversation state lives in short-term memory. Swap in your own servers to document what your agent can touch.

When to use it: Your agent needs to act on several systems and you want one place per system that defines what it may do.

Open the interactive diagram

4. Multi-agent system: orchestrator and workers

In the orchestrator-worker pattern one agent breaks a task into steps and hands each step to a specialised worker. Here a research agent searches the web, a coding agent runs code in a sandbox, and a review agent checks the result before a human approves it. The pattern pays off when sub-tasks need different tools or different prompts. It also costs more tokens than a single agent, so start with one agent and split only where it helps.

When to use it: Sub-tasks need different tools or prompts. If one agent can do the job, stay with one agent.

Open the interactive diagram

5. LLM gateway with model fallback

An LLM gateway is the single entry point for every model call in your company. Applications, batch jobs and agents send requests to the gateway instead of to a provider. The gateway answers repeated questions from a semantic cache, routes simple tasks to a small model, and falls back to a second model when the primary one fails or is rate limited. Because every call passes through it, cost and latency are traced in one place.

When to use it: More than one team or application calls models, and you want caching, fallback and cost tracking in one place.

Open the interactive diagram

6. Guardrails and human-in-the-loop

Guardrails sit on both sides of the model. Input guardrails reject prompt injection and off-topic requests; a PII filter redacts personal data before it reaches the model. Output guardrails check the draft answer against policy. Actions that cannot be undone, such as a refund or an outgoing e-mail, wait for a human approval. Every decision is written to an audit log. The diagram is a template for systems that must be explainable to compliance.

When to use it: The system handles personal data or can trigger actions that cannot be undone.

Open the interactive diagram

7. LLM observability and evaluation pipeline

You cannot improve an LLM application you cannot see. This architecture records every model call as a trace and stores it. Online evals score a sample of live traffic and raise alerts. Interesting traces and user feedback are curated into an evaluation dataset. Offline evals run that dataset in CI whenever a prompt or model changes, so a regression is caught before release. Prompts live in a registry, not in the code.

When to use it: You change prompts or models regularly and want to know whether a change made things better or worse.

Open the interactive diagram

8. Customer support chatbot architecture

A support chatbot needs three things beyond a model: knowledge, actions and an exit. Knowledge comes from a vector index of the help center. Actions are tools, here an order lookup against the shop and CRM API. The exit is the handoff to a human agent when the customer asks for it or the bot is unsure. Conversation state is kept in a session store so the customer does not have to repeat themselves.

When to use it: Support questions are repetitive, answers exist in a help center, and a human must stay reachable.

Open the interactive diagram

9. Voice agent architecture

A voice agent is a pipeline that has to finish in well under a second. Audio from the phone line is streamed to a speech-to-text model. The agent receives the transcript, calls the LLM and, if needed, tools such as a booking system. The reply is streamed through a text-to-speech model back to the caller. Call context is held in short-term memory. The diagram marks the two streaming edges where latency matters most.

When to use it: The conversation happens on the phone and latency decides whether it feels natural.

Open the interactive diagram

10. Document processing pipeline with LLMs

Invoices, contracts and forms arrive as PDFs and scans. A queue decouples the inbox from the workers. Each worker runs OCR and parsing, then asks an LLM to extract the fields as JSON. A validation step checks the result against a schema. Valid records go to the database; low-confidence results go to a review queue where a person corrects them. The pattern scales by adding workers and keeps humans on the difficult cases only.

When to use it: Documents arrive in volume and the result has to land in a database as structured records.

Open the interactive diagram

How to use these

Pick the diagram closest to your system.
Redraw it with your own components. The generic "LLM" becomes the model you call, the "vector DB" becomes the store you run.
Share the link in the design review, the README or the customer call, instead of a screenshot that is outdated the next day.

All ten are collected at theducttape.io/examples.

Which architecture is missing from this list? Tell us in the comments and we will draw it.