From AI Gibberish to Precise Code Changes: How I Made AI Understand a Legacy Project

Why AI Efficiency Matters

Over the past year AI has progressed from handling tiny, well‑defined tasks to diagnosing issues, proposing implementable solutions, and even executing and self‑testing code, making it a powerful ally in development.

Identifying the Core Bottleneck: Context

Even with strong AI capabilities, legacy projects suffer because AI lacks sufficient contextual knowledge. The missing context includes business history, documentation, runtime behavior, and architectural debt.

Building AI Context (AGENTS.md)

We started by creating a static AGENTS.md at the repository root to index essential knowledge such as business background, architecture decisions, reusable components, and third‑party integrations. Only concise summaries (path + 1‑2 sentence description) are kept in the root file, with detailed entries stored alongside the relevant modules.

Step 1: Remove Dead Code

Eliminate obsolete environment‑checking if/else blocks copied from old client code.

Discard unused OT‑collaboration code that never ran.

Delete abandoned messaging mechanisms left from a failed WebIDE redesign.

Separate AI Agent functionality from the front‑end to avoid tangled legacy paths.

AI assists by quickly identifying unreferenced code, while developers verify runtime relevance.

Step 2: Simplify Over‑Designed Architecture

We reduced unnecessary complexity, such as replacing OT‑based collaborative editing with simple HTTP updates and removing redundant WebSocket logic. Two refactor rounds showed AI’s judgment improving from frequent guidance needs to mostly accurate autonomous decisions.

Step 3: Define Standards and Boundaries

We introduced unified component libraries and style guidelines (layout, responsive design, component contracts) and encoded them in the repository so AI can automatically check compliance during merge requests.

Step 4: Build Automated Testing

Automated unit and end‑to‑end (E2E) tests were introduced in four phases:

Establish basic test framework for core features using mock data.

Add MR regression pipeline and Docker‑based images.

Refine test cases by categorizing them into P0/P1/P2 priorities.

Develop complex‑flow tests for intricate user journeys.

Tests now run on real data where needed, and visual regression tests compare screenshots with pixel‑tolerance thresholds to catch style regressions.

Step 5: Continuous Debt Management

By embedding standards and AI‑driven reviews into the daily workflow, technical debt becomes a routine activity rather than a periodic overhaul. AI follows newly defined conventions to automatically flag and fix lingering issues, while MR‑time AI reviews ensure new changes adhere to standards.

Outcome

After refactoring, release cycles require far less manual regression, user‑reported issues have dropped dramatically, and the platform’s user base continues to grow. The author concludes that while AI can handle execution, documentation, and repetitive decision‑making, human strategic thinking remains indispensable.