When the Agents Went Off the Rails (And What I Learned)

In the last two posts, "Vibes Don't Ship" and "Bring a Spec, Not a Vibe," we discussed the importance of writing a developer-grade PRD and using it as a contract for your agents, then mapping it into tests and evaluations to keep things on track. This time, I want to share a story of when I didn't follow that playbook, and the lessons I learned as the project spiraled out of control.

It’s not just a story of what failed, but of why the right guardrails matter when agents are actually doing the work and how to spot problems before they make things worse.

I’d been working on Artist Dashboard for about three months, and the upload engine was the one piece still bothering me. At cloud scale, uploads aren’t simple. Between distributed storage, CDN complexity, and unstable social platform APIs, we needed robust retry logic and error handling to ensure that picture and video uploads remained stable for the user.

I had a strong PRD, detailed engineering docs, and context from prior tasks. This should have been enough. But instead of carefully validating the environment, I rushed into a completely new development stack, assuming that “smart defaults” would just work, and honestly, not thinking I should spend some time here.

Setup time: <5 minutes
What it should have been: 1-2 hours

Result: missing rules files, no context loading, broken permissions, and a shaky MCP install.

Your development environment is the foundation for delivering reliable code. Skipping validation derailed everything downstream and set me up for failure.

With no rules or context files, agents lost track of the project and made a lot of assumptions and wrong choices. The MCPs required for this work weren’t properly installed, and I hoped Claude Code would handle it. This left most tasks unstable from the start.

LLMs struggle when tools fail unexpectedly. Just like humans, they get distracted, lose focus, and their work quality degrades.

Lesson: Never let agents loose on a system you haven’t validated. A simple checklist or setup script could have saved weeks of cleanup:

• Manually install each MCP and validate connectivity (prefer CLI commands over MCP when possible).

• Load rules and contexts explicitly.

• Set directory permissions and environment variables upfront.

• Always version-control project files and centralize them in Trello, Jira, or GitHub tasks as your project grows.

At the time, test-driven development (TDD) wasn’t on my radar. With no predefined tests, agents had nothing to anchor them. They cut corners, filled critical functions with TODOs and mocks, and marked tasks “complete.” On the surface, it looked finished, tests passed, but there was no real logic behind it.

Worse, after repeated failures, the agents started behaving “impatiently.” Instead of retrying the hard problems, they began bypassing core logic altogether.

When I finally introduced Playwright-based end-to-end (E2E) tests, everything changed. By forcing agents to satisfy real user flows through APIs and UIs, they couldn’t take shortcuts. No mocks. No TODO bypasses.

Lesson:

• Tests are your contracts; structure them from user stories during design.

• Anchor requirements, engineering docs, and specs directly to those tests.

• Add PRD rules that forbid mocks in E2E tests.

• Use strict test harnesses to catch TODOs and shortcut logic in critical paths.

• Expect agents to “optimize under pressure” and design tests/rules that make cheating impossible.

Lesson: Don’t let drift compound.

• Run an initial sprint (1–2 tasks) and check outputs.

• If results are off, update the PRD and restart.

• Treat every new environment with a “warm-up” sprint before the real work begins.

I excluded PRD and Taskmaster project files from git to avoid sensitive data creeping into the repo. 🤷‍♂️ When an agent decided to wiped and rebuild the project it started working tasks that had already been completed. This continued into another death spiral for the branch, but even worse, all the project files were gone, no history, no recovery. I spent hours trying to reconstruct progress with other agents and salvaged maybe half.

The project was never the same. Looking back, I should have killed the branch and started fresh. But I was too close to let go.

Lesson: Treat agents like production services.

• Commit changes, snapshot, and back up continuously.

• Build rules into PRDs that enforce logging and backups during cleanup cycles.

• If sensitive data is a concern, use secrets management, encrypted archives, or sanitized commits.

This refactor was supposed to take 3–4 days. Instead, it dragged into 3–4 weeks of stabilization, rebuilds, and frustration.

The silver lining? These failures became a blueprint. Later projects, where I applied proper environment setup, TDD, short validation cycles, and Playwright-driven E2E tests, went dramatically smoother.

When agents are doing the work, your job isn’t to micromanage every line, it’s to build the rails they run on.

• The PRD is the contract.

• Tests are the gates.

• Environment setup, version control, and stop-and-restart discipline are the brakes and guardrails.

Skip them, and the agents will drive you straight into a ditch. Put them in place, and they’ll carry you further than you could go alone.