How I Used AI to Untangle a Legacy Service I'd Never Touched Before

Three weeks ago I got handed a support escalation involving a service I'd never opened before. It was a Node.js microservice, about four years old, written by two engineers who had both since left the company. No meaningful README. Tests that hadn't run in CI for months. A Slack thread full of "this thing is a black box" going back two years.

The bug was real and customer-facing. I had one day to get a handle on it.

The Situation

The service sat between our API gateway and a third-party fulfillment provider. Something in the request transformation logic was intermittently dropping fields — but only under a specific combination of request shape and load. The output was wrong. The logs were unhelpful. The code was 3,200 lines across 14 files, and the logic was split between three layers of middleware with no clear separation of concerns.

I've been in this position before. Normally it means a half-day of console.log-driven archaeology before you even have a theory worth testing.

This time I tried something different.

What I Tried First (And Why It Wasn't Enough)

My first instinct was to paste the main handler into an AI chat and ask "what does this do?" That gave me a surface-level summary — not wrong, but not useful. It told me what the code said, not what it meant in the context of our system.

The problem with treating AI like a reader is that it reads what you give it. If you give it one file without context, it gives you one file's worth of insight.

The Shift: Giving It a Job Instead of a Question

The prompt pattern that actually unlocked the service for me was treating the AI as a new engineer joining the team, not a search engine. I fed it the core files in sequence and gave it a specific role with a specific goal:

You are a new backend engineer joining this team. I'm going to show you the core files of a legacy microservice one at a time. After each file, update a running list of:
1. What this file is responsible for
2. Any assumptions or implicit contracts you can see
3. Questions you'd want answered before touching this code

Do not summarize the code. Identify the load-bearing logic and flag anything that looks fragile.

After three files, it had surfaced something I'd glossed over: a field transformation function that silently returned undefined when the input didn't match an expected shape — no error, no log, just a missing field downstream. That was the bug. It had been in the codebase for four years.

Turning Understanding Into a Fix

Once I had the theory, I used a second prompt to pressure-test it before writing a single line of fix code:

Here is the function I believe is causing a silent field drop:

[paste function]

The upstream input looks like this:

[paste example payload]

Walk me through every code path in this function. For each path, tell me what the output would be and whether any field could be silently dropped or coerced to undefined. Flag the path you think is most likely to cause intermittent failures under load.

It walked through five code paths, flagged two that could produce undefined, and correctly identified the one tied to our intermittent failure pattern.

This pattern — role-first, file-by-file, output structured as questions not summaries — is one of the ones I've packaged into The AI Leverage Playbook: 50 Prompts & Workflows for Engineers — but the version above is enough to get value on its own.

What This Looked Like End-to-End

• Total time to root cause: ~90 minutes (vs. my usual half-day minimum for unfamiliar code)
• Files I had to read manually: 4 out of 14
• Lines of fix code: 11
• Test I wrote after: 1 regression test, also AI-assisted

The key wasn't the AI doing the work. It was the AI acting as a structured thinking partner while I retained ownership of the diagnosis. I still had to read the code. I still had to make the call. But I stopped thrashing.

The Takeaway

If you're dropped into unfamiliar legacy code, don't ask AI to explain it. Give it a role, feed it files incrementally, and ask it to maintain a running model of the system — including what it doesn't know. That output is far more useful than a summary.

The same pattern works for onboarding onto a new codebase, doing pre-refactor reconnaissance, or writing documentation after the fact.

The full set of prompts for situations like this — legacy code archaeology, debugging, refactor planning, test design — is in The AI Leverage Playbook: 50 Prompts & Workflows for Engineers. 50 prompts, $19. It covers code review, debugging, sprint planning, ADRs, and more — organized so you can grab the right prompt for whatever situation you're actually in.