Mistakes to avoid

The anti-patterns we see most. Catching them early saves the most time.

Asking for "a full SaaS" in one prompt

"Build me a complete project management tool with users, teams, projects, tasks, comments, notifications, billing, and a mobile-responsive design."

What happens: the agent scaffolds maybe two of those features, half-implements three more, never wires the rest. You'll spend more time debugging the soup than you would have building it incrementally.

What to do: scope the first prompt to a working skeleton — home page + one feature. Add more in follow-ups.

"Just make it like Linear / Vercel / Notion"

What happens: the agent has seen those products and has some idea, but every model interprets "like X" differently. You'll get a generic Tailwind dashboard that looks nothing like what you pictured.

What to do: describe the specific things you want — the layout, the color treatment, the interactions. "Three columns, with a sidebar on the left, and a dark theme with one accent color" is better than "like Linear".

Forgetting to say "use agentry"

"Build me a web app for tracking workouts."

What happens: most harnesses default to scaffolding files into whatever repo you're currently in. You end up with a half-built local project, no sandbox, no preview URL, no deploy path.

What to do: open with the magic words: "Use agentry to build me a web app for tracking workouts." That phrase routes the work into a sandbox.

Pinning a stack the sandbox doesn't need

"Build me a web app. Use Next.js with the App Router, Tailwind, and shadcn/ui."

What happens: the sandbox already has an opinionated default stack for web apps so the agent doesn't have to negotiate one. Overriding it tends to drag the build into less-paved paths — wrong devserver command, deploy preflights that don't recognise the build output, more friction overall.

What to do: leave the framework out unless you genuinely need a different one. Describe the shape of the app (pages, behaviours, look) and let the sandbox pick the technology. The default exists because it's the smoothest path.

When it is worth pinning: static-site builds (Astro), Python services, anything where the default genuinely doesn't fit. Make the call explicitly, don't pin by reflex.

Naming the sandbox app or test

What happens: every chat where you've done this will collide. agentry auto-suffixes (app-7f2a, test-ab12), so you don't lose anything — but the model gets confused about which sandbox it's working in.

What to do: don't name it yourself. Let the agent pick a descriptive name. Or use a project-shaped name (waitlist-landing, pocket-tracker).

Switching to a new chat halfway through

What happens: the new chat creates a new sandbox. Your work in the old one stays there but the new agent can't see it.

What to do: stay in the same chat for a project. If you need to share work between chats (rare), tell the new chat the existing sandbox_id:

Resume work in sandbox pocket-tracker. List the files there.

Trusting next dev as proof it works

The dev server is permissive. Type errors, missing imports, broken builds — many of these don't trip next dev (or vite dev, or equivalents).

The first time you find out is when you click Deploy and the preflight fails.

What to do: at the end of every working session, ask the agent:

Run the build. Make sure it passes.

If it fails, the agent reads the verbatim compiler error and fixes it. Repeat until clean.

Not binding services before scaffolding

What happens: the agent doesn't see a MONGODB_URL in env, so it writes mongodb-memory-server to fake it. Or it writes the connection string with a placeholder. Either way, your app doesn't work in production.

What to do: bind services before prompting. On your server:

agentry service bind mongodb
agentry service bind anthropic

Then the next sandbox the agent creates will see the real env vars. See Add a database.

Putting secrets in the prompt

"Use this MongoDB URL: mongodb://admin:supersecret@db.acme.com/prod"

What happens: the model includes the URL verbatim in code, comments, and (depending on harness) chat history that may be sent back to model providers.

What to do: bind a service, or use agentry env set NAME (omit the value — agentry will prompt you with hidden input) so the secret lives in the sandbox env, never in the chat.

Pasting an entire codebase as context

What happens: the model exhausts its context window, then drops the actual instruction. You get back a response that ignores most of what you asked.

What to do: paste only the file(s) you want the agent to look at, or ask the agent to look:

Read src/lib/db.ts and src/app/api/products/route.ts, then fix the issue where the products endpoint always returns an empty array.

The agent reads the files with file_read and gets exactly the right context.

"Just deploy it" while there are uncommitted intentions

The Deploy button runs a preflight build. If the project has TypeScript errors, missing env, or broken imports, Deploy fails — but the failure mode is to send you back to the chat with a long compiler error, which can be confusing if you've moved on mentally.

What to do: always close a session with a production build first. By the time you click Deploy, you should already know the build is green.

Letting the agent install random packages

"If you need any packages, just install them."

What happens: the agent installs five flavors of similar libraries, then reaches for whichever it imported first. Bundle size explodes.

What to do: name your library choices when you have preferences. "Use zod for validation, react-hook-form for forms." Otherwise the agent picks reasonable defaults — but they may not be your defaults.

Asking the agent to "run forever"

"Start the server and keep it running."

The dev server already keeps running once started — that's what project_start does. You don't need to ask. What you might need:

"Restart the dev server with the new env."

Or:

"Check the logs — the server seems wedged."

Those map to actual tools (project_stop + project_start, project_logs).

Next

• Patterns that work — the positive version of this page.
• Examples — real prompts that produced shippable apps.