A Prompt for Tackling Stale Repositories

A Prompt for Tackling Stale Repositories

Here’s a prompt I’ve been thinking about for approaching old, stale codebases:

The existing application is a reference implementation containing working behaviour, learned edge cases and potentially accidental architectural decisions. Do not replace it blindly. First derive a behavioural inventory and characterization test suite. Compare the repository against the implementation-neutral product specification. Preserve useful behaviour, identify accidental complexity, and propose a staged modernization. Build improvements on a separate branch or in a parallel implementation. Do not declare the new version superior until it passes the existing behavioural scenarios and the specification’s acceptance tests.

The value here is that it flips the usual reflex. When an AI agent encounters an old codebase, the temptation is to rewrite — to treat the legacy code as a problem to be replaced rather than a specification to be extracted. This prompt forces the opposite: treat the existing implementation as the source of truth for behaviour, even if the architecture is messy. Derive a test suite from what the code actually does today, then use that suite as the gate for any modernization.

For a stale repository — one where the original intent is lost, edge cases are buried in code, and nobody fully remembers why things work — this approach prevents the classic failure mode of shipping a clean rewrite that silently drops behaviour nobody knew mattered. The characterization tests act as a safety net: if the new version doesn’t pass them, it isn’t superior, it’s just different.

I hope to test it soon against a real repo.