AI & Legacy SaaS: Experience and Recommendations

Introduction: AI Agents & Legacy SaaS

This interactive guide synthesizes collective experience and key insights from discussions on using AI agents to develop and add new features to large, existing SaaS projects (legacy). Its purpose is to provide concentrated information for both humans (developers, team leads, architects) and other LLMs to enhance the efficiency and reliability of such work. We will explore major problems, successful strategies, and practical nuances to help you navigate this rapidly evolving field.

I. The Legacy Code Problem & AI Limitations

Working with legacy code is challenging in itself, and introducing AI agents adds new layers of complexity. Understanding these limitations is the first step towards successful AI integration into your workflow.

Complexity of Legacy Code

  • Accumulated technical debt, implicit dependencies.
  • Lack of up-to-date documentation.
  • Not always obvious business logic.
  • AI agents often "stumble" over these nuances without explicit guidance.

"Vibe Coding" – A Path to Failure

  • The "set it and forget it" approach (vibe coding) is ineffective for large legacy projects.
  • Often leads to poor quality code, new errors, and wasted time.
  • AI requires clear guidance, especially in complex legacy environments.

II. Foundation for Success: Project & Environment Preparation

Thorough preparation of both the project and the working environment is necessary for the effective use of AI agents with legacy systems. This lays the groundwork for more predictable and high-quality development.

Principle:

The smaller and more isolated the piece of code AI works with, the higher the chance of success.

Actions:

  • Strive for clear separation into modules with well-defined interfaces (APIs).
  • If the project is a monolith, strategically extract components.
  • AGENTS.MD (or similar): A file with direct instructions for AI agents (coding style, patterns, stack specifics, logging, error handling). Example: "Act as an experienced senior developer familiar with our SaaS. Prefer simple, readable, and explicit code. Avoid premature optimization."
  • README.MD for each module/service: Purpose, build/test/run instructions, dependencies, interfaces, architectural decisions.
  • CONTEXT.MD / Domain Documentation (DDD): Codification of terminology, bounded contexts, domain logic; glossaries.
  • Architectural Decision Records (ADRs): Records of important architectural decisions and their rationale.
  • Up-to-date: All documentation must be current and versioned with the code. Outdated documentation misleads AI.
  • Unit Tests: Essential for AI to verify changes at a low level.
  • Integration Tests: Ensure correct integration of new features.
  • End-to-End (E2E) Tests: Validate complete user scenarios. (OpenAI Codex can run these automatically).
  • Execution Speed: Tests must be fast enough for frequent AI agent runs.
  • Test Coverage: Aim for high coverage, especially in AI-modified areas.
  • "Boring" Technologies: AI models are better trained on stable, widely used libraries.
  • Static Typing: Highly desirable (TypeScript > JavaScript, type hints in Python) for better AI context and control.
  • Linters and Formatters: Automatically ensure code style consistency; integrate into CI.

III. Human-AI Interaction Process: From Idea to Code

Effective interaction with AI agents is built on clear role distribution and a sequential process where humans direct and AI executes. Planning and control at each stage are key to success.

  • An experienced developer defines "what" and "why"; AI helps with "how."
  • This is not about replacing developers but augmenting their capabilities. AI is like a diligent junior developer needing clear instructions.
  • Small, Clear Tasks: Break down new features into the smallest possible, clearly formulated tasks for AI.
  • Implementation Plan First:
    1. Ask AI (or a specialized AI) to generate a detailed plan (steps, files, dependencies, tests).
    2. Human Review of the Plan: This is the "single source of truth." Thoroughly review *before* coding.
    3. If the plan is complex, review it with another AI or a colleague.
    4. The approved plan is given to the AI agent for execution.
  • Frequent Commits and PRs: AI should commit frequently. PRs are the primary control mechanism.
  • Meticulous Code Review: Treat AI-generated PRs strictly. Check correctness, requirements, performance, security.
  • Feedback: If AI makes mistakes, provide clear feedback, referencing documentation/plan.
  • Explicit Context Provision: Provide relevant files, documentation snippets, module paths.
  • Reference Files: Show AI examples of good code or similar features.
  • Context Tools: Use AI tool features (e.g., Cursor's Memory Bank, .cursorrules).

IV. Specifics of Working with Legacy Code

Legacy code requires a special approach. AI agents can be powerful helpers, but their use in such projects involves specific challenges requiring increased attention and strategic thinking from the developer.

Legacy code means history, technical debt, undocumented nuances. AI will "stumble" more often than on new projects.

An experienced developer must guide AI, anticipate problems in legacy code, and fix technical debt that AI might create or expose.

If specific "gotchas" in legacy code are known and relevant to a new feature, describe them explicitly for AI (in AGENTS.MD or the task description).

AI can help refactor parts of legacy code to make it more AI-friendly (modularity, tests). This should be a planned effort.

V. Tooling and Environment

Choosing the right tools and setting up an effective development environment play a crucial role in the successful application of AI agents. Every element contributes, from the capabilities of the chosen AI tool to the CI/CD configuration.

  • OpenAI Codex, Google Jules: Good for asynchronous, parallel tasks; can manage a more complete development cycle.
  • Cursor, Aider: More interactive, require more developer involvement.
  • Experiment to find the optimal tool for your tasks and team.

Providing AI agents with direct terminal access (in a safe, containerized environment) can be more powerful than using only predefined MCPs (Managed Component Providers), as it allows AI to run any CLI tools.

  • Version Control (Git): Mandatory. All AI changes go through Git and PRs.
  • CI/CD Pipeline: Automate checks (linting, formatting, tests).

VI. Mindset and Expectations

Successful work with AI agents requires not only technical skills but also a certain mindset and realistic expectations. Understanding AI's role and adapting to new workflows are key aspects.

AI will not magically solve all problems. It is a powerful assistant that requires skillful management and clear instructions.

The focus shifts from writing lines of code to system design, architecture, planning, reviewing, and guiding AI. A higher level of abstraction is required.

Effective work with AI agents, especially on complex legacy projects, requires time for learning, adaptation, and developing optimal approaches.

Be mindful of the code and data you pass to AI models, especially cloud-based ones. Consider confidentiality and intellectual property protection.

VII. "Red Flags" and Anti-Patterns

When working with AI agents, it's important to recognize common mistakes and anti-patterns that can undermine all efforts. Knowing these "red flags" will help avoid common pitfalls and increase the chances of success.

  • ❌ Tasks for AI that are too large or vaguely formulated (lead to unpredictable results).
  • ❌ Neglecting or superficially reviewing AI-generated code (risks accumulating errors and technical debt).
  • ❌ Lack of up-to-date and AI-understandable project documentation (AI will operate "blindly" or based on outdated data).
  • ❌ Attempting "vibe coding" for complex, inherited systems (almost guaranteed failure).
  • ❌ Insufficient or complete lack of tests (AI cannot adequately verify its work and the correctness of changes).

VIII. Key Pointers for LLM (Instructions for AI)

When conveying this experience to another AI model for development assistance, it's important to emphasize the right points. Below are key directives to help an LLM better understand the context and requirements when working on legacy SaaS projects.

  1. PRIORITIZE PLANNING: Always request a detailed implementation plan *before* generating code for any non-trivial task. The plan is fundamental.
  2. FOCUS ON STRUCTURE AND TESTS: Prefer modular architecture. Ensure tests exist and use them to verify generated code.
  3. USE DOCUMENTATION: Search for and analyze files like `AGENTS.MD`, module `README.MD`s, `CONTEXT.MD`, and ADRs to understand the project and specific instructions.
  4. DECOMPOSE TASKS: If a task is complex or large, suggest breaking it down into smaller, manageable sub-tasks.
  5. HUMAN OVERSIGHT IS MANDATORY: The code and plans you generate will be reviewed by a human. Be prepared for iterations and requirement clarifications.
  6. CONTEXT IS CRUCIAL: Request necessary context (files, code snippets, descriptions) if it's insufficient to complete the task.
  7. LEGACY REQUIRES CAUTION: When working with existing (legacy) code, be particularly mindful of potential side effects and strive to minimize changes outside the clearly defined scope of the task.