The Case for Refactoring Over Deferral

When faced with legacy technical debt—in this case, ten fragmented repositories—the temptation is to wait for AI agents to become powerful enough to handle the refactor automatically. However, Denys Linkov’s experience at Wisedocs suggests that performing the refactor manually (or with AI-assisted tooling) is superior to waiting.

While modern models like Claude 3.5 Sonnet and Opus have significantly reduced the manual effort required for refactoring—dropping from three hours of back-and-forth to essentially one-shot execution—they are not yet capable of autonomous, end-to-end architectural migrations. Attempting to "zero-shot" a massive refactor often results in "AI psychosis," where the model generates convincing scaffolding that lacks actual implementation logic, deployment commands, or bootstrap scripts.

The ROI of a Clean Monorepo

Moving from ten repositories to a single monorepo yielded measurable business and social outcomes:

  • Shipping Velocity: The team moved from slow, debt-ridden releases to shipping features in under a week that previously took months.
  • Developer Engagement: A clean codebase transformed the developer experience. Developers who previously avoided the legacy repos began volunteering to contribute to the new monorepo, even outside their primary domains.
  • Commit Velocity: The commit rate remained high and consistent even after the initial refactor phase, indicating that the new architecture supported sustained feature development rather than just maintenance.

Mental Models for Agentic Workflows

Linkov argues that engineers must adjust their mental models regarding agent reliability. Instead of relying on the 50% success rate often cited in benchmarks, teams should target 80-90% reliability for long-running tasks.

  • Avoid the "Coin Flip" Trap: Launching an hour-long agent run with a 50% success rate is a net negative for productivity, as it wastes compute and fragments the developer's attention span.
  • The Importance of Scaffolding: Successful AI-assisted refactoring requires a robust harness. This includes sub-agents for specific criteria, shell command execution, and automated verification steps.
  • Human-in-the-loop: Even with advanced models, human oversight remains critical for validating hidden assumptions—such as verifying if a library feature is actually production-ready or merely in beta—which models frequently hallucinate.