What this prompt does
This prompt configures an AI coding assistant to work safely in a legacy [language] codebase that is [codebase_age] old, uses [legacy_patterns], has [test_coverage] coverage, was built by [original_team_size] developers, and [documentation_status]. It produces a seven-step setup that teaches the AI the system's existing conventions rather than letting it suggest modern replacements that would break consistency.
The structure works because it prioritizes understanding and safety over speed. A context document maps entry points, core logic, the data layer, and integrations so the AI grasps the system despite missing docs. A pattern dictionary catalogs how the codebase already handles errors, queries, and auth, so suggestions match existing style. Before any change, the AI writes characterization tests that capture current behavior including [known_quirks]. A dependency-mapping step traces how a change ripples through call sites and scheduled jobs, incremental prompts introduce [target_patterns] one function at a time, and a debt inventory scans for [debt_indicators] and ranks items by effort and risk.
When to use it
- You are extending a legacy codebase with thin tests and stale documentation.
- You want the AI to follow existing conventions, not replace them inconsistently.
- You need characterization tests before touching behavior with
[known_quirks]. - You want to trace the blast radius of a change before making it.
- You are modernizing toward
[target_patterns]incrementally, without a rewrite. - You need a prioritized technical-debt inventory based on
[debt_indicators].
Example output
Expect a configuration kit rather than a single document. It includes an architecture context document that maps entry points, core business logic, the data-access layer, and integration points so the AI understands the system despite missing docs. A pattern dictionary teaches the AI the existing conventions for errors, queries, and auth, and a safe-modification workflow writes characterization tests capturing [known_quirks] before any change. From there you get a dependency-mapping prompt that surfaces affected call sites, triggers, and scheduled jobs, incremental modernization prompts that introduce [target_patterns] one function at a time, a prioritized debt inventory built from [debt_indicators] with effort and risk estimates, and a knowledge-extraction workflow that generates explanatory comments and architectural notes for the team wiki.
Pro tips
- Invest in the pattern dictionary — teaching the AI your existing
[legacy_patterns]matters more than letting it propose modern rewrites that fracture consistency. - List
[known_quirks]explicitly so characterization tests lock in behavior like timezone-dependent parsing before you change anything. - Always run the dependency-mapping step before a change in low-coverage code; the call sites it surfaces are where silent breakage hides.
- Modernize one function at a time toward
[target_patterns]; resist the urge to let the AI rewrite a whole module. - Tune
[debt_indicators]to your real signals (suppressed warnings, hardcoded credentials) so the inventory ranks what actually hurts. - Capture the AI's explanatory notes into your wiki as you go; on a
[codebase_age]-old system that institutional knowledge is the scarcest resource.
